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'
- 包含以下元素插件:
BulletedListPlugin
NumberedListPlugin
ListItemPlugin
ListItemContentPlugin
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
待办事项列表项的勾选状态。
待办事项列表项是否为只读。
待办事项列表项元素。
编辑器实例。