List
Organize nestable items in a bulleted or numbered list.
'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 控制缩进
- 结合自动格式化插件,使用 markdown 快捷方式(
-
限制(使用 缩进列表 可获得这些功能):
- 拖放功能仅支持根级别列表
- 列表项无法对齐
如需更灵活的、类似 Word 的使用方式,请参见 缩进列表插件。
安装
npm install @udecode/plate-list使用
import { ListPlugin } from '@udecode/plate-list/react';
const plugins = [
// ...otherPlugins,
ListPlugin,
];快捷键
| Key | Description |
|---|---|
| Cmd + Opt + 4 | 插入有序列表。 |
| Cmd + Shift + 4 | 插入有序列表。 |
插件
ListPlugin
key: 'list'- 包含以下元素插件:
BulletedListPluginNumberedListPluginListItemPluginListItemContentPlugin
Options
指定列表项除了 p 和 ul 类型外的有效子节点类型。
决定按下 Shift+Tab 是否重置列表缩进级别。
BulletedListPlugin
无序(项目符号)列表的插件。
NumberedListPlugin
有序(编号)列表的插件。
ListItemPlugin
列表项的插件。
ListItemContentPlugin
列表项内容的插件。
API
editor.tf.toggle.list
在编辑器中切换列表。
Parameters
getHighestEmptyList
查找可以删除的最高级空列表。列表路径应与 diffListPath 不同。如果最高级空列表有 2 个或更多项目,则返回 liPath。它会向上遍历父列表直到:
- 列表项少于 2 个。
- 其路径不等于
diffListPath。
Parameters
编辑器实例。
Returns
可以删除的最高级空列表的路径。
getListItemEntry
返回给定路径(默认 = selection)的最近的 li 和 ul/ol 包装节点entry。
Parameters
编辑器实例。
Returns
最近的 li 和 ul/ol 包装节点entry。
getListRoot
向上搜索根列表元素。
Parameters
- 默认值:
editor.selection
编辑器实例。
开始搜索的位置。如果未提供,则使用当前选择。
Returns
根列表元素entry。
getListTypes
返回编辑器支持的列表类型数组。
Parameters
编辑器实例。
Returns
hasListChild
检查节点是否有列表子节点。
Parameters
编辑器实例。
要检查的节点。
Returns
如果节点有列表子节点则返回 true,否则返回 false。
indentListItems
缩进编辑器中的列表项。
Parameters
编辑器实例。
insertListItem
如果选择在 li>p 元素中,则插入列表项。
Parameters
编辑器实例。
Returns
如果列表项被缩进则返回 true,否则返回 false。
insertTodoListItem
如果选择在 li>p 元素中,则插入待办事项列表项。
Parameters
编辑器实例。
Returns
如果列表项被缩进则返回 true,否则返回 false。
isAcrossListItems
检查选择是否跨越包含列表项的块。
Parameters
编辑器实例。
Returns
如果选择跨越包含列表项的块则返回 true,否则返回 false。
isListNested
检查列表是否嵌套,即其父节点是否为列表项。
Parameters
编辑器实例。
列表的路径。
Returns
如果列表是嵌套的则返回 true,否则返回 false。
isListRoot
检查节点是否为列表的根。
Parameters
编辑器实例。
要检查的节点。
Returns
如果节点是列表的根则返回 true,否则返回 false。
moveListItemDown
将列表项向下移动到下一个列表项。
Parameters
编辑器实例。
Returns
如果列表项被移动则返回 true,否则返回 false。
moveListItemSublistItemsToListItemSublist
将子列表项从一个列表项移动到另一个列表项的子列表。
Parameters
编辑器实例。
Returns
moveListItemUp
向上移动列表项。
Parameters
编辑器实例。
Returns
如果列表项被移动则返回 true,否则返回 false。
moveListItems
在各自的列表中上下移动选定的列表项或增加/减少其缩进级别。
Parameters
编辑器实例。
Returns
如果列表项被移动则返回 true,否则返回 false。
moveListItemsToList
将列表项从子列表或列表移动到另一个列表。
Parameters
编辑器实例。
Returns
如果列表项被移动则返回 true,否则返回 false。
moveListSiblingsAfterCursor
将光标位置后的列表同级项移动到指定路径。
Parameters
编辑器实例。
Returns
removeFirstListItem
如果列表未嵌套且列表项不是第一个子项,则删除第一个列表项。
Parameters
编辑器实例。
Returns
如果列表项被删除则返回 true,否则返回 false。
removeListItem
删除列表项并将其子列表(如果有)移动到父列表。
Parameters
编辑器实例。
Returns
如果列表项被删除则返回 true,否则返回 false。
someList
检查当前选择是否在特定类型的列表内。
Parameters
编辑器实例。
要检查的列表类型。
Returns
如果选择在指定类型的列表内则返回 true,否则返回 false。
unindentListItems
减少编辑器中列表项的缩进级别。
Parameters
编辑器实例。
要取消缩进列表项的目标路径。如果未提供,将在当前选择处取消缩进列表项。
unwrapList
从选定的列表项或指定路径的列表项中移除列表格式。
Parameters
编辑器实例。
API 组件
useListToolbarButton
列表工具栏按钮的行为钩子。
State
- 默认值:
BulletedListPlugin.key
按钮的按下状态。
列表的节点类型。
Returns
API 待办事项列表
getTodoListItemEntry
返回给定路径(默认 = selection)在待办事项列表中的最近列表和列表项节点entry。
Parameters
编辑器实例。
Returns
-
如果在给定位置找到列表项,则返回包含
list和listItem节点entry的对象。 -
如果未找到列表项,则返回
undefined。
useTodoListElement
待办事项列表项元素的行为钩子。
State
待办事项列表项的勾选状态。
待办事项列表项是否为只读。
待办事项列表项元素。
编辑器实例。