经典列表

Organize nestable items in a bulleted or numbered list.

列表节点列表工具栏按钮

Loading…

选择您的列表插件

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

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

根据您的需求选择：

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

功能

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

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

套件使用

安装

添加列表功能的最快方法是使用 list-classic-kit 中导出的 ListKit，它包含预配置的列表插件、classic markdown entry rules、Plate UI 组件和键盘快捷键。

'use client';
 
import {
  BulletedListRules,
  OrderedListRules,
  TaskListRules,
} from '@platejs/list-classic';
import {
  BulletedListPlugin,
  ListItemContentPlugin,
  ListItemPlugin,
  ListPlugin,
  NumberedListPlugin,
  TaskListPlugin,
} from '@platejs/list-classic/react';
 
import {
  BulletedListElement,
  ListItemElement,
  NumberedListElement,
  TaskListElement,
} from '@/components/ui/list-classic-node';
 
export const ListKit = [
  ListPlugin.configure({
    inputRules: [
      BulletedListRules.markdown({ variant: '-' }),
      BulletedListRules.markdown({ variant: '*' }),
      OrderedListRules.markdown({ variant: '.' }),
      OrderedListRules.markdown({ variant: ')' }),
      TaskListRules.markdown({ checked: false }),
      TaskListRules.markdown({ checked: true }),
    ],
  }),
  ListItemPlugin,
  ListItemContentPlugin,
  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.withComponent(ListItemElement),
];

'use client';
 
import {
  BulletedListRules,
  OrderedListRules,
  TaskListRules,
} from '@platejs/list-classic';
import {
  BulletedListPlugin,
  ListItemContentPlugin,
  ListItemPlugin,
  ListPlugin,
  NumberedListPlugin,
  TaskListPlugin,
} from '@platejs/list-classic/react';
 
import {
  BulletedListElement,
  ListItemElement,
  NumberedListElement,
  TaskListElement,
} from '@/components/ui/list-classic-node';
 
export const ListKit = [
  ListPlugin.configure({
    inputRules: [
      BulletedListRules.markdown({ variant: '-' }),
      BulletedListRules.markdown({ variant: '*' }),
      OrderedListRules.markdown({ variant: '.' }),
      OrderedListRules.markdown({ variant: ')' }),
      TaskListRules.markdown({ checked: false }),
      TaskListRules.markdown({ checked: true }),
    ],
  }),
  ListItemPlugin,
  ListItemContentPlugin,
  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.withComponent(ListItemElement),
];

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

添加套件

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

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

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

内置的 ListKit 也会注册项目符号、编号和任务列表的 classic markdown entry rules。运行时模型请参阅 Plugin Input Rules。

手动使用

安装

pnpm add @platejs/list-classic

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';
 
const editor = createPlateEditor({
  plugins: [
    // ...其他插件,
    ListPlugin,
    BulletedListPlugin,
    NumberedListPlugin,
    TaskListPlugin,
    ListItemPlugin,
  ],
});

配置插件

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

import {
  BulletedListRules,
  OrderedListRules,
  TaskListRules,
} from '@platejs/list-classic';
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.configure({
      inputRules: [
        BulletedListRules.markdown({ variant: '-' }),
        BulletedListRules.markdown({ variant: '*' }),
        OrderedListRules.markdown({ variant: '.' }),
        OrderedListRules.markdown({ variant: ')' }),
        TaskListRules.markdown({ checked: false }),
        TaskListRules.markdown({ checked: true }),
      ],
    }),
    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,
  ],
});

import {
  BulletedListRules,
  OrderedListRules,
  TaskListRules,
} from '@platejs/list-classic';
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.configure({
      inputRules: [
        BulletedListRules.markdown({ variant: '-' }),
        BulletedListRules.markdown({ variant: '*' }),
        OrderedListRules.markdown({ variant: '.' }),
        OrderedListRules.markdown({ variant: ')' }),
        TaskListRules.markdown({ checked: false }),
        TaskListRules.markdown({ checked: true }),
      ],
    }),
    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,
  ],
});

inputRules：注册项目符号、编号和任务列表的 classic markdown entry rules。
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

列表项的有效子节点类型（除了 p 和 ul）。

是否应该用 Shift+Tab 重置列表缩进级别。

是否在行尾插入换行符后继承上方节点的选中状态。仅适用于任务列表。

默认： false

是否在行首插入换行符后继承下方节点的选中状态。仅适用于任务列表。

默认： 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

列表项的路径。

不同列表的路径。

ReturnsPath | undefined

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

`getListItemEntry`

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

Optionsobject

获取条目的位置。

默认： editor.selection

ReturnsElementEntry | undefined

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

`getListRoot`

向上搜索根列表元素。

Parameters

开始搜索的位置。

默认： editor.selection

ReturnsElementEntry | undefined

根列表元素条目。

`getListTypes`

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

Returnsstring[]

支持的列表类型数组。

`getTaskListProps`

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

Parameters

要检查的列表类型。

任务列表选项。

Returnsobject | undefined

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

`moveListSiblingsAfterCursor`

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

Optionsoptions

光标位置路径。

目标路径。

Returnsnumber

移动的兄弟项数量。

`removeFirstListItem`

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

Optionsoptions

包含项的列表条目。

要删除的列表项。

Returnsboolean

项是否被删除。

`removeListItem`

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

OptionsRemoveListItemOptions

包含项的列表条目。

要删除的列表项。

是否反转子列表项。

默认： true

Returnsboolean

项是否被删除。

`someList`

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

Parameters

要检查的列表类型。

Returnsboolean

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

`unindentListItems`

减少列表项的缩进级别。

OptionsUnindentListItemsOptions

取消缩进的目标路径。

`unwrapList`

移除选中项的列表格式。

Optionsoptions

取消包装的目标路径。

Hooks

`useListToolbarButton`

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

State

按钮按下状态。

列表节点类型。

默认： BulletedListPlugin.key

Returnsobject

工具栏按钮的属性。

`useTodoListElementState`

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

State

任务列表项元素。

Returnsobject

任务项是否被选中。

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

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

`useTodoListElement`

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

State

任务项是否被选中。

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

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

Returnsobject

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

Link Media

构建你的编辑器

生产就绪的 AI 模板和可重用的组件。

经典列表

功能

套件使用

安装

添加套件

手动使用

安装

添加插件

配置插件

添加工具栏按钮

转换为工具栏按钮

插入工具栏按钮

插件

ListPlugin

Optionsobject

validLiChildrenTypes optional string[]

validLiChildrenTypes optional string[]

enableResetOnShiftTab optional boolean

enableResetOnShiftTab optional boolean

inheritCheckStateOnLineEndBreak optional boolean

inheritCheckStateOnLineEndBreak optional boolean

inheritCheckStateOnLineStartBreak optional boolean

inheritCheckStateOnLineStartBreak optional boolean

BulletedListPlugin

NumberedListPlugin

TaskListPlugin

ListItemPlugin

ListItemContentPlugin

转换

tf.ul.toggle()

tf.ol.toggle()

tf.taskList.toggle()

API

getHighestEmptyList

Optionsobject

liPath Path

liPath Path

diffListPath optional Path

diffListPath optional Path

ReturnsPath | undefined

getListItemEntry

Optionsobject

at optional Location | null

at optional Location | null

ReturnsElementEntry | undefined

getListRoot

Parameters

at optional Path | TRange | Point | null

at optional Path | TRange | Point | null

ReturnsElementEntry | undefined

getListTypes

Returnsstring[]

getTaskListProps

Parameters

type string

type string

options optional object

options optional object

Show child attributes

Returnsobject | undefined

moveListSiblingsAfterCursor

Optionsoptions

at Path

at Path

to Path

to Path

Returnsnumber

removeFirstListItem

Optionsoptions

list ElementEntry

list ElementEntry

listItem ElementEntry

listItem ElementEntry

Returnsboolean

removeListItem

OptionsRemoveListItemOptions

list ElementEntry

list ElementEntry

listItem ElementEntry

listItem ElementEntry

`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`