经典列表

列表节点列表工具栏按钮

选择您的列表插件

Plate 提供两种实现列表的方法：

此经典列表插件 - 具有严格嵌套规则的传统 HTML 规范列表：
- 遵循标准 HTML 列表结构（ul/ol > li）
- 保持一致的列表层次结构
- 最适合可能导出为 HTML/markdown 的内容
- 复杂度最高
列表插件 - 灵活的基于缩进的列表：
- 更像 Word/Google Docs 的行为
- 任何块都可以缩进以创建类似列表的结构
- 在 AI 编辑器中使用
- 支持嵌套待办事项列表
- 更适合自由形式的内容组织

根据您的需求选择：

当您需要标准 HTML 列表兼容性时，使用经典列表插件
当您想要更灵活的缩进行为时，使用列表插件

功能

符合 HTML 的列表：
- 标准 ul/ol > li 结构
- 正确的嵌套和层次结构
- SEO 友好的标记
- 干净的 HTML/markdown 导出
列表类型：
- 无序（项目符号）列表
- 有序（编号）列表
- 带复选框的任务列表
- 嵌套子列表
拖放：
- 目前仅支持根级列表项
- 同级和嵌套项拖放尚未支持
快捷键：
- 结合自动格式化插件，使用 markdown 快捷键（-、*、1.、[ ]）创建列表
- Tab/Shift+Tab 用于缩进控制
限制（使用列表插件获取这些功能）：
- 拖放仅支持根级列表
- 列表项无法对齐

对于更灵活的、类似 Word 的方法，请参阅列表插件。

套件使用

安装

添加列表功能的最快方法是使用 ListKit，它包含预配置的列表插件，带有 Plate UI 组件和键盘快捷键。

BulletedListElement：渲染无序列表元素。
NumberedListElement：渲染有序列表元素。
TaskListElement：渲染带复选框的任务列表元素。

添加套件

将套件添加到您的插件中：

import { createPlateEditor } from 'platejs/react';
import { ListKit } from '@/components/editor/plugins/list-classic-kit';
 
const editor = createPlateEditor({
  plugins: [
    // ...其他插件,
    ...ListKit,
  ],
});

手动使用

安装


pnpm add @platejs/list-classic

添加插件

在创建编辑器时，将列表插件包含在您的 Plate 插件数组中。

import { ListPlugin, BulletedListPlugin, NumberedListPlugin, TaskListPlugin, ListItemPlugin } from '@platejs/list-classic/react';
import { createPlateEditor } from 'platejs/react';
 
const editor = createPlateEditor({
  plugins: [
    // ...其他插件,
    ListPlugin,
    BulletedListPlugin,
    NumberedListPlugin,
    TaskListPlugin,
    ListItemPlugin,
  ],
});

配置插件

使用自定义组件和键盘快捷键配置插件。

import { ListPlugin, BulletedListPlugin, NumberedListPlugin, TaskListPlugin, ListItemPlugin } from '@platejs/list-classic/react';
import { createPlateEditor } from 'platejs/react';
import { BulletedListElement, NumberedListElement, TaskListElement } from '@/components/ui/list-classic-node';
 
const editor = createPlateEditor({
  plugins: [
    // ...其他插件,
    ListPlugin,
    BulletedListPlugin.configure({
      node: { component: BulletedListElement },
      shortcuts: { toggle: { keys: 'mod+alt+5' } },
    }),
    NumberedListPlugin.configure({
      node: { component: NumberedListElement },
      shortcuts: { toggle: { keys: 'mod+alt+6' } },
    }),
    TaskListPlugin.configure({
      node: { component: TaskListElement },
      shortcuts: { toggle: { keys: 'mod+alt+7' } },
    }),
    ListItemPlugin,
  ],
});

node.component：分配 BulletedListElement、NumberedListElement 和 TaskListElement 来渲染列表元素。
shortcuts.toggle：定义键盘快捷键来切换列表类型（mod+alt+5 用于项目符号，mod+alt+6 用于编号，mod+alt+7 用于任务列表）。

添加工具栏按钮

您可以将 ListToolbarButton 添加到您的工具栏中以创建和管理列表。

转换为工具栏按钮

使用 ListPlugin 时，请使用 turn-into-toolbar-classic-button，它包含所有列表类型（项目符号、编号和任务列表）。

插入工具栏按钮

使用 ListPlugin 时，请使用 insert-toolbar-classic-button，它包含所有列表类型（项目符号、编号和任务列表）。

插件

`ListPlugin`

包含以下元素插件：

BulletedListPlugin
NumberedListPlugin
TaskListPlugin
ListItemPlugin
ListItemContentPlugin

Optionsobject

validLiChildrenTypes optional string[]
列表项的有效子节点类型（除了 p 和 ul）。
enableResetOnShiftTab optional boolean
是否应该用 Shift+Tab 重置列表缩进级别。
inheritCheckStateOnLineEndBreak optional boolean
是否在行尾插入换行符后继承上方节点的选中状态。仅适用于任务列表。
- 默认： false
inheritCheckStateOnLineStartBreak optional boolean
是否在行首插入换行符后继承下方节点的选中状态。仅适用于任务列表。
- 默认： false

`BulletedListPlugin`

用于无序（项目符号）列表的插件。

`NumberedListPlugin`

用于有序（编号）列表的插件。

`TaskListPlugin`

用于带复选框的任务列表的插件。

`ListItemPlugin`

用于列表项的插件。

`ListItemContentPlugin`

用于列表项内容的插件。

转换

`tf.ul.toggle()`

切换项目符号列表（ul）。

示例快捷键：Mod+Alt+5

`tf.ol.toggle()`

切换编号列表（ol）。

示例快捷键：Mod+Alt+6

`tf.taskList.toggle()`

切换带复选框的任务列表。

示例快捷键：Mod+Alt+7

API

`getHighestEmptyList`

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

列表的项目少于 2 个
其路径不等于 diffListPath

Optionsobject

Collapse all

liPath Path

列表项的路径。

diffListPath optional Path

不同列表的路径。

ReturnsPath | undefined

最高可删除端列表的路径。

`getListItemEntry`

返回给定路径的最近 li 和 ul/ol 包装节点条目（默认 = 选择）。

Optionsobject

Collapse all

at optional Location | null

获取条目的位置。

默认： editor.selection

ReturnsElementEntry | undefined

最近的 li 和 ul/ol 包装节点条目。

`getListRoot`

向上搜索根列表元素。

Parameters

Collapse all

at optional Path | TRange | Point | null

开始搜索的位置。

默认： editor.selection

ReturnsElementEntry | undefined

根列表元素条目。

`getListTypes`

获取支持的列表类型数组。

Returnsstring[]

支持的列表类型数组。

`getTaskListProps`

根据提供的类型返回任务列表项的属性。

Parameters

Collapse all

type string

要检查的列表类型。

options optional object

任务列表选项。

Returnsobject | undefined

如果类型是任务列表，则返回带有 checked 属性的对象，否则返回 undefined。

`moveListSiblingsAfterCursor`

将光标后的列表兄弟项移动到指定路径。

Optionsoptions

Collapse all

at Path

光标位置路径。

to Path

目标路径。

Returnsnumber

移动的兄弟项数量。

`removeFirstListItem`

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

Optionsoptions

Collapse all

list ElementEntry

包含项的列表条目。

listItem ElementEntry

要删除的列表项。

Returnsboolean

项是否被删除。

`removeListItem`

删除列表项，如果有子列表则移动到父级。

OptionsRemoveListItemOptions

Collapse all

list ElementEntry

包含项的列表条目。

listItem ElementEntry

要删除的列表项。

reverse optional boolean

是否反转子列表项。

默认： true

Returnsboolean

项是否被删除。

`someList`

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

Parameters

Collapse all

type string

要检查的列表类型。

Returnsboolean

选择是否在指定的列表类型中。

`unindentListItems`

减少列表项的缩进级别。

OptionsUnindentListItemsOptions

取消缩进的目标路径。

`unwrapList`

移除选中项的列表格式。

Optionsoptions

Collapse all

at optional Path

取消包装的目标路径。

Hooks

`useListToolbarButton`

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

State

Collapse all

pressed boolean

按钮按下状态。

nodeType string

列表节点类型。

默认： BulletedListPlugin.key

Returnsobject

Collapse all

props object

工具栏按钮的属性。

`useTodoListElementState`

管理任务列表项状态的钩子。

State

Collapse all

element TTodoListItemElement

任务列表项元素。

Returnsobject

Collapse all

checked boolean

任务项是否被选中。

readOnly boolean

编辑器是否处于只读模式。

onCheckedChange function

切换选中状态的处理函数。

`useTodoListElement`

获取任务列表项复选框属性的钩子。

State

Collapse all

checked boolean

任务项是否被选中。

readOnly boolean

编辑器是否处于只读模式。

onCheckedChange function

切换选中状态的处理函数。

Returnsobject

Collapse all

checkboxProps object

要扩展到复选框组件的属性。

Link List Classic

经典列表

功能

套件使用

安装

添加套件

手动使用

安装

添加插件

配置插件

添加工具栏按钮

转换为工具栏按钮

插入工具栏按钮

插件

ListPlugin

Optionsobject

validLiChildrenTypes optional string[]

enableResetOnShiftTab optional boolean

inheritCheckStateOnLineEndBreak optional boolean

inheritCheckStateOnLineStartBreak optional boolean

BulletedListPlugin

NumberedListPlugin

TaskListPlugin

ListItemPlugin

ListItemContentPlugin

转换

tf.ul.toggle()

tf.ol.toggle()

tf.taskList.toggle()

API

getHighestEmptyList

Optionsobject

liPath Path

diffListPath optional Path

ReturnsPath | undefined

getListItemEntry

Optionsobject

at optional Location | null

ReturnsElementEntry | undefined

getListRoot

Parameters

at optional Path | TRange | Point | null

ReturnsElementEntry | undefined

getListTypes

Returnsstring[]

getTaskListProps

Parameters

type string

options optional object

Show child attributes

Returnsobject | undefined

moveListSiblingsAfterCursor

Optionsoptions

at Path

to Path

Returnsnumber

removeFirstListItem

Optionsoptions

list ElementEntry

listItem ElementEntry

Returnsboolean

removeListItem

OptionsRemoveListItemOptions

list ElementEntry

listItem ElementEntry

reverse optional boolean

Returnsboolean

someList

Parameters

type string

Returnsboolean

unindentListItems

OptionsUnindentListItemsOptions

unwrapList

Optionsoptions

at optional Path

Hooks

useListToolbarButton

State

pressed boolean

nodeType string

`ListPlugin`

`BulletedListPlugin`

`NumberedListPlugin`

`TaskListPlugin`

`ListItemPlugin`

`ListItemContentPlugin`

`tf.ul.toggle()`

`tf.ol.toggle()`

`tf.taskList.toggle()`

`getHighestEmptyList`

`getListItemEntry`

`getListRoot`

`getListTypes`

`getTaskListProps`

`moveListSiblingsAfterCursor`

`removeFirstListItem`

`removeListItem`

`someList`

`unindentListItems`

`unwrapList`

`useListToolbarButton`

`useTodoListElementState`

`useTodoListElement`