页眉和页脚

Word 中的页眉和页脚会在每一页的顶部和底部显示重复内容。导入 API 会从 DOCX 文件中提取页眉和页脚内容,并且当安装了 Pages 扩展 时,该扩展可以自动应用它们。导出扩展会将它们写回 DOCX。

你需要什么

  • 扩展: 用于导入的 @tiptap-pro/extension-import-docx,用于导出的 @tiptap-pro/extension-export-docx
  • 用于编辑器渲染: Pages 扩展,用于编辑页眉/页脚并自动应用已导入的页眉/页脚

支持概览

功能导入编辑器导出
Default header/footerSupportedSupported (Pages)Supported
Different first pageSupportedSupportedSupported
Different odd/even pagesSupportedSupportedSupported
页码占位符支持。 PAGE/NUMPAGES 字段被转换为规范的 {page} / {numpages} 文本标记(安装 Pages 时默认打开;传递 placeholders: false 以将缓存的显示值保留为纯文本)。支持({page}、{total} 在渲染时由页面扩展替换;通过 placeholders 配置重命名)。导入的 {numpages} 仅在 Pages.configure({ placeholders: { total: 'numpages' } }) 之后渲染。支持。编辑器扩展和 REST API 在页眉/页脚中发出 {page} / {total} 令牌作为实时 PAGE / NUMPAGES 字段。 REST API 还接受 {numpages} 作为 {total} 的同义词。编辑器扩展使用 Pages 令牌名称,因此需要相同的重命名才能导出导入的 {numpages}。
Rich text in headers/footersSupportedSupportedSupported

导入

可使用 编辑器扩展 或 REST API 导入页眉和页脚。两者返回的页眉/页脚数据完全相同。若安装了 Pages 扩展,该扩展还会自动将页眉和页脚应用到编辑器中。REST API 会返回原始数据供你自行处理。

DOCX 导入服务会从源文档中提取页眉和页脚内容。响应中最多包含六个有内容的字段(外加两个始终为 null 的占位字段),覆盖默认、首页,以及页眉和页脚的奇偶页变体。

当使用安装了 Pages 扩展 的编辑器扩展时,导入的页眉和页脚会通过 setEditorContent() 自动应用到编辑器中。没有 Pages 扩展时,页眉/页脚数据仍可在 onImport 回调中获取,并由你手动处理。

可用字段

字段描述
header默认页眉内容
footer默认页脚内容
headerFirstPage首页页眉(当 Word 中启用了“首页不同”时)
footerFirstPage首页页脚
headerOdd始终为 null(见下方说明)
footerOdd始终为 null(见下方说明)
headerEven偶数页页眉
footerEven偶数页页脚

每个字段都包含有效的 Tiptap JSON;如果源文档不包含该变体,则为 null。

奇数页页眉会出现在默认字段中

Word 的 OOXML 模型使用三种页眉类型:default、first 和 even。当 Word 中启用了“奇偶页不同”时,默认页眉就是奇数页上显示的内容。API 也遵循这一点:

  • header / footer 包含 默认(奇数页)内容。
  • headerEven / footerEven 包含偶数页内容。
  • headerFirstPage / footerFirstPage 包含首页内容。
  • headerOdd / footerOdd 始终为 null。它们仅作为响应结构中的字段存在,用于保持对称。

要获取奇数页页眉,请读取 context.header(而不是 context.headerOdd)。如果源文档只引用了首页和偶数页页眉而没有默认页眉,那么响应中不会包含奇数页内容:导入器无法生成源文档未提供的内容。

需要 Pages 扩展才能自动应用

没有 Pages 扩展时,导入扩展仍会在回调中返回页眉/页脚数据,但无法自动将其应用到编辑器。你可以通过 onImport 回调获取这些数据,并在自己的代码中处理它们。

`PAGE` 和 `NUMPAGES` 字段会作为 `{page}` / `{numpages}` 标记导入

Word 的 PAGE 和 NUMPAGES 字段代码在安装了 Pages 扩展时,默认会被翻译为规范的文本标记:PAGE 对应 {page},NUMPAGES 对应 {numpages}。Pages 扩展会原生渲染 {page},因此一个显示为 Page 5 of 12 的 Word 页眉会导入为 Page {page} of {numpages},并立即显示实时页码。若要让 {numpages} 也实时渲染,请配置 Pages.configure({ placeholders: { total: 'numpages' } })。在 importDocx 命令中传入 placeholders: false 可禁用该翻译,并改为导入缓存显示值(例如字面量 Page 5 of 12)。其他字段代码如 DATE 和 AUTHOR 仍会按其缓存显示值导入。参见 DOCX 导入 → 页码字段。

编辑器

Pages 扩展 提供完整的页眉和页脚支持,以及分页布局。有关完整设置和配置,请参见 页面页眉和页脚指南。

Pages 扩展支持三种与 Word 行为一致的页眉/页脚模式:

  • 默认: 每一页使用同一个页眉和页脚
  • 首页不同: 首页使用独立的页眉/页脚
  • 奇偶页不同: 奇数页和偶数页使用不同的页眉/页脚

页码通过占位符渲染:{page} 表示当前页,{total} 表示总页数。在编辑器中渲染每个页面时,页面扩展会替换它们,并且 ExportDocx 编辑器扩展 在导出时将它们作为实时 PAGE / NUMPAGES 字段发出,因此导出的文档显示 Word 中的真实页码。 REST API 导出端点发出相同的实时字段。请参阅下面的 Export] 部分。

导入后,用户可以双击已导入的页眉或页脚进行编辑。Pages 扩展通过 editor.storage.pages 暴露当前激活的浮层编辑器,并提供 headerEditorOn / headerEditorOff(以及 footerEditorOn / footerEditorOff)事件订阅辅助方法,适用于同步工具栏或响应焦点变化。有关详情,请参见页面页眉和页脚指南中的 Active editor state。

导出

使用编辑器扩展或 REST API 导出页眉和页脚。两者都支持默认、首页和奇数页/偶数页变体。扩展接受 docx.js 页眉/页脚对象,也可以从 Pages 扩展中自动提取;REST API 接受纯文本字符串、序列化后的 Tiptap JSON 或 Tiptap JSON 对象。

对于 PDF 导出而言,该扩展还支持更丰富的槽位值集合(纯文本、字符串化的 JSONContent、JSONContent 对象、docx.Header/Footer 实例,以及按需构建页眉的异步工厂函数)。完整表格请参见 PDF 页眉和页脚指南。

当导出扩展与 Pages 扩展同时安装时,页眉/页脚内容会自动从 Pages 扩展存储中提取,无需额外配置。

如果没有 Pages 扩展,你可以通过导出选项手动提供页眉和页脚:

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

ExportDocx.configure({
  headers: {
    default: new Docx.Header({
      children: [new Docx.Paragraph({ text: '我的文档' })],
    }),
  },
  footers: {
    default: new Docx.Footer({
      children: [new Docx.Paragraph({ text: '机密' })],
    }),
  },
})

导出支持页眉和页脚的 default、first 和 even 变体。当提供相应变体时,differentFirstPage 和 evenAndOddHeaders 标志会自动设置。

显式提供的页眉/页脚选项会覆盖从 Pages 扩展中自动提取的内容。

`{page}` and `{total}` render as live DOCX page-number fields

当页眉或页脚包含 {page} 或 {total} 时,ExportDocx 编辑器扩展 将每个标记作为实时 PAGE / NUMPAGES 字段发出,因此 Word 显示实际的当前页面和总页数,而不是文字标记字符串。这适用于从页面扩展自动提取的页眉和页脚,以及传递 placeholders 选项的直接 convertHeader / convertFooter 调用。 REST API 在每个页眉和页脚槽形状中翻译相同的标记,并且还接受 {numpages} 作为 {total} 的同义词。对于更丰富的结构(例如,超出裸标记的 "Page X of Y" 格式),您还可以使用 Docx.PageNumber.CURRENT / Docx.PageNumber.TOTAL_PAGES 手动提供 Docx.Header / Docx.Footer 实例。

可往返保留的内容

安装 Pages 扩展后,页眉和页脚内容可以完整经历导入到导出的往返流程。导入扩展会提取并应用页眉/页脚内容,导出扩展则会将其写回 DOCX。通过 Pages 扩展在编辑器中编写的内容,或通过导出配置提供的内容,也会正确出现在导出的 DOCX 中。

页码在一个条件下往返。 {page} 无需设置。使用默认的 Pages 配置,导入将总页数写入 {numpages},但 Pages 和导出扩展需要 {total}。配置 Pages.configure({ placeholders: { total: 'numpages' } }),以便在编辑器中渲染总计并再次导出为实时 NUMPAGES 字段。如果没有它,{numpages} 在这两个地方都保留文字文本。