页面结构

页面结构涵盖控制内容如何跨页面流动的元素：分页符、节、页面大小、页边距和页码。分页符可在管道中完整往返。其他页面结构属性仅部分支持。

你需要了解的内容

• 扩展： @tiptap-pro/extension-pagebreak（不在 StarterKit 中）以及用于分页布局的 Pages
• 导出选项： 导出扩展或 REST API 上的 pageSize 和 pageMargins
• 集成路径： 通过 编辑器扩展 和 REST API 导入与导出都以相同方式工作。两种导出路径都接受 pageSize 和 pageMargins。

支持概览

分页符

分页符可在管道中完整往返。详见专门的分页符页面。

页面大小和页边距

DOCX 中的页面大小和页边距不会被导入。解析器会从节属性中读取它们，但 Tiptap 渲染器会丢弃这些信息。

Pages 扩展提供带可配置页面大小和页边距的分页布局。配置详情请参见页面格式指南。

导出扩展接受 pageSize 和 pageMargins 选项：

ExportDocx.configure({
  pageSize: {
    width: '21.0cm',
    height: '29.7cm',
  },
  pageMargins: {
    top: '2.54cm',
    bottom: '2.54cm',
    left: '3.17cm',
    right: '3.17cm',
  },
})

这些值支持 CSS 风格单位：cm、in、pt、pc、mm、px。默认值会生成带标准 Word 页边距的 A4 页面。

节

Word 文档可以有多个节，每个节都有自己的页面布局属性（大小、方向、页边距、栏、页眉/页脚）。转换管道对节的支持是部分的：

• 导入： 节边界用于检测多栏布局。多栏节会被包装为 columns/column Tiptap 节点。其他节级属性（大小、方向、页边距）会被解析，但不会应用。
• 编辑器： Tiptap 没有节的概念，但栏节点可以原生渲染。
• 导出： 生成单个节。无法创建纵向/横向混排或多节文档。

页码

Word 中的页码是页眉和页脚里的域代码（PAGE、NUMPAGES）。当安装了 Pages 扩展时（或者你显式启用它：在 编辑器命令 中设置 placeholders: true（或 { page?, total? }），或者在 REST API 中使用 placeholders={} 表单字段），导入会将它们转换为规范文本标记（PAGE 对应 {page}，NUMPAGES 对应 {numpages}）。导出时，编辑器扩展 会在页眉/页脚内容中输出 {page} / {total} 标记，并将其作为实时的 PAGE / NUMPAGES 域，这样 Word 就会在打印或重新分页时重新计算它们。REST API 导出也会进行同样的转换；传入 placeholders: false 可将这些标记保留为字面文本。

Pages 扩展默认识别 {page} 和 {total}；它不识别 {numpages}。若要让 Word 的 NUMPAGES 域在导入后于编辑器预览中实时渲染，请配置 Pages.configure({ placeholders: { total: 'numpages' } })。参见 DOCX 导入 → page-number fields。

可往返内容