表格

功能特性

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

套件使用指南

安装

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

TableElement: 渲染表格容器
TableRowElement: 渲染表格行
TableCellElement: 渲染表格单元格
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,
}

禁用合并示例

插件说明

TablePlugin

Options

disableMerge optional boolean
禁用单元格合并行为
disableExpandOnInsert optional boolean
禁用插入单元格时的表格扩展
disableMarginLeft optional boolean
禁用表格第一列的左侧调整手柄
enableUnsetSingleColSize optional boolean
禁用当表格只有一列时取消设置第一列宽度。设置为 true 可在单列情况下调整表格宽度，保持 false 可实现全宽表格
initialTableWidth optional number
若定义此值，标准化器会将每个未定义的表格 colSizes 设置为该值除以列数（注意：暂不支持合并单元格）
minColumnWidth optional number
表格列的最小宽度
- 默认值: 48

TableRowPlugin

表格行插件

TableCellPlugin

表格单元格插件

TableCellHeaderPlugin

表头单元格插件

API 参考

editor.api.create.table

Parameters

Collapse all

options optional GetEmptyTableNodeOptions

扩展 GetEmptyRowNodeOptions

Options

Collapse all

header optional boolean

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

rowCount optional number

表格行数

默认值: 0

colCount optional number | undefined

表格列数

Returns

Collapse all

TElement

表格节点

editor.api.create.tableCell

创建表格的空单元格节点

Options

Collapse all

header optional boolean

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

row optional TTableRowElement

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

children optional Descendant[]

新单元格节点的子元素

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

Returns

Collapse all

TElement

单元格节点

editor.api.create.tableRow

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

Options

Collapse all

header optional boolean

设为 true 表示创建表头行

colCount optional number

行的列数

默认值: 1

Returns

Collapse all

TElement

行节点

editor.api.table.getCellBorders

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

Options

Collapse all

element TTableCellElement

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

defaultBorder optional Required<TTableCellElementBorder>

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

Returns

Collapse all

BorderStylesDefault

包含以下属性的对象:

editor.api.table.getCellChildren

获取表格单元格的子元素

Parameters

Collapse all

cell TElement

表格单元格元素

Returns

Collapse all

Descendant[]

表格单元格的子元素

editor.api.table.getCellSize

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

Options

Collapse all

element TTableCellElement

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

colSizes optional number[]

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

Returns

Collapse all

width number

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

minHeight number | undefined

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

editor.api.table.getColSpan

获取表格单元格的列跨度

Parameters

Collapse all

element TTableCellElement

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

Returns

Collapse all

number

单元格跨越的列数

默认值: 1

editor.api.table.getRowSpan

获取表格单元格的行跨度

Parameters

Collapse all

element TTableCellElement

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

Returns

Collapse all

number

单元格跨越的行数

默认值: 1

getCellType

获取插件单元格类型

Returns

Collapse all

string[]

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

getNextTableCell

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

Parameters

Collapse all

currentCell NodeEntry

当前单元格的 entry

currentPath Path

当前单元格的路径

currentRow NodeEntry

当前行的 entry

Returns

Collapse all

NodeEntry | undefined

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

getPreviousTableCell

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

Parameters

Collapse all

currentCell NodeEntry

当前单元格的 entry

currentPath Path

当前单元格的路径

currentRow NodeEntry

当前行的 entry

Returns

Collapse all

NodeEntry | undefined

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

getTableColumnCount

获取表格列数

Parameters

Collapse all

tableNode TElement

要获取列数的表格节点

Returns

Collapse all

number

表格列数

getTableColumnIndex

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

Parameters

Collapse all

cellNode TElement

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

Returns

Collapse all

number

单元格的列索引

getTableEntries

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

Options

Collapse all

at optional Location | null

表格单元格所在位置

默认值: editor.selection

Returns

Collapse all

table NodeEntry | undefined

表格节点 entry

row NodeEntry | undefined

行节点 entry

cell NodeEntry | undefined

单元格节点 entry

getTableGridAbove

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

Options

Collapse all

format optional string

要获取的子表格格式

默认值: 'table'

Returns

Collapse all

ElementEntry[]

子表格 entry 数组

getTableGridByRange

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

Options

Collapse all

at TRange

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

format optional 'table' | 'cell'

输出格式

默认值: 'table'

Returns

Collapse all

ElementEntry[]

子表格 entry 数组

getTableRowIndex

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

Parameters

Collapse all

cellNode TElement

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

Returns

Collapse all

number

单元格的行索引

getTopTableCell

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

Parameters

Collapse all

at optional Path

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

Returns

Collapse all

ElementEntry | undefined

单元格节点 entry

isTableBorderHidden

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

Parameters

Collapse all

border 'top' | 'left' | 'bottom' | 'right'

要检查的边框方向

Returns

Collapse all

boolean

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

转换操作

`tf.insert.table`

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

Parameters

Collapse all

getEmptyTableNodeOptions optional GetEmptyTableNodeOptions

扩展 GetEmptyRowNodeOptions

options optional InsertNodesOptions

插入表格节点的选项

`tf.insert.tableColumn`

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

Options

Collapse all

at optional Path

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

before optional boolean

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

fromCell optional Path

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

header optional boolean

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

select optional boolean

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

`tf.insert.tableRow`

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

Options

Collapse all

at optional Path

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

before optional boolean

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

fromRow optional Path

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

header optional boolean

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

select optional boolean

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

`tf.remove.tableColumn`

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

`tf.remove.tableRow`

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

`tf.remove.table`

删除整个表格。

`tf.table.merge`

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

合并后的单元格将：

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

`tf.table.split`

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

拆分操作将：

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

`tf.moveSelectionFromCell`

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

Options

Collapse all

at optional Location

要从中移动选区的位置。

reverse optional boolean

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

edge optional 'top' | 'left' | 'right' | 'bottom'

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

fromOneCell optional boolean

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

`tf.setBorderSize`

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

Parameters

Collapse all

size number

边框的大小。

options optional object

设置边框大小的选项。

Options

Collapse all

at optional Location

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

border optional 'all' | 'top' | 'left' | 'bottom' | 'right'

要设置大小的边框方向。

默认值: 'all'

`tf.setTableColSize`

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

Options

Collapse all

colIndex optional number

要设置宽度的列索引。

width optional number

所需的列宽度。

getAboveNodeOptions optional EditorAboveOptions

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

`tf.setTableMarginLeft`

设置表格的左边距。

Options

Collapse all

marginLeft number

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

getAboveNodeOptions optional EditorAboveOptions

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

`tf.setTableRowSize`

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

Options

Collapse all

rowIndex number

要设置大小的行索引。

height number

所需的行高度。

getAboveNodeOptions optional EditorAboveOptions

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

插件扩展

`onKeyDownTable`

处理表格的键盘事件。

Parameters

Collapse all

plugin PlatePlugin

Plate 插件。

Returns

Collapse all

KeyboardHandlerReturnType

键盘处理程序返回类型。

`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

colIndex number

列索引。

colSpan number

此单元格跨越的列数。

rowIndex number

行索引。

step optional number

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

stepX optional number

水平调整大小的步长。

stepY optional number

垂直调整大小的步长。

默认值: step

Returns

Collapse all

bottomProps ResizeHandleProps

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

hiddenLeft boolean

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

leftProps ResizeHandleProps

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

rightProps ResizeHandleProps

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

`useTableStore`

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

Attributes

Collapse all

colSizeOverrides TableStoreSizeOverrides

列大小覆盖。

rowSizeOverrides TableStoreSizeOverrides

行大小覆盖。

marginLeftOverride number | null

左边距覆盖。

selectedCells TElement[] | null

选中的单元格。

selectedTables TElement[] | null

选中的表格。

`useIsCellSelected`

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

Parameters

Collapse all

element TElement

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

`useSelectedCells`

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

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

`useTableBordersDropdownMenuContentState`

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

Returns

Collapse all

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

hasBottomBorder boolean

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

hasTopBorder boolean

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

hasLeftBorder boolean

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

hasRightBorder boolean

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

hasNoBorders boolean

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

hasOuterBorders boolean

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

getOnSelectTableBorder function

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

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

`useTableColSizes`

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

Options

Collapse all

disableOverrides optional boolean

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

默认值： false

Returns

Collapse all

overriddenColSizes number[]

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

`useTableElement`

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

Returns

Collapse all

isSelectingCell boolean

是否正在选择单元格。

marginLeft number

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

props object

表格元素的属性：

`useTableCellElement`

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

Returns

Collapse all

borders BorderStylesDefault

表格单元格的边框样式。

colIndex number

结束列索引（考虑 colSpan）。

colSpan number

此单元格跨越的列数。

isSelectingCell boolean

是否正在选择单元格。

minHeight number | undefined

单元格的最小高度。

rowIndex number

结束行索引（考虑 rowSpan）。

selected boolean

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

width number | string

单元格的宽度。

`useTableCellBorders`

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

Returns

Collapse all

BorderStylesDefault

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

`useTableCellSize`

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

Returns

Collapse all

object

包含以下内容的对象：

Mention Table

On This Page

功能特性套件使用指南安装添加套件手动配置安装添加插件插件配置添加工具栏按钮插入工具栏按钮禁用合并示例插件说明 TablePlugin TableRowPlugin TableCellPlugin TableCellHeaderPlugin API 参考 editor.api.create.table editor.api.create.tableCell editor.api.create.tableRow editor.api.table.getCellBorders editor.api.table.getCellChildren editor.api.table.getCellSize editor.api.table.getColSpan editor.api.table.getRowSpan getCellType getNextTableCell getPreviousTableCell getTableColumnCount getTableColumnIndex getTableEntries getTableGridAbove getTableGridByRange getTableRowIndex getTopTableCell isTableBorderHidden 转换操作 tf.insert.tabletf.insert.tableColumntf.insert.tableRowtf.remove.tableColumntf.remove.tableRowtf.remove.tabletf.table.mergetf.table.splittf.moveSelectionFromCelltf.setBorderSizetf.setTableColSizetf.setTableMarginLefttf.setTableRowSize插件扩展 onKeyDownTablewithDeleteTablewithGetFragmentTablewithInsertFragmentTablewithInsertTextTablewithNormalizeTablewithSelectionTablewithSetFragmentDataTablewithTableHooks useTableCellElementResizableuseTableStoreuseIsCellSelecteduseSelectedCellsuseTableBordersDropdownMenuContentStateuseTableColSizesuseTableElementuseTableCellElementuseTableCellBordersuseTableCellSize

表格

功能特性

套件使用指南

安装

添加套件

手动配置

安装

添加插件

插件配置

添加工具栏按钮

插入工具栏按钮

禁用合并示例

插件说明

TablePlugin

Options

disableMerge optional boolean

disableExpandOnInsert optional boolean

disableMarginLeft optional boolean

enableUnsetSingleColSize optional boolean

initialTableWidth optional number

minColumnWidth optional number

TableRowPlugin

TableCellPlugin

TableCellHeaderPlugin

API 参考

editor.api.create.table

Parameters

options optional GetEmptyTableNodeOptions

Options

header optional boolean

rowCount optional number

colCount optional number | undefined

Returns

TElement

editor.api.create.tableCell

Options

header optional boolean

row optional TTableRowElement

children optional Descendant[]

Returns

TElement

editor.api.create.tableRow

Options

header optional boolean

colCount optional number

Returns

TElement

editor.api.table.getCellBorders

Options

element TTableCellElement

defaultBorder optional Required<TTableCellElementBorder>

Show child attributes

Returns

BorderStylesDefault

Show child attributes

editor.api.table.getCellChildren

Parameters

cell TElement

Returns

Descendant[]

editor.api.table.getCellSize

Options

element TTableCellElement

colSizes optional number[]

Returns

width number

minHeight number | undefined

editor.api.table.getColSpan

Parameters

element TTableCellElement

Returns

number

editor.api.table.getRowSpan

Parameters

element TTableCellElement

Returns

number

getCellType

Returns

string[]

`tf.insert.table`