表格

PreviousNext
表格工具栏按钮表格节点
Files
components/demo.tsx
'use client';

import * as React from 'react';

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

import { EditorKit } from '@/components/editor/editor-kit';
import { Editor, EditorContainer } from '@/components/ui/editor';

import { DEMO_VALUES } from './values/demo-values';

export default function Demo({ id }: { id: string }) {
  const editor = usePlateEditor({
    plugins: EditorKit,
    value: DEMO_VALUES[id],
  });

  return (
    <Plate editor={editor}>
      <EditorContainer variant="demo">
        <Editor />
      </EditorContainer>
    </Plate>
  );
}
Customizable tables with resizable columns and row merging options.
table-demo
table-demo

功能特性

  • 支持创建和编辑具有高级行为的表格
  • 箭头键导航（上/下）
  • 网格单元格选择
  • 使用 Shift+箭头键 扩展单元格选择范围
  • 单元格复制粘贴功能
  • 行拖拽重新排序
  • 通过拖拽手柄选择整行

套件使用指南

安装

最快捷的表格功能集成方式是使用 TableKit，它包含预配置的 TablePlugin、TableRowPlugin、TableCellPlugin 和 TableCellHeaderPlugin 及其 Plate UI 组件。

'use client';

import {
  TableCellHeaderPlugin,
  TableCellPlugin,
  TablePlugin,
  TableRowPlugin,
} from '@platejs/table/react';

import {
  TableCellElement,
  TableCellHeaderElement,
  TableElement,
  TableRowElement,
} from '@/components/ui/table-node';

export const TableKit = [
  TablePlugin.withComponent(TableElement),
  TableRowPlugin.withComponent(TableRowElement),
  TableCellPlugin.withComponent(TableCellElement),
  TableCellHeaderPlugin.withComponent(TableCellHeaderElement),
];

添加套件

将套件添加到插件列表：

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

手动配置

安装

pnpm add @platejs/table

添加插件

在创建编辑器时将 TablePlugin 加入插件数组：

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

插件配置

使用自定义组件和选项配置表格插件：

import {
  TableCellHeaderPlugin,
  TableCellPlugin,
  TablePlugin,
  TableRowPlugin,
} from '@platejs/table/react';
import { createPlateEditor } from 'platejs/react';
import {
  TableCellElement,
  TableCellHeaderElement,
  TableElement,
  TableRowElement,
} from '@/components/ui/table-node';
 
const editor = createPlateEditor({
  plugins: [
    // ...其他插件
    TablePlugin.configure({
      node: { component: TableElement },
      options: {
        initialTableWidth: 600,
        disableMerge: false,
        minColumnWidth: 48,
      },
    }),
    TableRowPlugin.withComponent(TableRowElement),
    TableCellPlugin.withComponent(TableCellElement),
    TableCellHeaderPlugin.withComponent(TableCellHeaderElement),
  ],
});
  • node.component: 指定 TableElement 渲染表格容器
  • withComponent: 为表格行、单元格和表头单元格分配组件
  • options.initialTableWidth: 设置新建表格的初始宽度
  • options.disableMerge: 禁用单元格合并功能
  • options.minColumnWidth: 设置表格列的最小宽度

添加工具栏按钮

可以在工具栏中添加 TableToolbarButton 来插入表格。

插入工具栏按钮

将此条目添加到插入工具栏按钮以插入表格元素：

{
  icon: <TableIcon />,
  label: '表格',
  value: KEYS.table,
}

禁用合并示例

Files
components/table-nomerge-demo.tsx
'use client';

import * as React from 'react';

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

import { EditorKit } from '@/components/editor/editor-kit';
import { tableValue } from '@/registry/examples/values/table-value';
import { Editor, EditorContainer } from '@/components/ui/editor';

export default function TableNoMergeDemo() {
  const editor = usePlateEditor({
    plugins: [
      ...EditorKit,
      TablePlugin.configure({
        options: {
          disableMerge: true,
        },
      }),
    ],
    value: tableValue,
  });

  return (
    <Plate editor={editor}>
      <EditorContainer variant="demo">
        <Editor />
      </EditorContainer>
    </Plate>
  );
}
table-nomerge-demo
table-nomerge-demo

插件说明

TablePlugin

Options

Collapse all

    禁用单元格合并行为

    禁用插入单元格时的表格扩展

    禁用表格第一列的左侧调整手柄

    禁用当表格只有一列时取消设置第一列宽度。设置为 true 可在单列情况下调整表格宽度，保持 false 可实现全宽表格

    若定义此值，标准化器会将每个未定义的表格 colSizes 设置为该值除以列数（注意：暂不支持合并单元格）

    表格列的最小宽度

    • 默认值: 48

TableRowPlugin

表格行插件

TableCellPlugin

表格单元格插件

TableCellHeaderPlugin

表头单元格插件

API 参考

editor.api.create.table

Parameters

Collapse all

    扩展 GetEmptyRowNodeOptions

Options

Collapse all

    设为 true 表示表格包含表头行

    表格行数

    • 默认值: 0

    表格列数

Returns

Collapse all

    表格节点

editor.api.create.tableCell

创建表格的空单元格节点

Options

Collapse all

    设为 true 表示创建表头单元格

    行元素。若未指定 header，将根据行的子元素判断是否为表头单元格

    新单元格节点的子元素

    • 默认值: [editor.api.create.block()]

Returns

Collapse all

    单元格节点

editor.api.create.tableRow

创建具有指定列数的空行节点

Options

Collapse all

    设为 true 表示创建表头行

    行的列数

    • 默认值: 1

Returns

Collapse all

    行节点

editor.api.table.getCellBorders

获取表格单元格的边框样式，处理首行和首列单元格的特殊情况

Options

Collapse all

    要获取边框样式的表格单元格元素

    当单元格边框未定义时使用的默认边框样式

Returns

Collapse all

    包含以下属性的对象:

editor.api.table.getCellChildren

获取表格单元格的子元素

Parameters

Collapse all

    表格单元格元素

Returns

Collapse all

    表格单元格的子元素

editor.api.table.getCellSize

获取表格单元格的宽度和最小高度，考虑列跨度和列宽设置

Options

Collapse all

    要获取尺寸的表格单元格元素

    列宽数组。若未提供，将使用表格的覆盖列宽设置

Returns

Collapse all

    单元格总宽度（根据跨列数计算各列宽度之和）

    单元格最小高度（根据行的尺寸属性确定）

editor.api.table.getColSpan

获取表格单元格的列跨度

Parameters

Collapse all

    要获取列跨度的表格单元格元素

Returns

Collapse all

    单元格跨越的列数

    • 默认值: 1

editor.api.table.getRowSpan

获取表格单元格的行跨度

Parameters

Collapse all

    要获取行跨度的表格单元格元素

Returns

Collapse all

    单元格跨越的行数

    • 默认值: 1

getCellType

获取插件单元格类型

Returns

Collapse all

    编辑器表格单元格元素类型数组（td 和 th）

getNextTableCell

获取表格中的下一个单元格

Parameters

Collapse all

    当前单元格的 entry

    当前单元格的路径

    当前行的 entry

Returns

Collapse all

    下一行单元格的节点 entry，若当前行是最后一行则返回 undefined

getPreviousTableCell

获取表格中的上一个单元格

Parameters

Collapse all

    当前单元格的 entry

    当前单元格的路径

    当前行的 entry

Returns

Collapse all

    上一行单元格的节点 entry，若当前行是首行则返回 undefined

getTableColumnCount

获取表格列数

Parameters

Collapse all

    要获取列数的表格节点

Returns

Collapse all

    表格列数

getTableColumnIndex

获取单元格在表格中的列索引

Parameters

Collapse all

    要获取列索引的单元格节点

Returns

Collapse all

    单元格的列索引

getTableEntries

根据当前选区或指定位置获取表格、行和单元格的节点 entry

Options

Collapse all

    表格单元格所在位置

    • 默认值: editor.selection

Returns

Collapse all

    表格节点 entry

    行节点 entry

    单元格节点 entry

getTableGridAbove

根据指定格式（表格或单元格）获取锚点和焦点位置上方的子表格

Options

Collapse all

    要获取的子表格格式

    • 默认值: 'table'

Returns

Collapse all

    子表格 entry 数组

getTableGridByRange

获取指定范围内两个单元格路径之间的子表格

Options

Collapse all

    指定起始和结束单元格路径的范围

    输出格式

    • 默认值: 'table'

Returns

Collapse all

    子表格 entry 数组

getTableRowIndex

获取单元格在表格中的行索引

Parameters

Collapse all

    要获取行索引的单元格节点

Returns

Collapse all

    单元格的行索引

getTopTableCell

获取表格中当前单元格上方的单元格

Parameters

Collapse all

    当前单元格路径。若未提供，函数将在编辑器中搜索当前单元格

Returns

Collapse all

    单元格节点 entry

isTableBorderHidden

检查表格单元格或表格本身的指定方向边框是否隐藏

Parameters

Collapse all

    要检查的边框方向

Returns

Collapse all

    true 表示边框隐藏，false 表示可见

转换操作

tf.insert.table

在当前选区插入表格（若编辑器中无现有表格）。选中插入表格的起始位置。

Parameters

Collapse all

    扩展 GetEmptyRowNodeOptions

    插入表格节点的选项

tf.insert.tableColumn

在表格的当前选区或指定单元格路径处插入一列。

Options

Collapse all

    要插入列的单元格的确切路径。这会覆盖 fromCell 选项。

    如果为 true，则在当前列之前插入列，而不是之后。

    要从中插入列的单元格路径。

    如果为 true，则插入的列将被视为表头列。

    如果为 true，则插入后会自动选中该列。

tf.insert.tableRow

在表格的当前选区或指定行路径处插入一行。

Options

Collapse all

    要插入行的确切路径。传入表格路径可在表格末尾插入。这将覆盖 fromRow。

    如果为 true，则在当前行之前插入行，而不是之后。

    要从中插入新行的行路径。

    如果为 true，则插入的行将被视为表头行。

    如果为 true，则插入后会自动选中该行。

tf.remove.tableColumn

删除表格中包含选中单元格的列。

tf.remove.tableRow

删除表格中包含选中单元格的行。

tf.remove.table

删除整个表格。

tf.table.merge

将多个选中的单元格合并为一个。

合并后的单元格将：

  • 列跨度等于所选单元格跨越的列数
  • 行跨度等于所选单元格跨越的行数
  • 包含所有合并单元格的组合内容（仅非空单元格）
  • 继承第一个选中单元格的表头状态

tf.table.split

将合并的单元格拆分回单独的单元格。

拆分操作将：

  • 为每个跨越的列和行创建新单元格
  • 从原始合并单元格复制表头状态
  • 将原始单元格的内容放在第一个单元格中
  • 为剩余空间创建空单元格

tf.moveSelectionFromCell

在表格内按单元格单位移动选区。

Options

Collapse all

    要从中移动选区的位置。

    设置为 true 将选区移动到上方单元格，false 移动到下方单元格。

    要扩展单元格选区的边缘。

    设置为 true 仅从单个选中单元格移动选区。

tf.setBorderSize

设置表格单元格中指定边框的大小。

Parameters

Collapse all

    边框的大小。

    设置边框大小的选项。

Options

Collapse all

    要设置边框大小的单元格位置。

    要设置大小的边框方向。

    • 默认值: 'all'

tf.setTableColSize

设置表格中特定列的宽度。

Options

Collapse all

    要设置宽度的列索引。

    所需的列宽度。

    查找表格节点的其他选项。

tf.setTableMarginLeft

设置表格的左边距。

Options

Collapse all

    包含所需左边距值的对象。

    查找表格节点的其他选项。

tf.setTableRowSize

设置表格行的大小（高度）。

Options

Collapse all

    要设置大小的行索引。

    所需的行高度。

    查找表格节点的其他选项。

插件扩展

onKeyDownTable

处理表格的键盘事件。

Parameters

Collapse all

    Plate 插件。

Returns

Collapse all

    键盘处理程序返回类型。

withDeleteTable

防止删除表格中的单元格。

withGetFragmentTable

如果选区在表格内，它会获取选区上方的子表格作为片段。这在复制和粘贴表格单元格时很有用。

withInsertFragmentTable

如果插入表格：

  • 如果选区锚点上方的块是表格，则用插入的表格替换上方的每个单元格，直到超出边界。选中插入的单元格。
  • 如果锚点上方没有表格，检查选区是否在表格内。如果是，找到锚点位置的单元格并用插入的片段替换其子元素。

withInsertTextTable

如果选区已展开：

  • 检查选区是否在表格内。如果是，将选区折叠到焦点边缘。

withNormalizeTable

通过执行以下操作规范化表格结构：

  • 如果单元格子元素是文本，则将其包装在段落中。
  • 解包不是有效表格元素的节点。
  • 如果指定了初始列大小，则为表格设置初始列大小。

withSelectionTable

通过执行以下操作处理表格选区：

  • 当锚点在表格内且焦点在表格前后的块中时，调整选区的焦点。
  • 当焦点在表格内且锚点在表格前后的块中时，调整选区的焦点。
  • 如果前一个和新选区在不同的单元格中，则覆盖从单元格的选区。

withSetFragmentDataTable

通过执行以下操作处理复制或剪切表格数据时设置剪贴板数据：

  • 检查是否存在表格条目和选中的单元格条目。
  • 通过复制单元格内容而不是表格结构来处理单单元格复制或剪切操作。
  • 创建包含选中单元格内容的表格结构。
  • 将文本、HTML、CSV、TSV 和 Slate 片段数据设置到剪贴板。

withTable

通过应用以下高阶函数增强编辑器实例的表格相关功能：

  • withNormalizeTable：规范化表格结构和内容。
  • withDeleteTable：防止删除表格中的单元格。
  • withGetFragmentTable：处理复制或剪切表格单元格时获取片段数据。
  • withInsertFragmentTable：处理插入表格片段。
  • withInsertTextTable：处理在表格中插入文本。
  • withSelectionTable：处理调整表格内的选区。
  • withSetFragmentDataTable：处理复制或剪切表格数据时设置片段数据。

Hooks

useTableCellElementResizable

提供表格单元格元素调整大小功能的 hook。

OptionsTableCellElementResizableOptions

Collapse all

    列索引。

    此单元格跨越的列数。

    行索引。

    按步长而不是像素调整大小。

    水平调整大小的步长。

    垂直调整大小的步长。

    • 默认值: step

Returns

Collapse all

    底部调整大小手柄的属性，包括调整方向和处理器。

    是否应该隐藏左侧调整大小手柄。如果不是第一列或左边距被禁用则为 true。

    左侧调整大小手柄的属性，包括调整方向和处理器。

    右侧调整大小手柄的属性，包括调整方向、初始大小和处理器。

useTableStore

表格存储存储表格插件的状态。

Attributes

Collapse all

    列大小覆盖。

    行大小覆盖。

    左边距覆盖。

    选中的单元格。

    选中的表格。

useIsCellSelected

检查表格单元格是否被选中的自定义 hook。

Parameters

Collapse all

    要检查的表格单元格元素。

useSelectedCells

管理表格中单元格选择的 hook。

它跟踪当前选中的单元格，并根据编辑器选择的变化更新它们。

useTableBordersDropdownMenuContentState

表格边框下拉菜单内容的状态 hook。

Returns

Collapse all

    一个具有以下属性的对象：

    指示选中的表格单元格是否有底部边框。

    指示选中的表格单元格是否有顶部边框。

    指示选中的表格单元格是否有左侧边框。

    指示选中的表格单元格是否有右侧边框。

    指示选中的表格单元格是否没有边框。

    指示选中的表格单元格是否有外部边框（即所有边都有边框）。

    返回特定边框类型的 onSelectTableBorder 处理程序的工厂函数。

    • onSelectTableBorder 处理程序负责为选中的表格单元格设置边框样式。

useTableColSizes

返回应用了覆盖的表格列大小的自定义 hook。如果表格的 colCount 更新为 1 且启用了 enableUnsetSingleColSize 选项，它将取消设置 colSizes 节点。

Options

Collapse all

    如果为 true，则禁用对列大小应用覆盖。

    • 默认值： false

Returns

Collapse all

    应用了覆盖的表格列大小。

useTableElement

处理单元格选择和左边距计算的表格元素 hook。

Returns

Collapse all

    是否正在选择单元格。

    表格的左边距，考虑覆盖和插件选项。

    表格元素的属性：

useTableCellElement

为表格单元格提供状态和功能的表格单元格元素 hook。

Returns

Collapse all

    表格单元格的边框样式。

    结束列索引（考虑 colSpan）。

    此单元格跨越的列数。

    是否正在选择单元格。

    单元格的最小高度。

    结束行索引（考虑 rowSpan）。

    此单元格当前是否被选中。

    单元格的宽度。

useTableCellBorders

返回表格单元格边框样式的 hook。

Returns

Collapse all

    包含单元格边框样式的对象：

useTableCellSize

返回表格单元格大小（宽度和最小高度）的 hook。

Returns

Collapse all

    包含以下内容的对象：

MentionTable