在编辑器中导入 .docx

Available in Start planBeta

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

如果你需要在编辑器外导入 .docx 内容，请使用REST API。

安装 DOCX 导入扩展

转换扩展发布在 Tiptap 的私有 npm 注册表中。按照私有注册表指南集成扩展。

安装 Tiptap 导入扩展包：

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

确保你的编辑器包含处理 DOCX 内容所需的所有 Tiptap 扩展。例如，包含图像扩展以处理行内图像，和表格扩展以处理表格。

所需扩展

为了完全映射 DOCX 内容（例如图像、表格、格式化文本）到 Tiptap 的架构中，必须包含相关的 Tiptap 扩展。没有这些扩展，某些 DOCX 元素可能不会被编辑器识别或正确呈现。

import StarterKit from '@tiptap/starter-kit'
import Color from '@tiptap/extension-color'
import FontFamily from '@tiptap/extension-font-family'
import Highlight from '@tiptap/extension-highlight'
import { Image } from '@tiptap/extension-image'
import Link from '@tiptap/extension-link'
import Paragraph from '@tiptap/extension-paragraph'
import Table from '@tiptap/extension-table'
import TableCell from '@tiptap/extension-table-cell'
import TableHeader from '@tiptap/extension-table-header'
import TableRow from '@tiptap/extension-table-row'
import TextAlign from '@tiptap/extension-text-align'
import TextStyle from '@tiptap/extension-text-style'
import Underline from '@tiptap/extension-underline'

配置

将导入扩展添加到你的编辑器设置中。

// 导入导入扩展
import { Import } from '@tiptap-pro/extension-import-docx'

const editor = new Editor({
  extensions: [
    // 其他扩展 ...
    Import.configure({
      appId: 'your-app-id', // 你的转换应用 ID（见 Tiptap Cloud 设置）
      token: 'your-jwt-token', // 用于身份验证的 JWT（见身份验证文档）
      imageUploadCallbackUrl: 'https://your-image-upload-endpoint.com', // 你的图像上传端点
    })
    // 其他扩展 ...
  ],
  // 其他编辑器设置 ...
})

属性	描述
`appId`	你的 Tiptap 转换应用的 ID（在你的 Tiptap 账户的转换设置中查找）
`token`	由你的服务器为转换服务生成的 JWT 身份验证令牌。（有关获取和使用这些凭据的详细信息，请参见身份验证指南。）
`imageUploadCallbackUrl`	上传 DOCX 中找到的图像的端点。转换服务将把每个嵌入图像发送到此 URL，并在内容中使用返回的 URL。无法处理的任何图像将被删除。

导入 DOCX 文件

扩展配置完成后，可以导入用户选择的 DOCX 文件。

基本导入

最简单的方法是将文件直接传递给 import 命令。在这里，它用转换的内容替换当前的编辑器内容并聚焦编辑器：

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

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

导入处理

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

editor
  .chain()
  .import({
    file,
    onImport(context) {
      const { setEditorContent, content, error } = context

      // 添加错误处理
      if (error) {
        showErrorToast({ message: error.message })
      }

      // 在插入之前，你也可以修改内容
      content.doc.content.push({ type: 'paragraph', content: [{ type: 'text', text: '你好!' }] })

      // 例如，你可以更改应用的加载状态
      isLoading = false

      // 在编辑器中执行插入
      editor.commands.setEditorContent(content)
    },
  })
  .focus()
  .run()

我们在上面的例子中控制的操作：

操作	描述
错误处理	如果转换失败，可以显示一个提示或记录错误。
内容修改	可以插入额外的节点、删除某些节点，或根据需要调整转换后的 Tiptap JSON。
编辑器插入	如果希望依赖扩展的默认插入行为（替换编辑器内容），可以调用回调中提供的 `setEditorContent()` 函数。如果你自己修改内容，必须手动使用 `editor.commands.setContent(content)` 设置它。

支持 & 限制

将 .docx 文件导入 Tiptap 提供了一种处理大多数标准 Word 内容的方法，但 这并不是一对一的映射，因为 DOCX 格式和 Tiptap 基于 CSS 的样式之间存在固有差异。

当前支持的功能和已知限制：

功能	支持
文本内容	✓ 基本金本文字、间距、标点
文本格式	✓ 粗体、斜体、下划线、删除线、对齐、行高
块元素	✓ 段落、标题（1-6）、引用、编号和未编号列表
表格	✓ 基本结构、表头行、跨列
链接	✓ 超链接
媒体（图像)	✓ 嵌入图像，尺寸保留
样式	✓ 字体系列*、字体颜色、字体大小、背景颜色、行高
页眉和页脚	~ 开发中
部分和分页	~ 开发中
脚注和尾注	~ 开发中
数学	~ 开发中
评论和修订	✗
目录	✗
高级格式	✗ 列、文本方向、表单、宏、嵌入脚本
元数据	✗
文本框、形状、智能图形	✗

* 字体系列在打开 .docx 文件时，目标字体安装在操作系统上时会被支持。