通过 REST API 导出 ODT

Start 计划Betav2.39.1

ODT 导出 API 将 Tiptap JSON 文档转换为 OpenDocument Text(.odt)文件,与 LibreOffice 和 OpenOffice 兼容。

查看 Postman 集合

您也可以通过我们的 Postman 集合 来体验文档转换 API。

选择您的区域

默认端点 api.tiptap.dev 位于欧盟区域。转换服务也在美国区域提供,端点为 api-us.tiptap.dev。编辑器扩展通过 region 选项('eu' 或 'us')选择区域。 REST 调用则直接使用对应的主机。

导出 ODT

POST /v2/convert/export/odt

/v2/convert/export/odt 端点将 Tiptap JSON 文档转换为 ODT 格式。发送带有文档 JSON 正文的 POST 请求,即可接收可下载的 ODT 文件。

示例(cURL)

curl --output document.odt -X POST "https://api.tiptap.dev/v2/convert/export/odt" \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "doc": "{\"type\":\"doc\",\"content\":[{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Hello World\"}]}]}"
    }'

需要订阅

使用此端点需要有效的 Tiptap 订阅。详情请查看我们的价格页面。

必填请求头

名称描述
Authorization用于验证请求的 JWT 令牌。示例:Bearer your-jwt-token
Content-Type必须是 application/json

请求体参数

名称类型描述默认值
docStringTiptap JSON document as a stringN/A
exportTypestringThe expected export typeblob
styleOverridesObjectStyle overrides{}
pageSizeObjectPage size configurationundefined
pageMarginsObjectPage margins configurationundefined
headersObjectPage header configurationundefined
footersObjectPage footer configurationundefined
tableOverridesObjectTable-level rendering overrides forwarded to the DOCX stepundefined
paragraphOverridesObjectParagraph-level rendering overrides forwarded to the DOCX stepundefined
textRunOverridesObjectText run rendering overrides forwarded to the DOCX stepundefined
tableCellOverridesObjectTable cell rendering overrides forwarded to the DOCX stepundefined
imageOverridesObjectImage rendering overrides forwarded to the DOCX stepundefined
headerFooterOverridesObjectPer-field overrides scoped to header/footer content (same five keys as the element overrides). See Element Overrides.undefined
placeholdersObject | false页眉/页脚中页码标记的重命名映射 ({ page?, total? }),与 Pages.configure({ placeholders }) 匹配。适用于每种槽形状:纯文本、字符串化 Tiptap JSON 或 Tiptap JSON 对象。传递 false 以禁用替换。请参阅自定义代币名称。undefined
customNodeDslObjectCustom-node DSL rules for rendering custom Tiptap nodes into the exported file.undefined

Page Size Configuration

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

PropertyTypeDescriptionDefault
widthstringThe width of the page. Must be a positive number followed by a valid unit (cm, in, pt, pc, mm, px)."21.0cm"
heightstringThe height of the page. Must be a positive number followed by a valid unit (cm, in, pt, pc, mm, px)."29.7cm"

Page Margins Configuration

The pageMargins object allows you to customize the margins of your exported ODT document:

PropertyTypeDescriptionDefault
topstringThe top margin of the page. Can be negative. Must be a number followed by a valid unit (cm, in, pt, pc, mm, px)."1.0cm"
bottomstringThe bottom margin of the page. Can be negative. Must be a number followed by a valid unit (cm, in, pt, pc, mm, px)."1.0cm"
leftstringThe left margin of the page. Must be a positive number followed by a valid unit (cm, in, pt, pc, mm, px)."1.0cm"
rightstringThe right margin of the page. Must be a positive number followed by a valid unit (cm, in, pt, pc, mm, px)."1.0cm"

Headers Configuration

The headers object allows you to customize the headers of your exported ODT document:

PropertyTypeDescription
evenAndOddHeadersbooleanWhether to use different headers for odd and even pages
differentFirstPagebooleanWhether to use a different header on the first page. When true, the first value is used on page one instead of default.
defaultstring | Object每页上的标准默认页眉,或激活 evenAndOddHeaders 时奇数页上的页眉。接受纯文本、字符串化 Tiptap JSONContent 或 Tiptap JSONContent 对象。
firststring | Object第一页上的标题。仅当 differentFirstPage 设置为 true 时使用。接受纯文本、字符串化 Tiptap JSONContent 或 Tiptap JSONContent 对象。
evenstring | Object激活 evenAndOddHeaders 选项时偶数页上的页眉。接受纯文本、字符串化 Tiptap JSONContent 或 Tiptap JSONContent 对象。

接受的槽值

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

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

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

页脚配置

footers 对象允许自定义导出 ODT 文档的页脚:

PropertyTypeDescription
evenAndOddFootersbooleanWhether to use different footers for odd and even pages
differentFirstPagebooleanWhether to use a different footer on the first page. When true, the first value is used on page one instead of 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。

元素覆盖

ODT 生成会经过 DOCX 流水线,因此在发送 Tiptap JSON 时,/export/docx 接受的相同五种元素覆盖也同样适用于这里。通过 docxFile 上传预构建的 DOCX 时,它们不会生效。

五种元素覆盖对象可让你调整各个 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 document.odt -X POST "https://api.tiptap.dev/v2/convert/export/odt" \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "doc": "{\"type\":\"doc\",\"content\":[{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"ODT with element-level overrides\"}]}]}",
      "paragraphOverrides": {
        "spacing": { "before": 200, "after": 200 }
      },
      "textRunOverrides": {
        "font": "Arial",
        "size": 24
      }
    }'

带自定义页面布局的示例

curl --output document.odt -X POST "https://api.tiptap.dev/v2/convert/export/odt" \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "doc": "{\"type\":\"doc\",\"content\":[{\"type\":\"paragraph\",\"content\":[{\"type\":\"text\",\"text\":\"Hello World\"}]}]}",
      "pageSize": {
        "width": "210mm",
        "height": "297mm"
      },
      "pageMargins": {
        "top": "20mm",
        "bottom": "20mm",
        "left": "15mm",
        "right": "15mm"
      }
    }'

响应

成功时,API 返回 ODT 文件作为二进制下载:

  • 状态:200 OK
  • Content-Type:application/vnd.oasis.opendocument.text
  • Content-Disposition:attachment; filename=export-{timestamp}.odt

错误响应

状态码代码描述
400NO_DOCUMENT_PROVIDED请求体中未提供文档
422FAILED_TO_PARSE_DOCX_FILE解析 JSON 输入失败
422FAILED_TO_EXPORT_ODT_FILE导出中间格式失败
422FAILED_TO_CONVERT_DOCX_TO_ODT转换为 ODT 失败