---
title: "从编辑器导出 DOC"
description: "了解如何在我们的文档中使用 Export DOC 扩展将 Tiptap 编辑器内容导出为 DOC（旧版 Word）文件。"
canonical_url: "https://tiptap.zhcndoc.com/conversion/export/doc/editor-extension"
---

# 从编辑器导出 DOC

了解如何在我们的文档中使用 Export DOC 扩展将 Tiptap 编辑器内容导出为 DOC（旧版 Word）文件。

- **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:** [ExportDoc](https://embed-pro.tiptap.dev/preview/Extensions/ExportDoc)

> **建议改用 DOCX:**
>
> DOC 格式是来自 Microsoft Word 97-2003 的旧版格式。对于现代用途，我们建议改为导出为
> [DOCX](https://tiptap.zhcndoc.com/conversion/export/docx/editor-extension.md)。仅当兼容旧系统有要求时才使用 DOC。

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

如果你更愿意自行处理转换，也可以改用 [REST API](https://tiptap.zhcndoc.com/conversion/export/doc/rest-api.md)。

## 安装 DOC 导出扩展

转换扩展发布在 Tiptap 的私有 npm 注册表中。请按照 [私有注册表指南](https://tiptap.zhcndoc.com/guides/pro-extensions.md) 集成这些扩展。

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

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

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

## 配置扩展

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

```ts
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',
      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                                           | `''`                                  |
| `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`。

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

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

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

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

const editor = new Editor({
  extensions: [
    // 其他扩展 ...
    ExportDoc.configure({
      token: 'YOUR_TOKEN',
      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）。在服务端生成 JWT。请参阅 [Conversion 安装指南](https://tiptap.zhcndoc.com/conversion/getting-started/install.md)。
- **需要处理的 HTTP 响应：**`401`（缺少或无效的 JWT）、`403`（此操作不适用于你的应用——通常是你的套餐不包含的格式）、`5xx`（临时性的服务器端错误；使用退避重试）。
- **每个请求在响应之前都会端到端完成处理。** 对于大型文档，请预留更长的往返时间。

## 不应期待的内容

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

## 支持与限制

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

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

有关更详细的逐项功能说明，请参阅 [支持的功能](https://tiptap.zhcndoc.com/conversion/getting-started/feature-support-matrix.md) 矩阵。请注意，[DOCX 导出扩展](https://tiptap.zhcndoc.com/conversion/export/docx/editor-extension.md) 中可用的元素覆盖（`paragraphOverrides`、`textRunOverrides`、`tableOverrides`、`tableCellOverrides`、`imageOverrides`）不会传递到 DOC 转换中。