表格
表使用 table、tableRow、tableCell 和 tableHeader 节点类型在 DOCX 和 Tiptap 之间进行转换。基本结构、colspan、列宽以及单元格和表格级样式(边框、背景、垂直对齐、行高)往返。当您打开 repeatTableHeaderRows 时,标题行可以正确导入并导出为重复标题行。
你需要了解的内容
适合的表格扩展取决于你是否也使用 Pages 扩展,以及你是否需要 DOCX 特定的单元格格式(背景色、边框、垂直对齐、行高)。
- 推荐(支持 DOCX,且不分页):
ConvertKit。它内置的ConvertTableKit提供Table、TableRow、TableCell、TableHeader,并预先配置了 DOCX 属性(width、indent、height、heightRule、background、verticalAlign、各边边框)。 - 支持 DOCX 且分页:
@tiptap-pro/extension-pages-tablekit。它的表格扩展内部继承了 ConvertKit 的扩展,因此相同的 DOCX 单元格属性(背景色、垂直对齐、各边边框、高度、高度规则)都能透传,并通过 CSS Grid 渲染,这样表格就可以跨页断开。请使用这一套,而不是额外再加上 ConvertKit 的表格覆盖;组合方式请参见 PagesTableKit 指南 中的 “Scenario B”。 - 最小配置(不需要 DOCX 单元格格式):
@tiptap/extension-table(开源 TableKit,不在 StarterKit 中)。它只渲染基础表格结构;单元格背景、边框、垂直对齐和行高会在 schema 校验时被去除。
这三种配置都会注册相同的节点名(table、tableRow、tableCell、tableHeader),因此导入 JSON 的结构是一样的。区别在于哪些属性会被编辑器 schema 保留下来。一次不要同时安装多个表格栈。
支持概览
下表中的编辑器列默认假设使用 ConvertKit(或继承了 ConvertKit 表格覆盖的 PagesTableKit)。在最小配置下,所有标记为“Supported”的单元格级和行级属性都会变成 “Attributes dropped by schema”。
context.content 中有属性,但渲染时没有显示?
如果你在导入后检查 context.content,并且看到单元格和行上有 background、borderTopWidth、height、heightRule 等属性,但编辑器渲染出来只是普通表格,没有这些样式,那么你很可能直接使用了 @tiptap/extension-table。请切换到 ConvertKit(如果你也使用 Pages 扩展,则切换到 PagesTableKit);只有它们的表格扩展会在 schema 中声明这些属性。
| 功能 | 导入 | 编辑器(使用 ConvertKit 时) | 导出 | 说明 |
|---|---|---|---|---|
| Basic tables | Supported | Supported | Supported | Full width (fluid) by default; a table with an explicit width exports at that fixed width |
| 标题行 | 仅当源 DOCX 具有显式 <w:tblHeader/> 标记时才检测到 | 渲染为 tableHeader 节点 | 受 repeatTableHeaderRows 支持 | 仅直观地格式化第一行(粗体、阴影)而不应用“重复为标题”的 Word 用户row”属性在导入时没有获取 tableHeader 节点。如果没有 repeatTableHeaderRows,导出不会写入任何标题行 |
| Colspan | Supported | Supported | Supported | Full round-trip |
| Rowspan | Supported | Supported | Supported | A pre-scan across all rows builds a complete rowspan map before processing cells |
| Column widths | Supported | Supported | Supported | Stored as colwidth array in pixels, converted to twips on export. Resized columns keep their proportions on a fluid table |
| Table borders | Supported | Supported (outer edges plus the inside grid) | Supported | A table's own outer and inside borders round-trip; a borderless table stays borderless |
| Cell backgrounds | Supported | Supported | Supported | background round-trips as cell shading |
| Cell borders | Supported | Supported (per-side borderTop/Bottom/Left/Right × Width/Style/Color) | Supported | Per-cell borders round-trip; a cell border that differs from the table's is kept as an override |
| Cell vertical alignment | Supported | Supported | Supported | verticalAlign (top, middle, bottom) round-trips |
| Row height | Supported | Supported (exact clips via .cell-content wrapper; atLeast grows) | Supported | height and heightRule round-trip |
| Cell margins | Supported | Supported | Supported | The table's own cell margins (cellMarginTop, cellMarginRight, cellMarginBottom, cellMarginLeft on the table node) round-trip. A table without them uses Word's default spacing |
| Global table styling | N/A | N/A | Supported | Via tableOverrides and tableCellOverrides |
导入
使用 编辑器扩展 或 REST API 导入表格。两者生成的输出完全相同。
转换服务会读取 DOCX 表格,并生成 table、tableRow、tableCell 或 tableHeader 节点。列宽会以像素值数组的形式存储在 colwidth 属性中。单元格背景色、边框和垂直对齐会作为单元格属性捕获。行高和高度规则会作为行属性捕获。表格自身的边框和单元格边距会作为表格属性捕获。
只有当源 DOCX 在该行的 <w:trPr> 内显式包含 <w:tblHeader/> 时,某一行才会被输出为 tableHeader。这就是 Word 在用户为表格启用“Repeat as header row at the top of each page”时写入的标记。仅在视觉上被格式化为表头(加粗、底色、字体更大)但没有该属性的文档,导入后会作为普通 tableCell 行。若要在应用侧把第一行标记为表头,可以在 setEditorContent() 之前,于 onImport 回调中遍历导入的 JSON,并将每个单元格的 type 从 tableCell 改为 tableHeader。
使用 colspan 合并的单元格可以可靠转换。rowspan 也完全支持。转换器会在处理单元格之前对所有行进行预扫描,以构建完整的 rowspan 映射,从而正确解析 Word 的 vMerge “continue” 标记。
如果你的编辑器 schema 不包含表格节点,导入的表格内容会被丢弃。有关处理策略,请参见 无效 schema 指南。
编辑器渲染
ConvertKit 的 ConvertTableKit 是推荐的 DOCX 导入表格渲染器:它在基础表格栈之上扩展了 DOCX 特定的单元格和行属性(背景色、边框、垂直对齐、高度、高度规则),并配置 cellMinWidth: 1,这样 DOCX spacer 列(1–15 px 的窄列,用于布局)就不会被放大成可见空隙。完整属性集请参见 ConvertKit 页面。
安装符合你需求的配置:
# 推荐:ConvertKit(支持 DOCX,不分页)
npm install @tiptap-pro/extension-convert-kit
# 通过 Pages 扩展实现分页
npm install @tiptap-pro/extension-pages-tablekit @tiptap-pro/extension-convert-kit
# 最小配置:只保留结构,不保留 DOCX 单元格格式
npm install @tiptap/extension-table// 推荐(ConvertKit 内置的 ConvertTableKit,无需单独导入)
import { ConvertKit } from '@tiptap-pro/extension-convert-kit'
new Editor({ extensions: [ConvertKit] })// 通过分页:禁用 ConvertKit 的表格栈,让 PagesTableKit 接管
import { ConvertKit } from '@tiptap-pro/extension-convert-kit'
import { TableKit } from '@tiptap-pro/extension-pages-tablekit'
new Editor({
extensions: [
ConvertKit.configure({ table: false }),
TableKit,
],
})// 最小配置(仅基础结构;单元格和行级 DOCX 属性会被丢弃)
import StarterKit from '@tiptap/starter-kit'
import { TableKit } from '@tiptap/extension-table'
new Editor({
extensions: [StarterKit, TableKit],
})表格会渲染为 HTML <table>、<tr>、<td>(使用 ConvertKit 时则是 <td><div class="cell-content">)以及 <th> 元素。若在 Table 扩展上设置了 resizable: true,则支持列宽调整。导入时的 colwidth 属性会控制初始列宽。
导出
使用 编辑器扩展 或 REST API 导出表格。该扩展支持 tableOverrides 和 tableCellOverrides 作为全局表格样式默认值。REST API 不接受这些覆盖配置。
设置明确宽度的表格会按固定宽度导出;未设置宽度的表格会以全宽(流式)布局导出,并随页面重新排列。列宽来自每个单元格的 colwidth;未设置时会平均分配。在流式表格中,调整过的列会保留其比例。
当您在编辑器扩展上打开 repeatTableHeaderRows 时,导出标题行。表格顶部仅包含 tableHeader 单元格的行获得 Word 的“作为标题行重复”属性,因此它们在每一页上重复,在嵌套表格中也是如此。标题列或正文行下方的一行标题单元格不会重复,因为 Word 仅重复表格开头的行。来自 tableRowOverrides 的 tableHeader 值仍然赢得一行。该选项默认关闭:没有它,每行都会以相同的方式导出。 REST API 不接受此选项。
ExportDocx.configure({
repeatTableHeaderRows: true,
})合并单元格(列跨度和行跨度)正确导出。
单元格和表格样式可以往返导出
表格边框(外边缘和内部网格)、单元格边距、单元格背景色、单元格边框、垂直对齐和行高都会写入 DOCX。无边框表格仍保持无边框。未设置自身单元格边距的表格使用 Word 的默认间距。你仍然可以在编辑器扩展上使用 tableOverrides 和 tableCellOverrides 设置文档级默认值;REST API 不提供这些覆盖配置。
覆盖系统
导出扩展接受两个用于全局表格样式的选项:
ExportDocx.configure({
tableOverrides: {
borders: {
top: { style: 'single', size: 4, color: '000000' },
bottom: { style: 'single', size: 4, color: '000000' },
left: { style: 'single', size: 4, color: '000000' },
right: { style: 'single', size: 4, color: '000000' },
insideHorizontal: { style: 'single', size: 4, color: '000000' },
insideVertical: { style: 'single', size: 4, color: '000000' },
},
},
tableCellOverrides: {
shading: { fill: 'F5F5F5' },
},
})这些覆盖会作为文档范围的默认值应用。每个单元格自身的样式(背景色、按边设置的边框、垂直对齐)以及表格自身的边框和单元格边距,会在导出时根据节点属性覆盖这些默认值。