经典列表

PreviousNext
列表节点列表工具栏按钮
Files
components/list-classic-demo.tsx
'use client';

import * as React from 'react';

import { Plate, usePlateEditor } from 'platejs/react';

import { EditorKit } from '@/components/editor/editor-kit';
import { AutoformatKit } from '@/components/editor/plugins/autoformat-classic-kit';
import { FixedToolbarKit } from '@/components/editor/plugins/fixed-toolbar-classic-kit';
import { FloatingToolbarKit } from '@/components/editor/plugins/floating-toolbar-classic-kit';
import { ListKit } from '@/components/editor/plugins/list-classic-kit';
import { listValue } from '@/registry/examples/values/list-classic-value';
import { Editor, EditorContainer } from '@/components/ui/editor';

export default function ListClassicDemo() {
  const editor = usePlateEditor({
    // Disable EditorKit's indent and list plugins
    override: {
      enabled: {
        indent: false,
        list: false,
      },
    },
    plugins: [
      ...EditorKit,
      ...ListKit,
      ...FixedToolbarKit,
      ...FloatingToolbarKit,
      ...AutoformatKit,
    ],
    value: listValue,
  });

  return (
    <Plate editor={editor}>
      <EditorContainer variant="demo">
        <Editor />
      </EditorContainer>
    </Plate>
  );
}
List creation and formatting.
list-classic-demo
list-classic-demo

选择您的列表插件

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

  1. 此经典列表插件 - 具有严格嵌套规则的传统 HTML 规范列表：

    • 遵循标准 HTML 列表结构（ul/ol > li）
    • 保持一致的列表层次结构
    • 最适合可能导出为 HTML/markdown 的内容
    • 复杂度最高

  2. 列表插件 - 灵活的基于缩进的列表：

    • 更像 Word/Google Docs 的行为
    • 任何块都可以缩进以创建类似列表的结构
    • 在 AI 编辑器 中使用
    • 支持嵌套待办事项列表
    • 更适合自由形式的内容组织

根据您的需求选择：

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

功能

  • 符合 HTML 的列表：

    • 标准 ul/ol > li 结构
    • 正确的嵌套和层次结构
    • SEO 友好的标记
    • 干净的 HTML/markdown 导出

  • 列表类型：

    • 无序（项目符号）列表
    • 有序（编号）列表
    • 带复选框的任务列表
    • 嵌套子列表

  • 拖放：

    • 目前仅支持根级列表项
    • 同级和嵌套项拖放尚未支持

  • 快捷键：

    • 结合自动格式化插件，使用 markdown 快捷键（-、*、1.、[ ]）创建列表
    • Tab/Shift+Tab 用于缩进控制

  • 限制（使用 列表插件 获取这些功能）：

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

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

套件使用

安装

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

'use client';

import {
  BulletedListPlugin,
  ListItemPlugin,
  ListPlugin,
  NumberedListPlugin,
  TaskListPlugin,
} from '@platejs/list-classic/react';

import {
  BulletedListElement,
  ListItemElement,
  NumberedListElement,
  TaskListElement,
} from '@/components/ui/list-classic-node';

export const ListKit = [
  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.withComponent(ListItemElement),
];

添加套件

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

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,
  ],
});

添加工具栏按钮

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

转换为工具栏按钮

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

插入工具栏按钮

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

插件

ListPlugin

包含以下元素插件：

  • BulletedListPlugin
  • NumberedListPlugin
  • TaskListPlugin
  • ListItemPlugin
  • ListItemContentPlugin

Optionsobject

Collapse all

    列表项的有效子节点类型（除了 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

Collapse all

    列表项的路径。

    不同列表的路径。

ReturnsPath | undefined

Collapse all

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

getListItemEntry

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

Optionsobject

Collapse all

    获取条目的位置。

    • 默认： editor.selection

ReturnsElementEntry | undefined

Collapse all

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

getListRoot

向上搜索根列表元素。

Parameters

Collapse all

    开始搜索的位置。

    • 默认： editor.selection

ReturnsElementEntry | undefined

Collapse all

    根列表元素条目。

getListTypes

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

Returnsstring[]

Collapse all

    支持的列表类型数组。

getTaskListProps

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

Parameters

Collapse all

    要检查的列表类型。

    任务列表选项。

Returnsobject | undefined

Collapse all

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

moveListSiblingsAfterCursor

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

Optionsoptions

Collapse all

    光标位置路径。

    目标路径。

Returnsnumber

Collapse all

    移动的兄弟项数量。

removeFirstListItem

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

Optionsoptions

Collapse all

    包含项的列表条目。

    要删除的列表项。

Returnsboolean

Collapse all

    项是否被删除。

removeListItem

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

OptionsRemoveListItemOptions

Collapse all

    包含项的列表条目。

    要删除的列表项。

    是否反转子列表项。

    • 默认： true

Returnsboolean

Collapse all

    项是否被删除。

someList

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

Parameters

Collapse all

    要检查的列表类型。

Returnsboolean

Collapse all

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

unindentListItems

减少列表项的缩进级别。

OptionsUnindentListItemsOptions

Collapse all

    取消缩进的目标路径。

unwrapList

移除选中项的列表格式。

Optionsoptions

Collapse all

    取消包装的目标路径。

Hooks

useListToolbarButton

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

State

Collapse all

    按钮按下状态。

    列表节点类型。

    • 默认： BulletedListPlugin.key

Returnsobject

Collapse all

    工具栏按钮的属性。

useTodoListElementState

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

State

Collapse all

    任务列表项元素。

Returnsobject

Collapse all

    任务项是否被选中。

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

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

useTodoListElement

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

State

Collapse all

    任务项是否被选中。

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

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

Returnsobject

Collapse all

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

LinkList Classic