从编辑器导出 DOC

Available in Start planBetav0.3.0

建议改用 DOCX

DOC 格式是来自 Microsoft Word 97-2003 的旧版格式。对于现代用途，我们建议改为导出为 DOCX。仅当兼容旧系统有要求时才使用 DOC。

使用 Tiptap 的 @tiptap-pro/extension-export-doc 将编辑器内容导出为 .doc 文件。此扩展通过将文档发送到 Tiptap 转换服务进行转换，将 DOC 导出功能集成到你的编辑器中。

如果你更愿意自行处理转换，也可以改用 REST API。

安装 DOC 导出扩展

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

完成后，你可以安装并导入 Export DOC 扩展包。

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

import { ExportDoc } from '@tiptap-pro/extension-export-doc'

配置扩展

ExportDoc 扩展可以通过 ExportDocOptions（object）作为 configure 方法的参数进行配置，包含以下属性：

import { ExportDoc } from '@tiptap-pro/extension-export-doc'

const editor = new Editor({
  extensions: [
    // 其他扩展 ...
    ExportDoc.configure({
      endpoint: 'https://api.tiptap.dev/v2/convert',
      token: 'YOUR_TOKEN',
      appId: 'YOUR_APP_ID',
      styleOverrides: {},
      headers: {},
      footers: {},
      pageSize: { width: '21cm', height: '29.7cm' },
      pageMargins: { top: '1cm', bottom: '1cm', left: '1cm', right: '1cm' },
      customNodes: [],
      onCompleteExport: (result) => {
        // 处理导出的 Blob
      },
    }),
    // 其他扩展 ...
  ],
})

参数	类型	描述	默认值
`endpoint`	`string`	用于转换的 Tiptap API 端点	`'https://api.tiptap.dev/v2/convert'`
`token`	`string`	用于认证的 Tiptap JWT	`''`
`appId`	`string`	用于认证的 Tiptap App ID	`''`
`styleOverrides`	`Record<string, string>`	要应用于导出的样式覆盖	`undefined`
`headers`	`HeaderConfig`	导出文档的页眉配置	`undefined`
`footers`	`FooterConfig`	导出文档的页脚配置	`undefined`
`pageSize`	`PageSize`	页面尺寸配置	`undefined`
`pageMargins`	`PageMargins`	页面边距配置	`undefined`
`customNodes`	`CustomNodeDefinition[]`	基于 DOCX 转换的自定义节点定义（需要 `@tiptap-pro/extension-export-docx`）	`undefined`
`onCompleteExport`	`(result: Blob) => void`	接收导出文件 Blob 的回调	如果未提供则抛出错误

HeaderConfig

属性	类型	描述
`evenAndOddHeaders`	`boolean`	是否为奇数页和偶数页使用不同的页眉
`differentFirstPage`	`boolean`	是否在第一页使用不同的页眉。为 `true` 时，第一页使用 `first` 值而不是 `default`。
`default`	`string`	每页的标准默认页眉，或者在启用 `evenAndOddHeaders` 时用于奇数页的页眉。接受纯文本字符串或序列化后的 Tiptap JSONContent 以支持富格式。
`first`	`string`	第首页眉。仅在 `differentFirstPage` 设置为 `true` 时使用。接受纯文本字符串或序列化后的 Tiptap JSONContent 以支持富格式。
`even`	`string`	启用 `evenAndOddHeaders` 选项时偶数页的页眉。接受纯文本字符串或序列化后的 Tiptap JSONContent 以支持富格式。

FooterConfig

属性	类型	描述
`evenAndOddFooters`	`boolean`	是否为奇数页和偶数页使用不同的页脚
`differentFirstPage`	`boolean`	是否在第一页使用不同的页脚。为 `true` 时，第一页使用 `first` 值而不是 `default`。
`default`	`string`	每页的标准默认页脚，或者在启用 `evenAndOddFooters` 时用于奇数页的页脚。接受纯文本字符串或序列化后的 Tiptap JSONContent 以支持富格式。
`first`	`string`	第首页脚。仅在 `differentFirstPage` 设置为 `true` 时使用。接受纯文本字符串或序列化后的 Tiptap JSONContent 以支持富格式。
`even`	`string`	启用 `evenAndOddFooters` 选项时偶数页的页脚。接受纯文本字符串或序列化后的 Tiptap JSONContent 以支持富格式。

PageSize

属性	类型	描述	默认值
`width`	`string`	页面宽度。必须是一个正数，后跟有效单位（cm、in、pt、pc、mm、px）。	`"21cm"`
`height`	`string`	页面高度。必须是一个正数，后跟有效单位（cm、in、pt、pc、mm、px）。	`"29.7cm"`

PageMargins

属性	类型	描述	默认值
`top`	`string`	页面的上边距。可以为负数。必须是一个数字，后跟有效单位（cm、in、pt、pc、mm、px）。	`"1cm"`
`bottom`	`string`	页面的下边距。可以为负数。必须是一个数字，后跟有效单位（cm、in、pt、pc、mm、px）。	`"1cm"`
`left`	`string`	页面的左边距。必须是一个正数，后跟有效单位（cm、in、pt、pc、mm、px）。	`"1cm"`
`right`	`string`	页面的右边距。必须是一个正数，后跟有效单位（cm、in、pt、pc、mm、px）。	`"1cm"`

导出 DOC 文件

安装扩展后，你可以使用 exportDoc 命令将编辑器内容导出为 .doc。

/**
 * 通过 Tiptap 转换服务将当前文档导出为 DOC 文件。
 *
 * @param options - 所有扩展级别的选项都可以在每次调用时覆盖
 * @example editor.commands.exportDoc({ onCompleteExport: (result) => {} })
 */
exportDoc: (options?: ExportDocCommandOptions) => ReturnType

ExportDocCommandOptions 接口扩展了 ExportDocOptions，因此每个配置项都可以在每次命令调用时覆盖：

属性	类型	描述
`endpoint`	`string`	为此次特定导出覆盖 API 端点
`token`	`string`	为此次特定导出覆盖 JWT 令牌
`appId`	`string`	为此次特定导出覆盖 App ID
`styleOverrides`	`Record<string, string>`	为此次特定导出覆盖样式覆盖
`headers`	`HeaderConfig`	为此次特定导出覆盖页眉配置
`footers`	`FooterConfig`	为此次特定导出覆盖页脚配置
`pageSize`	`PageSize`	为此次特定导出覆盖页面尺寸
`pageMargins`	`PageMargins`	为此次特定导出覆盖页面边距
`customNodes`	`CustomNodeDefinition[]`	为此次特定导出覆盖自定义节点定义
`onCompleteExport`	`(result: Blob) => void`	为此次特定导出覆盖回调

import { ExportDoc } from '@tiptap-pro/extension-export-doc'

const editor = new Editor({
  extensions: [
    // 其他扩展 ...
    ExportDoc.configure({
      token: 'YOUR_TOKEN',
      appId: 'YOUR_APP_ID',
      onCompleteExport(result) {
        // 下载 DOC 文件
        const url = URL.createObjectURL(result)
        const a = document.createElement('a')

        a.href = url
        a.download = 'document.doc'
        a.click()

        URL.revokeObjectURL(url)
      },
    }),
    // 其他扩展 ...
  ],
})

// 使用扩展级回调
editor.chain().exportDoc().run()

// 或为某个特定导出覆盖选项
editor
  .chain()
  .exportDoc({
    pageSize: { width: '8.5in', height: '11in' },
    onCompleteExport(result) {
      // 针对此次特定导出的自定义处理
      const url = URL.createObjectURL(result)
      window.open(url)
    },
  })
  .run()

工作原理

当你调用 exportDoc 时，扩展会将编辑器文档以及任何已配置的选项（样式覆盖、页面布局、页眉、页脚）发送到 Convert 服务，随后返回生成的 .doc 文件作为二进制 blob。onCompleteExport 回调会直接接收该 blob。错误会作为异常抛出，而不会通过回调传递。

预期内容

需要身份验证（token JWT 和 appId）。请在服务器端生成 JWT。请参阅 Conversion 安装指南。
需要处理的 HTTP 响应： 401（缺少或无效的 JWT）、403（该操作对你的应用不允许——通常是你的计划不包含的格式）、5xx（瞬态服务器端错误；请使用退避重试）。
每个请求都会在响应前端到端处理完成。 对于大型文档，请预留更长的往返时间。

不应期待的内容

往返一致性。 DOC 是一种 1997–2003 年的二进制格式，具有其自身的渲染特性；我们的目标是忠实呈现，而不是字节级完全一致的输出。
现代 Word 功能。 DOC 早于许多 Word 功能；高级布局、批注、修订和带样式的元数据都会被简化或移除。在面向现代 Word 版本时，请使用 DOCX。

支持与限制

功能	支持
文本内容	✓ 基本文本、间距、标点符号
文本格式	✓ 加粗、斜体、下划线、删除线、对齐、行高
块元素	✓ 段落、标题（1–6）、引用块、有序列表和无序列表
表格	✓ 基本结构、表头行、colspan
链接	✓ 超链接
媒体（图片）	✓ 嵌入图片、保留尺寸
样式	✓ 字体族*、字体颜色、字体大小、背景颜色、行高
页眉和页脚	✓
数学	✓
分页符	✓
分节	✗
脚注与尾注	✗
批注与修订	✗
目录	✗
高级格式设置	✗ 栏、文字方向、表单、宏、嵌入脚本
元数据	✗
文本框、形状、SmartArt	✗

只要在打开导出文件时，目标字体安装在操作系统上，就支持字体族。

有关更详细的逐项功能说明，请参阅支持的功能矩阵。请注意，DOCX 导出扩展中可用的元素覆盖（paragraphOverrides、textRunOverrides、tableOverrides、tableCellOverrides、imageOverrides）不会传递到 DOC 转换中。

PreviouslyREST API

Next upREST API