--- title: "ConvertKit：DOCX 感知编辑器扩展" description: "一个打包的 Tiptap 扩展，用于为从 DOCX 导入的内容配置编辑器。" canonical_url: "https://tiptap.zhcndoc.com/conversion/import/docx/convertkit" --- # ConvertKit：DOCX 感知编辑器扩展 一个打包的 Tiptap 扩展，用于为从 DOCX 导入的内容配置编辑器。 > **Beta 功能:** > > ConvertKit 的 API、属性名称和捆绑扩展正在趋于稳定，但在正式可用之前仍可能会有所 > 调整。如果你依赖 ConvertKit，请锁定准确的包版本，并在采用之前阅读 **哪些内容无 > 法工作** 这一节。 - **1. 激活试用或订阅** 在你的账户中开始 [免费试用](https://cloud.tiptap.dev/v2?trial=true) 或 [订阅 Start 套餐](https://cloud.tiptap.dev/v2/billing)。 - **2. 从私有注册表安装** 按照 [设置指南](https://tiptap.zhcndoc.com/guides/pro-extensions.md) 验证并访问 Tiptap 的私有 npm 注册表。 > **Interactive demo:** [ImportDocxCssStyles](https://embed-pro.tiptap.dev/preview/Extensions/ImportDocxCssStyles) ## 这会做什么 DOCX 文件包含了基础 Tiptap 扩展并不了解的格式元数据：段落间距（以 twips 为单位）、表格行高规则、图片裁剪百分比、单元格垂直对齐、各边框宽度。如果你用原生 Tiptap 渲染 DOCX 内容，这些信息会丢失或渲染错误。 **ConvertKit 是一个单一扩展，用于配置你的编辑器以导入 DOCX 内容。** 引入它后，你将获得： - 30 个捆绑扩展，彼此联动以处理 Convert API 生成的一切内容。 - 自定义的 Paragraph、Heading、Image、Table、TableRow、TableCell 和 TableHeader 扩展，可接受 DOCX 特定属性。 - 在编辑器创建时注入的一小段 CSS 重置，用于规范浏览器默认样式，从而让 DOCX 间距值能够准确渲染。 - 每个捆绑扩展都可以单独配置或禁用。 ## 安装 ```bash npm i @tiptap-pro/extension-convert-kit@^0.1.0 ``` ## 工作原理 三个部分： 1. **一组预配置扩展。** ConvertKit 注册了一组精选的 Tiptap 扩展（用于 marks 和 lists 的基础扩展，以及针对段落、标题、图片和表格的支持 DOCX 的自定义覆盖）。你可以在 `ConvertKit.configure({…})` 中为任意槽位传入 `false` 来排除对应扩展。 2. **schema 节点上的 DOCX 属性。** 支持 DOCX 的覆盖扩展会继承其基础对应项，并声明额外属性（段落间距、图片裁剪、表格单元格属性）。转换服务会生成这些属性；ConvertKit 的节点会将其渲染出来。 3. **作用域化 CSS 重置。** ConvertKit 注入了一小段 CSS 重置，用于规范段落外边距、表格行高、单元格垂直对齐以及精确高度行的浏览器默认值，从而使 DOCX 间距值能够准确渲染。编辑器销毁时，这个重置会被移除。 ```ts import { Editor } from '@tiptap/core' import { ConvertKit } from '@tiptap-pro/extension-convert-kit' const editor = new Editor({ extensions: [ConvertKit], }) ``` 自定义或禁用特定子扩展： ```ts new Editor({ extensions: [ ConvertKit.configure({ heading: { levels: [1, 2, 3] }, // 仅允许 H1–H3 codeBlock: false, // 完全移除 code-block 节点 table: false, // 替换为另一套表格栈 }), ], }) ``` ## 能工作 ### 内置扩展 ConvertKit 在单个 `@tiptap-pro/extension-convert-kit` 包中捆绑了 **30** 个扩展。下面的列表是参考资料，帮助你了解编辑器 schema 中会出现哪些内容；你不需要单独安装或注册这些扩展。 | Category | Extensions | | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Core | `Document`, `Text`, `Paragraph`*, `Heading`* | | Marks | `Bold`, `Italic`, `Underline`, `Strike`, `Code`, `Link` | | Blocks | `Blockquote`, `HorizontalRule`, `HardBreak`, `CodeBlock`, `PageBreak` | | Lists | `BulletList`, `OrderedList`, `ListItem`, `ListKeymap`, `OrderedListNumbering`† | | Media | `Image`\* | | Styling | `TextStyleKit` (`TextStyle`, `Color`, `BackgroundColor`, `FontFamily`, `FontSize`, `LineHeight`), `TextAlign`, `Highlight` (multicolor), `Superscript`, `Subscript` | | UI helpers | `Dropcursor`, `Gapcursor` | | History | `UndoRedo` | | Tables | `ConvertTableKit` (Table\*, TableRow\*, TableCell\*, TableHeader\*) | 标记为 `*` 的扩展是自定义的、支持 DOCX 的 Tiptap 基础扩展覆写。请参阅下一节了解它们新增了什么。标记为 `†` 的扩展已捆绑但**默认关闭**：请通过同名配置项启用它们（参见 [配置参考](#configuration-reference)）。 ConvertKit 还导出与 `OrderedListNumbering` 配套、用于编辑器预览渲染的辅助函数和类型：`generateNumberingFormatCss`、`GenerateNumberingFormatCssOptions`、`NumberingFormatDefinition`、`NumberingLevelDefinition`、`NumberingBaseStyle` 和 `NumberingMarkerFont`。有关端到端流程，请参见 [有序列表编号](https://tiptap.zhcndoc.com/conversion/export/docx/ordered-list-numbering.md)。 ### 在 Tiptap 基础扩展上新增的属性 | Extension | Added attributes | Source | | --------------------------- | ----------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | `Paragraph` | `spacingBefore`, `spacingAfter`, `lineHeight`, `fontSize`, `indent`, `firstLineIndent`, `contextualSpacing` | paragraph mark 上的 DOCX `w:pPr` + `w:rPr` | | `Heading` | same as `Paragraph` | paragraph mark 上的 DOCX `w:pPr` + `w:rPr` | | `Image` | `cropTop`, `cropBottom`, `cropLeft`, `cropRight` | drawings 上的 DOCX `a:srcRect` | | `Table` | `width`, `indent` (+ `cellMinWidth: 1` 默认值，相较于 Tiptap 的 `25`) | DOCX `w:tblW`, `w:tblInd`, `w:tblGrid` | | `TableRow` | `height`, `heightRule` (`exact` / `atLeast`) | DOCX `w:trHeight` + `w:hRule` | | `TableCell` / `TableHeader` | `background`, `verticalAlign`, 每边边框（top/bottom/left/right 上的 `width` / `style` / `color`） | DOCX `w:tcPr` | | `OrderedListNumbering`† | `numberingFormat` | `ExportDocx` numbering format registry. See [Ordered list numbering](https://tiptap.zhcndoc.com/conversion/export/docx/ordered-list-numbering.md). | ### CSS 重置会规范什么 该重置作用于 `.tiptap`，并调整了几个区域；否则浏览器默认样式会与 DOCX 间距不对齐： - **段落间距。** 段落以及 `*` 后代元素的上、下外边距会被清零，因此 DOCX 作者设置的间距值（其自身包含前后值）能够准确渲染，而不会叠加在浏览器默认外边距之上。 - **表格行高和单元格内边距。** 默认值会被收紧，因此声明了特定行高的表格能够按那些高度实际渲染。 - **精确高度行会裁剪溢出内容。** 具有 `heightRule: "exact"` 的行会通过内部单元格包装器裁剪溢出内容；比声明行高更高的内容会被隐藏，这与 Word 的行为一致。 - **尾随换行伪影。** ProseMirror 的尾随换行会设置为零外边距和内边距，因此不会在段落末尾引入虚假的空白。 如果你需要覆盖其中任何内容，请在 `.tiptap` 内部定位你自己的选择器；你的规则会覆盖重置。 ### 一些小但重要的默认值 - 表格的 `cellMinWidth: 1`。Tiptap 默认是 `25`，这会把 DOCX 的间距列（1–15 px 的窄列，用于布局）放大成可见的间隙。ConvertKit 将最小值上限限制为 `1` px。 - 使用 `types: ['paragraph', 'heading']` 配置 `textAlign`，使 DOCX 段落两种对齐块都能传递过去。 - 使用 `multicolor: true` 配置 `highlight`，从而让 DOCX `w:highlight` 的颜色原样传递。 ## 将无法工作 > **这些是有意的限制:** > > 这些都不是 bug。它们是该功能明确记录的边界。如果你的工作流依赖下面任何一项， > 那么这个功能并不适合你。 - **浮动表格。** DOCX `w:tblpPr`（相对于锚点定位并带文字环绕的表格）会渲染为普通的纵向堆叠内联表格。定位元数据会被转换器丢弃。这是刻意为之；浮动布局的保真度不在范围内。 - **负表格缩进。** 小于零的 `w:tblInd` 值会保留在 `attrs.indent` 中，但在渲染时会被限制为 `0`。Word 会把负缩进渲染到页面边距沟槽中；浏览器没有这个沟槽，因此渲染它们会把表格推到页面边缘之外。 - **精确行高溢出。** 具有 `heightRule: "exact"` 的行会通过 `.cell-content` 包装器的 `overflow: hidden` 裁剪溢出内容。比声明高度更高的内容不可见。 - **过宽表格宽度。** 声明宽度超过容器的表格会以 `max-width: 100%` 渲染。声明的宽度会保留在 `attrs.width` 中，但视觉上会被限制。 - **多页布局。** ConvertKit 不进行分页。如果你需要跨页表格、真实的页面容器、页眉/页脚，或者希望页面分隔符在视觉上生效，请将 ConvertKit 与 [Pages extension](https://tiptap.zhcndoc.com/pages/getting-started/overview.md) 配合使用，并为表格扩展使用 [PagesTableKit](https://tiptap.zhcndoc.com/pages/guides/pages-tablekit.md)。 - **脚注、尾注、评论。** 不会渲染。转换器会把它们作为段落输出或直接丢弃；ConvertKit 不会添加任何脚注/评论 UI。 ## 你应该预期到 - 在编辑器挂载期间，会应用一个小范围的 CSS 重置。页面上多个由 ConvertKit 驱动的编辑器会共享这份重置：它只会插入一次，并且只有在最后一个编辑器被销毁时才会移除。 - 你应用中 DOCX 导入内容的一致渲染。带有非零 DOCX 裁剪的图片会真正以裁剪后的效果渲染；`heightRule: "atLeast"` 的行在其列收缩时会垂直增高；`verticalAlign: "center"` 的单元格会将内容居中。 - 与 Tiptap Pro 其余扩展生态完全兼容。`@tiptap-pro/extension-import-docx` 和 `@tiptap-pro/extension-export-docx` 是天然的配套扩展；如果你需要分页，`@tiptap-pro/extension-pages-tablekit` 可以叠加使用。 - **紧凑的默认排版。** CSS 重置会将段落外边距清零，并应用紧凑的行高。如果你使用 ConvertKit 来处理并非从 DOCX 导入的内容，请在其基础上叠加你自己的排版规则。这种重置是有意为之，而不是我们期望默认就视觉上足够精美的样式。 ## 不要预期到 - **超出节点属性级别的 DOCX 保真度。** ConvertKit 会接入 Convert API 生成的属性。如果转换器没有解析某个 DOCX 特性，ConvertKit 就无法渲染它。 - **表格的自动缩放手柄。** ConvertKit 的 Table 扩展继承自 `@tiptap/extension-table`，并支持标准的缩放行为，但默认的 `cellMinWidth: 1` 意味着手柄可以把列拖到 1 px 宽，这通常不是你在手动编辑时想要的。将 DOCX 导入与手动创作混合使用时，请覆盖 `table.cellMinWidth`。 ## ConvertKit 不覆盖的内容 ConvertKit 会将 Convert API 产出的所有特性作为 Tiptap 节点和标记来处理。某些导入的 DOCX 内容超出了这一范围，仍然需要在应用层处理： - **脚注和尾注引用。** [导入 REST API](https://tiptap.zhcndoc.com/conversion/import/docx/rest-api.md) 会返回脚注和尾注数据，但 [编辑器扩展](https://tiptap.zhcndoc.com/conversion/import/docx/editor-extension.md) 不会展示这些内容，也没有任何 Tiptap 扩展可以渲染脚注标记或注释。参见 [脚注和尾注](https://tiptap.zhcndoc.com/conversion/content-types/structures-and-media/footnotes-endnotes.md)。 - **多栏布局。** 导入会为多栏章节生成 `columns` 和 `column` 节点，但没有可用于渲染它们的编辑器扩展。参见 [页面结构](https://tiptap.zhcndoc.com/conversion/content-types/page-layout/page-structure.md)。 - **目录。** 会被导入为 `tableOfContents` 节点。除非你添加自定义扩展，否则会以普通内容形式渲染。参见 [支持的功能](https://tiptap.zhcndoc.com/conversion/getting-started/feature-support-matrix.md)。 - **Word 样式。** 样式名在导入时用于结构识别（标题、引用块、代码块）。文档样式目录中定义的视觉样式不会被应用。可将 ConvertKit 与 [CSS 注入](https://tiptap.zhcndoc.com/conversion/import/docx/css-injection.md) 配合，以保留样式目录；或者参见 [Word 样式](https://tiptap.zhcndoc.com/conversion/content-types/structures-and-media/word-styles.md)。 - **数学公式。** Convert API 不会解析 OMML。参见 [数学公式](https://tiptap.zhcndoc.com/conversion/content-types/structures-and-media/math-equations.md)。 - **字间距。** Convert API 会将字符间距按逐段标记提取为 `textStyle.letterSpacing`，但捆绑的 `TextStyleKit` 没有声明 `letterSpacing` 属性，因此该值在渲染时会被丢弃。[CSS 注入](https://tiptap.zhcndoc.com/conversion/import/docx/css-injection.md) 也不会提取它（只有导出侧编译才接受它）。若要渲染导入的字间距，请为 `TextStyle` 扩展一个 `letterSpacing` 属性，并在 `renderHTML` 中输出 `style="letter-spacing: …"`。参见 [字体族和字号](https://tiptap.zhcndoc.com/conversion/content-types/text-and-formatting/font-family-size.md)。 - **页面布局。** 页面大小、页边距、页眉和页脚属于文档级别的事项。ConvertKit 负责渲染内容；可将其与 [Pages 扩展](https://tiptap.zhcndoc.com/pages/getting-started/overview.md) 配合使用，以实现分页布局。 如需了解如何扩展 ConvertKit 的内置扩展，以及如何使用 CSS 为转换后的内容设置样式，请参阅 [转换后内容样式](https://tiptap.zhcndoc.com/conversion/getting-started/guides/styling-converted-content.md) 指南。 ## 配置参考 每个键都是可选的。传入 `false` 可排除某个扩展。传入部分选项对象会转发到底层扩展的 `configure()`。每个键的默认值都是 `{}`，但下面特别说明的除外。 ```ts ConvertKit.configure({ document: Record | false, text: Record | false, paragraph: Partial | false, heading: Partial | false, blockquote: Partial | false, bold: Partial | false, italic: Partial | false, underline: Partial | false, strike: Partial | false, code: Partial | false, link: Partial | false, bulletList: Partial | false, orderedList: Partial | false, listItem: Partial | false, listKeymap: Partial | false, orderedListNumbering: boolean | Partial, // 默认：false；使用 `true` 开启，或传入一个选项对象（`defaultFormat`、`formats`） hardBreak: Partial | false, horizontalRule: Partial | false, dropcursor: Partial | false, gapcursor: Record | false, codeBlock: Partial | false, image: Partial | false, textStyleKit: Partial | false, textAlign: Partial | false, // 默认：{ types: ['paragraph', 'heading'] } highlight: Partial | false, // 默认：{ multicolor: true } superscript: Partial | false, subscript: Partial | false, pageBreak: Partial | false, table: Partial | false, }) ``` ## 相关 - [PagesTableKit](https://tiptap.zhcndoc.com/pages/guides/pages-tablekit.md): 封装 ConvertKit 的 Table 扩展的配套包，提供与 Pages 扩展分页兼容的 CSS Grid NodeView。 - [CSS 注入（导入）](https://tiptap.zhcndoc.com/conversion/import/docx/css-injection.md): 将 ConvertKit 与 CSS 注入配合，以从 DOCX 样式目录中获得排版保真度。 - [编辑器扩展（导入 DOCX）](https://tiptap.zhcndoc.com/conversion/import/docx/editor-extension.md): `ImportDocx` 扩展如何调用 Convert API。