通过 REST API 转换 .docx

Available in Start planBeta

DOCX 文档转换 API 支持将 docx 文件转换为及从 Tiptap 的 JSON 格式。

查看 Postman 集合

您还可以通过访问我们的 Postman 集合来实验文档转换 API。

导入 DOCX

POST /v2/convert/import

/v2/convert/import 端点将 docx 文件转换为 Tiptap 的 JSON 格式。用户可以将文档 POST 到此端点，并使用各种参数自定义在转换过程中如何处理不同的文档元素。

示例 (cURL)

curl -X POST "https://api.tiptap.dev/v2/convert/import" \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "X-App-Id: YOUR_APP_ID" \
    -F "file=@/path/to/your/file.docx" \
    -F "imageUploadCallbackUrl=https://your-image-upload-endpoint.com" \
    -F "promisemirrorNodes={\"nodeKey\":\"nodeValue\"}" \
    -F "prosemirrorMarks={\"markKey\":\"markValue\"}"

需要订阅

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

必需的头部

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

请求体

名称	类型	描述
`file`	`File`	要转换的文件
`imageUploadCallbackUrl`	`string`	上传文档中遇到的图像的回调端点，查看更多信息
`prosemirrorNodes`	`Object string`	转换的自定义节点映射，查看更多信息。
`prosemirrorMarks`	`Object string`	转换的自定义标记映射，查看更多信息

自定义节点和标记映射

您可以通过在请求体中分别指定 prosemirrorNodes 和 prosemirrorMarks 来覆盖导入期间使用的默认 node/mark 类型。如果您的编辑器使用自定义的 nodes/marks，并且希望导入的 JSON 使用这些内容，则需要提供这些。

例如，如果您的架构使用一个名为 textBlock 的自定义节点类型，而不是默认的段落，您可以在请求体中包含 "{\"paragraph\":\"textBlock\"}"。

您还可以类似地调整标题、列表、加粗或斜体等标记。

默认节点

名称	描述
`paragraph`	定义段落转换使用的 prosemirror 类型
`heading`	定义标题转换使用的 prosemirror 类型
`blockquote`	定义引用转换使用的 prosemirror 类型
`codeblock`	定义代码块转换使用的 prosemirror 类型
`bulletlist`	定义无序列表转换使用的 prosemirror 类型
`orderedlist`	定义有序列表转换使用的 prosemirror 类型
`listitem`	定义列表项转换使用的 prosemirror 类型
`hardbreak`	定义硬换行转换使用的 prosemirror 类型
`horizontalrule`	定义水平线转换使用的 prosemirror 类型
`table`	定义表格转换使用的 prosemirror 类型
`tablecell`	定义表格单元格转换使用的 prosemirror 类型
`tableheader`	定义表格头部转换使用的 prosemirror 类型
`tablerow`	定义表格行转换使用的 prosemirror 类型
`image`	定义图片转换使用的 prosemirror 标记

默认标记

名称	描述
`bold`	定义粗体转换使用的 prosemirror 标记
`italic`	定义斜体转换使用的 prosemirror 标记
`underline`	定义下划线转换使用的 prosemirror 标记
`strikethrough`	定义删除线转换使用的 prosemirror 标记
`link`	定义链接转换使用的 prosemirror 标记
`code`	定义代码转换使用的 prosemirror 标记

导出 DOCX

POST /v2/convert/export

/v2/convert/export 端点将 Tiptap 文档转换为 DOCX 格式。用户可以将文档 POST 到此端点，并使用各种参数自定义在转换过程中如何处理不同的文档元素。

导出自定义支持

/v2/convert/export 端点不支持自定义节点转换，因为函数无法序列化，但它支持自定义样式覆盖。如果您希望在您自己的服务器上转换文档以拥有此选项，可以按照服务器端导出指南进行操作。

示例 (cURL)

curl --output example.docx -X POST https://api.tiptap.dev/v2/convert/export \
    -H "Authorization: Bearer <your-jwt-token>" \
    -H "X-App-Id: <your-app-id>" \
    -F 'doc={"type":"doc","content":[{"type":"paragraph","attrs":{"textAlign":"left"},"content":[{"type":"text","text":"欢迎来到我们编辑器的演示，这里展示了导出多种格式选项到 DOCX 的能力，确保您的内容在 Word 中保持其预期的外观。"}]}]}' \
    -F 'exportType=blob' \
    -F 'styleOverrides={}'

需要订阅

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

必需的头部

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

请求体

名称	类型	描述	默认值
`doc`	`String`	Tiptap 的 JSON	`N/A`
`exportType`	`string`	预期的导出类型	`blob`
`styleOverrides`	`Object`	样式覆盖	`{}`