页眉和页脚

Beta

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

你需要什么

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

支持概览

功能	导入	编辑器	导出
默认页眉/页脚	支持	支持 (Pages)	支持
首页不同	支持	支持	支持
奇偶页不同	支持	支持	支持
页码占位符	支持。PAGE/NUMPAGES 字段会被翻译为规范的 `{page}` / `{numpages}` 文本标记（在安装 Pages 时默认启用；传入 `placeholders: false` 可让缓存的显示值保持为纯文本）。	支持（`{page}`、`{total}` 会在渲染时由 Pages 扩展替换；可通过 `placeholders` 配置重命名）。	通过编辑器扩展支持：页眉/页脚中的 `{page}` / `{total}` 标记会作为实时的 `PAGE` / `NUMPAGES` 字段输出。REST API 目前不会翻译这些标记，因此它们会按字面文本渲染。
页眉/页脚中的富文本	支持	支持	支持

导入

可使用编辑器扩展或 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} 表示总页数。Pages 扩展在编辑器中渲染每一页时会替换这些占位符，而 ExportDocx 编辑器扩展在导出时会将它们作为动态 PAGE / NUMPAGES 字段输出，因此导出的文档在 Word 中会显示真实页码。REST API 的导出路径目前不会转换这些标记，因此它们会作为字面文本显示。请参见下面的导出部分。

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

导出

可使用编辑器扩展或 REST API 导出页眉和页脚。两者都支持默认、首页和奇偶页变体。该扩展接受 docx.js 的 Header/Footer 对象，或自动从 Pages 扩展中提取。REST API 接受纯文本字符串或字符串化的 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}` 和 `{total}` 会渲染为实时的 DOCX 页码字段

当页眉或页脚包含 {page} 或 {total} 时，ExportDocx 编辑器扩展会将每个标记发出为实时的 PAGE / NUMPAGES 字段，因此 Word 显示的是实际的当前页码和总页数，而不是字面量标记字符串。这适用于从 Pages 扩展中自动提取的页眉和页脚，也适用于传入 placeholders 选项的直接 convertHeader / convertFooter 调用。当前 REST API 不会转换这些标记，因此它们会以字面文本形式渲染。对于更丰富的组合（例如超出基础标记的 "Page X of Y" 格式），你也可以手动提供 Docx.Header / Docx.Footer 实例，并使用 Docx.PageNumber.CURRENT / Docx.PageNumber.TOTAL_PAGES。

可往返保留的内容

当安装了 Pages 扩展时，页眉和页脚可以在完整的“导入到导出”往返流程中保留下来。导入扩展会提取并应用页眉/页脚内容，导出扩展会将其写回 DOCX。通过 Pages 扩展在编辑器中创建的内容，或通过导出配置提供的内容，也会在导出的 DOCX 中正确显示。

PreviouslyWord styles

Next up分页符