---
title: "旧版 DOCX 导入与导出"
description: "查看如何配置旧版导入和导出扩展以及 REST API 端点。更多内容请参阅文档。"
canonical_url: "https://tiptap.zhcndoc.com/conversion/legacy/overview"
---

# 旧版 DOCX 导入与导出

查看如何配置旧版导入和导出扩展以及 REST API 端点。更多内容请参阅文档。

Tiptap 原始的 `extension-import` 和 `extension-export` 包提供了可靠的方法来导入和导出 DOCX 文件。

这些扩展及相关端点仍对所有拥有 Tiptap 账户的用户开放，但已不再积极开发。

它们将于 2025 年晚些时候正式退役，并由新的 [Tiptap 转换](https://tiptap.zhcndoc.com/conversion/getting-started/overview.md) 扩展和服务取代。

> **从旧版扩展迁移:**
>
> 有关迁移到特定格式的 Conversion 扩展和 `/v2/` REST 端点的分步说明，请参阅 [迁移指南](https://tiptap.zhcndoc.com/conversion/legacy/migration-guide.md)。

> **默认端点已不再托管:**
>
> 旧版 `extension-import` 和 `extension-export` 包会将 `endpoint` 选项默认设为
> `/v1/convert`，但 Conversion 服务已不再托管该端点。现有集成必须显式传入
> `endpoint: 'https://api.tiptap.dev/v2/convert'`（并接受下文所述的响应结构差异），
> 或迁移到特定格式的 Conversion 扩展。

以下指南重点介绍如何配置旧版扩展。

## 导入旧版扩展

> **旧版导入扩展（已弃用）:**
>
> **extension-import** 包已弃用，不会再获得新功能；在移除旧版端点之前，我们会提前 90 天通知。
> 请迁移到我们的[更新方案](https://tiptap.zhcndoc.com/conversion/getting-started/overview.md)，以确保服务不中断。

```js
// 首先导入扩展
import { Import } from '@tiptap-pro/extension-import'

const editor = new Editor({
  // ...
  extensions: [
    // ...
    Import.configure({
      // 从转换设置页面获取的 Convert App-ID：https://cloud.tiptap.dev/convert-settings
      appId: 'your-app-id',

      // 之前步骤生成的 JWT 令牌
      token: 'your-jwt',

      // 图片上传的 URL，若未提供，文档中的图片将被移除
      imageUploadCallbackUrl: 'https://your-image-upload-url.com',

      // 启用实验性的 DOCX 导入功能，更好地保留内容样式
      experimentalDocxImport: true,
    }),
  ],
})
```

### 导入第一个文档

```js
// 最简单的文件导入方式
// 导入上传的文件，替换编辑器内容并聚焦编辑器
editor.chain().focus().import({ file }).run()
```

#### 自定义导入行为

```js
// 也可以使用 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: 'Hello!' }] })

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

      // 如果希望运行扩展的默认插入行为，确保调用 setEditorContent 函数
      // setEditorContent()
      // 由于我们修改了内容，需要手动插入
      editor.commands.setContent(content)
    },
  })
  .focus()
  .run()
```

### 导入选项

| Name                     | Type       | Default     | Description                                                                                              |
| ------------------------ | ---------- | ----------- | -------------------------------------------------------------------------------------------------------- |
| `appId`                  | `string`   | `undefined` | 转换应用的 ID，来自转换设置页面：[https://cloud.tiptap.dev/convert-settings](https://cloud.tiptap.dev/convert-settings) |
| `token`                  | `string`   | `undefined` | 通过你的服务器生成的 JWT                                                                                           |
| `imageUploadCallbackUrl` | `string`   | `undefined` | 用于上传图片的 URL；如果未提供，图片将从文档中移除                                                                              |
| `experimentalDocxImport` | `boolean ` | `false`     | 启用实验性的 DOCX 导入，以更好地保留内容样式（实验性功能，此 API 在 alpha 阶段可能并不完全稳定），仅适用于上传的 DOCX 文件                                |

### 命令

| 名称       | 描述       |
| -------- | -------- |
| `import` | 将文件导入编辑器 |

#### `import`

##### 参数

| 名称         | 类型         | 默认值         | 选项            | 描述                                                              |
| ---------- | ---------- | ----------- | ------------- | --------------------------------------------------------------- |
| `file`     | `File`     | `undefined` | 任意文件          | 要导入的文件                                                          |
| `format`   | `string`   | `undefined` | `gfm`         | 用于格式不明确的特殊情况，比如 GitHub Flavored Markdown                        |
| `onImport` | `Function` | `undefined` | `fn(context)` | 用于自定义导入行为的回调函数。context 包含内容、错误信息以及用于修改内容的 `setEditorContent` 函数 |

### 支持的格式

- `docx` - Microsoft Word、Google Docs、OpenOffice、LibreOffice 等
- `odt` - OpenDocument 文本文档格式，OpenOffice、LibreOffice 等使用
- `rtf` - Microsoft Word、Google Docs 等使用的富文本格式
- Commonmark `markdown` - 多种编辑器和平台使用的 Markdown 格式
- GFM `markdown` - GitHub 风格 Markdown 格式

### 注意事项与限制

- **图片上传** - 假设图片是文档内联的，因此需要编辑器配置 `Image.configure({ inline: true })` 以正确显示，否则会被移除
- **导入时不支持的 DOCX 元素** - 当前导入时不支持分页符、页眉页脚、水平分割线或文本样式
- **建议模式中添加的内容** - 建议模式添加的内容不会包含在导入的 ProseMirror 文档中
- **PDF 导入与导出** - 目前不支持 PDF 文件的导入和导出
- **内联样式** - 当前不解析内联样式，导入导出中不可用

## 导出旧版扩展

> **旧版导出扩展（已弃用）:**
>
> **extension-export** 包已弃用，不会再获得新功能；在移除旧版端点之前，我们会提前 90 天通知。
> 我们强烈建议迁移到更新后的 [导出扩展](https://tiptap.zhcndoc.com/conversion/getting-started/overview.md)，它提供了更好的自定义能力和持续支持。

```js
// 首先导入扩展
import { Export } from '@tiptap-pro/extension-export'

const editor = new Editor({
  // ...
  extensions: [
    // ...
    Export.configure({
      // 从转换设置页面获取的 Convert App-ID：https://cloud.tiptap.dev/convert-settings
      appId: 'your-app-id',

      // 之前步骤生成的 JWT 令牌
      token: 'your-jwt',
    }),
  ],
})
```

### 导出文档

```js
// 简单导出为 docx
// 支持格式: docx, odt, md 和 gfm
editor.chain().focus().export({ format: 'docx' }).run()
```

### 自定义导出行为

```js
// 也可以使用 onExport 回调自定义导出行为
editor.chain().export({
  format: 'docx',
  onExport(context) {
    const { blob, error, download, filename } = context

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

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

    // 这里可以修改文件名或以其他方式处理 blob
    // 但此处保持不变

    // 可以直接调用 download 方法触发下载
    download()

    // 请注意，download 方法仅在浏览器中有效
    // 如果对 blob 或 filename 做了修改，需要手动处理下载
  },
})
```

### 导出选项

| 名称      | 类型       | 默认值         | 描述                                                                                                               |
| ------- | -------- | ----------- | ---------------------------------------------------------------------------------------------------------------- |
| `appId` | `string` | `undefined` | 从转换设置页面获取的 Convert App ID：[https://cloud.tiptap.dev/convert-settings](https://cloud.tiptap.dev/convert-settings) |
| `token` | `string` | `undefined` | 通过服务端密钥生成的 JWT 令牌                                                                                                |

### 命令

| 名称       | 描述      |
| -------- | ------- |
| `export` | 导出编辑器内容 |

#### `export`

##### 参数

| 名称         | 类型            | 默认值         | 选项                | 描述                                                                 |
| ---------- | ------------- | ----------- | ----------------- | ------------------------------------------------------------------ |
| `format`   | `string`      | `undefined` | `docx,odt,md,gfm` | 要导出的格式                                                             |
| `content`  | `JSONContent` | `undefined` | 任意 Tiptap JSON    | 要导出的 Tiptap JSON 内容                                                |
| `onExport` | `Function`    | `undefined` | `fn(context)`     | 用于自定义导出行为的回调函数。context 包含关于 blob、文件名、错误信息以及用于直接下载文档的 `download` 函数 |

### 支持的格式

- `docx` - Microsoft Word、Google Docs、OpenOffice、LibreOffice 等
- `odt` - OpenDocument 文本文档格式，OpenOffice、LibreOffice 等使用
- Commonmark `markdown` - 多种编辑器和平台使用的 Markdown 格式
- GFM `markdown` - GitHub 风格 Markdown 格式

### 注意事项与限制

- **自定义节点导出** - 自定义节点或标记的导出支持请参考新版 [Conversion](https://tiptap.zhcndoc.com/conversion/getting-started/overview.md) 扩展和端点
- **自定义 DOCX 模板** - 请查看我们的新版 [Conversion](https://tiptap.zhcndoc.com/conversion/getting-started/overview.md) 扩展和端点以集成 DOCX 模板
- **PDF 导入与导出** - 目前不支持 PDF 文件的导入和导出
- **内联样式** - 详情请参考新版 [Conversion](https://tiptap.zhcndoc.com/conversion/getting-started/overview.md) 扩展和端点以集成内联样式

## 旧版 REST API

> **旧版 /v1/ 转换 REST API（已弃用）:**
>
> **/v1/ 文档转换 REST API** 已弃用，不会再获得新功能；在移除旧版端点之前，我们会提前 90 天通知。
> 如需持续更新和维护，请迁移到更新后的 [API 端点](https://tiptap.zhcndoc.com/conversion/getting-started/overview.md)，或查看我们的
> [Postman
> 集合](https://www.postman.com/tiptap-platform/workspace/tiptap-workspace/collection/33042171-bcc93ecb-8bad-4484-8cb0-d995ee23ae60)
> 以获取最新资源。

旧版文档转换 API 支持 DOCX、ODT 和 Markdown 与 Tiptap JSON 格式之间的转换。

### /import 端点

`/import` 端点支持将 `docx`、`odt` 或 `markdown` 文件转换为 Tiptap 的 JSON 格式。用户可以向该端点 POST 文档，并使用多种参数自定义不同文档元素在转换过程中的处理方式。

- **请求方法**：`POST`

#### 必需请求头

| 名称              | 描述                                                                                                              |
| --------------- | --------------------------------------------------------------------------------------------------------------- |
| `Authorization` | 用于认证请求的 JWT 令牌。例如：`Bearer your-jwt-token`                                                                       |
| `X-App-Id`      | 来自协作设置页面的 Convert App-ID：[https://cloud.tiptap.dev/convert-settings](https://cloud.tiptap.dev/convert-settings) |

#### 请求体

| Name                     | Type     | Description     |
| ------------------------ | -------- | --------------- |
| `file`                   | `File`   | 要转换的文件          |
| `imageUploadCallbackUrl` | `string` | 上传文档中遇到的图片的回调端点 |

#### 查询参数

指定源文档元素如何映射到 ProseMirror 的节点或标记，并调整转换以满足具体的样式和结构偏好。

| 名称               | 默认值              | 描述                        |
| ---------------- | ---------------- | ------------------------- |
| `paragraph`      | `paragraph`      | 用于段落转换的 ProseMirror 类型    |
| `heading`        | `heading`        | 用于标题转换的 ProseMirror 类型    |
| `blockquote`     | `blockquote`     | 用于引用块转换的 ProseMirror 类型   |
| `codeblock`      | `codeblock`      | 用于代码块转换的 ProseMirror 类型   |
| `bulletlist`     | `bulletlist`     | 用于无序列表转换的 ProseMirror 类型  |
| `orderedlist`    | `orderedlist`    | 用于有序列表转换的 ProseMirror 类型  |
| `listitem`       | `listitem`       | 用于列表项转换的 ProseMirror 类型   |
| `hardbreak`      | `hardbreak`      | 用于硬换行转换的 ProseMirror 类型   |
| `horizontalrule` | `horizontalrule` | 用于水平分割线转换的 ProseMirror 类型 |
| `table`          | `table`          | 用于表格转换的 ProseMirror 类型    |
| `tablecell`      | `tablecell`      | 用于表格单元格转换的 ProseMirror 类型 |
| `tableheader`    | `tableheader`    | 用于表格头部转换的 ProseMirror 类型  |
| `tablerow`       | `tablerow`       | 用于表格行转换的 ProseMirror 类型   |
| `bold`           | `bold`           | 用于加粗转换的 ProseMirror 标记    |
| `italic`         | `italic`         | 用于斜体转换的 ProseMirror 标记    |
| `underline`      | `underline`      | 用于下划线转换的 ProseMirror 标记   |
| `strikethrough`  | `strike`         | 用于删除线转换的 ProseMirror 标记   |
| `link`           | `link`           | 用于链接转换的 ProseMirror 标记    |
| `code`           | `code`           | 用于代码转换的 ProseMirror 标记    |
| `image`          | `image`          | 用于图片转换的 ProseMirror 标记    |

### /import-docx 端点（实验性）

`/import-docx` 端点支持将 docx 文件转换为 Tiptap 的 JSON 格式，允许更多针对 docx 的特定功能，相较于 `/import` 端点具有更丰富的参数。用户可以向该端点 POST 文档，并使用各种参数自定义不同文档元素在转换过程中的处理方式。

- **请求方法**：`POST`

#### 必需请求头

| 名称              | 描述                                                                                                              |
| --------------- | --------------------------------------------------------------------------------------------------------------- |
| `Authorization` | 用于认证请求的 JWT 令牌。例如：`Bearer your-jwt-token`                                                                       |
| `X-App-Id`      | 来自协作设置页面的 Convert App-ID：[https://cloud.tiptap.dev/convert-settings](https://cloud.tiptap.dev/convert-settings) |

#### 请求体

| Name                     | Type     | Description     |
| ------------------------ | -------- | --------------- |
| `file`                   | `File`   | 要转换的文件          |
| `imageUploadCallbackUrl` | `string` | 上传文档中遇到的图片的回调端点 |

#### 查询参数

同 `/import`，指定源文档元素映射规则和转换行为。

| 名称               | 默认值              | 描述                        |
| ---------------- | ---------------- | ------------------------- |
| `paragraph`      | `paragraph`      | 用于段落转换的 ProseMirror 类型    |
| `heading`        | `heading`        | 用于标题转换的 ProseMirror 类型    |
| `blockquote`     | `blockquote`     | 用于引用块转换的 ProseMirror 类型   |
| `codeblock`      | `codeblock`      | 用于代码块转换的 ProseMirror 类型   |
| `bulletlist`     | `bulletlist`     | 用于无序列表转换的 ProseMirror 类型  |
| `orderedlist`    | `orderedlist`    | 用于有序列表转换的 ProseMirror 类型  |
| `listitem`       | `listitem`       | 用于列表项转换的 ProseMirror 类型   |
| `hardbreak`      | `hardbreak`      | 用于硬换行转换的 ProseMirror 类型   |
| `horizontalrule` | `horizontalrule` | 用于水平分割线转换的 ProseMirror 类型 |
| `table`          | `table`          | 用于表格转换的 ProseMirror 类型    |
| `tablecell`      | `tablecell`      | 用于表格单元格转换的 ProseMirror 类型 |
| `tableheader`    | `tableheader`    | 用于表格头部转换的 ProseMirror 类型  |
| `tablerow`       | `tablerow`       | 用于表格行转换的 ProseMirror 类型   |
| `bold`           | `bold`           | 用于加粗转换的 ProseMirror 标记    |
| `italic`         | `italic`         | 用于斜体转换的 ProseMirror 标记    |
| `underline`      | `underline`      | 用于下划线转换的 ProseMirror 标记   |
| `strikethrough`  | `strike`         | 用于删除线转换的 ProseMirror 标记   |
| `link`           | `link`           | 用于链接转换的 ProseMirror 标记    |
| `code`           | `code`           | 用于代码转换的 ProseMirror 标记    |
| `image`          | `image`          | 用于图片转换的 ProseMirror 标记    |

### /export 端点

`/export` 端点支持将 Tiptap 文档转换回 `docx`、`odt` 或 `markdown` 等格式。

- **请求方法**：`POST`

将 Tiptap 文档转换为指定格式。

#### 必需请求头

| 名称              | 描述                                                                                                              |
| --------------- | --------------------------------------------------------------------------------------------------------------- |
| `Authorization` | 用于认证请求的 JWT 令牌。例如：`Bearer your-jwt-token`                                                                       |
| `X-App-Id`      | 来自协作设置页面的 Convert App-ID：[https://cloud.tiptap.dev/convert-settings](https://cloud.tiptap.dev/convert-settings) |

#### 请求体

| 名称        | 类型       | 描述                                  |
| --------- | -------- | ----------------------------------- |
| `content` | `Object` | Tiptap 文档                           |
| `format`  | `string` | 要转换的格式，可为 `docx`、`odt` 或 `markdown` |

#### 查询参数

| 名称               | 默认值              | 描述                        |
| ---------------- | ---------------- | ------------------------- |
| `gfm`            | `0`              | 使用 GitHub 风格 Markdown 导出  |
| `paragraph`      | `paragraph`      | 用于段落转换的 ProseMirror 类型    |
| `heading`        | `heading`        | 用于标题转换的 ProseMirror 类型    |
| `blockquote`     | `blockquote`     | 用于引用块转换的 ProseMirror 类型   |
| `codeblock`      | `codeblock`      | 用于代码块转换的 ProseMirror 类型   |
| `bulletlist`     | `bulletlist`     | 用于无序列表转换的 ProseMirror 类型  |
| `orderedlist`    | `orderedlist`    | 用于有序列表转换的 ProseMirror 类型  |
| `listitem`       | `listitem`       | 用于列表项转换的 ProseMirror 类型   |
| `hardbreak`      | `hardbreak`      | 用于硬换行转换的 ProseMirror 类型   |
| `horizontalrule` | `horizontalrule` | 用于水平分割线转换的 ProseMirror 类型 |
| `table`          | `table`          | 用于表格转换的 ProseMirror 类型    |
| `tablecell`      | `tablecell`      | 用于表格单元格转换的 ProseMirror 类型 |
| `tableheader`    | `tableheader`    | 用于表格头部转换的 ProseMirror 类型  |
| `tablerow`       | `tablerow`       | 用于表格行转换的 ProseMirror 类型   |
| `bold`           | `bold`           | 用于加粗转换的 ProseMirror 标记    |
| `italic`         | `italic`         | 用于斜体转换的 ProseMirror 标记    |
| `underline`      | `underline`      | 用于下划线转换的 ProseMirror 标记   |
| `strikethrough`  | `strike`         | 用于删除线转换的 ProseMirror 标记   |
| `link`           | `link`           | 用于链接转换的 ProseMirror 标记    |
| `code`           | `code`           | 用于代码转换的 ProseMirror 标记    |