页面结构

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

你需要了解的内容

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

支持概览

功能导入编辑器导出
Page breaksSupportedSupported (PageBreak)Supported
Page sizeNot supportedSupported (Pages)Supported (configurable)
Page marginsNot supportedSupported (Pages)Supported (configurable)
SectionsPartial (column configuration is extracted and applied)Not supportedSingle section only
页码支持(PAGE/NUMPAGES → {page}/{numpages} 标记,请参阅下文 )支持(通过页眉/页脚)支持。编辑器扩展和 REST API 在页眉/页脚中发出 {page}/{total} 令牌作为实时 PAGE/NUMPAGES 字段。 REST API 还接受 {numpages}。
ColumnsSupported on import (columns/column nodes created)Not supportedNot supported

分页符

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

页面大小和页边距

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 页面。

Pages 与导出之间不会自动同步

导出扩展不会自动从 Pages 扩展读取页面大小或页边距。如果你的编辑器使用自定义页面格式,请在导出配置中传入匹配的值。

节

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。

可往返内容

功能可往返?说明
Page breaksYesRequires @tiptap-pro/extension-pagebreak
Page sizeNoConfigure separately for editor (Pages) and export
Page marginsNoConfigure separately for editor (Pages) and export
SectionsPartialColumn configuration survives; other section properties do not
页码是字 PAGE / NUMPAGES ↔ {page} / {numpages} (总计的页面规范名称为 {total};将 placeholders: { total: 'numpages' } 配置为桥接)。如果没有该设置,REST API 会在导出时识别 {numpages}。
ColumnsPartialImport creates column nodes; export does not yet write them back