在编辑器中导入 .docx

Available in Start planBetav0.11.0

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

使用 @tiptap-pro/extension-import-docx 编辑器扩展将 .docx 文件转换为 Tiptap JSON 非常简单，该扩展可直接集成到您的 Tiptap 编辑器中。

您也可以通过 REST API 导入。这两种方式使用相同的转换服务，并生成完全相同的内容输出。主要区别如下：

	编辑器扩展	REST API
运行位置	您的编辑器（客户端）	Tiptap 云（服务端）
脚注和尾注	通过 Pages 自动应用；数据在回调中提供	在响应中返回
页眉和页脚	通过 Pages 扩展自动应用	作为单独的数据字段返回
未知内容	按您的编辑器架构重新写入	原始 JSON，不进行架构过滤

如果您需要服务端处理或原始未过滤的 JSON，请选择 REST API。

安装 DOCX Import 扩展

Conversion 扩展发布在 Tiptap 的私有 npm 注册表中。请按照私有注册表指南集成这些扩展。

安装 Tiptap Import 扩展包：

npm i @tiptap-pro/extension-import-docx

请确保您的编辑器包含处理 DOCX 内容所需的所有 Tiptap 扩展。完整的扩展列表、配置以及各自处理的内容，请参见 ConvertKit 页面。

所需扩展

安装 ConvertKit：它捆绑了导入器所需的每个扩展：标准节点和 mark，TextStyleKit 用于颜色/字体/大小/行高/背景，预配置为 ['paragraph', 'heading'] 的 TextAlign，带有 multicolor: true 的 Highlight，带有 DOCX 裁剪属性的 Image，用于支持 DOCX 的表格的 ConvertTableKit，以及 PageBreak：

import { ConvertKit } from '@tiptap-pro/extension-convert-kit'

new Editor({ extensions: [ConvertKit] })

如果您需要将捆绑扩展中的某一个替换为自己的实现，可以通过 ConvertKit.configure({ slot: false }) 禁用任意单个 slot（例如，与 Pages extension 配合时，设置 table: false，并改为注册来自 @tiptap-pro/extension-pages-tablekit 的 TableKit）。完整的 slot 列表请参见 ConvertKit reference。

配置

将 Import 扩展添加到您的编辑器设置中。

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 身份验证令牌。（有关如何获取和使用这些凭据的详情，请参见身份验证指南。）
`imageUploadConfig`	用于导入过程中图片上传的结构化配置。详情请参见图片上传配置。
`verbose`	一个 `string \| number` 配置属性，可帮助您控制导入过程中的诊断输出级别。这对于调试或更深入了解转换过程中发生的情况特别有用。更多信息请参见详细输出

图片上传配置

imageUploadConfig 选项让您可以配置转换服务如何将 DOCX 文件中找到的图片上传到您的服务器。这取代了已弃用的 imageUploadCallbackUrl 字符串选项，并使您能够完全控制请求头、HTTP 方法和查询参数。

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<string, string>`	否	由转换服务附加到上传 URL 的查询参数。

从 imageUploadCallbackUrl 迁移

imageUploadCallbackUrl 选项已弃用。请改用 imageUploadConfig：

// 之前（已弃用）
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 命令。在这里，它会用转换后的内容替换当前编辑器内容，并聚焦编辑器：

editor.chain().focus().importDocx({ file }).run()

在大多数情况下，这一行代码就足以让用户导入 .docx 文件。该扩展会负责将文件发送到转换端点、获取转换后的 Tiptap JSON，并将其插入编辑器。

导入处理

为了在导入过程结束后拥有更多控制权，您可以使用 onImport 回调来处理转换结果。此回调会提供转换后的内容、发生的任何错误，以及一个名为 setEditorContent 的函数，用于将 context.content 中的内容插入编辑器。如果您不提供 onImport 回调，扩展会自动将内容插入编辑器，但您将无法处理错误或加载状态等其他事项。

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 扩展，导入扩展会自动检测并应用它们。没有 Pages 时，页眉/页脚数据仍会返回给你的 onImport 回调（见下方手动处理），但没有地方可以渲染。请安装 Pages 以便它们在编辑器中可见。

自动处理

如果你的编辑器中注册了 Pages 扩展，在调用 setEditorContent() 时，页眉和页脚会自动应用：

editor
  .chain()
  .importDocx({
    file,
    onImport(context) {
      if (context.error) {
        console.error(context.error)
        return
      }

      // 页眉和页脚会与正文内容一起自动应用
      context.setEditorContent()
    },
  })
  .focus()
  .run()

如果没有安装 Pages 扩展，页眉和页脚数据仍可在 onImport 回调中获取，但不会自动应用到编辑器中。

手动处理

onImport 回调提供所有页眉和页脚字段，供手动处理：

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 扩展时，importDocx 会将这些字段转换为与你当前 Pages 注册表匹配的文本令牌（开箱即用为 {page} 和 {total}），从而在重新导出为 Word 时能够无缝地还原为实时字段，无需额外配置。

当您重命名这些内置占位符时，导入器会将您的注册表转发给转换服务，以便输出相同的名称：

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 扩展时很有用：

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 同时包含这两组数据：

editor
  .chain()
  .importDocx({
    file,
    onImport(context) {
      if (context.error) return

      context.footnotes // Record<noteId, JSONContent>, 每个 id 对应的脚注内容
      context.endnotes // Record<noteId, JSONContent>, 每个 id 对应的尾注内容

      context.setEditorContent(context.content)
    },
  })
  .run()

与 Tiptap Pages 自动应用

当 Pages 扩展与脚注和/或尾注一起启用时，导入的注释会自动应用：标记会在正文中渲染，脚注内容会进入每页的脚注区域，尾注内容会进入文档末尾的尾注列表，并且编号与源文档保持一致。无需额外配置。

如果不使用 Pages，footnoteReference / endnoteReference 节点需要一个自定义扩展才能在编辑器中渲染。ImportContext 上的数据已经提供了构建你自己的展示所需的一切。

详细输出

DOCX 导入扩展提供了一个 verbose 配置属性，用于帮助你控制导入过程中诊断输出的级别。这对于调试或更深入地了解转换过程中发生了什么特别有用。

verbose 属性是一个位掩码数字，用于确定输出哪些类型的日志消息。该扩展使用以下级别：

值	级别	描述
1	`log`	一般信息日志
2	`warn`	警告
4	`error`	错误

详细输出位掩码

你可以将各级别的值相加来组合它们。例如，verbose: 3 将同时启用 log（1）和 warn（2）消息。

详细输出除了 data 属性之外，还会再提供一个名为 logs 的属性，其中包含 info、warn 和 error 属性；它们各自都是数组，包含与对应详细级别相关的全部信息。

{
  "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": "上传图像时发生一般错误"
      }
    ]
  }
}

支持与限制

有关管道各阶段支持哪些文档特性的详细说明，请参见支持的特性矩阵。

Previously支持功能

Next upConvertKit