List

Organize nestable items in a bulleted or numbered list.

Loading...
Files
components/list-demo.tsx
'use client';

import React from 'react';

import { withProps } from '@udecode/cn';
import { Plate, PlateElement } from '@udecode/plate-common/react';
import {
  BulletedListPlugin,
  ListItemPlugin,
  ListPlugin,
  NumberedListPlugin,
  TodoListPlugin,
} from '@udecode/plate-list/react';

import { autoformatListPlugin } from '@/components/editor/plugins/autoformat-list-plugin';
import { editorPlugins } from '@/components/editor/plugins/editor-plugins';
import { FixedToolbarListPlugin } from '@/components/editor/plugins/fixed-toolbar-list-plugin';
import { useCreateEditor } from '@/components/editor/use-create-editor';
import { listValue } from '@/components/values/list-value';
import { Editor, EditorContainer } from '@/components/plate-ui/editor';
import { ListElement } from '@/components/plate-ui/list-element';
import { TodoListElement } from '@/components/plate-ui/todo-list-element';

export default function ListDemo() {
  const editor = useCreateEditor({
    components: {
      [BulletedListPlugin.key]: withProps(ListElement, { variant: 'ul' }),
      [ListItemPlugin.key]: withProps(PlateElement, { as: 'li' }),
      [NumberedListPlugin.key]: withProps(ListElement, { variant: 'ol' }),
      [TodoListPlugin.key]: TodoListElement,
    },
    plugins: [
      ...editorPlugins,
      ListPlugin,
      TodoListPlugin,
      FixedToolbarListPlugin,
      autoformatListPlugin,
    ],
    value: listValue,
  });

  return (
    <Plate editor={editor}>
      <EditorContainer variant="demo">
        <Editor />
      </EditorContainer>
    </Plate>
  );
}

功能特性

  • 符合 HTML 规范的列表

    • 标准的 ul/ol > li 结构
    • 正确的嵌套和层次结构
    • 对 SEO 友好的标记
    • 清晰的 HTML/markdown 导出
  • 列表类型

    • 无序(项目符号)列表
    • 有序(编号)列表
    • 带复选框的待办事项列表
    • 嵌套子列表
  • 拖放功能

    • 目前仅支持根级别列表项的拖放
    • 暂不支持同级和嵌套项目的拖放
  • 快捷键

    • 结合自动格式化插件,使用 markdown 快捷方式(-*1.)创建列表
    • 使用 Tab/Shift+Tab 控制缩进
  • 限制(使用 缩进列表 可获得这些功能)

    • 拖放功能仅支持根级别列表
    • 列表项无法对齐

如需更灵活的、类似 Word 的使用方式,请参见 缩进列表插件

安装

npm install @udecode/plate-list

使用

import { ListPlugin } from '@udecode/plate-list/react';
 
const plugins = [
  // ...otherPlugins,
  ListPlugin,
];

快捷键

KeyDescription
Cmd + Opt + 4插入有序列表。
Cmd + Shift + 4插入有序列表。

插件

ListPlugin

  • key: 'list'
  • 包含以下元素插件:
    • BulletedListPlugin
    • NumberedListPlugin
    • ListItemPlugin
    • ListItemContentPlugin

Options

Collapse all

    指定列表项除了 pul 类型外的有效子节点类型。

    决定按下 Shift+Tab 是否重置列表缩进级别。

BulletedListPlugin

无序(项目符号)列表的插件。

NumberedListPlugin

有序(编号)列表的插件。

ListItemPlugin

列表项的插件。

ListItemContentPlugin

列表项内容的插件。

API

editor.tf.toggle.list

在编辑器中切换列表。

Parameters

Collapse all

getHighestEmptyList

查找可以删除的最高级空列表。列表路径应与 diffListPath 不同。如果最高级空列表有 2 个或更多项目,则返回 liPath。它会向上遍历父列表直到:

  • 列表项少于 2 个。
  • 其路径不等于 diffListPath

Parameters

Collapse all

    编辑器实例。

Returns

Collapse all

    可以删除的最高级空列表的路径。

getListItemEntry

返回给定路径(默认 = selection)的最近的 liul/ol 包装节点entry。

Parameters

Collapse all

    编辑器实例。

Returns

Collapse all

    最近的 liul/ol 包装节点entry。

getListRoot

向上搜索根列表元素。

Parameters

Collapse all

    编辑器实例。

    开始搜索的位置。如果未提供,则使用当前选择。

    • 默认值: editor.selection

Returns

Collapse all

    根列表元素entry。

getListTypes

返回编辑器支持的列表类型数组。

Parameters

Collapse all

    编辑器实例。

Returns

Collapse all

    列表类型。

hasListChild

检查节点是否有列表子节点。

Parameters

Collapse all

    编辑器实例。

    要检查的节点。

Returns

Collapse all

    如果节点有列表子节点则返回 true,否则返回 false

indentListItems

缩进编辑器中的列表项。

Parameters

Collapse all

    编辑器实例。

insertListItem

如果选择在 li>p 元素中,则插入列表项。

Parameters

Collapse all

    编辑器实例。

Returns

Collapse all

    如果列表项被缩进则返回 true,否则返回 false

insertTodoListItem

如果选择在 li>p 元素中,则插入待办事项列表项。

Parameters

Collapse all

    编辑器实例。

Returns

Collapse all

    如果列表项被缩进则返回 true,否则返回 false

isAcrossListItems

检查选择是否跨越包含列表项的块。

Parameters

Collapse all

    编辑器实例。

Returns

Collapse all

    如果选择跨越包含列表项的块则返回 true,否则返回 false

isListNested

检查列表是否嵌套,即其父节点是否为列表项。

Parameters

Collapse all

    编辑器实例。

    列表的路径。

Returns

Collapse all

    如果列表是嵌套的则返回 true,否则返回 false

isListRoot

检查节点是否为列表的根。

Parameters

Collapse all

    编辑器实例。

    要检查的节点。

Returns

Collapse all

    如果节点是列表的根则返回 true,否则返回 false

moveListItemDown

将列表项向下移动到下一个列表项。

Parameters

Collapse all

    编辑器实例。

Returns

Collapse all

    如果列表项被移动则返回 true,否则返回 false

moveListItemSublistItemsToListItemSublist

将子列表项从一个列表项移动到另一个列表项的子列表。

Parameters

Collapse all

    编辑器实例。

Returns

Collapse all

    移动的子列表项数量。

moveListItemUp

向上移动列表项。

Parameters

Collapse all

    编辑器实例。

Returns

Collapse all

    如果列表项被移动则返回 true,否则返回 false

moveListItems

在各自的列表中上下移动选定的列表项或增加/减少其缩进级别。

Parameters

Collapse all

    编辑器实例。

Returns

Collapse all

    如果列表项被移动则返回 true,否则返回 false

moveListItemsToList

将列表项从子列表或列表移动到另一个列表。

Parameters

Collapse all

    编辑器实例。

Returns

Collapse all

    如果列表项被移动则返回 true,否则返回 false

moveListSiblingsAfterCursor

将光标位置后的列表同级项移动到指定路径。

Parameters

Collapse all

    编辑器实例。

Returns

Collapse all

    移动的列表同级项数量。

removeFirstListItem

如果列表未嵌套且列表项不是第一个子项,则删除第一个列表项。

Parameters

Collapse all

    编辑器实例。

Returns

Collapse all

    如果列表项被删除则返回 true,否则返回 false

removeListItem

删除列表项并将其子列表(如果有)移动到父列表。

Parameters

Collapse all

    编辑器实例。

Returns

Collapse all

    如果列表项被删除则返回 true,否则返回 false

someList

检查当前选择是否在特定类型的列表内。

Parameters

Collapse all

    编辑器实例。

    要检查的列表类型。

Returns

Collapse all

    如果选择在指定类型的列表内则返回 true,否则返回 false

unindentListItems

减少编辑器中列表项的缩进级别。

Parameters

Collapse all

    编辑器实例。

    要取消缩进列表项的目标路径。如果未提供,将在当前选择处取消缩进列表项。

unwrapList

从选定的列表项或指定路径的列表项中移除列表格式。

Parameters

Collapse all

    编辑器实例。

API 组件

useListToolbarButton

列表工具栏按钮的行为钩子。

State

Collapse all

    按钮的按下状态。

    列表的节点类型。

    • 默认值: BulletedListPlugin.key

Returns

Collapse all

API 待办事项列表

getTodoListItemEntry

返回给定路径(默认 = selection)在待办事项列表中的最近列表和列表项节点entry。

Parameters

Collapse all

    编辑器实例。

Returns

    • 如果在给定位置找到列表项,则返回包含 listlistItem 节点entry的对象。

    • 如果未找到列表项,则返回 undefined

useTodoListElement

待办事项列表项元素的行为钩子。

State

Collapse all

    待办事项列表项的勾选状态。

    待办事项列表项是否为只读。

    待办事项列表项元素。

    编辑器实例。

Returns

Collapse all