探索 Tiptap V3 的最新功能

旧版 DOCX 导入与导出

Editor

Tiptap 原始的 extension-importextension-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()

导入选项

名称类型默认值描述
appIdstringundefined从转换设置页面获取的 Convert App ID:https://cloud.tiptap.dev/convert-settings
tokenstringundefined通过服务端密钥生成的 JWT 令牌
imageUploadCallbackUrlstringundefined图片上传的 URL,若未提供,文档内的图片将被移除,查看更多信息
experimentalDocxImportbooleanfalse启用实验性的 DOCX 导入功能,更好地保留内容样式(实验性功能,此 API 在 alpha 期间可能不稳定),仅适用于上传的 DOCX 文件

命令

名称描述
import将文件导入编辑器

import

参数
名称类型默认值选项描述
fileFileundefined任意文件要导入的文件
formatstringundefinedgfm用于格式不明确的特殊情况,比如 GitHub Flavored Markdown
onImportFunctionundefinedfn(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 做了修改,需要手动处理下载
  },
})

导出选项

名称类型默认值描述
appIdstringundefined从转换设置页面获取的 Convert App ID:https://cloud.tiptap.dev/convert-settings
tokenstringundefined通过服务端密钥生成的 JWT 令牌

命令

名称描述
export导出编辑器内容

export

参数
名称类型默认值选项描述
formatstringundefineddocx,odt,md,gfm要导出的格式
contentJSONContentundefined任意 Tiptap JSON要导出的 Tiptap JSON 内容
onExportFunctionundefinedfn(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 端点支持将 docxodtmarkdown 文件转换为 Tiptap 的 JSON 格式。用户可以向该端点 POST 文档,并使用多种参数自定义不同文档元素在转换过程中的处理方式。

  • 请求方法POST

必需请求头

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

请求体

名称类型描述
fileFile要转换的文件
imageUploadCallbackUrlstring上传文档中遇到的图片的回调端点,查看详情

查询参数

指定源文档元素如何映射到 ProseMirror 的节点或标记,并调整转换以满足具体的样式和结构偏好。

名称默认值描述
paragraphparagraph用于段落转换的 ProseMirror 类型
headingheading用于标题转换的 ProseMirror 类型
blockquoteblockquote用于引用块转换的 ProseMirror 类型
codeblockcodeblock用于代码块转换的 ProseMirror 类型
bulletlistbulletlist用于无序列表转换的 ProseMirror 类型
orderedlistorderedlist用于有序列表转换的 ProseMirror 类型
listitemlistitem用于列表项转换的 ProseMirror 类型
hardbreakhardbreak用于硬换行转换的 ProseMirror 类型
horizontalrulehorizontalrule用于水平分割线转换的 ProseMirror 类型
tabletable用于表格转换的 ProseMirror 类型
tablecelltablecell用于表格单元格转换的 ProseMirror 类型
tableheadertableheader用于表格头部转换的 ProseMirror 类型
tablerowtablerow用于表格行转换的 ProseMirror 类型
boldbold用于加粗转换的 ProseMirror 标记
italicitalic用于斜体转换的 ProseMirror 标记
underlineunderline用于下划线转换的 ProseMirror 标记
strikethroughstrike用于删除线转换的 ProseMirror 标记
linklink用于链接转换的 ProseMirror 标记
codecode用于代码转换的 ProseMirror 标记
imageimage用于图片转换的 ProseMirror 标记

/import-docx 端点(实验性)

/import-docx 端点支持将 docx 文件转换为 Tiptap 的 JSON 格式,允许更多针对 docx 的特定功能,相较于 /import 端点具有更丰富的参数。用户可以向该端点 POST 文档,并使用各种参数自定义不同文档元素在转换过程中的处理方式。

  • 请求方法POST

必需请求头

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

请求体

名称类型描述
fileFile要转换的文件
imageUploadCallbackUrlstring上传文档中遇到的图片的回调端点,查看详情

查询参数

/import,指定源文档元素映射规则和转换行为。

名称默认值描述
paragraphparagraph用于段落转换的 ProseMirror 类型
headingheading用于标题转换的 ProseMirror 类型
blockquoteblockquote用于引用块转换的 ProseMirror 类型
codeblockcodeblock用于代码块转换的 ProseMirror 类型
bulletlistbulletlist用于无序列表转换的 ProseMirror 类型
orderedlistorderedlist用于有序列表转换的 ProseMirror 类型
listitemlistitem用于列表项转换的 ProseMirror 类型
hardbreakhardbreak用于硬换行转换的 ProseMirror 类型
horizontalrulehorizontalrule用于水平分割线转换的 ProseMirror 类型
tabletable用于表格转换的 ProseMirror 类型
tablecelltablecell用于表格单元格转换的 ProseMirror 类型
tableheadertableheader用于表格头部转换的 ProseMirror 类型
tablerowtablerow用于表格行转换的 ProseMirror 类型
boldbold用于加粗转换的 ProseMirror 标记
italicitalic用于斜体转换的 ProseMirror 标记
underlineunderline用于下划线转换的 ProseMirror 标记
strikethroughstrike用于删除线转换的 ProseMirror 标记
linklink用于链接转换的 ProseMirror 标记
codecode用于代码转换的 ProseMirror 标记
imageimage用于图片转换的 ProseMirror 标记

/export 端点

/export 端点支持将 Tiptap 文档转换回 docxodtmarkdown 等格式。

  • 请求方法POST

将 Tiptap 文档转换为指定格式。

必需请求头

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

请求体

名称类型描述
contentObjectTiptap 文档
formatstring要转换的格式,可为 docxodtmarkdown

查询参数

名称默认值描述
gfm0使用 GitHub 风格 Markdown 导出
paragraphparagraph用于段落转换的 ProseMirror 类型
headingheading用于标题转换的 ProseMirror 类型
blockquoteblockquote用于引用块转换的 ProseMirror 类型
codeblockcodeblock用于代码块转换的 ProseMirror 类型
bulletlistbulletlist用于无序列表转换的 ProseMirror 类型
orderedlistorderedlist用于有序列表转换的 ProseMirror 类型
listitemlistitem用于列表项转换的 ProseMirror 类型
hardbreakhardbreak用于硬换行转换的 ProseMirror 类型
horizontalrulehorizontalrule用于水平分割线转换的 ProseMirror 类型
tabletable用于表格转换的 ProseMirror 类型
tablecelltablecell用于表格单元格转换的 ProseMirror 类型
tableheadertableheader用于表格头部转换的 ProseMirror 类型
tablerowtablerow用于表格行转换的 ProseMirror 类型
boldbold用于加粗转换的 ProseMirror 标记
italicitalic用于斜体转换的 ProseMirror 标记
underlineunderline用于下划线转换的 ProseMirror 标记
strikethroughstrike用于删除线转换的 ProseMirror 标记
linklink用于链接转换的 ProseMirror 标记
codecode用于代码转换的 ProseMirror 标记