支持的功能
下表展示了每种文档功能在转换流水线的三个阶段中的表现:
- 导入 将 DOCX 内容转换为 Tiptap JSON。
- 编辑器 在浏览器中渲染该 JSON。每种节点和标记类型都需要匹配的 Tiptap 扩展才能正确显示。
- 导出 将编辑器内容转换回 DOCX 文件。
某项功能可能在某个阶段受支持,但在另一个阶段不受支持。例如,制表符会被导入并在编辑器中渲染,但导出扩展目前还不会将其写回 DOCX。
导入和导出各自都有两种集成路径:一种是 编辑器扩展,另一种是 REST API。对于大多数功能,这两种路径会产生相同的结果。对于存在差异的地方(脚注、页眉/页脚、导出自定义),相关安装页面会说明具体细节。
编辑器列默认假设使用 ConvertKit
下表中的编辑器列默认假设推荐配置:已安装 ConvertKit 作为编辑器的扩展套件。ConvertKit 是基础功能的超集(相当于 StarterKit 的节点,加上针对 Paragraph、Heading、Image 以及表格栈的 DOCX 感知覆盖)。如果没有 ConvertKit,段落间距和缩进、图片裁剪以及表格单元格格式仍会被提取到 JSON 中,但会被编辑器的 schema 丢弃。若编辑器支持取决于其他因素(Pages、某个自定义扩展),该行会注明依赖项。
其他格式
这些表格专门描述 DOCX 流水线,因为 DOCX 是所有其他导出所基于的参考格式。PDF、ODT、EPUB 和 DOC 都是先生成一个 DOCX 文件,然后通过云服务将其转换为目标格式。凡是在 DOCX 导出中可用的功能,通常也会延续到其他格式,不过每种格式都可能引入自己的限制。详情请参见相应格式页面。
Markdown 走的是完全独立的转换路径,并支持另一组功能。相关内容记录在其单独的页面中。
内联格式
块级元素
文本和段落样式
导入服务会从 DOCX 源中提取段落级样式属性,例如间距、缩进和行高。ConvertKit 的自定义 Paragraph 和 Heading 会自动渲染这些样式。对于文档命名样式目录(Heading 1、Normal、Quote 等)中的排版样式,请使用实验性的 CSS 注入 功能,它会将样式目录提取为带作用域的 CSS 规则。
* 字母间距会被提取为 textStyle.letterSpacing,但没有内置扩展来渲染它。要渲染导入的字母间距,请扩展 TextStyle。
** 默认不会应用 Word 的命名样式排版。请使用 CSS 注入 将其提取为作用域 CSS。
*** 导出时会往返保留行距。比例值(无单位的倍数,如 1.5,或百分比,如 150%)会写入为相对行距,并随字体大小缩放;带绝对单位的固定值(24px、18pt、1cm)会写入为精确行高。em 和 rem 等与字体相关的单位则保留为文档默认值。
列表
表格
单元格级和行级属性(背景、边框、垂直对齐、行高)需要 ConvertKit 的 ConvertTableKit,该套件默认包含。若使用独立的 @tiptap/extension-table,这些属性仍会被提取到 JSON 中,但会被编辑器的 schema 丢弃。若要通过 Pages 扩展 实现分页布局,请改用 PagesTableKit;其表格扩展在内部继承了 ConvertKit 的扩展,因此相同的 DOCX 单元格属性也会继续传递。有关具体组成,请参见 表格内容参考。
| 功能 | 导入 | 编辑器 | 导出 |
|---|---|---|---|
| Basic tables | ✓ | ✓ | ✓ |
| Merged cells (colspan) | ✓ | ✓ | ✓ |
| Merged cells (rowspan) | ✓ | ✓ | ✓ |
| 表格标题行 | ✓ | ✓ | ✓‡ |
| Table width | ✓ | ✓ | ✓† |
| Column widths | ✓ | ✓ | ✓ |
| Table borders | ✓ | ✓ | ✓ |
| Cell backgrounds | ✓ | ✓ | ✓ |
| Cell borders | ✓ | ✓ | ✓ |
| Cell vertical alignment | ✓ | ✓ | ✓ |
| Row height | ✓ | ✓ | ✓ |
| Table-level cell margins | ✓ | ✓ | ✓ |
† 具有明确宽度的表格保持固定宽度宽度。未设置宽度的表格保持全宽度(流动)并回流到页面,而不是锁定到固定测量值。
******** 仅当 repeatTableHeaderRows 在编辑器扩展名 中启用时,标题行才会导出为 Word 的“重复为标题行”。默认情况下它处于关闭状态,并且 REST API 不接受它。
Media
* ConvertKit 的自定义 Image 会声明 cropTop/cropBottom/cropLeft/cropRight,并将它们作为 data-crop-* 属性输出。若要实现视觉裁剪,请添加 CSS,将这些数据属性转换为 clip-path 或 object-position。
页面布局
| 功能 | 导入 | 编辑器 | 导出 |
|---|---|---|---|
| Page breaks | ✓ | ~ | ✓ |
| Headers and footers | ✓* | ✓ | ✓ |
| Sections | ~ | ✕ | ✕ |
| Page size and margins | ✕ | ✓ | ✓ |
| 页码 | ~** | ✓ | ✓** |
| Footnotes | ✓* | ✕ | ✕ |
| Endnotes | ✓* | ✕ | ✕ |
| Comments | ✓ | ✓ | ✓ |
* Import behavior differs between integration paths. The REST API returns footnotes, endnotes, and headers/footers as separate fields in the response. The editor extension auto-applies headers and footers via the Pages extension but does not surface footnote or endnote data. See the install pages for details.
** Word PAGE and NUMPAGES fields in headers/footers translate to canonical text tokens ({page} / {numpages}): auto-on with the Pages extension, opt-in elsewhere via the placeholders field. Other field codes (DATE, AUTHOR, MERGEFIELD) still import as their cached display value. On export, both the editor extension and the REST API emit {page} / {total} tokens in header/footer content as live PAGE / NUMPAGES fields. See page-number fields.
Page layout requires the Pages extension
Headers, footers, page breaks, and paginated layout all require the Pages extension for editor rendering. Without it, these features have nowhere to render even if the conversion service produces them.
审阅和协作
| 功能 | 导入 | 编辑器 | 导出 |
|---|---|---|---|
| 修订记录 | ~* | ✓* | ~* |
* 在 preserve 模式下,插入和删除会以建议的形式往返转换。accept 和 reject 会在导入期间直接应用或丢弃它们,因此不会有建议进入文档。编辑器渲染需要修订记录扩展。目前尚未携带某些修订类型,包括导入时的段落拆分、格式变化和移动,以及导出时图片上的格式修订和建议。在这些情况下,内容会进入文档,但变化记录不会保留。请参阅导入修订记录和导出修订记录。
不支持
这些功能在导入期间不会被转换,或者仅有限转换。
| 功能 | 状态 |
|---|---|
| Table of Contents | Imported as tableOfContents node (title and heading range). A custom extension is needed to render it in the editor. The existing Table of Contents extension is a headless utility for building sidebar navigation, not a document block renderer. Not exported. |
| Text boxes | Not converted. Content inside text boxes is not extracted. |
| Shapes, SmartArt, WordArt | Not converted. These elements are not extracted during import. |
| Field codes (DATE, AUTHOR, MERGEFIELD) | The cached display value is preserved as plain text (e.g., a DATE field showing "April 10, 2026" imports as the text "April 10, 2026"). The field code itself is not converted, so the value becomes static and will not update. |
| Page-number field codes (PAGE, NUMPAGES) | Translated to canonical text tokens ({page} for PAGE, {numpages} for NUMPAGES) when placeholders is enabled (default-on with the Pages extension; opt-in via the placeholders={} form field on the REST API). The Pages extension renders {page} natively; map {numpages} via Pages.configure({ placeholders: { total: 'numpages' } }) to render it live. With placeholders: false (or omitted on the REST API), the cached display value imports as plain text. |
| Document metadata (author, title, keywords) | Not converted. Metadata is not included in the JSON output. |
| 表单字段和内容控件 | 部分转换。内联和块级结构化文档标签 (SDT) 保留其内容,但控制元数据被丢弃。复选框内容控件是例外。打开任务列表导入后,以 1 开头的列表项将作为具有勾选状态的任务项导入,任务项将导出为复选框内容控件。请参阅任务列表。 |
| Hidden text | Text runs marked as hidden (w:vanish) are excluded from the import output. |
| Right-to-left text direction | DOCX <w:bidi> (paragraph direction) and <w:rtl> (run direction) are not parsed on import or written on export. Documents authored in Arabic, Hebrew, Persian, Urdu, and other RTL languages render with the editor's CSS direction (LTR by default). Set dir="rtl" on the editor root or detect language at the application level to handle this today. See Text alignment for details. |