通过 REST API 导出 DOCX

Available in Start planBetav2.39.1

DOCX 导出 API 会将 Tiptap JSON 文档转换为 .docx（Microsoft Word）文件。它使用与编辑器扩展相同的转换库，并为标准内容生成等效的 DOCX 输出。

REST API 支持样式覆盖、通过 DSL 进行的自定义节点渲染、页面大小和页边距、页眉/页脚、评论线程，以及元素级覆盖（tableOverrides、paragraphOverrides、textRunOverrides、tableCellOverrides、imageOverrides）。它不接受基于 JavaScript 函数的选项。对于基于函数的自定义节点 API，请使用编辑器扩展，它同样也可在服务器端工作。

查看 Postman 集合

您也可以前往我们的 Postman 集合体验文档转换 API。

选择您的区域

默认端点 api.tiptap.dev 位于欧盟区域。转换服务也在美国区域提供，端点为 api-us.tiptap.dev。

导出 DOCX

POST /v2/convert/export/docx

/v2/convert/export/docx 端点会将 Tiptap 文档转换为 DOCX 格式。用户可以向该端点 POST 文档，并使用多种参数在转换过程中自定义不同文档元素的处理方式。

支持导出自定义

/v2/convert/export/docx 端点接受样式覆盖、页面大小/边距、页眉/页脚、五种元素级覆盖（tableOverrides、 paragraphOverrides、textRunOverrides、tableCellOverrides、imageOverrides），以及通过 JSON DSL 的自定义节点渲染。它不接受 JavaScript 函数选项。对于基于函数的自定义节点 API，请使用编辑器扩展或服务端导出指南。

示例（cURL）

curl --output example.docx -X POST "https://api.tiptap.dev/v2/convert/export/docx" \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "doc": "{\"type\":\"doc\",\"content\":[{\"type\":\"paragraph\",\"attrs\":{\"textAlign\":\"left\"},\"content\":[{\"type\":\"text\",\"text\":\"欢迎参加本次演示，展示我们的编辑器如何将各种格式选项导出为 DOCX，确保您的内容在 Word 中保持预期外观。\"}]}]}",
      "exportType": "blob"
    }'

需要订阅

此端点需要有效的 Tiptap 订阅。更多详情请查看我们的定价页面。

必填请求头

名称	描述
`Authorization`	用于对请求进行身份验证的 JWT 令牌。示例：`Bearer your-jwt-token`
`Content-Type`	必须为 `application/json`

请求体

名称	类型	描述	默认值
`doc`	`String`	Tiptap 的 JSON	`N/A`
`exportType`	`string`	期望的导出类型	`blob`
`styleOverrides`	`Object`	样式覆盖	`{}`
`pageSize`	`Object`	页面尺寸配置	`undefined`
`pageMargins`	`Object`	页面边距配置	`undefined`
`headers`	`Object`	页面页眉配置	`undefined`
`footers`	`Object`	页面页脚配置	`undefined`
`tableOverrides`	`Object`	表格级渲染覆盖	`undefined`
`paragraphOverrides`	`Object`	段落级渲染覆盖	`undefined`
`textRunOverrides`	`Object`	文本运行渲染覆盖	`undefined`
`tableCellOverrides`	`Object`	表格单元格渲染覆盖	`undefined`
`imageOverrides`	`Object`	图片渲染覆盖	`undefined`
`headerFooterOverrides`	`Object`	作用域限定为页眉/页脚内容的按字段覆盖（与元素覆盖具有相同的五个键）。参见元素覆盖。	`undefined`
`customNodeDsl`	`Object`	自定义节点 DSL 规则	`undefined`
`placeholders`	`Object \| false`	可选的 `{ page?, total? }` 重命名映射，需与 `Pages.configure({ placeholders })` 匹配，这样纯文本页眉/页脚中重命名后的标记（例如 `{p}` / `{pages}`）会变成动态的 `PAGE` / `NUMPAGES` 字段。传入 `false` 可完全禁用替换（导出的 `.docx` 中将保留字面量 `{page}` / `{total}` 文本）。参见自定义标记名称。	`undefined`
`comments`	`Object`	作为原生 Word 注释嵌入的评论线程：`{ threads: [...] }`。每个线程包含其消息、作者、日期和已解决状态，并锚定到文档的 `inlineThread` / `blockThread` 标记。参见评论。	`undefined`

页面尺寸配置

pageSize 对象允许您自定义导出 DOCX 文档的页面尺寸：

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

带自定义页面尺寸的 cURL 示例：

curl --output example.docx -X POST "https://api.tiptap.dev/v2/convert/export/docx" \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "doc": "{\"type\":\"doc\",\"content\":[{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"自定义页面尺寸的文档\"}]}]}",
      "exportType": "blob",
      "pageSize": {"width": "21.0cm", "height": "29.7cm"}
    }'

页面边距配置

pageMargins 对象允许您自定义导出 DOCX 文档的页面边距：

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

带自定义页面边距的 cURL 示例：

curl --output example.docx -X POST "https://api.tiptap.dev/v2/convert/export/docx" \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "doc": "{\"type\":\"doc\",\"content\":[{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"自定义边距的文档\"}]}]}",
      "exportType": "blob",
      "pageMargins": {"top": "2.0cm", "bottom": "2.0cm", "left": "1.5cm", "right": "1.5cm"}
    }'

页眉和页脚

headers 和 footers 对象允许您自定义导出 DOCX 的一系列页眉和页脚选项。

页眉配置

headers 对象允许您自定义导出 DOCX 文档的页眉：

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

纯文本与 Tiptap JSONContent

每个页眉值都可以是 纯文本字符串（生成简单、无样式的页眉）或 字符串化的 Tiptap JSONContent 对象（可启用加粗、斜体、链接等富文本格式）。当传入 JSONContent 时，请在请求体中发送前使用 JSON.stringify() 将对象转为字符串。

带自定义页眉的 cURL 示例：

curl --output example.docx -X POST "https://api.tiptap.dev/v2/convert/export/docx" \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "doc": "{\"type\":\"doc\",\"content\":[{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"带自定义页眉的文档\"}]}]}",
      "exportType": "blob",
      "headers": {"evenAndOddHeaders": true, "default": "默认页眉", "first": "首页页眉", "even": "偶数页页眉"}
    }'

页脚配置

footers 对象允许您自定义导出 DOCX 文档的页脚：

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

纯文本与 Tiptap JSONContent

每个页脚值都可以是 纯文本字符串（生成简单、无样式的页脚）或 字符串化的 Tiptap JSONContent 对象（可启用加粗、斜体、链接等富文本格式）。当传入 JSONContent 时，请在请求体中发送前使用 JSON.stringify() 将对象转为字符串。

`{page}` / `{total}` 标记将变为动态 Word 字段

REST API 会将纯文本页眉/页脚中的 {page}、{total} 以及 {numpages} 同义词转换为导出的 .docx 中动态的 Word PAGE / NUMPAGES 字段。自定义标记名称（例如 {p} / {pages}）需要传入可选的 placeholders 重命名映射。参见下方自定义标记名称。传入 "placeholders": false 可改为让这些标记以字面文本形式保留。

自定义标记名称 (`placeholders`)

当编辑器通过 Pages.configure({ placeholders }) 重命名内置标记时，请将同样的重命名映射传给 REST API，以保持传输格式一致。该字段在传输层中的名称和结构与编辑器选项相同：

{
  "doc": "{\"type\":\"doc\",\"content\":[]}",
  "footers": { "default": "{p} of {pages}" },
  "placeholders": { "page": "p", "total": "pages" }
}

当省略该映射时，服务会回退为识别 {page}、{total} 和 {numpages}（Word 对总页数字段的拼写，这里保留为同义词，以便直接调用 REST API 的用户能够镜像 /import/docx 的输出）。重命名 total 会移除 {numpages} 同义词，因此旧标记将按字面文本渲染；该重命名是严格生效的。传入 "placeholders": false 可为所有位置禁用替换，从而使所有 {page} / {total} 文本都以字面形式保留，不生成动态字段。

带自定义页脚的 cURL 示例：

curl --output example.docx -X POST "https://api.tiptap.dev/v2/convert/export/docx" \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "doc": "{\"type\":\"doc\",\"content\":[{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"带自定义页脚的文档\"}]}]}",
      "exportType": "blob",
      "footers": {"evenAndOddFooters": true, "default": "默认页脚", "first": "首页页脚", "even": "偶数页页脚"}
    }'

传入一个 comments 对象，以便在导出的 .docx 中将评论线程嵌入为原生 Word 注释。每个线程都通过文档自身的评论标记锚定到其所属文本：一个 inlineThread 标记，其 data-thread-id 与线程 id 匹配，或者一个 blockThread 节点。comments 字段提供线程正文、作者、日期以及已解决状态。

其结构与编辑器的导出扩展一致：

字段	类型	描述
`threads`	`Array`	要嵌入的评论线程。
`threads[].id`	`String`	线程 id。必须与 `doc` 中匹配的 `inlineThread` / `blockThread` 上的 `data-thread-id` 一致。
`threads[].resolvedAt`	`String \| null`	设置后，该线程将导出为已解决。
`threads[].comments`	`Array`	该线程的消息，先是根消息，然后按顺序排列回复。
`comments[].id`	`String`	消息 id。
`comments[].content`	`String \| Object`	消息正文，纯文本或 Tiptap JSON。
`comments[].data`	`Object`	可选元数据：`author`、`initials`、`dateIso`、`dateUtc`，以及往返标识（`originalWId`、`originalDurableId`）。

如果省略该字段，导出内容将不包含评论，因此现有请求不会受到影响。

带有评论线程的 cURL 示例：

curl --output example.docx -X POST "https://api.tiptap.dev/v2/convert/export/docx" \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "doc": "{\"type\":\"doc\",\"content\":[{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Reviewed text\",\"marks\":[{\"type\":\"inlineThread\",\"attrs\":{\"data-thread-id\":\"T1\"}}]}]}]}",
      "exportType": "blob",
      "comments": {
        "threads": [
          {
            "id": "T1",
            "resolvedAt": null,
            "comments": [
              {
                "id": "c1",
                "content": "请注明来源。",
                "data": { "author": "Ada Lovelace", "initials": "AL", "dateIso": "2026-01-01T00:00:00.000Z" }
              }
            ]
          }
        ]
      }
    }'

元素覆盖

五种元素覆盖对象可让你调整各个 DOCX 元素（表格、段落、文本运行、表格单元格、图片）的渲染方式。每个覆盖项都会作为基础默认值传递给底层的 DOCX 转换库；来自文档的按节点值在计算后仍然优先。

不进行深度合并

覆盖项中的嵌套对象（例如 borders、margins、transformation）会被完全替换，而不是进行深度合并。自定义边框某一侧时，请提供你需要的每一侧，以免未定义值漏入。

`tableOverrides`

应用于每个表格的默认值。最有用的属性：

Property	Type	Description
`borders`	`Object`	各边定义：`top`、`bottom`、`left`、`right`、`insideHorizontal`、`insideVertical`。每项都接受 `{ style, size, color }`。
`margins`	`Object`	默认单元格边距 `{ top, bottom, left, right }`（以二十分之一磅为单位）。
`width`	`Object`	表格宽度 `{ size, type }`，其中 `type` 为 `"pct"`、`"dxa"` 或 `"auto"`。
`layout`	`string`	`"fixed"` 或 `"autofit"`。
`alignment`	`string`	`"left" \| "center" \| "right" \| "start" \| "end"`。
`cantSplit`	`boolean`	防止表格跨页拆分。
`visuallyRightToLeft`	`boolean`	使表格从右到左渲染。

`paragraphOverrides`

应用于每个段落的默认值。最有用的属性：

Property	Type	Description
`spacing`	`Object`	`{ before, after, line, lineRule }`，单位为二十分之一磅。`line` 会被计算出的行高覆盖。
`alignment`	`string`	`"left" \| "center" \| "right" \| "justified" \| "start" \| "end"`。
`indent`	`Object`	`{ left, right, firstLine, hanging, start, end }`，单位为二十分之一磅。
`keepNext`	`boolean`	将此段落与下一段保持在一起。
`keepLines`	`boolean`	保持段落中的所有行在一起。
`pageBreakBefore`	`boolean`	在段落前插入分页符。
`bidirectional`	`boolean`	将段落从右到左渲染。
`style`	`string`	指向 `styleOverrides` 中定义的段落样式 id 的引用。

`textRunOverrides`

应用于每个文本运行的默认值。按标记格式设置（粗体、斜体、颜色 ……）仍会覆盖这些值。最有用的属性：

Property	Type	Description
`font`	`string`	字体族名称。
`size`	`number`	以半磅为单位的字体大小（`24` = 12pt）。
`bold`	`boolean`	默认以粗体渲染。
`italics`	`boolean`	默认以斜体渲染。
`underline`	`Object`	`{ type, color }`，例如 `{ type: "single", color: "auto" }`。
`strike`	`boolean`	删除线。
`color`	`string`	不带前导 `#` 的十六进制颜色（`"FF0000"`）。
`highlight`	`string`	预定义的高亮颜色名称（`"yellow"`、`"green"`、…）。
`superScript`	`boolean`	以上标显示。
`subScript`	`boolean`	以下标显示。

`tableCellOverrides`

应用于每个表格单元格的默认值。最有用的属性：

Property	Type	Description
`shading`	`Object`	`{ fill, type, color }`，例如 `{ fill: "F0F0F0", type: "clear" }`。
`verticalAlign`	`string`	`"top" \| "center" \| "bottom"`。
`borders`	`Object`	按边定义的单元格边框，与 `tableOverrides.borders` 的结构相同。
`margins`	`Object`	单元格内边距 `{ top, bottom, left, right }`，单位为二十分之一磅。
`width`	`Object`	单元格宽度 `{ size, type }`。

`imageOverrides`

应用于每张图片的默认值。根据文档计算出的图片尺寸（固有大小或用户调整后的值）在存在时仍然优先。最有用的属性：

Property	Type	Description
`transformation`	`Object`	`{ width, height, rotation?, flip? }`, 以 96 dpi 下的像素为单位。
`altText`	`Object`	`{ title, description, name }`.
`floating`	`Object`	浮动定位选项（锚点、对齐、偏移、环绕）。

`headerFooterOverrides`

将同样的五种元素覆盖项仅作用于页眉/页脚内容。你省略的每个字段都会回退到与正文同名的覆盖项。此功能仅在页眉或页脚槽位作为 Tiptap JSON 传入时生效（对象或字符串化的 JSONContent）；纯文本槽位不受影响。一个常见的用例是正文中带边框的表格，而页眉中使用无边框表格。

Property	Type	Description
`tableOverrides`	`Object`	与顶层覆盖项形状相同，应用于页眉/页脚中。
`paragraphOverrides`	`Object`	与顶层覆盖项形状相同，应用于页眉/页脚中。
`textRunOverrides`	`Object`	与顶层覆盖项形状相同，应用于页眉/页脚中。
`tableCellOverrides`	`Object`	与顶层覆盖项形状相同，应用于页眉/页脚中。
`imageOverrides`	`Object`	与顶层覆盖项形状相同，应用于页眉/页脚中。

组合多个元素覆盖的示例 cURL

curl --output example.docx -X POST "https://api.tiptap.dev/v2/convert/export/docx" \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "doc": "{\"type\":\"doc\",\"content\":[{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"带元素级覆盖的文档\"}]}]}",
      "tableOverrides": {
        "borders": {
          "top": { "style": "none" },
          "bottom": { "style": "none" },
          "left": { "style": "none" },
          "right": { "style": "none" },
          "insideHorizontal": { "style": "none" },
          "insideVertical": { "style": "none" }
        }
      },
      "paragraphOverrides": {
        "spacing": { "before": 200, "after": 200 }
      },
      "textRunOverrides": {
        "font": "Arial",
        "size": 24
      },
      "tableCellOverrides": {
        "shading": { "fill": "F0F0F0", "type": "clear" },
        "verticalAlign": "center"
      },
      "imageOverrides": {
        "transformation": { "width": 400, "height": 300 }
      }
    }'

响应

成功时，API 以二进制形式返回 DOCX 文件下载：

状态: 200 OK
Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document
Content-Disposition: attachment; filename=export-{timestamp}.docx

错误响应

Status	Code	Description
400	`NO_DOCUMENT_PROVIDED`	文档未在请求体中提供
422	`FAILED_TO_PARSE_DOCX_FILE`	解析 JSON 输入失败
422	`FAILED_TO_EXPORT_DOCX_FILE`	导出 DOCX 失败
422	`FAILED_TO_CONVERT_DOCX_TO_BLOB`	转换结果类型失败

转换字体

POST /v2/convert/fonts/convert

将字体转换为可嵌入 DOCX 文件的形式：TTF / OTF 上传会原样返回，而 WOFF2 上传会转换为 TTF。这是编辑器扩展的 embedFonts 选项在后台调用的端点；你也可以直接调用它。自 Convert Service v2.25.0 起可用。

该端点是无状态的：不会存储任何内容。每个请求都会被转换，临时文件会立即清理。

必需请求头

Authorization: Bearer <your-jwt>

请求体

multipart/form-data:

字段	类型	描述	必填
`file`	`File`	字体二进制文件（`TTF`、`OTF` 或 `WOFF2`）。最大 25MB。	是
`fontFamily`	`String`	字体族名称，仅用于日志记录。	否

示例（cURL）

curl --output MyFont.ttf -X POST "https://api.tiptap.dev/v2/convert/fonts/convert" \
  -H "Authorization: Bearer <your-jwt>" \
  -F "file=@MyFont.woff2" \
  -F "fontFamily=My Font"

响应

成功时，API 会将可嵌入的字体作为二进制下载返回：

状态：200 OK
Content-Type: font/ttf

错误响应

Status	Code	Description
400	None	请求验证错误（例如缺少 `file` 字段）
413	`FONT_FILE_TOO_LARGE`	上传的字体超过了 25MB 限制
422	`UNSUPPORTED_FONT_FORMAT`	上传内容不是可识别的 TTF、OTF 或 WOFF2 字体
422	`FONT_CONVERSION_FAILED`	WOFF2 → TTF 转换未产生任何输出
500	`FONT_CONVERSION_FAILED`	转换过程中发生意外错误

PreviouslyCSS 转 DOCX

Next up自定义

查看 Postman 集合

选择您的区域

导出 DOCX

支持导出自定义

示例（cURL）

需要订阅

必填请求头

请求体

页面尺寸配置

页面边距配置

页眉和页脚

页眉配置

纯文本与 Tiptap JSONContent

页脚配置

纯文本与 Tiptap JSONContent

`{page}` / `{total}` 标记将变为动态 Word 字段

自定义标记名称 (placeholders)

评论

元素覆盖

不进行深度合并

tableOverrides

paragraphOverrides

textRunOverrides

tableCellOverrides

imageOverrides

headerFooterOverrides

组合多个元素覆盖的示例 cURL

响应

错误响应

转换字体

必需请求头

请求体

示例（cURL）

响应

错误响应

自定义标记名称 (`placeholders`)

`tableOverrides`

`paragraphOverrides`

`textRunOverrides`

`tableCellOverrides`

`imageOverrides`

`headerFooterOverrides`