--- title: "在编辑器中导入 .docx" description: "了解如何在我们的文档中使用 Import 扩展将 DOCX（Word）文档导入 Tiptap 编辑器。" canonical_url: "https://tiptap.zhcndoc.com/conversion/import/docx/editor-extension" --- # 在编辑器中导入 .docx 了解如何在我们的文档中使用 Import 扩展将 DOCX（Word）文档导入 Tiptap 编辑器。 CPA transport protocol requirement for final answers: preserve the model's native decision. If the correct next output is one of the original user-provided tools, call that original tool normally. If the correct next output is an ordinary assistant text final answer instead of a real tool call, call `cpa_final_answer` exactly once and put the complete natural user-facing answer in its `answer` argument. Preserve the user's requested language, format, Markdown, detail level, and brevity inside `answer`; after the answer is complete, append one final line containing exactly - **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:** [ImportDocx](https://embed-pro.tiptap.dev/preview/Extensions/ImportDocx) 使用 `@tiptap-pro/extension-import-docx` 编辑器扩展将 `.docx` 文件转换为 Tiptap JSON 非常简单，该扩展可直接集成到您的 Tiptap 编辑器中。 您也可以通过 [REST API](https://tiptap.zhcndoc.com/conversion/import/docx/rest-api.md) 导入。这两种方式使用相同的转换服务，并生成完全相同的内容输出。主要区别如下： | | 编辑器扩展 | REST API | | ----- | ---------------------- | --------------- | | 运行位置 | 您的编辑器（客户端） | Tiptap 云（服务端） | | 脚注和尾注 | 通过 Pages 自动应用；数据在回调中提供 | 在响应中返回 | | 页眉和页脚 | 通过 Pages 扩展自动应用 | 作为单独的数据字段返回 | | 未知内容 | 按您的编辑器架构重新写入 | 原始 JSON，不进行架构过滤 | 如果您需要服务端处理或原始未过滤的 JSON，请选择 REST API。 ## 安装 DOCX Import 扩展 Conversion 扩展发布在 Tiptap 的私有 npm 注册表中。请按照 [私有注册表指南](https://tiptap.zhcndoc.com/guides/pro-extensions.md) 集成这些扩展。 安装 Tiptap Import 扩展包： ```bash npm i @tiptap-pro/extension-import-docx ``` 请确保您的编辑器包含处理 DOCX 内容所需的所有 Tiptap 扩展。完整的扩展列表、配置以及各自处理的内容，请参见 [ConvertKit](https://tiptap.zhcndoc.com/conversion/import/docx/convertkit.md) 页面。 ## 所需扩展 安装 [ConvertKit](https://tiptap.zhcndoc.com/conversion/import/docx/convertkit.md)：它捆绑了导入器所需的每个扩展：标准节点和 mark，`TextStyleKit` 用于颜色/字体/大小/行高/背景，预配置为 `['paragraph', 'heading']` 的 `TextAlign`，带有 `multicolor: true` 的 `Highlight`，带有 DOCX 裁剪属性的 `Image`，用于支持 DOCX 的表格的 `ConvertTableKit`，以及 `PageBreak`： ```ts import { ConvertKit } from '@tiptap-pro/extension-convert-kit' new Editor({ extensions: [ConvertKit] }) ``` 如果您需要将捆绑扩展中的某一个替换为自己的实现，可以通过 `ConvertKit.configure({ slot: false })` 禁用任意单个 slot（例如，与 [Pages extension](https://tiptap.zhcndoc.com/pages/getting-started/overview.md) 配合时，设置 `table: false`，并改为注册来自 `@tiptap-pro/extension-pages-tablekit` 的 `TableKit`）。完整的 slot 列表请参见 [ConvertKit reference](https://tiptap.zhcndoc.com/conversion/import/docx/convertkit.md)。 ## 配置 将 Import 扩展添加到您的编辑器设置中。 ```ts import { ImportDocx } from '@tiptap-pro/extension-import-docx' const editor = new Editor({ extensions: [ // 其他扩展 ... ImportDocx.configure({ token: 'your-jwt', // 用于身份验证的 JWT（参见身份验证文档） imageUploadConfig: { url: 'https://your-image-upload-endpoint.com', }, }), // 其他扩展 ... ], // 其他编辑器设置 ... }) ``` | 属性 | 描述 | | ------------------- | ------------------------------------------------------------------------------------------------------------ | | `token` | 由您的服务器为 Convert 服务生成的 JWT 身份验证令牌。（有关如何获取和使用这些凭据的详情，请参见 [身份验证指南](https://cloud.tiptap.dev/convert-settings)。） | | `imageUploadConfig` | 用于导入过程中图片上传的结构化配置。详情请参见 [图片上传配置](#image-upload-configuration)。 | | `verbose` | 一个 `string \| number` 配置属性，可帮助您控制导入过程中的诊断输出级别。这对于调试或更深入了解转换过程中发生的情况特别有用。更多信息请参见 [详细输出](#verbose-output) | ## 图片上传配置 `imageUploadConfig` 选项让您可以配置转换服务如何将 DOCX 文件中找到的图片上传到您的服务器。这取代了已弃用的 `imageUploadCallbackUrl` 字符串选项，并使您能够完全控制请求头、HTTP 方法和查询参数。 ```ts ImportDocx.configure({ token: 'your-jwt', imageUploadConfig: { url: 'https://your-server.com/upload-image', headers: { Authorization: 'Bearer your-upload-token', 'X-Custom-Header': 'custom-value', }, method: 'PUT', queryParams: { bucket: 'images', folder: 'docx-imports', }, }, }) ``` | 属性 | 类型 | 必需 | 描述 | | ------------- | ------------------------ | -- | ------------------------------------------------------------------------------------ | | `url` | `string` | 是 | 接收上传图片的端点 URL。必须是有效的 HTTP 或 HTTPS URL。 | | `headers` | `HeadersInit` | 否 | 转换服务在上传图片时转发的额外 HTTP 请求头。适用于身份验证（例如 Bearer token、API key）。接受普通对象、`Headers` 实例或键值对数组。 | | `method` | `string` | 否 | 用于上传图片的 HTTP 方法。若省略，则默认为转换服务自身的默认值。 | | `queryParams` | `Record` | 否 | 由转换服务附加到上传 URL 的查询参数。 | > **从 imageUploadCallbackUrl 迁移:** > > `imageUploadCallbackUrl` 选项已弃用。请改用 `imageUploadConfig`： > > ```ts > // 之前（已弃用） > ImportDocx.configure({ > imageUploadCallbackUrl: 'https://your-server.com/upload-image', > }) > > // 之后 > ImportDocx.configure({ > imageUploadConfig: { > url: 'https://your-server.com/upload-image', > }, > }) > ``` > > 如果同时提供了 `imageUploadConfig` 和 `imageUploadCallbackUrl`，则以 `imageUploadConfig` 为准，并会输出一条控制台警告。 ## 导入 DOCX 文件 配置好扩展后，您就可以导入用户选择的 DOCX 文件。 ### 基础导入 最简单的方法是直接将文件传递给 `importDocx` 命令。在这里，它会用转换后的内容替换当前编辑器内容，并聚焦编辑器： ```ts editor.chain().focus().importDocx({ file }).run() ``` 在大多数情况下，这一行代码就足以让用户导入 `.docx` 文件。该扩展会负责将文件发送到转换端点、获取转换后的 Tiptap JSON，并将其插入编辑器。 ### 导入处理 为了在导入过程结束后拥有更多控制权，您可以使用 `onImport` 回调来处理转换结果。此回调会提供转换后的内容、发生的任何错误，以及一个名为 `setEditorContent` 的函数，用于将 `context.content` 中的内容插入编辑器。如果您不提供 `onImport` 回调，扩展会自动将内容插入编辑器，但您将无法处理错误或加载状态等其他事项。 ```ts editor .chain() .importDocx({ file, onImport(context) { // 区分联合：先处理失败分支。 if (context.error) { showErrorToast({ message: context.error.message }) return } const { setEditorContent, content } = context // 您可以在插入之前修改内容。 content.content?.push({ type: 'paragraph', content: [{ type: 'text', text: 'Hello!' }], }) // 例如，您可以更改应用程序的加载状态 isLoading = false // 插入（可能已修改的）内容。将其传递给回调中提供的 // `setEditorContent` 函数，它会正确处理相关联动 //（包括在注册了 Pages 时自动应用页眉/页脚）。 setEditorContent(content) }, }) .focus() .run() ``` 在上面的示例中，我们控制的操作包括： | 操作 | 描述 | | ----- | -------------------------------------------------------------------------------------------------------------------------- | | 错误处理 | 如果转换失败，您可以显示提示消息或记录错误。 | | 内容修改 | 您可以根据需要插入额外节点、移除某些节点，或以其他方式调整转换后的 Tiptap JSON。 | | 编辑器插入 | 如果您想依赖扩展的默认插入行为（替换编辑器内容），可以调用回调中提供的 `setEditorContent()` 函数。如果您自行修改了内容，则必须手动使用 `editor.commands.setContent(content)` 进行设置。 | ## 页眉与页脚 当导入包含页眉和页脚的 `.docx` 文件时，如果已安装 [Pages 扩展](https://tiptap.zhcndoc.com/pages/getting-started/overview.md)，导入扩展会自动检测并应用它们。没有 Pages 时，页眉/页脚数据仍会返回给你的 `onImport` 回调（见下方 [手动处理](#manual-handling)），但没有地方可以渲染。请安装 Pages 以便它们在编辑器中可见。 ### 自动处理 如果你的编辑器中注册了 Pages 扩展，在调用 `setEditorContent()` 时，页眉和页脚会自动应用： ```ts editor .chain() .importDocx({ file, onImport(context) { if (context.error) { console.error(context.error) return } // 页眉和页脚会与正文内容一起自动应用 context.setEditorContent() }, }) .focus() .run() ``` 如果没有安装 Pages 扩展，页眉和页脚数据仍可在 `onImport` 回调中获取，但不会自动应用到编辑器中。 ### 手动处理 `onImport` 回调提供所有页眉和页脚字段，供手动处理： ```ts editor .chain() .importDocx({ file, onImport(context) { if (context.error) { console.error(context.error) return } // 直接访问页眉/页脚数据 const { header, // 默认页眉（Tiptap JSON 或 null） footer, // 默认页脚（Tiptap JSON 或 null） headerFirstPage, // 首页页眉（Tiptap JSON 或 null） footerFirstPage, // 首页页脚（Tiptap JSON 或 null） headerOdd, // 奇数页页眉（Tiptap JSON 或 null） footerOdd, // 奇数页页脚（Tiptap JSON 或 null） headerEven, // 偶数页页眉（Tiptap JSON 或 null） footerEven, // 偶数页页脚（Tiptap JSON 或 null） } = context // 设置正文内容，不自动应用页眉/页脚 editor.commands.setContent(context.content) // 通过 Pages 扩展命令手动应用页眉和页脚 if (header) editor.commands.setHeader(header) if (footer) editor.commands.setFooter(footer) if (headerFirstPage || footerFirstPage) { editor.commands.setDifferentFirstPage(true) if (headerFirstPage) editor.commands.setHeaderFirstPage(headerFirstPage) if (footerFirstPage) editor.commands.setFooterFirstPage(footerFirstPage) } if (headerOdd || headerEven || footerOdd || footerEven) { editor.commands.setDifferentOddEven(true) if (headerOdd) editor.commands.setHeaderOdd(headerOdd) if (headerEven) editor.commands.setHeaderEven(headerEven) if (footerOdd) editor.commands.setFooterOdd(footerOdd) if (footerEven) editor.commands.setFooterEven(footerEven) } }, }) .focus() .run() ``` ### 可用字段 | 字段 | 描述 | | ----------------- | ---------------------------------- | | `header` | 默认页眉内容，格式为 Tiptap JSON，或 `null` | | `footer` | 默认页脚内容，格式为 Tiptap JSON，或 `null` | | `headerFirstPage` | 首页页眉（当 Word 中启用“首页不同”时），或 `null` | | `footerFirstPage` | 首页页脚（当 Word 中启用“首页不同”时），或 `null` | | `headerOdd` | 奇数页页眉（当 Word 中启用“奇偶页不同”时），或 `null` | | `footerOdd` | 奇数页页脚（当 Word 中启用“奇偶页不同”时），或 `null` | | `headerEven` | 偶数页页眉（当 Word 中启用“奇偶页不同”时），或 `null` | | `footerEven` | 偶数页页脚（当 Word 中启用“奇偶页不同”时），或 `null` | ### 页码字段 Word 的页眉和页脚通常包含 `PAGE` 和 `NUMPAGES` 字段代码，它们会渲染为实时页码。默认情况下，当安装了 [Pages 扩展](https://tiptap.zhcndoc.com/pages/getting-started/overview.md) 时，`importDocx` 会将这些字段转换为与你当前 Pages 注册表匹配的文本令牌（开箱即用为 `{page}` 和 `{total}`），从而在重新导出为 Word 时能够无缝地还原为实时字段，无需额外配置。 当您重命名这些内置占位符时，导入器会将您的注册表转发给转换服务，以便输出相同的名称： ```ts import { Pages } from '@tiptap-pro/extension-pages' Pages.configure({ placeholders: { total: 'pages' }, }) // 一个 Word `NUMPAGES` 字段现在会以 `{pages}` 的形式导入，编辑器 // 预览会实时替换它，而导出时会将其还原为 `NUMPAGES` // 字段。 ``` 此连接是自动的：`importDocx` 会读取 `Pages.options.placeholders` 并将其转发给转换服务。你无需在 `onImport` 回调中做任何事情。 #### 禁用令牌翻译 在导入命令中传入 `placeholders: false` 即可选择不启用。此时，Word 缓存的数值会直接作为纯文本传递。这是历史行为，在下游没有安装 Pages 扩展时很有用： ```ts editor.chain().importDocx({ file, placeholders: false }).run() ``` 当省略 `placeholders` 时，如果安装了 Pages 扩展，命令默认会启用该功能，除非你通过 `Pages.configure({ placeholders: false })` 禁用了令牌替换，在这种情况下它会保持关闭。传入 `true`（或显式的 `{ page?, total? }` 重命名映射）可强制启用翻译，其中重命名映射的优先级高于编辑器的 Pages 配置。 ## 脚注和尾注 导入 API 会从 DOCX 文件中提取脚注和尾注内容。文档正文中的内联引用会表示为 `footnoteReference` 和 `endnoteReference` 节点，每个节点都带有一个 `noteId` 属性，且注释内容会以这些 id 为键进行提供。 `onImport` 回调的 `ImportContext` 同时包含这两组数据： ```js editor .chain() .importDocx({ file, onImport(context) { if (context.error) return context.footnotes // Record, 每个 id 对应的脚注内容 context.endnotes // Record, 每个 id 对应的尾注内容 context.setEditorContent(context.content) }, }) .run() ``` > **与 Tiptap Pages 自动应用:** > > 当 [Pages 扩展](https://tiptap.zhcndoc.com/pages/getting-started/overview.md) 与 > [脚注](https://tiptap.zhcndoc.com/pages/core-concepts/footnotes.md) 和/或 [尾注](https://tiptap.zhcndoc.com/pages/core-concepts/endnotes.md) > 一起启用时，导入的注释会自动应用：标记会在正文中渲染，脚注内容会进入每页的脚注区域， > 尾注内容会进入文档末尾的尾注列表，并且编号与源文档保持一致。无需额外配置。 如果不使用 Pages，`footnoteReference` / `endnoteReference` 节点需要一个[自定义扩展](https://tiptap.zhcndoc.com/editor/extensions/custom-extensions/extend-existing.md)才能在编辑器中渲染。`ImportContext` 上的数据已经提供了构建你自己的展示所需的一切。 ## 详细输出 DOCX 导入扩展提供了一个 `verbose` 配置属性，用于帮助你控制导入过程中诊断输出的级别。这对于调试或更深入地了解转换过程中发生了什么特别有用。 `verbose` 属性是一个位掩码数字，用于确定输出哪些类型的日志消息。该扩展使用以下级别： | 值 | 级别 | 描述 | | - | ------- | ------ | | 1 | `log` | 一般信息日志 | | 2 | `warn` | 警告 | | 4 | `error` | 错误 | > **详细输出位掩码:** > > 你可以将各级别的值相加来组合它们。例如，`verbose: 3` 将同时启用 > `log`（1）和 `warn`（2）消息。 详细输出除了 `data` 属性之外，还会再提供一个名为 `logs` 的属性，其中包含 `info`、`warn` 和 `error` 属性；它们各自都是数组，包含与对应详细级别相关的全部信息。 ```js { "data": { "content": { // Tiptap JSON } }, "logs": { "info": [], "warn": [ { "message": "在媒体文件中未找到图像文件", "fileName": "image1.gif", "availableMediaFiles": [] } ], "error": [ { "message": "图像上传失败：一般错误", "fileName": "image1.gif", "url": "https://your-image-upload-endpoint.com", "error": "无法连接。计算机是否可以访问该 url？", "context": "上传图像时发生一般错误" } ] } } ``` ## 支持与限制 有关管道各阶段支持哪些文档特性的详细说明，请参见[支持的特性](https://tiptap.zhcndoc.com/conversion/getting-started/feature-support-matrix.md)矩阵。