通过 REST API 导出 DOCX

Start 计划Betav2.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。编辑器扩展通过 region 选项('eu' 或 'us')选择区域。 REST 调用则直接使用对应的主机。

导出 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

请求体

名称类型描述默认值
docStringTiptap's JSONN/A
exportTypestringThe expected export typeblob
styleOverridesObjectStyle overrides{}
pageSizeObjectPage size configurationundefined
pageMarginsObjectPage margins configurationundefined
headersObjectPage header configurationundefined
footersObjectPage footer configurationundefined
tableOverridesObjectTable-level rendering overridesundefined
paragraphOverridesObjectParagraph-level rendering overridesundefined
textRunOverridesObjectText run rendering overridesundefined
tableCellOverridesObjectTable cell rendering overridesundefined
imageOverridesObjectImage rendering overridesundefined
headerFooterOverridesObjectPer-field overrides scoped to header/footer content (same five keys as the element overrides). See Element Overrides.undefined
customNodeDslObjectCustom-node DSL rulesundefined
placeholdersObject | false可选的 { page?, total? } 重命名映射匹配 Pages.configure({ placeholders }) 以便重命名令牌(例如 {p} /{pages}) 在每个页眉或页脚槽中成为实时 PAGE / NUMPAGES 字段。传递 false 以完全禁用替换(导出的 .docx 中的文字 {page} / {total} 文本)。请参阅自定义令牌名称。undefined
commentsObjectComment threads to embed as native Word comments: { threads: [...] }. Each thread carries its messages, author, dates, and resolved state, and is anchored to the document's inlineThread / blockThread marks. See Comments.undefined
footnotesObject脚注正文由注释 ID 键入。每个值都是 Tiptap JSON 文档。请参阅脚注和尾注。undefined
endnotesObject由注释 id 键控的尾注正文,形状与 footnotes 相同。请参阅脚注和尾注。undefined

Page Size Configuration

The pageSize object allows you to customize the dimensions of your exported DOCX document:

PropertyTypeDescriptionDefault
widthstring页面的宽度。必须是一个正数,后跟有效单位(cm、in、pt、pc、mm、px)。"21.0cm"
heightstring页面的高度。必须是一个正数,后跟有效单位(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 文档的页面边距:

属性类型描述默认值
topstring页面的上边距。可以为负数。必须是一个数字,后跟有效单位(cm、in、pt、pc、mm、px)。"1.0cm"
bottomstring页面的下边距。可以为负数。必须是一个数字,后跟有效单位(cm、in、pt、pc、mm、px)。"1.0cm"
leftstring页面的左边距。必须是一个正数,后跟有效单位(cm、in、pt、pc、mm、px)。"1.0cm"
rightstring页面的右边距。必须是一个正数,后跟有效单位(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 文档的页眉:

属性类型描述
evenAndOddHeadersboolean是否使用不同标头对于奇数页和偶数页
differentFirstPageboolean是否在首页上使用不同的页眉。当 true 时,第一页上使用 first 值而不是 default。
defaultstring | Object每页上的标准默认页眉,或激活 evenAndOddHeaders 选项时奇数页上的页眉。接受纯文本、字符串化 Tiptap JSONContent 或 Tiptap JSONContent 对象。
firststring | Object第一页上的标题。仅当 differentFirstPage 设置为 true 时使用。接受纯文本、字符串化 Tiptap JSONContent 或 Tiptap JSONContent 对象。
evenstring | Object激活 evenAndOddHeaders 选项时偶数页上的页眉。接受纯文本、字符串化 Tiptap JSONContent 或 Tiptap JSONContent 对象。

接受的槽值

每个标头值可以是以下三种形状之一:

  • A 纯文本字符串。 生成简单的无样式标头。
  • A 字符串化 Tiptap JSONContent。 启用丰富的格式,例如粗体、斜体和链接。使用 JSON.stringify(yourHeaderDoc) 生成它。
  • A Tiptap JSONContent 对象。 相同的丰富内容,作为请求正文内的嵌套 JSON 对象发送,而不对其进行字符串化。

在 JSON 请求正文中,对象必须包含 type 字段,无效形状将返回 400 Bad Request。

带自定义页眉的 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 文档的页脚:

属性类型说明
evenAndOddFootersboolean奇数页和偶数页是否使用不同的页脚
differentFirstPageboolean是否在首页上使用不同的页脚。当 true 时,第一页上使用 first 值而不是 default。
defaultstring | Object每页上的标准默认页脚,或激活 evenAndOddFooters 选项时奇数页上的页脚。接受纯文本、字符串化 Tiptap JSONContent 或 Tiptap JSONContent 对象。
firststring | Object第一页的页脚。仅当 differentFirstPage 设置为 true 时使用。接受纯文本、字符串化 Tiptap JSONContent 或 Tiptap JSONContent 对象。
evenstring | Object激活 evenAndOddFooters 选项时偶数页上的页脚。接受纯文本、字符串化 Tiptap JSONContent 或 Tiptap JSONContent 对象。

接受的槽值

每个页脚值可以是与页眉值相同的三种形状之一:纯文本字符串、字符串化的 Tiptap JSONContent 或 Tiptap JSONContent 对象。在 JSON 请求正文中,对象必须包含 type 字段,无效形状将返回 400 Bad Request。

`{page}` / `{total}` tokens become live Word fields

REST API 将页眉/页脚内的 {page}、{total} 和 {numpages} 同义词转换为导出的 .docx 中的实时 Word PAGE / NUMPAGES 字段。这适用于每种槽形状:纯文本字符串、字符串化 Tiptap JSON 或 Tiptap JSON 对象。自定义令牌名称(例如 {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 字段提供线程正文、作者、日期以及已解决状态。

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

字段类型描述
threadsArray要嵌入的评论线程。
threads[].idString线程 id。必须与 doc 中匹配的 inlineThread / blockThread 上的 data-thread-id 一致。
threads[].resolvedAtString | null设置后,该线程将导出为已解决。
threads[].commentsArray该线程的消息,先是根消息,然后按顺序排列回复。
comments[].idString消息 id。
comments[].contentString | Object消息正文,纯文本或 Tiptap JSON。
comments[].dataObject可选元数据: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" }
              }
            ]
          }
        ]
      }
    }'

脚注和尾注

通过 footnotes 和 endnotes 导出 Word 脚注和尾注。每个都是由注释 id 键控的对象,每个值都是带有 "type": "doc" 的 Tiptap JSON 文档。当 doc 中的 footnoteReference 或 endnoteReference 节点的 noteId 属性在匹配对象中具有条目时,该节点将成为 Word 注释。导出时会留下没有条目的参考文献。非 Tiptap JSON 文档的值返回 400 Bad Request。

该形状与 DOCX import 返回的 footnotes 和 endnotes 字段匹配。在 multipart/form-data 请求中,将每个字段作为 JSON 字符串发送。

带有脚注的 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\":\"Body text\"},{\"type\":\"footnoteReference\",\"attrs\":{\"noteId\":\"1\"}}]}]}",
      "footnotes": {
        "1": { "type": "doc", "content": [{ "type": "paragraph", "content": [{ "type": "text", "text": "A footnote." }] }] }
      }
    }'

Element Overrides

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

不进行深度合并

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

tableOverrides

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

PropertyTypeDescription
bordersObject各边定义:top、bottom、left、right、insideHorizontal、insideVertical。每项都接受 { style, size, color }。
marginsObject默认单元格边距 { top, bottom, left, right }(以二十分之一磅为单位)。
widthObject表格宽度 { size, type },其中 type 为 "pct"、"dxa" 或 "auto"。
layoutstring"fixed" 或 "autofit"。
alignmentstring"left" | "center" | "right" | "start" | "end"。
cantSplitboolean防止表格跨页拆分。
visuallyRightToLeftboolean使表格从右到左渲染。

paragraphOverrides

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

PropertyTypeDescription
spacingObject{ before, after, line, lineRule },单位为二十分之一磅。line 会被计算出的行高覆盖。
alignmentstring"left" | "center" | "right" | "justified" | "start" | "end"。
indentObject{ left, right, firstLine, hanging, start, end },单位为二十分之一磅。
keepNextboolean将此段落与下一段保持在一起。
keepLinesboolean保持段落中的所有行在一起。
pageBreakBeforeboolean在段落前插入分页符。
bidirectionalboolean将段落从右到左渲染。
stylestring指向 styleOverrides 中定义的段落样式 id 的引用。

textRunOverrides

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

PropertyTypeDescription
fontstring字体族名称。
sizenumber以半磅为单位的字体大小(24 = 12pt)。
boldboolean默认以粗体渲染。
italicsboolean默认以斜体渲染。
underlineObject{ type, color },例如 { type: "single", color: "auto" }。
strikeboolean删除线。
colorstring不带前导 # 的十六进制颜色("FF0000")。
highlightstring预定义的高亮颜色名称("yellow"、"green"、…)。
superScriptboolean以上标显示。
subScriptboolean以下标显示。

tableCellOverrides

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

PropertyTypeDescription
shadingObject{ fill, type, color },例如 { fill: "F0F0F0", type: "clear" }。
verticalAlignstring"top" | "center" | "bottom"。
bordersObject按边定义的单元格边框,与 tableOverrides.borders 的结构相同。
marginsObject单元格内边距 { top, bottom, left, right },单位为二十分之一磅。
widthObject单元格宽度 { size, type }。

imageOverrides

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

PropertyTypeDescription
transformationObject{ width, height, rotation?, flip? }, 以 96 dpi 下的像素为单位。
altTextObject{ title, description, name }.
floatingObject浮动定位选项(锚点、对齐、偏移、环绕)。

headerFooterOverrides

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

PropertyTypeDescription
tableOverridesObject与顶层覆盖项形状相同,应用于页眉/页脚中。
paragraphOverridesObject与顶层覆盖项形状相同,应用于页眉/页脚中。
textRunOverridesObject与顶层覆盖项形状相同,应用于页眉/页脚中。
tableCellOverridesObject与顶层覆盖项形状相同,应用于页眉/页脚中。
imageOverridesObject与顶层覆盖项形状相同,应用于页眉/页脚中。

组合多个元素覆盖的示例 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

错误响应

StatusCodeDescription
400NO_DOCUMENT_PROVIDED文档未在请求体中提供
422FAILED_TO_PARSE_DOCX_FILE解析 JSON 输入失败
422FAILED_TO_EXPORT_DOCX_FILE导出 DOCX 失败
422FAILED_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:

字段类型描述必填
fileFile字体二进制文件(TTF、OTF 或 WOFF2)。最大 25MB。是
fontFamilyString字体族名称,仅用于日志记录。否

示例(cURL)

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

响应

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

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

错误响应

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