--- title: "页眉和页脚" description: "DOCX 转换流程中如何处理文档页眉和页脚，包括导入限制和导出配置。" canonical_url: "https://tiptap.zhcndoc.com/conversion/content-types/page-layout/headers-footers" --- # 页眉和页脚 DOCX 转换流程中如何处理文档页眉和页脚，包括导入限制和导出配置。 Word 中的页眉和页脚会在每一页的顶部和底部显示重复内容。导入 API 会从 DOCX 文件中提取页眉和页脚内容，并且当安装了 [Pages 扩展](https://tiptap.zhcndoc.com/pages/getting-started/overview.md) 时，该扩展可以自动应用它们。导出扩展会将它们写回 DOCX。 ## 你需要什么 - **扩展：** 用于导入的 `@tiptap-pro/extension-import-docx`，用于导出的 `@tiptap-pro/extension-export-docx` - **用于编辑器渲染：** [`Pages`](https://tiptap.zhcndoc.com/editor/extensions/functionality/pages.md) 扩展，用于编辑页眉/页脚并自动应用已导入的页眉/页脚 ## 支持概览 | 功能 | 导入 | 编辑器 | 导出 | | ---------- | ------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | | 默认页眉/页脚 | 支持 | 支持 ([Pages](https://tiptap.zhcndoc.com/editor/extensions/functionality/pages.md)) | 支持 | | 首页不同 | 支持 | 支持 | 支持 | | 奇偶页不同 | 支持 | 支持 | 支持 | | 页码占位符 | 支持。PAGE/NUMPAGES 字段会被翻译为规范的 `{page}` / `{numpages}` 文本标记（在安装 Pages 时默认启用；传入 `placeholders: false` 可让缓存的显示值保持为纯文本）。 | 支持（`{page}`、`{total}` 会在渲染时由 Pages 扩展替换；可通过 `placeholders` 配置重命名）。 | 通过编辑器扩展支持：页眉/页脚中的 `{page}` / `{total}` 标记会作为实时的 `PAGE` / `NUMPAGES` 字段输出。REST API 目前不会翻译这些标记，因此它们会按字面文本渲染。 | | 页眉/页脚中的富文本 | 支持 | 支持 | 支持 | ## 导入 可使用 [编辑器扩展](https://tiptap.zhcndoc.com/conversion/import/docx/editor-extension.md) 或 [REST API](https://tiptap.zhcndoc.com/conversion/import/docx/rest-api.md) 导入页眉和页脚。两者返回的页眉/页脚数据完全相同。若安装了 [Pages 扩展](https://tiptap.zhcndoc.com/editor/extensions/functionality/pages.md)，该扩展还会自动将页眉和页脚应用到编辑器中。REST API 会返回原始数据供你自行处理。 DOCX 导入服务会从源文档中提取页眉和页脚内容。响应中最多包含六个有内容的字段（外加两个始终为 null 的占位字段），覆盖默认、首页，以及页眉和页脚的奇偶页变体。 当使用安装了 [Pages 扩展](https://tiptap.zhcndoc.com/editor/extensions/functionality/pages.md) 的编辑器扩展时，导入的页眉和页脚会通过 `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 导入 → 页码字段](https://tiptap.zhcndoc.com/conversion/import/docx/editor-extension.md#page-number-fields)。 ## 编辑器 [Pages 扩展](https://tiptap.zhcndoc.com/editor/extensions/functionality/pages.md) 提供完整的页眉和页脚支持，以及分页布局。有关完整设置和配置，请参见 [页面页眉和页脚指南](https://tiptap.zhcndoc.com/pages/core-concepts/page-header-footer.md)。 Pages 扩展支持三种与 Word 行为一致的页眉/页脚模式： - **默认：** 每一页使用同一个页眉和页脚 - **首页不同：** 首页使用独立的页眉/页脚 - **奇偶页不同：** 奇数页和偶数页使用不同的页眉/页脚 页码通过占位符渲染：`{page}` 表示当前页，`{total}` 表示总页数。Pages 扩展在编辑器中渲染每一页时会替换这些占位符，而 [`ExportDocx` 编辑器扩展](https://tiptap.zhcndoc.com/conversion/export/docx/editor-extension.md) 在导出时会将它们作为动态 `PAGE` / `NUMPAGES` 字段输出，因此导出的文档在 Word 中会显示真实页码。REST API 的导出路径目前不会转换这些标记，因此它们会作为字面文本显示。请参见下面的 [导出](#export) 部分。 导入后，用户可以双击已导入的页眉或页脚进行编辑。Pages 扩展通过 `editor.storage.pages` 暴露当前激活的浮层编辑器，并提供 `headerEditorOn` / `headerEditorOff`（以及 `footerEditorOn` / `footerEditorOff`）事件订阅辅助方法，适用于同步工具栏或响应焦点变化。有关详情，请参见页面页眉和页脚指南中的 [Active editor state](https://tiptap.zhcndoc.com/pages/core-concepts/page-header-footer.md#active-editor-state)。 ## 导出 可使用 [编辑器扩展](https://tiptap.zhcndoc.com/conversion/export/docx/editor-extension.md) 或 [REST API](https://tiptap.zhcndoc.com/conversion/export/docx/rest-api.md) 导出页眉和页脚。两者都支持默认、首页和奇偶页变体。该扩展接受 `docx.js` 的 Header/Footer 对象，或自动从 Pages 扩展中提取。REST API 接受纯文本字符串或字符串化的 Tiptap JSON。 对于 PDF 导出而言，该扩展还支持更丰富的槽位值集合（纯文本、字符串化的 JSONContent、JSONContent 对象、`docx.Header`/`Footer` 实例，以及按需构建页眉的异步工厂函数）。完整表格请参见 [PDF 页眉和页脚指南](https://tiptap.zhcndoc.com/conversion/export/pdf/headers-footers.md)。 当导出扩展与 Pages 扩展同时安装时，页眉/页脚内容会自动从 Pages 扩展存储中提取，无需额外配置。 如果没有 Pages 扩展，你可以通过导出选项手动提供页眉和页脚： ```ts 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` 编辑器扩展](https://tiptap.zhcndoc.com/conversion/export/docx/editor-extension.md) > 会将每个标记发出为实时的 `PAGE` / `NUMPAGES` 字段，因此 Word 显示的是实际的当前页码和 > 总页数，而不是字面量标记字符串。这适用于从 Pages 扩展中自动提取的页眉和页脚， > 也适用于传入 `placeholders` 选项的直接 `convertHeader` / `convertFooter` 调用。当前 [REST API](https://tiptap.zhcndoc.com/conversion/export/docx/rest-api.md) > 不会转换这些标记，因此它们会以字面文本形式渲染。对于更丰富的组合 > （例如超出基础标记的 `"Page X of Y"` 格式），你也可以手动提供 > `Docx.Header` / `Docx.Footer` 实例，并使用 `Docx.PageNumber.CURRENT` / > `Docx.PageNumber.TOTAL_PAGES`。 ### 可往返保留的内容 当安装了 Pages 扩展时，页眉和页脚可以在完整的“导入到导出”往返流程中保留下来。导入扩展会提取并应用页眉/页脚内容，导出扩展会将其写回 DOCX。通过 Pages 扩展在编辑器中创建的内容，或通过导出配置提供的内容，也会在导出的 DOCX 中正确显示。