通过 REST API 导入 DOCX

Available in Start planBetav2.12.0

DOCX 导入 API 会将 .docx 文件转换为 Tiptap 的 JSON 格式。它使用与编辑器扩展相同的转换服务，并生成完全相同的内容输出。

当您需要服务器端处理、访问脚注或尾注数据（这是扩展不会暴露的），或需要不经过 schema 过滤的原始 JSON 时，REST API 是更好的选择。如果您希望将内容直接加载到 Tiptap 编辑器中，并自动应用页眉和页脚，请改用编辑器扩展。

查看 Postman 集合

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

导入 DOCX

POST /v2/convert/import/docx

/v2/convert/import/docx 端点将 docx 文件转换为 Tiptap 的 JSON 格式。用户可向该端点 POST 文档，并通过多种参数定制转换过程中对不同文档元素的处理方式。

示例（cURL）

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

需要订阅

该端点需有效的 Tiptap 订阅。详细信息请查看我们的定价页面。

必需的请求头

名称	说明
`Authorization`	用于身份验证的 JWT 令牌。例如：`Bearer your-jwt-token`
`X-App-Id`	来自 Convert 设置页面的 Convert App-ID：https://cloud.tiptap.dev/v2/cloud/convert

请求体

名称	类型	说明
`file`	`File`	要转换的文件
`imageUploadConfig`	`JSON string`	配置图片上传的 JSON 对象。包含 `url`（必需），并可选包含 `headers`、`method` 和 `queryParams`。完整 schema 请参见编辑器扩展文档。
`prosemirrorNodes`	`Object string`	用于转换的自定义节点映射，查看更多信息。
`prosemirrorMarks`	`Object string`	用于转换的自定义标记映射，查看更多信息
`verbose`	`string \| number`	用于帮助您控制导入过程中诊断输出级别的配置属性。这对于调试或更深入了解转换过程中特别有用。更多信息请参见详细输出
`extractCssStyles`	`"true" \| "false"`	实验性。当为 `"true"` 时，响应将包含一个 `cssStyles` 字段，其中 DOCX 样式目录会转换为兼容 CSS 的键/值对。默认值为 `"false"`。有关输出结构和注意事项，请参见 CSS 样式提取。

导入详细输出

DOCX 导入扩展提供了一个 verbose 配置属性，帮助您控制导入过程中的诊断输出级别。此功能特别适合调试或获取转换过程的更多细节。

verbose 属性是一个位掩码数字，用于决定输出哪些类型的日志信息。扩展使用以下级别：

值	级别	说明
1	`log`	一般信息日志
2	`warn`	警告
4	`error`	错误

详细输出位掩码

您可以通过相加值来组合级别。例如，verbose: 3 会启用 log (1) 和 warn (2) 两种消息。

详细输出会在返回的 data 属性外，增加一个名为 logs 的属性，包含 info、warn 和 error 三个数组，分别保存对应级别的日志信息。

{
  "data": {
    "content": {
        // Tiptap JSON
    }
  },
  "logs": {
    "info": [],
    "warn": [
      {
        "message": "未在媒体文件中找到图片文件",
        "fileName": "image1.gif",
        "availableMediaFiles": []
      }
    ],
    "error": [
      {
        "message": "图片上传失败：一般错误",
        "fileName": "image1.gif",
        "url": "https://your-image-upload-endpoint.com",
        "error": "无法连接。计算机是否能够访问该 url？",
        "context": "uploadImage general error"
      }
    ]
  }
}

响应中的页眉与页脚

导入 API 会从 .docx 文件中提取页眉和页脚。当文档包含页眉或页脚内容时，响应的 data 对象会包含额外字段。

响应字段

字段名	类型	说明
`content`	`Object`	以 Tiptap JSON 格式表示的文档主体
`header`	`Object \| null`	默认页眉内容，Tiptap JSON
`footer`	`Object \| null`	默认页脚内容，Tiptap JSON
`headerFirstPage`	`Object \| null`	首页页眉（当 Word 中启用了"首页不同"功能时）
`footerFirstPage`	`Object \| null`	首页页脚（当 Word 中启用了"首页不同"功能时）
`headerOdd`	`Object \| null`	奇数页页眉（当 Word 中启用了"奇偶页不同"功能时）
`footerOdd`	`Object \| null`	奇数页页脚（当 Word 中启用了"奇偶页不同"功能时）
`headerEven`	`Object \| null`	偶数页页眉（当 Word 中启用了"奇偶页不同"功能时）
`footerEven`	`Object \| null`	偶数页页脚（当 Word 中启用了"奇偶页不同"功能时）

字段为 null 表示该文档未定义该特定页眉或页脚内容。

响应中的脚注与尾注

导入 API 会从 .docx 文件中提取脚注和尾注。当文档包含脚注或尾注内容时，响应的 data 对象会包含额外字段。

响应字段

字段	类型	说明
`footnotes`	`Object`	以脚注 ID 为键的对象，每个值是一个 Tiptap JSON 文档 (`{ type: "doc", content: [...] }`)
`endnotes`	`Object`	以尾注 ID 为键的对象，每个值是一个 Tiptap JSON 文档 (`{ type: "doc", content: [...] }`)

不包含脚注或尾注的文档会返回空对象 ({})，因此不会影响现有集成。

文档体中的内联引用表示为 footnoteReference 和 endnoteReference 节点，每个都携带一个 noteId 属性，链接到 footnotes 或 endnotes 中对应的条目。

响应示例

{
  "data": {
    "content": {
      "type": "doc",
      "content": [
        {
          "type": "paragraph",
          "content": [
            { "type": "text", "text": "This sentence has a footnote" },
            { "type": "footnoteReference", "attrs": { "noteId": "1" } },
            { "type": "text", "text": " and an endnote" },
            { "type": "endnoteReference", "attrs": { "noteId": "1" } },
            { "type": "text", "text": "." }
          ]
        }
      ]
    },
    "footnotes": {
      "1": {
        "type": "doc",
        "content": [
          {
            "type": "paragraph",
            "content": [{ "type": "text", "text": "This is the footnote content." }]
          }
        ]
      }
    },
    "endnotes": {
      "1": {
        "type": "doc",
        "content": [
          {
            "type": "paragraph",
            "content": [{ "type": "text", "text": "This is the endnote content." }]
          }
        ]
      }
    },
    "header": null,
    "footer": null,
    "headerFirstPage": null,
    "footerFirstPage": null,
    "headerOdd": null,
    "footerOdd": null,
    "headerEven": null,
    "footerEven": null
  }
}

CSS 样式提取（实验性）

实验性功能

extractCssStyles 为选择启用的实验性功能。响应的形状可能会在不另行通知的情况下发生变化。如果您依赖它，请固定精确的客户端版本；并阅读完整的 CSS 注入文档，以获取支持的选择器、 CSS 属性以及已知限制的完整列表。

在请求中传入 extractCssStyles=true，即可使响应包含一个 cssStyles 字段。该字段包含将 DOCX 默认样式目录转换为兼容 CSS 的键/值对，并以 CSS 选择器为键。

请求

curl -X POST "https://api.tiptap.dev/v2/convert/import/docx" \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "X-App-Id: YOUR_APP_ID" \
    -F "file=@/path/to/your/file.docx" \
    -F "extractCssStyles=true"

响应字段

Field	Type	Description
`cssStyles`	`Object`	以 CSS 选择器为键的对象，每个值都是一个 CSS 属性对象。当文档没有可提取的默认样式时，该对象为空 (`{}`)。当未设置 `extractCssStyles` 或其值为 `"false"` 时，此字段会完全从响应中省略。

支持的选择器

提取器会将 DOCX 命名样式映射到以下固定的 CSS 选择器集合。与映射不匹配的样式不会被转换。

p, h1, h2, h3, h4, h5, h6, blockquote, ul li, ol li, strong, em, u, s, a, code

支持的 CSS 属性

以上每个选择器都可以携带以下属性的任意子集，具体取决于 DOCX 中定义的样式。

color, fontSize, fontFamily, fontWeight, fontStyle, textDecoration, backgroundColor, textAlign, marginTop, marginBottom, lineHeight

示例响应

{
  "data": {
    "content": {
      "type": "doc",
      "content": [
        {
          "type": "paragraph",
          "content": [{ "type": "text", "text": "Document body..." }]
        }
      ]
    },
    "cssStyles": {
      "p": {
        "fontSize": "16px",
        "fontFamily": "Calibri",
        "lineHeight": 1.15,
        "marginBottom": "8pt"
      },
      "h1": {
        "fontSize": "28px",
        "fontWeight": "bold",
        "color": "#1F3864",
        "marginTop": "24pt",
        "marginBottom": "6pt"
      },
      "a": {
        "color": "#0563C1",
        "textDecoration": "underline"
      },
      "blockquote": {
        "fontStyle": "italic",
        "color": "#595959"
      }
    }
  }
}

关于输出的说明：

值为字符串或数字。 基于像素的属性（fontSize）会输出为 "Npx" 字符串；基于磅的间距（marginTop、marginBottom）会输出为 "Npt"；无单位的乘数（auto 行规则下的 lineHeight）会输出为普通数字。
样式继承已解析。 子 DOCX 样式会包含其从父样式继承的所有内容（通过 basedOn）；输出会被扁平化，因此您无需沿链向上遍历。
支持本地化文档。 非英语版 Word 中的命名样式会在输出前映射回其规范选择器。
缺失字段表示“未定义”。 只有在至少提取到一个属性时，某个选择器才会出现。如果 DOCX 没有样式目录（或所有命名样式都不在这 16 个选择器映射中），cssStyles 将为 {}。

自定义节点与标记映射

您可以通过请求体中的 prosemirrorNodes 和 prosemirrorMarks 覆盖导入时的默认 node/mark 类型。如果您的编辑器使用自定义的 nodes/marks，希望导入的 JSON 采用它们，则需要提供这些映射。

例如，如果您的 schema 使用名为 textBlock 的自定义节点替代默认的段落，可以在请求体中包含 "{\"textBlock\":\"paragraph\"}"。

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

默认节点

名称	说明
`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 标记
`footnoteReference`	定义用于脚注引用转换的 ProseMirror 类型
`endnoteReference`	定义用于尾注引用转换的 ProseMirror 类型

默认标记

名称	说明
`bold`	指定用于加粗转换的 ProseMirror 标记
`italic`	指定用于斜体转换的 ProseMirror 标记
`underline`	指定用于下划线转换的 ProseMirror 标记
`strikethrough`	指定用于删除线转换的 ProseMirror 标记
`link`	指定用于链接转换的 ProseMirror 标记
`code`	指定用于代码转换的 ProseMirror 标记

支持与限制

有关管道每个阶段支持哪些文档特性的详细说明，请参见支持的特性矩阵。

PreviouslyCSS 注入

Next up自定义