Tiptap 中文文档

页面

Tiptap Pages 是 Tiptap 的分页编辑层。它在任何 Tiptap 编辑器之上增加了页面边界、页面格式、页眉、页脚、分页符和缩放功能。有了它，你的读者可以像在文字处理器中一样撰写报告、信件、合同或书籍。

Try Tiptap Pages，在这个交互式 DOCX 编辑器演示中体验分页、 页眉和页脚，以及 DOCX/PDF 导出。

全屏|了解更多

Pro 套餐

Pages 是一个 Pro 套餐，包含在 Tiptap 订阅 中。安装前，请先配置好 访问 Tiptap 的私有 NPM 仓库。

这项功能的作用

  • 分页布局：内容会在所选格式（A4、Letter、自定义）的可视页面之间流动。
  • 页面格式和边距：内置格式提供合理的默认值，自定义格式对象则让你完全掌控。
  • 页眉和页脚：可将其定义为静态文本、HTML 字符串或 Tiptap JSON。它们支持 {page} 和 {total} 占位符，并且你可以像 Word 一样，为首页或奇偶页分别设置独立的槽位。
  • 脚注：类似 Word 的脚注，会显示在每页页脚上方，自动编号，并在内容重排时跟随其引用位置。参见 脚注。
  • 尾注：类似 Word 的尾注，收集在文档末尾，使用小写罗马数字、自动编号，并支持就地编辑。参见 尾注。
  • 就地编辑：双击页眉、页脚、脚注或尾注区域，即可在覆盖层中打开功能完整的 Tiptap 编辑器。
  • 缩放：视觉缩放范围为 [0.25, 4]，不会影响文档内容或导出。
  • 分页符：可通过 PageBreak 扩展 插入显式分页，或让 Pages 自动处理分页。

随之安装的内容

Pages 不 自带节点和标记（mark）模式。要使用它，你还需要安装：

  • @tiptap-pro/extension-convert-kit：用于 Conversion 和 Pages 工作流的标准编辑器套件。ConvertKit 注册了一个支持 DOCX 的 schema（段落、标题、列表、图片、标记）。
  • @tiptap-pro/extension-pages-tablekit：支持分页安全的表格。必须安装，因为 ConvertKit 内置的表格并不是为分页而设计的。
npm install @tiptap-pro/extension-convert-kit \
            @tiptap-pro/extension-pages-tablekit \
            @tiptap-pro/extension-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',
      header: '我的文档',
      footer: '第 {page} 页，共 {total} 页',
    }),
  ],
})

完整步骤请参阅 安装指南。

可用内容

  • 内置页面格式：A4、A3、A5、Letter、Legal、Tabloid。你也可以定义具有任意尺寸和边距的自定义格式。
  • 页眉和页脚内容可以是纯文本、HTML 或 Tiptap JSON，并支持 {page} / {total} 占位符。
  • 首页面以及奇数/偶数页可使用不同的页眉和页脚，类似 Word。
  • 类 Word 的 脚注：每页脚注区域，带自动连续编号，会随其引用重新排版并占用页面空间。
  • 类 Word 的 尾注：文档末尾的单一列表，使用小写罗马数字和自动编号，跨页面流动，并保留完整页面外壳。
  • 在专用覆盖层中实时编辑页眉、页脚、脚注和尾注。它们会与主文档一起参与协作。参见 为 Pages 添加协作。
  • 程序化控制：打开或关闭页眉/页脚/脚注/尾注编辑器，对页面格式变化作出响应，对缩放变化作出响应。
  • 可在配置时或运行时通过 editableHeader / editableFooter / footnotes.editable / endnotes.editable 选项以及 setHeaderEditable / setFooterEditable / setFootnotesEditable / setEndnotesEditable 命令来锁定或解锁每个覆盖层的编辑。
  • 通过 PagesTableKit 实现分页安全的表格。表格会按比例缩小以适应页面，固定高度的行会被裁剪，声明的宽度会被保留。
  • 与 Tiptap Conversion 往返兼容：导入的 DOCX 页眉、页脚、脚注和尾注会自动应用，而导出的 DOCX、PDF、ODT 和 EPUB 文件会保留页眉、页脚和分页信息。DOCX 导出会写入真正的 Word 脚注和尾注。

不可用的内容

这些是真实且已记录的限制，不是 bug。如果你的工作流依赖其中任何一项，请将该约束视为设计边界。

  • 大于一页且不可拆分的块会导致无限布局循环。 这是在采用 Pages 之前最重要的一项限制。表格行、图形、定位容器以及大多数其他块格式化上下文（BFC）元素都不能跨页拆分。布局只能把整个块移到下一页。如果该块本身就比页面还高，它也无法放下，布局就会不断尝试将其继续前移，始终无法稳定。结果就是编辑器无响应。这是当前在页面之间拆分内容的方法所固有的硬限制，不是近期路线图中的功能项。完整说明（包括如何检测和预防）请参见 限制。表格相关的具体情况见 PagesTableKit 的已知问题。
  • 没有按页样式，也没有页面模板。 每一页都使用相同的布局和视觉样式。
  • 没有浏览器打印集成。 如需可直接打印的输出，请使用 Conversion 扩展和 REST 端点。

Expectations

  • Beta stage. Pages is still under active development. If you depend on it, pin the exact package version, because minor versions may introduce breaking changes.
  • Pixel values are CSS pixels. All sizes in the API correspond to standard browser CSS pixels (1 inch = 96 px). The cmToPixels and inchToPixels utilities can round-trip without loss, so you can create using real-world units.
  • What you see is what you edit in collaboration. Double-clicking the header or footer opens the full Tiptap editor, and that editor is in the same collaborative session as the main document.

不要期待的内容

  • Pages 本身并不是一个完整的编辑器。 它只是一个布局覆盖层。请将其与用于文档 schema 的 ConvertKit 以及来自 extension-pages-tablekit 的 TableKit 搭配使用。
  • Pages 本身不实现 DOCX 的导入或导出。 它是一个渲染目标。若要与文件往返配合使用，请搭配 Conversion 扩展：通过 extension-import-docx 导入，通过 extension-export-docx、extension-export-pdf 等导出。
  • Pages 不负责分页内容的表格渲染。 请使用 PagesTableKit，不要使用开源的 @tiptap/extension-table 或 ConvertKit 内置表格。

与 Conversion 搭配使用

这两个产品就是为了协同工作而构建的：

相关内容

Next up安装