Tiptap 中文文档

从零开始到打印就绪：Pages 与 DOCX 导出

Alpha

本指南将带你从零开始搭建一个 Tiptap 编辑器，使用 Pages 扩展实现分页、类似印刷的版式，并支持 DOCX 导入导出，以便构建专业、可直接印刷的工作流。

1. 安装 Pages 技术栈

安装这三个始终会一起使用的 Pro 包，当你使用 Pages 构建时需要它们：

npm install @tiptap-pro/extension-convert-kit \
            @tiptap-pro/extension-pages-tablekit \
            @tiptap-pro/extension-pages

为什么是这三个包

@tiptap-pro/extension-convert-kit 提供编辑器的节点和标记 schema（段落、 标题、列表、图片、标记）。@tiptap-pro/extension-pages-tablekit 提供分页安全的 表格——这是必须的，因为 ConvertKit 内置的表格并不是为分页而设计的。 @tiptap-pro/extension-pages 提供页面布局本身。请确保你已经先完成对 Tiptap 私有 npm registry 的身份验证；有关设置，请参阅 Pro Extensions 指南。

2. 使用 Pages 设置你的编辑器 

import { Editor } from '@tiptap/core'
import { ConvertKit } from '@tiptap-pro/extension-convert-kit'
import { TableKit } from '@tiptap-pro/extension-pages-tablekit'
import { Pages } from '@tiptap-pro/extension-pages'

const editor = new Editor({
  extensions: [
    ConvertKit.configure({ table: false }),
    TableKit,
    Pages.configure({
      pageFormat: 'A4',
      pageGap: 40,
      header: '我的项目',
      footer: '第 {page} 页，共 {total} 页',
      pageGapBackground: '#f8f8f8',
    }),
  ],
})

最佳实践

尽早在你的设置中添加 Pages，这样文档结构和布局从一开始就是一致的。 你之后可以通过命令更改页面格式、页眉和页脚；但如果某个文档在创建时没有考虑分页， 再补加 Pages 会更困难。

3. 添加 DOCX 导出能力

安装 DOCX 导出扩展：

npm install @tiptap-pro/extension-export-docx

将其添加到你的编辑器：

import { ExportDocx } from '@tiptap-pro/extension-export-docx'

const editor = new Editor({
  extensions: [
    ConvertKit.configure({ table: false }),
    TableKit,
    Pages.configure({
      /* ... */
    }),
    ExportDocx,
  ],
})

3a. 配置 DOCX 导出

DOCX 导出扩展完全在浏览器中运行——没有 JWT，没有 App ID，也没有服务器调用。你需要通过一个 onCompleteExport 回调来配置它，该回调会接收结果：

import { ExportDocx } from '@tiptap-pro/extension-export-docx'

ExportDocx.configure({
  // 必需。导出的文件会通过这个回调传递。
  onCompleteExport: (result) => {
    const blob = new Blob([result], {
      type: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
    })
    const url = URL.createObjectURL(blob)
    const a = document.createElement('a')
    a.href = url
    a.download = 'document.docx'
    a.click()
    URL.revokeObjectURL(url)
  },
  // 可选：'blob'（默认）、'buffer'、'string' 等。
  exportType: 'blob',
  // 可选：覆盖段落、标题、表格样式等。
  styleOverrides: {},
  // 可选：为你添加的任何自定义 Tiptap 节点定义 DOCX 序列化。
  customNodes: [],
})

必需项

onCompleteExport 是必需的。导出不会直接返回结果；它会把结果交给你的 回调，由你来下载、上传或处理。

4. 导出你的文档

从编辑器的命令链触发导出：

editor.commands.exportDocx()

往返并不完全字节一致

DOCX 导出是忠实的，但不是无损的。有少数特性（下标/上标标记、段落 行高、浮动表格）在往返转换时并不完美。完整列表请参阅 功能支持 矩阵。

5. 将 DOCX 文件导入到你的编辑器中

添加导入扩展，这样用户就可以把 Word 文档加载到分页编辑器中：

npm install @tiptap-pro/extension-import-docx
import { ImportDocx } from '@tiptap-pro/extension-import-docx'

const editor = new Editor({
  extensions: [
    ConvertKit.configure({ table: false }),
    TableKit,
    Pages.configure({
      /* ... */
    }),
    ExportDocx.configure({
      /* ... */
    }),
    ImportDocx.configure({
      appId: 'YOUR_APP_ID', // 你的 Convert App ID
      token: 'YOUR_JWT', // 由你的服务器生成的 JWT
      // 可选：导入服务应将文档中提取出的图片上传到哪里
      // imageUploadConfig: { url: 'https://your-server.com/upload-image' },
    }),
  ],
})

要触发导入，请从 <input type="file" /> 传入一个 File：

editor
  .chain()
  .importDocx({
    file,
    onImport(context) {
      if (context.error) {
        // 处理失败（提示、日志、重试等）
        return
      }
      context.setEditorContent(context.content)
    },
  })
  .run()

当导入的文档包含页眉和页脚时，Pages 扩展会自动识别它们——它们会在每个渲染页面的顶部和底部显示，无需额外配置。

在哪里获取你的 App ID 和 JWT

有关凭据设置，请参阅 转换安装指南。JWT 必须在服务器端生成；切勿将你的密钥嵌入浏览器中。

接下来的步骤

  • Pages 选项 — Pages 暴露的每个选项
  • 页面页眉和页脚 — 不同的首页、奇偶页、通过程序打开/关闭编辑器
  • PagesTableKit — 详细介绍分页安全表格，包括最重要的已知限制
  • 限制 — 不可拆分内容、Pages 不做什么，以及如何处理每种情况

需要帮助吗？

如果你遇到意料之外的问题，请联系支持团队，或者查看文档的其他部分以了解 高级工作流。

PreviouslyinchToPixels 工具