列表

PreviousNext

Turn any block into a list item.

列表工具栏按钮
Loading…

特性

  • 灵活的块缩进：通过缩进将任何块类型（段落、标题等）转换为列表项。
  • 简化结构：扁平的DOM结构，每个缩进的块都是独立的，不同于List Classic插件。
  • 列表类型：支持项目符号列表（无序）和编号列表（有序）。
  • Markdown 快捷输入：通过注册列表 input rules，可使用 -、*、1.、[] 等触发方式创建列表。

有关底层缩进系统的更多信息，请参阅缩进插件。

套件使用

安装

添加列表功能的最快方式是使用ListKit，它包含预配置的ListPlugin、自带的列表 input rules，以及必需的缩进插件，针对段落、标题、引用块、代码块和折叠元素。

'use client';
 
import {
  BulletedListRules,
  isOrderedList,
  OrderedListRules,
  TaskListRules,
} from '@platejs/list';
import { ListPlugin } from '@platejs/list/react';
import { KEYS } from 'platejs';
 
import { IndentKit } from '@/components/editor/plugins/indent-kit';
import { BlockList } from '@/components/ui/block-list';
 
export const ListKit = [
  ...IndentKit,
  ListPlugin.configure({
    inputRules: [
      BulletedListRules.markdown({ variant: '-' }),
      BulletedListRules.markdown({ variant: '*' }),
      OrderedListRules.markdown({ variant: '.' }),
      OrderedListRules.markdown({ variant: ')' }),
      TaskListRules.markdown({ checked: false }),
      TaskListRules.markdown({ checked: true }),
    ],
    inject: {
      nodeProps: {
        nodeKey: KEYS.listType,
        query: ({ nodeProps }) => {
          const element = nodeProps.element;
 
          return !!element?.listStyleType && !isOrderedList(element);
        },
        transformProps: ({ props }) => ({
          ...props,
          role: 'listitem',
          style: {
            ...props.style,
            display: 'list-item',
          },
        }),
      },
      targetPlugins: [
        ...KEYS.heading,
        KEYS.p,
        KEYS.blockquote,
        KEYS.codeBlock,
        KEYS.toggle,
        KEYS.img,
      ],
    },
    render: {
      belowNodes: BlockList,
    },
  }),
];
'use client';
 
import {
  BulletedListRules,
  isOrderedList,
  OrderedListRules,
  TaskListRules,
} from '@platejs/list';
import { ListPlugin } from '@platejs/list/react';
import { KEYS } from 'platejs';
 
import { IndentKit } from '@/components/editor/plugins/indent-kit';
import { BlockList } from '@/components/ui/block-list';
 
export const ListKit = [
  ...IndentKit,
  ListPlugin.configure({
    inputRules: [
      BulletedListRules.markdown({ variant: '-' }),
      BulletedListRules.markdown({ variant: '*' }),
      OrderedListRules.markdown({ variant: '.' }),
      OrderedListRules.markdown({ variant: ')' }),
      TaskListRules.markdown({ checked: false }),
      TaskListRules.markdown({ checked: true }),
    ],
    inject: {
      nodeProps: {
        nodeKey: KEYS.listType,
        query: ({ nodeProps }) => {
          const element = nodeProps.element;
 
          return !!element?.listStyleType && !isOrderedList(element);
        },
        transformProps: ({ props }) => ({
          ...props,
          role: 'listitem',
          style: {
            ...props.style,
            display: 'list-item',
          },
        }),
      },
      targetPlugins: [
        ...KEYS.heading,
        KEYS.p,
        KEYS.blockquote,
        KEYS.codeBlock,
        KEYS.toggle,
        KEYS.img,
      ],
    },
    render: {
      belowNodes: BlockList,
    },
  }),
];
  • BlockList：渲染列表包装元素，支持待办事项列表。
  • 包含IndentKit用于底层缩进系统。
  • 配置Paragraph、Heading、Blockquote、CodeBlock和Toggle元素以支持列表功能。

添加套件

将套件添加到插件中：

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

添加工具栏按钮

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

转换为工具栏按钮

您可以将以下项添加到转换为工具栏按钮中，将块转换为列表：

{
  icon: <ListIcon />,
  label: '项目符号列表',
  value: KEYS.ul,
}
{
  icon: <ListIcon />,
  label: '项目符号列表',
  value: KEYS.ul,
}
{
  icon: <ListOrderedIcon />,
  label: '编号列表',
  value: KEYS.ol,
}
{
  icon: <ListOrderedIcon />,
  label: '编号列表',
  value: KEYS.ol,
}
{
  icon: <SquareIcon />,
  label: '待办列表',
  value: KEYS.listTodo,
}
{
  icon: <SquareIcon />,
  label: '待办列表',
  value: KEYS.listTodo,
}

手动使用

安装

pnpm add @platejs/list @platejs/indent
pnpm add @platejs/list @platejs/indent

添加插件

在创建编辑器时，将IndentPlugin和ListPlugin都包含在Plate插件数组中。列表插件依赖于缩进插件。

import { IndentPlugin } from '@platejs/indent/react';
import { ListPlugin } from '@platejs/list/react';
import { createPlateEditor } from 'platejs/react';
 
const editor = createPlateEditor({
  plugins: [
    // ...其他插件,
    IndentPlugin,
    ListPlugin,
  ],
});
import { IndentPlugin } from '@platejs/indent/react';
import { ListPlugin } from '@platejs/list/react';
import { createPlateEditor } from 'platejs/react';
 
const editor = createPlateEditor({
  plugins: [
    // ...其他插件,
    IndentPlugin,
    ListPlugin,
  ],
});

配置插件

您可以配置这两个插件以针对特定元素、自定义列表行为，并注册内置的 Markdown rules。

import { IndentPlugin } from '@platejs/indent/react';
import {
  BulletedListRules,
  OrderedListRules,
  TaskListRules,
} from '@platejs/list';
import { ListPlugin } from '@platejs/list/react';
import { KEYS } from 'platejs';
import { createPlateEditor } from 'platejs/react';
import { BlockList } from '@/components/ui/block-list';
 
const editor = createPlateEditor({
  plugins: [
    // ...其他插件,
    IndentPlugin.configure({
      inject: {
        targetPlugins: [...KEYS.heading, KEYS.p, KEYS.blockquote, KEYS.codeBlock],
      },
    }),
    ListPlugin.configure({
      inputRules: [
        BulletedListRules.markdown({ variant: '-' }),
        OrderedListRules.markdown({ variant: '.' }),
        TaskListRules.markdown({ checked: false }),
      ],
      inject: {
        targetPlugins: [...KEYS.heading, KEYS.p, KEYS.blockquote, KEYS.codeBlock],
      },
      render: {
        belowNodes: BlockList,
      },
    }),
  ],
});
import { IndentPlugin } from '@platejs/indent/react';
import {
  BulletedListRules,
  OrderedListRules,
  TaskListRules,
} from '@platejs/list';
import { ListPlugin } from '@platejs/list/react';
import { KEYS } from 'platejs';
import { createPlateEditor } from 'platejs/react';
import { BlockList } from '@/components/ui/block-list';
 
const editor = createPlateEditor({
  plugins: [
    // ...其他插件,
    IndentPlugin.configure({
      inject: {
        targetPlugins: [...KEYS.heading, KEYS.p, KEYS.blockquote, KEYS.codeBlock],
      },
    }),
    ListPlugin.configure({
      inputRules: [
        BulletedListRules.markdown({ variant: '-' }),
        OrderedListRules.markdown({ variant: '.' }),
        TaskListRules.markdown({ checked: false }),
      ],
      inject: {
        targetPlugins: [...KEYS.heading, KEYS.p, KEYS.blockquote, KEYS.codeBlock],
      },
      render: {
        belowNodes: BlockList,
      },
    }),
  ],
});
  • inject.targetPlugins：插件键的数组，指示哪些元素类型可以成为列表项。
  • inputRules：注册项目符号、编号和待办列表的 feature-owned Markdown 快捷输入。
  • render.belowNodes：分配BlockList以渲染列表包装元素。

完整运行时模型和其他变体请参阅 Plugin Input Rules。

插件

ListPlugin

用于创建和管理列表的插件。它与缩进插件配合使用，提供灵活的列表功能，任何块都可以通过缩进转换为列表项。

Options

    用于确定兄弟元素缩进列表选项的函数。

    将HTML元素映射到列表样式类型的函数。

API

getNextList

获取具有缩进列表的下一个兄弟entry。

Parameters

    当前元素的entry。

    获取下一个缩进列表的选项。

ReturnsNodeEntry | undefined

    具有缩进列表的下一个兄弟entry，如果未找到则为undefined。

getPreviousList

获取具有缩进列表的上一个兄弟entry。

Parameters

    当前元素的entry。

    获取上一个缩进列表的选项。

ReturnsNodeEntry | undefined

    具有缩进列表的上一个兄弟entry，如果未找到则为undefined。

indentList

增加所选块的缩进。

OptionsListOptions

    使用的列表样式类型。

    • 默认值: ListStyleType.Disc

outdentList

减少所选块的缩进。

OptionsListOptions

    使用的列表样式类型。

    • 默认值: ListStyleType.Disc

someList

检查所选块是否具有特定的列表样式类型。

Parameters

    要检查的列表样式类型。

toggleList

切换缩进列表。

OptionsListOptions

    使用的列表样式类型。

    覆盖列表项的编号。

    覆盖列表项的编号，仅在列表项是列表中的第一个时生效。

类型

GetSiblingListOptions

用于提供在文本块中获取兄弟缩进列表的选项。

Options

    此函数用于从给定entry获取上一个兄弟entry。

    此函数用于从给定entry获取下一个兄弟entry。

    此函数用于在查找过程中验证兄弟节点。 如果返回false，则检查下一个兄弟节点。

    指示当兄弟节点具有与当前节点相同的缩进级别时是否中断查找。如果为true，则在找到具有相同缩进级别的兄弟节点时停止查找。

    一个函数，接受TNode并返回布尔值或undefined。 此函数用于指定查找过程应停止的条件。

    指示当找到具有较低缩进级别的兄弟节点时是否中断查找。如果为true，则在找到具有较低缩进级别的兄弟节点时停止查找。

    指示当找到具有相同缩进级别但不同列表样式类型的兄弟节点时是否中断查找。如果为true，则在找到这样的兄弟节点时停止查找。

钩子

useListToolbarButton

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

State

    列表样式类型。

    按钮是否被按下。

Returnsobject

    工具栏按钮的属性。