从编辑器导出 .docx

Available in Start planBeta

使用 Tiptap 的 @tiptap-pro/extension-export-docx 扩展将编辑器内容导出为 .docx 文件。该扩展将 DOCX 导出功能集成到您的编辑器中。

您可以在任何 JavaScript 环境使用此扩展，包括服务器端应用程序，这受益于 exportDocx 函数的同构特性。

如果您更倾向于在我们的服务端处理转换，也可以使用 REST API。

默认情况下，该扩展将 Tiptap 节点映射为 DOCX 元素。如果您的内容包含自定义节点，请配置它们的导出行为，确保正确转换。

安装 DOCX 导出扩展

转换扩展发布在 Tiptap 私有 npm 注册表中。请遵循私有注册表指南完成集成。

完成后，您可以安装并导入 Export DOCX 扩展包：

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

使用导出扩展不需要任何 Tiptap 转换凭据，因为转换在扩展内部即时处理。

import { ExportDocx } from '@tiptap-pro/extension-export-docx'

配置扩展

ExportDocx 扩展可以通过 ExportDocxOptions （object）作为 configure 方法的参数进行配置，参数具有以下属性：

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

const editor = new Editor({
  extensions: [
    // 其他扩展 ...
    ExportDocx.configure({
      onCompleteExport: (result: string | Buffer<ArrayBufferLike> | Blob | Stream) => void, // 必填
      exportType: 'blob', // 可选。默认值：'blob'
      customNodes: [], // 可选。默认值：[]
      styleOverrides: {}, // 可选。默认值：{}
    }),
    // 其他扩展 ...
  ],
  // 其他编辑器配置 ...
})

参数	描述	默认值
onCompleteExport	一个必填的回调函数，接收导出的数据。您可以根据需求处理数据（例如，提示文件下载）	N/A
options	一个对象，用于配置导出行为： exportType：返回数据类型： - buffer：返回 Node.js `Buffer`（仅服务器端） - stream：返回 Node.js `Stream`（仅服务器端） - string：返回一个字符串 - blob：返回一个 `Blob`	'blob'
customNodes	自定义节点定义数组。如果内容含自定义节点，请传入定义以确保正确转换	[]
styleOverrides	用于覆盖导出文档默认样式的对象

导出 DOCX 文件

安装扩展后，您可以将编辑器内容导出为 .docx 文件。

先查看可在编辑器命令中使用的 exportDocx 方法签名：

/**
* 导出当前文档为 .docx 文件
*
* 注意：服务器环境中支持 'buffer' 和 'stream' 导出类型
* 因为它们分别利用了 Node.js 的 Buffer 和 Stream API
*
* @param onCompleteExport - 回调函数以处理导出结果
* @param options - 导出选项
* @param customNodes - 自定义节点定义
* @param styleOverrides - 导出文档样式覆盖
* @example editor.commands.exportDocx((result) => {}, { exportType: 'buffer' }, [])
*
*/
exportDocx: (options?: ExportDocxOptions) => Promise<string | Buffer<ArrayBufferLike> | Blob | Stream>

exportDocx 方法接受一个可选的 ExportDocxOptions （object），属性可用于覆盖您通过 ExportDocx.configure 配置的选项：

参数	描述	默认值
onCompleteExport	一个必填的回调函数（若未在配置中定义），用于接收导出的数据。您可据需处理(如提示下载)	N/A
options	用于配置导出行为： exportType：返回数据类型类型： - buffer：返回 Node.js `Buffer`（仅服务器端） - stream：返回 Node.js `Stream`（仅服务器端） - string：返回字符串 - blob：返回 `Blob`	'blob'
customNodes	自定义节点定义数组。如果包含自定义节点，请传入定义以确保转换正确	[]
styleOverrides	用于覆盖导出文档默认样式的对象

示例如下：

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

// 设置编辑器
const editor = new Editor({
  extensions: [
    // 其他扩展 ...
    ExportDocx.configure({
      onCompleteExport: (result: string | Buffer<ArrayBufferLike> | Blob | Stream) => {}, // 必填
      exportType: 'blob', // 可选，默认: 'blob'
      customNodes: [], // 可选，默认: []
      styleOverrides: {}, // 可选，默认: {}
    }),
    // 其他扩展 ...
  ],
  // 其他编辑器配置 ...
})

// 声明调用编辑器导出方法的函数

function handleExportDocx() {
  // 调用编辑器的 exportDocx 方法
  editor
    .chain()
    // 企业配置中定义的选项，无覆盖
    .exportDocx()
    .run()
}

function handleExportDocxBuffer() {
  // 调用编辑器的 exportDocx 方法，带覆盖
  editor
    .chain()
    // 覆盖部分设置
    .exportDocx({
      // 覆盖 onCompleteExport 回调处理 Buffer 类型导出
      onCompleteExport: (result: Buffer) => {
        // 处理导出的缓冲数据
      },
      // 覆盖导出类型
      exportType: 'Buffer',
    })
    .run()
}

// 在应用任意位置调用这些函数
handleExportDocx()
handleExportDocxBuffer()

工作原理

上述示例完整运行于浏览器，ExportDocx 扩展生成一个 DOCX Blob。由于未覆写导出类型，采用默认的 blob。然后以编程方式触发文件下载。您也可以修改逻辑，例如，将 blob 上传至服务器，而非直接下载。

参数	描述
onCompleteExport	转换完成时会获得转换结果 `result`，作为回调函数的唯一参数。在此示例中因 exportType 为 `blob`，result 即是一个 `Blob`。您可以按需处理，如触发文件下载。
exportType	此示例中使用默认 `blob`，转换返回一个 `Blob`。
customNodes	此示例中未传入任何自定义节点定义。
styleOverrides	未传入任何样式覆盖，导出文档将应用 Microsoft Word 默认样式的通用规则。

服务器端导出

对于需要复杂文档生成或减轻客户端包体积的应用，您可以在服务器端导出 .docx 文件。

您需从 @tiptap-pro/extension-export-docx 包中导入 exportDocx 函数，将 Tiptap JSON 格式内容传入，并将结果返回给客户端。

先看下 exportDocx 函数签名：

/**
 * 导出当前文档为 .docx 文件
 *
 * 注意：服务器环境中支持 'buffer' 和 'stream' 导出类型
 * 因为它们分别利用 Node 的 Buffer 和 Stream API
 *
 * @param options.document - 文档的 JSON 表示
 * @param options.exportType - 导出类型
 * @param options.customNodes - 自定义节点定义
 * @param options.styleOverrides - 样式覆盖
 * @example exportDocx({ document: editor.getJSON(), exportType: 'blob', customNodes: [], styleOverrides: {} })
 */
async function exportDocx ({ document, exportType, customNodes, styleOverrides }: ExportDocxOptions) {}

exportDocx 函数将返回一个准备好的 DOCX 文档，以多种格式输出。

以下是使用 Express 和 @tiptap-pro/extension-export-docx 在服务器端导出简单示例：

import { exportDocx } from '@tiptap-pro/extension-export-docx'
import express from 'express'

const app = express()

app.post('/export-docx', async (req, res) => {
  try {
    // 从请求获取 Tiptap JSON 内容，或从数据库读取
    const { content } = req.body

    // 转换为 DOCX Buffer
    const docxBuffer = await exportDocx({ document: content })

    // 作为下载文件发送
    res.setHeader('Content-Type', 'application/vnd.openxmlformats-officedocument.wordprocessingml.document')
    res.setHeader('Content-Disposition', 'attachment; filename="document.docx"')
    res.send(docxBuffer)
  } catch (error) {
    res.status(500).json({ error: error.message })
  }
})

支持与限制

从 Tiptap JSON 导出 .docx 文件能满足处理大多数标准 Word 内容需求，但由于 DOCX 格式与基于 CSS 的 Tiptap 样式间固有限制，不存在一对一完美映射。

当前支持功能及已知限制：

功能	支持情况
文本内容	✓ 基本文字、间距、标点
文本格式	✓ 粗体、斜体、下划线、删除线、对齐、行距
块级元素	✓ 段落、标题（1–6 级）、引用、序列列表及无序列表
表格	✓ 基础结构、表头行、跨列
链接	✓ 超链接
媒体（图片）	✓ 内嵌图片，保持大小
样式	✓ 字体系列*、字体颜色、字体大小、背景色、行距
页眉和页脚	~ 正在开发
分节和分页	~ 正在开发
脚注和尾注	~ 正在开发
数学公式	~ 正在开发
评论和修订	✗ 不支持
目录	✗ 不支持
高级格式	✗ 列、文本方向、表单、宏、嵌入脚本等不支持
元数据	✗ 不支持
文本框、形状、SmartArt	✗ 不支持

* 字体系列支持前提是目标字体已安装于打开 .docx 文件的操作系统中。