安装

Available in Start planBeta

为你的项目设置凭据并安装转换扩展。

前置条件

开始免费试用或选择订阅。
设置对 Tiptap 私有 npm 仓库的访问权限。

身份验证

大多数转换扩展和 REST API 端点都需要签名 JWT。DOCX 导出扩展是例外，无需凭据即可使用。

将 aud 声明设置为 "Convert"，并授予集成所使用的格式和方向操作。要创建密钥对并签署令牌，请参阅身份验证。

操作

每个转换方向都有自己的操作，因此，令牌的作用域始终严格限定为某项功能所需的操作；即使新增了转换方向，也不会被静默扩大：

操作	授予权限
`Convert:Import:Docx`	导入 DOCX
`Convert:Export:Docx`	导出 DOCX
`Convert:Import:Markdown`	导入 Markdown
`Convert:Export:Markdown`	导出 Markdown
`Convert:Export:Doc`	导出旧版 DOC
`Convert:Export:Odt`	导出 ODT
`Convert:Export:Epub`	导出 EPUB
`Convert:Export:Pdf`	导出 PDF
`Convert:Fonts`	管理字体缓存（`/fonts/*`），仅限本地部署

不带明确格式的旧路由（POST /v2/import、POST /v2/export）分别检查 Convert:Import:Docx 和 Convert:Export:Docx。

示例令牌

{
  "iss": "env_abc123",
  "aud": "Convert",
  "exp": 1777033105,
  "permissions": [
    { "action": "Convert:Import:Docx", "resource": "*" },
    { "action": "Convert:Export:Docx", "resource": "*" },
    { "action": "Convert:Export:Pdf", "resource": "*" }
  ]
}

使用此令牌请求 POST /v2/export/pdf 会成功。POST /v2/export/odt 会返回 permission_denied 错误，指出缺少的操作权限。

对于 REST 调用，请将令牌放在 Authorization: Bearer <jwt> 标头中；对于编辑器扩展，请通过 token 选项传递令牌。请求只需要令牌即可。

导入批注

导入包含批注的文档时，会将这些批注写入 Document Server。请将 Documents:Write 与你的 Convert:Import:* 操作一并包含，这样导入才能保存这些批注。参见跨服务操作。

错误响应

当令牌缺少所需权限时，服务会返回 403 Forbidden，内容如下：

{
  "message": "Token is missing permission Convert:Export:Pdf.",
  "code": "permission_denied"
}

如果环境的订阅根本不包含 Convert，则响应为 403，且 code: feature_not_available。上游云错误会被清晰映射：429 rate_limited、503 service_unavailable，以及 401 token_expired / signature_invalid，这样你的客户端就能区分无效令牌和临时性的云端问题。

正在维护现有集成？

之前的 App ID 和 secret 流程记录在旧版身份验证中，并且仍然可用。

安装包

安装你需要支持的格式所对应的扩展。

导入：

# DOCX 导入（编辑器扩展）
npm install @tiptap-pro/extension-import-docx

导出：

# DOCX 导出（编辑器扩展，无需身份验证）
npm install @tiptap-pro/extension-export-docx

# PDF 导出
npm install @tiptap-pro/extension-export-pdf

# ODT 导出
npm install @tiptap-pro/extension-export-odt

# EPUB 导出
npm install @tiptap-pro/extension-export-epub

# Markdown 导出
npm install @tiptap-pro/extension-export-markdown

DOCX 导出无需身份验证

@tiptap-pro/extension-export-docx 软件包完全在客户端处理转换。无需令牌或服务器调用。

下一步

在侧边栏中选择您的格式，以查看每个扩展和 REST API 的完整设置与配置指南。

Previously概述

Next up在线演示