Tiptap 原始的 extension-import 和 extension-export 包提供了可靠的方法来导入和导出 DOCX 文件。
这些扩展及相关端点仍对所有拥有 Tiptap 账户的用户开放,但已不再积极开发。
它们将于 2025 年晚些时候正式退役,并由新的 Tiptap 转换 扩展和服务取代。
以下指南重点介绍如何配置旧版扩展。
导入旧版扩展
旧版导入扩展即将废弃
extension-import 包将于 2025 年晚些时候停止支持。请规划迁移至我们的新版解决方案或其他端点,以确保服务不中断。
// 首先导入扩展
import { Import } from '@tiptap-pro/extension-import'
const editor = new Editor({
// ...
extensions: [
// ...
Import.configure({
// 从转换设置页面获取的 Convert App-ID:https://cloud.tiptap.dev/convert-settings
appId: 'your-app-id',
// 之前步骤生成的 JWT 令牌
token: 'your-jwt',
// 图片上传的 URL,若未提供,文档中的图片将被移除
imageUploadCallbackUrl: 'https://your-image-upload-url.com',
// 启用实验性的 DOCX 导入功能,更好地保留内容样式
experimentalDocxImport: true,
}),
],
})
导入第一个文档
// 最简单的文件导入方式
// 导入上传的文件,替换编辑器内容并聚焦编辑器
editor.chain().focus().import({ file }).run()
自定义导入行为
// 也可以使用 onImport 回调自定义导入行为
editor
.chain()
.import({
file,
onImport(context) {
const { setEditorContent, content, error } = context
// 添加错误处理
if (error) {
showErrorToast({ message: error.message })
}
// 也可以在插入前修改内容
content.doc.content.push({ type: 'paragraph', content: [{ type: 'text', text: 'Hello!' }] })
// 例如,你可以更改应用程序的加载状态
isLoading = false
// 如果希望运行扩展的默认插入行为,确保调用 setEditorContent 函数
// setEditorContent()
// 由于我们修改了内容,需要手动插入
editor.commands.setContent(content)
},
})
.focus()
.run()
导入选项
| 名称 | 类型 | 默认值 | 描述 |
|---|
appId | string | undefined | 从转换设置页面获取的 Convert App ID:https://cloud.tiptap.dev/convert-settings |
token | string | undefined | 通过服务端密钥生成的 JWT 令牌 |
imageUploadCallbackUrl | string | undefined | 图片上传的 URL,若未提供,文档内的图片将被移除,查看更多信息 |
experimentalDocxImport | boolean | false | 启用实验性的 DOCX 导入功能,更好地保留内容样式(实验性功能,此 API 在 alpha 期间可能不稳定),仅适用于上传的 DOCX 文件 |
命令
import
参数
| 名称 | 类型 | 默认值 | 选项 | 描述 |
|---|
file | File | undefined | 任意文件 | 要导入的文件 |
format | string | undefined | gfm | 用于格式不明确的特殊情况,比如 GitHub Flavored Markdown |
onImport | Function | undefined | fn(context) | 用于自定义导入行为的回调函数。context 包含内容、错误信息以及用于修改内容的 setEditorContent 函数 |
支持的格式
docx - Microsoft Word、Google Docs、OpenOffice、LibreOffice 等
odt - OpenDocument 文本文档格式,OpenOffice、LibreOffice 等使用
rtf - Microsoft Word、Google Docs 等使用的富文本格式
- Commonmark
markdown - 多种编辑器和平台使用的 Markdown 格式
- GFM
markdown - GitHub 风格 Markdown 格式
注意事项与限制
- 图片上传 - 假设图片是文档内联的,因此需要编辑器配置
Image.configure({ inline: true }) 以正确显示,否则会被移除
- 导入时不支持的 DOCX 元素 - 当前导入时不支持分页符、页眉页脚、水平分割线或文本样式
- 建议模式中添加的内容 - 建议模式添加的内容不会包含在导入的 ProseMirror 文档中
- PDF 导入与导出 - 目前不支持 PDF 文件的导入和导出
- 内联样式 - 当前不解析内联样式,导入导出中不可用
导出旧版扩展
旧版导出扩展即将废弃
extension-export 包将于 2025 年晚些时候停止支持。我们强烈建议迁移至更新的导出扩展,享受更好的自定义功能和持续支持。
// 首先导入扩展
import { Export } from '@tiptap-pro/extension-export'
const editor = new Editor({
// ...
extensions: [
// ...
Export.configure({
// 从转换设置页面获取的 Convert App-ID:https://cloud.tiptap.dev/convert-settings
appId: 'your-app-id',
// 之前步骤生成的 JWT 令牌
token: 'your-jwt',
}),
],
})
导出文档
// 简单导出为 docx
// 支持格式: docx, odt, md 和 gfm
editor.chain().focus().export({ format: 'docx' }).run()
自定义导出行为
// 也可以使用 onExport 回调自定义导出行为
editor.chain().export({
format: 'docx',
onExport(context) {
const { blob, error, download, filename } = context
// 添加错误处理
if (error) {
showErrorToast({ message: error.message })
}
// 例如,可以更改应用程序的加载状态
isLoading = false
// 这里可以修改文件名或以其他方式处理 blob
// 但此处保持不变
// 可以直接调用 download 方法触发下载
download()
// 请注意,download 方法仅在浏览器中有效
// 如果对 blob 或 filename 做了修改,需要手动处理下载
},
})
导出选项
命令
export
参数
| 名称 | 类型 | 默认值 | 选项 | 描述 |
|---|
format | string | undefined | docx,odt,md,gfm | 要导出的格式 |
content | JSONContent | undefined | 任意 Tiptap JSON | 要导出的 Tiptap JSON 内容 |
onExport | Function | undefined | fn(context) | 用于自定义导出行为的回调函数。context 包含关于 blob、文件名、错误信息以及用于直接下载文档的 download 函数 |
支持的格式
docx - Microsoft Word、Google Docs、OpenOffice、LibreOffice 等
odt - OpenDocument 文本文档格式,OpenOffice、LibreOffice 等使用
- Commonmark
markdown - 多种编辑器和平台使用的 Markdown 格式
- GFM
markdown - GitHub 风格 Markdown 格式
注意事项与限制
- 自定义节点导出 - 自定义节点或标记的导出支持请参考新版 Conversion 扩展和端点
- 自定义 DOCX 模板 - 请查看我们的新版 Conversion 扩展和端点以集成 DOCX 模板
- PDF 导入与导出 - 目前不支持 PDF 文件的导入和导出
- 内联样式 - 详情请参考新版 Conversion 扩展和端点以集成内联样式
旧版 REST API
旧版 /v1/ 转换 REST API 即将废弃
/v1/ 文档转换 REST API 将于 2025 年晚些时候停止支持。请迁移至新版 API 端点 以获得持续更新和维护,或查阅我们的 Postman 集合 获取最新资源。
旧版文档转换 API 支持 DOCX、ODT 和 Markdown 与 Tiptap JSON 格式之间的转换。
/import 端点
/import 端点支持将 docx、odt 或 markdown 文件转换为 Tiptap 的 JSON 格式。用户可以向该端点 POST 文档,并使用多种参数自定义不同文档元素在转换过程中的处理方式。
必需请求头
请求体
| 名称 | 类型 | 描述 |
|---|
file | File | 要转换的文件 |
imageUploadCallbackUrl | string | 上传文档中遇到的图片的回调端点,查看详情 |
查询参数
指定源文档元素如何映射到 ProseMirror 的节点或标记,并调整转换以满足具体的样式和结构偏好。
| 名称 | 默认值 | 描述 |
|---|
paragraph | paragraph | 用于段落转换的 ProseMirror 类型 |
heading | heading | 用于标题转换的 ProseMirror 类型 |
blockquote | blockquote | 用于引用块转换的 ProseMirror 类型 |
codeblock | codeblock | 用于代码块转换的 ProseMirror 类型 |
bulletlist | bulletlist | 用于无序列表转换的 ProseMirror 类型 |
orderedlist | orderedlist | 用于有序列表转换的 ProseMirror 类型 |
listitem | listitem | 用于列表项转换的 ProseMirror 类型 |
hardbreak | hardbreak | 用于硬换行转换的 ProseMirror 类型 |
horizontalrule | horizontalrule | 用于水平分割线转换的 ProseMirror 类型 |
table | table | 用于表格转换的 ProseMirror 类型 |
tablecell | tablecell | 用于表格单元格转换的 ProseMirror 类型 |
tableheader | tableheader | 用于表格头部转换的 ProseMirror 类型 |
tablerow | tablerow | 用于表格行转换的 ProseMirror 类型 |
bold | bold | 用于加粗转换的 ProseMirror 标记 |
italic | italic | 用于斜体转换的 ProseMirror 标记 |
underline | underline | 用于下划线转换的 ProseMirror 标记 |
strikethrough | strike | 用于删除线转换的 ProseMirror 标记 |
link | link | 用于链接转换的 ProseMirror 标记 |
code | code | 用于代码转换的 ProseMirror 标记 |
image | image | 用于图片转换的 ProseMirror 标记 |
/import-docx 端点(实验性)
/import-docx 端点支持将 docx 文件转换为 Tiptap 的 JSON 格式,允许更多针对 docx 的特定功能,相较于 /import 端点具有更丰富的参数。用户可以向该端点 POST 文档,并使用各种参数自定义不同文档元素在转换过程中的处理方式。
必需请求头
请求体
| 名称 | 类型 | 描述 |
|---|
file | File | 要转换的文件 |
imageUploadCallbackUrl | string | 上传文档中遇到的图片的回调端点,查看详情 |
查询参数
同 /import,指定源文档元素映射规则和转换行为。
| 名称 | 默认值 | 描述 |
|---|
paragraph | paragraph | 用于段落转换的 ProseMirror 类型 |
heading | heading | 用于标题转换的 ProseMirror 类型 |
blockquote | blockquote | 用于引用块转换的 ProseMirror 类型 |
codeblock | codeblock | 用于代码块转换的 ProseMirror 类型 |
bulletlist | bulletlist | 用于无序列表转换的 ProseMirror 类型 |
orderedlist | orderedlist | 用于有序列表转换的 ProseMirror 类型 |
listitem | listitem | 用于列表项转换的 ProseMirror 类型 |
hardbreak | hardbreak | 用于硬换行转换的 ProseMirror 类型 |
horizontalrule | horizontalrule | 用于水平分割线转换的 ProseMirror 类型 |
table | table | 用于表格转换的 ProseMirror 类型 |
tablecell | tablecell | 用于表格单元格转换的 ProseMirror 类型 |
tableheader | tableheader | 用于表格头部转换的 ProseMirror 类型 |
tablerow | tablerow | 用于表格行转换的 ProseMirror 类型 |
bold | bold | 用于加粗转换的 ProseMirror 标记 |
italic | italic | 用于斜体转换的 ProseMirror 标记 |
underline | underline | 用于下划线转换的 ProseMirror 标记 |
strikethrough | strike | 用于删除线转换的 ProseMirror 标记 |
link | link | 用于链接转换的 ProseMirror 标记 |
code | code | 用于代码转换的 ProseMirror 标记 |
image | image | 用于图片转换的 ProseMirror 标记 |
/export 端点
/export 端点支持将 Tiptap 文档转换回 docx、odt 或 markdown 等格式。
将 Tiptap 文档转换为指定格式。
必需请求头
请求体
| 名称 | 类型 | 描述 |
|---|
content | Object | Tiptap 文档 |
format | string | 要转换的格式,可为 docx、odt 或 markdown |
查询参数
| 名称 | 默认值 | 描述 |
|---|
gfm | 0 | 使用 GitHub 风格 Markdown 导出 |
paragraph | paragraph | 用于段落转换的 ProseMirror 类型 |
heading | heading | 用于标题转换的 ProseMirror 类型 |
blockquote | blockquote | 用于引用块转换的 ProseMirror 类型 |
codeblock | codeblock | 用于代码块转换的 ProseMirror 类型 |
bulletlist | bulletlist | 用于无序列表转换的 ProseMirror 类型 |
orderedlist | orderedlist | 用于有序列表转换的 ProseMirror 类型 |
listitem | listitem | 用于列表项转换的 ProseMirror 类型 |
hardbreak | hardbreak | 用于硬换行转换的 ProseMirror 类型 |
horizontalrule | horizontalrule | 用于水平分割线转换的 ProseMirror 类型 |
table | table | 用于表格转换的 ProseMirror 类型 |
tablecell | tablecell | 用于表格单元格转换的 ProseMirror 类型 |
tableheader | tableheader | 用于表格头部转换的 ProseMirror 类型 |
tablerow | tablerow | 用于表格行转换的 ProseMirror 类型 |
bold | bold | 用于加粗转换的 ProseMirror 标记 |
italic | italic | 用于斜体转换的 ProseMirror 标记 |
underline | underline | 用于下划线转换的 ProseMirror 标记 |
strikethrough | strike | 用于删除线转换的 ProseMirror 标记 |
link | link | 用于链接转换的 ProseMirror 标记 |
code | code | 用于代码转换的 ProseMirror 标记 |