--- title: "页面扩展 API 参考" description: "Tiptap Pages 扩展的 API 参考，涵盖选项、命令和存储。" canonical_url: "https://tiptap.zhcndoc.com/pages/core-concepts/options" --- # 页面扩展 API 参考 Tiptap Pages 扩展的 API 参考，涵盖选项、命令和存储。 此页面是 Pages 扩展的 **选项**、**命令** 和 **存储** 的权威参考。有关面向任务的逐步指南，请参见 [页面格式](https://tiptap.zhcndoc.com/pages/core-concepts/page-format.md)、[页面页眉和页脚](https://tiptap.zhcndoc.com/pages/core-concepts/page-header-footer.md)、[脚注](https://tiptap.zhcndoc.com/pages/core-concepts/footnotes.md)、[页面间距](https://tiptap.zhcndoc.com/pages/core-concepts/page-gap.md)、[分页节点](https://tiptap.zhcndoc.com/pages/core-concepts/page-break-node.md) 和 [缩放](https://tiptap.zhcndoc.com/pages/core-concepts/zoom.md)。 ## 选项接口 ```ts import type { Extensions, JSONContent } from '@tiptap/core' type PagesHeaderFooter = string | JSONContent type BuiltInPageFormat = 'A4' | 'A3' | 'A5' | 'Letter' | 'Legal' | 'Tabloid' interface CustomPageFormat { id: string width: number // 像素 height: number // 像素 margins: { top: number right: number bottom: number left: number } } type PageFormat = BuiltInPageFormat | CustomPageFormat interface PagesOptions { /** 内置格式名称或自定义页面格式对象。默认：'A4'。 */ pageFormat: PageFormat /** 初始缩放级别。限制在 [0.25, 4]。默认：1。 */ zoom?: number /** 默认页眉内容。接受纯字符串、HTML 字符串或 Tiptap JSONContent。 * 支持 `{page}` 和 `{total}` 占位符。默认：''。 */ header: string | JSONContent /** 默认页脚内容。与 `header` 结构相同。默认：''。 */ footer: string | JSONContent /** 从页面顶部到页眉内容开始位置的距离（像素）。 * 默认为页面上边距的 50%。 */ headerTopMargin?: number /** 从页脚内容底部到页面底部的距离（像素）。 * 默认为页面下边距的 50%。 */ footerBottomMargin?: number /** 页面之间的视觉间距（像素）。默认：50。 */ pageGap?: number /** 显示在页面之间区域中的 CSS 颜色。默认：'#ffffff'。 */ pageGapBackground?: string /** 应用于页眉和页脚编辑器覆盖层的强调色。默认：'#6366f1'。 */ accentColor?: string /** 仅用于页眉覆盖层的强调色。默认为 `accentColor` 的值。 */ headerAccentColor?: string /** 仅用于页脚覆盖层的强调色。默认为 `accentColor` 的值。 */ footerAccentColor?: string /** 显示编辑覆盖层工具栏（页眉、页脚、 * 脚注、尾注）后面的白色渐隐渐变。设为 false 可获得平面、无渐变的工具栏。默认：true。 */ toolbarGradient?: boolean /** 启用首页使用不同的页眉和页脚（Word 的“首页不同”）。 * 默认：false。 */ differentFirstPage?: boolean /** 首页页眉内容。默认：''。 */ headerFirstPage?: PagesHeaderFooter /** 首页页脚内容。默认：''。 */ footerFirstPage?: PagesHeaderFooter /** 启用奇数页与偶数页使用不同的页眉和页脚（Word 的“奇偶页不同”）。 * 默认：false。 */ differentOddEven?: boolean /** 奇数页页眉内容。默认：''。 */ headerOdd?: PagesHeaderFooter /** 偶数页页眉内容。默认：''。 */ headerEven?: PagesHeaderFooter /** 奇数页页脚内容。默认：''。 */ footerOdd?: PagesHeaderFooter /** 偶数页页脚内容。默认：''。 */ footerEven?: PagesHeaderFooter /** 双击页眉是否会打开内联编辑器覆盖层。 * 当为 false 时，用户或 `openHeaderEditor` 都无法打开覆盖层。 * 默认：true。 */ editableHeader?: boolean /** 双击页脚是否会打开内联编辑器覆盖层。 * 当为 false 时，用户或 `openFooterEditor` 都无法打开覆盖层。 * 默认：true。 */ editableFooter?: boolean /** 独立启用与 `differentFirstPage` 无关的不同首页页脚。 * 调用 `setDifferentFirstPage(true)` 时会自动设置。 */ differentFirstPageFooter?: boolean /** 独立启用与 `differentOddEven` 无关的不同奇偶页页脚。 * 调用 `setDifferentOddEven(true)` 时会自动设置。 */ differentOddEvenFooter?: boolean /** 注册到内部页眉/页脚编辑器上的扩展。 * * 接受静态 `Extensions` 数组，或一个回调：该回调会针对每种子类型（默认 / 首页 / 奇数页 / 偶数页 × * 页眉 / 页脚）接收一个 `HeaderFooterExtensionsContext`，并返回该子编辑器的扩展。使用回调形式 * 可针对每种子类型将 `Collaboration` 挂载到自动计算的 Y 字段上。请参阅为 Pages 添加协作。 * * 默认值为 ConvertKit；请镜像主编辑器的扩展栈以保持 schema 对齐。 */ headerFooterExtensions?: Extensions | ((ctx: HeaderFooterExtensionsContext) => Extensions) /** 当 `setPageFormat()` 成功，或 configure() 应用了新格式时调用。 */ onPageFormatChange?: (pageFormat: PageFormat) => void /** 当 `setZoom()` 更改缩放级别时调用。 */ onZoomChange?: (zoom: number) => void /** 可选：返回 true 可在用户双击编辑器外部时保持当前活动的页眉或页脚编辑器打开。 * 适用于两者。 */ onDblClickHeaderFooterPreventClose?: (event: MouseEvent) => boolean /** 类似 `onDblClickHeaderFooterPreventClose`，但仅适用于页眉覆盖层。 * 当两者都设置时，优先于回退项。 */ onDblClickHeaderPreventClose?: (event: MouseEvent) => boolean /** 类似 `onDblClickHeaderFooterPreventClose`，但仅适用于页脚覆盖层。 * 当两者都设置时，优先于回退项。 */ onDblClickFooterPreventClose?: (event: MouseEvent) => boolean /** 重命名内置的 `{page}` / `{total}` 占位符标记，或传入 * `false` 以完全禁用替换。默认：undefined（按原样使用内置项）。 */ placeholders?: false | { page?: string; total?: string } /** 类 Word 的脚注。除非 `enabled` 为 true，否则处于禁用状态。参见脚注。 */ footnotes?: { /** 主开关。默认：false。 */ enabled?: boolean /** 脚注编辑器的扩展。静态数组，或接收 * 脚注编辑器协作上下文（Y 字段 + Y.Doc）的回调。 * 默认：ConvertKit。 */ extensions?: Extensions | ((ctx: FootnotesExtensionsContext) => Extensions) /** 按 note id 作为键预置脚注内容（与 DOCX 导入结构匹配）。 * 仅限非协作文档。 */ initialContent?: Record /** 在脚注区域上方渲染 Word 风格的分隔线。默认：true。 */ separator?: boolean /** 脚注区域在被裁剪前最多可占据页面内容高度的比例。 * 默认：0.5。 */ maxHeightRatio?: number /** 双击脚注区域时是否打开编辑器。默认：true。 */ editable?: boolean /** 脚注标记和脚注编辑器的强调色。 * 默认为 `accentColor` 的值。 */ accentColor?: string } /** 类似 `onDblClickHeaderFooterPreventClose`，但仅适用于脚注编辑器。 * 当两者都设置时，优先于回退项。 */ onDblClickFootnotesPreventClose?: (event: MouseEvent) => boolean /** 类 Word 的尾注，收集于文档末尾。除非 `enabled` 为 true，否则处于禁用状态。 * 参见尾注。 */ endnotes?: { /** 主开关。默认：false。 */ enabled?: boolean /** 尾注编辑器的扩展。静态数组，或接收 * 尾注编辑器协作上下文（Y 字段 + Y.Doc）的回调。 * 默认：ConvertKit。 */ extensions?: Extensions | ((ctx: EndnotesExtensionsContext) => Extensions) /** 按 note id 作为键预置尾注内容（与 DOCX 导入结构匹配）。 * 仅限非协作文档。 */ initialContent?: Record /** 在尾注列表上方渲染 Word 风格的分隔线。默认：true。 */ separator?: boolean /** 双击尾注列表时是否打开编辑器。默认：true。 */ editable?: boolean /** 尾注标记和尾注编辑器的强调色。 * 默认为 `accentColor` 的值。 */ accentColor?: string } /** 类似 `onDblClickHeaderFooterPreventClose`，但仅适用于尾注编辑器。 * 当两者都设置时，优先于回退项。 */ onDblClickEndnotesPreventClose?: (event: MouseEvent) => boolean } ``` ## 选项参考 ### 布局 | Option | Type | Default | Notes | | ------------------- | ------------ | ----------- | ------------------------------------------------------------------------------------ | | `pageFormat` | `PageFormat` | `'A4'` | 参见 [页面格式](https://tiptap.zhcndoc.com/pages/core-concepts/page-format.md) 了解内置格式。 | | `zoom` | `number` | `1` | 限制在 `[0.25, 4]` 范围内。参见 [缩放](https://tiptap.zhcndoc.com/pages/core-concepts/zoom.md)。 | | `pageGap` | `number` | `50` | 像素。仅用于视觉显示；不影响导出。 | | `pageGapBackground` | `string` | `'#ffffff'` | 任意 CSS 颜色值。 | ### 页眉和页脚 页眉/页脚选项的完整参考位于 [页眉和页脚](https://tiptap.zhcndoc.com/pages/core-concepts/page-header-footer.md#complete-options-reference)。下表概述了表面层；有关首页、奇偶页、内容类型以及编辑器覆盖层行为，请点击链接查看。 | Option | Type | Default | Description | | ------------------------------------ | ----------------------------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | `header` | `PagesHeaderFooter` | `''` | 默认页眉内容 | | `footer` | `PagesHeaderFooter` | `''` | 默认页脚内容 | | `headerTopMargin` | `number` | 50% of top margin | 距离页面顶部到页眉内容的距离（px） | | `footerBottomMargin` | `number` | 50% of bottom margin | 距离页脚内容到底部的距离（px） | | `differentFirstPage` | `boolean` | `false` | 首页页眉和页脚与其余页面不同 | | `headerFirstPage` | `PagesHeaderFooter` | `''` | 首页页眉内容 | | `footerFirstPage` | `PagesHeaderFooter` | `''` | 首页页脚内容 | | `differentOddEven` | `boolean` | `false` | 奇偶页使用不同的页眉和页脚 | | `headerOdd` | `PagesHeaderFooter` | `''` | 奇数页页眉内容 | | `headerEven` | `PagesHeaderFooter` | `''` | 偶数页页眉内容 | | `footerOdd` | `PagesHeaderFooter` | `''` | 奇数页页脚内容 | | `footerEven` | `PagesHeaderFooter` | `''` | 偶数页页脚内容 | | `editableHeader` | `boolean` | `true` | 允许通过双击打开页眉覆盖层 | | `editableFooter` | `boolean` | `true` | 允许通过双击打开页脚覆盖层 | | `headerFooterExtensions` | `Extensions \| (ctx) => Extensions` | `ConvertKit` | 内部页眉/页脚编辑器的扩展；传入回调可按子类型附加 `Collaboration`（见 [为 Pages 添加协作](https://tiptap.zhcndoc.com/pages/guides/collaboration-with-pages.md)）。 | | `onDblClickHeaderFooterPreventClose` | `(event: MouseEvent) => boolean` | `undefined` | 防止在外部双击时关闭（页眉 + 页脚） | | `onDblClickHeaderPreventClose` | `(event: MouseEvent) => boolean` | `undefined` | 防止在外部双击时关闭（仅页眉） | | `onDblClickFooterPreventClose` | `(event: MouseEvent) => boolean` | `undefined` | 防止在外部双击时关闭（仅页脚） | | `accentColor` | `string` | `'#6366f1'` | 两个覆盖层的强调色 | | `headerAccentColor` | `string` | `accentColor` value | 仅页眉覆盖层的强调色 | | `footerAccentColor` | `string` | `accentColor` value | 仅页脚覆盖层的强调色 | | `toolbarGradient` | `boolean` | `true` | 在编辑覆盖层工具栏后显示白色渐隐渐变（页眉、页脚、脚注、尾注）。设为 `false` 可使用平面工具栏。 | | `placeholders` | `false \| { page?, total? }` | `undefined` | 重命名 `{page}` / `{total}` 标记，或设为 `false` 以禁用 | ### 脚注 脚注选项的完整参考位于 [脚注](https://tiptap.zhcndoc.com/pages/core-concepts/footnotes.md#complete-options-reference)。以下所有选项都位于 `footnotes` 键下，除非另有说明。 | Option | Type | Default | Description | | --------------------------------- | --------------------------------------------------- | ------------------- | -------------------------- | | `footnotes.enabled` | `boolean` | `false` | 脚注功能的主开关 | | `footnotes.extensions` | `Extensions \| (ctx) => Extensions` | `ConvertKit` | 脚注编辑器的扩展；回调形式启用协作 | | `footnotes.initialContent` | `Record` | `undefined` | 按 note id 作为键预置脚注内容（仅限非协作） | | `footnotes.separator` | `boolean` | `true` | 在脚注区域上方渲染分隔线 | | `footnotes.maxHeightRatio` | `number` | `0.5` | 该区域最多可占据页面内容高度的比例 | | `footnotes.editable` | `boolean` | `true` | 允许双击打开脚注编辑器 | | `footnotes.accentColor` | `string` | `accentColor` value | 标记和脚注编辑器的强调色 | | `onDblClickFootnotesPreventClose` | `(event: MouseEvent) => boolean` (top-level option) | `undefined` | 防止在外部双击时关闭脚注编辑器 | ### 尾注 尾注选项的完整参考位于 [尾注](https://tiptap.zhcndoc.com/pages/core-concepts/endnotes.md#complete-options-reference)。以下所有选项都位于 `endnotes` 键下，除非另有说明。 | Option | Type | Default | Description | | -------------------------------- | --------------------------------------------------- | ------------------- | -------------------------- | | `endnotes.enabled` | `boolean` | `false` | 尾注功能的主开关 | | `endnotes.extensions` | `Extensions \| (ctx) => Extensions` | `ConvertKit` | 尾注编辑器的扩展；回调形式启用协作 | | `endnotes.initialContent` | `Record` | `undefined` | 按 note id 作为键预置尾注内容（仅限非协作） | | `endnotes.separator` | `boolean` | `true` | 在尾注列表上方渲染分隔线 | | `endnotes.editable` | `boolean` | `true` | 允许通过双击打开尾注编辑器 | | `endnotes.accentColor` | `string` | `accentColor` value | 标记和尾注编辑器的强调色 | | `onDblClickEndnotesPreventClose` | `(event: MouseEvent) => boolean` (top-level option) | `undefined` | 防止在外部双击时关闭尾注编辑器 | ### 回调 | Option | Type | Description | | -------------------- | ------------------------------ | ------------------------------------------ | | `onPageFormatChange` | `(format: PageFormat) => void` | 当通过 configure 或 `setPageFormat` 更改页面格式时触发。 | | `onZoomChange` | `(zoom: number) => void` | 当通过 `setZoom` 更改缩放级别时触发。 | ## 命令参考 有关每个命令的深入说明，请参见链接的 core-concepts 页面。 ### 布局命令 | Command | Parameters | Description | | ---------------------- | ------------------------ | ---------------------------------------- | | `setPageFormat` | `pageFormat: PageFormat` | 更改页面格式。触发 `onPageFormatChange`。 | | `setZoom` | `zoom: number` | 设置缩放（限制在 `[0.25, 4]`）。触发 `onZoomChange`。 | | `setPageGap` | `pageGap: number` | 设置页面间距（px）。必须为正数。 | | `setPageGapBackground` | `color: string` | 设置页面间距背景颜色（任意 CSS 颜色值）。 | ### 页眉 / 页脚命令 完整参考也位于 [页面页眉和页脚](https://tiptap.zhcndoc.com/pages/core-concepts/page-header-footer.md#commands-reference)。 | Command | Parameters | Description | | ----------------------------- | --------------------------- | -------------------------------- | | `setHeader` | `header: PagesHeaderFooter` | 设置默认页眉内容 | | `setFooter` | `footer: PagesHeaderFooter` | 设置默认页脚内容 | | `setHeaderTopMargin` | `margin: number` | 设置页眉上边距（px） | | `setFooterBottomMargin` | `margin: number` | 设置页脚下边距（px） | | `setDifferentFirstPage` | `enabled: boolean` | 切换不同的首页页眉 *和* 页脚 | | `setDifferentFirstPageFooter` | `enabled: boolean` | 单独切换不同的首页页脚 | | `setHeaderFirstPage` | `header: PagesHeaderFooter` | 设置首页页眉内容 | | `setFooterFirstPage` | `footer: PagesHeaderFooter` | 设置首页页脚内容 | | `setDifferentOddEven` | `enabled: boolean` | 切换不同的奇数/偶数页页眉 *和* 页脚 | | `setDifferentOddEvenFooter` | `enabled: boolean` | 单独切换不同的奇数/偶数页页脚 | | `setHeaderOdd` | `header: PagesHeaderFooter` | 设置奇数页页眉内容 | | `setHeaderEven` | `header: PagesHeaderFooter` | 设置偶数页页眉内容 | | `setFooterOdd` | `footer: PagesHeaderFooter` | 设置奇数页页脚内容 | | `setFooterEven` | `footer: PagesHeaderFooter` | 设置偶数页页脚内容 | | `setHeaderEditable` | `enabled: boolean` | 锁定或解锁页眉覆盖层（控制 `editableHeader`）。 | | `setFooterEditable` | `enabled: boolean` | 锁定或解锁页脚覆盖层（控制 `editableFooter`）。 | | `openHeaderEditor` | `{ pageNumber: number }` | 为特定页面打开页眉编辑器（从 1 开始编号）。 | | `openFooterEditor` | `{ pageNumber: number }` | 为特定页面打开页脚编辑器（从 1 开始编号）。 | | `closeHeaderFooterEditors` | none | 关闭当前打开的任意页眉/页脚编辑器 | | `closeHeaderEditor` | none | 如果页眉编辑器已打开，则将其关闭 | | `closeFooterEditor` | none | 如果页脚编辑器已打开，则将其关闭 | | `setAccentColor` | `color: string` | 为两个编辑器覆盖层设置强调色 | | `setHeaderAccentColor` | `color: string` | 仅为页眉覆盖层设置强调色 | | `setFooterAccentColor` | `color: string` | 仅为页脚覆盖层设置强调色 | ### 脚注命令 完整参考也位于 [脚注](https://tiptap.zhcndoc.com/pages/core-concepts/footnotes.md#commands-reference)。 | Command | Parameters | Description | | ------------------------- | ---------------------------------------------- | ---------------------------------- | | `insertFootnote` | none | 在选区插入脚注并打开其编辑器 | | `setFootnotes` | `footnotes: Record` | 使用从 id → 文档映射替换所有脚注内容 | | `openFootnoteEditor` | `{ pageNumber: number, focusNoteId?: string }` | 为某一页面打开脚注编辑器（从 1 开始编号） | | `closeFootnoteEditor` | none | 如果脚注编辑器已打开，则将其关闭 | | `setFootnotesEditable` | `enabled: boolean` | 锁定或解锁脚注编辑（控制 `footnotes.editable`） | | `cleanupOrphanFootnotes` | none | 永久移除其引用已消失的脚注内容 | | `setFootnotesAccentColor` | `color: string` | 设置脚注强调色 | ### 尾注命令 完整参考也位于 [尾注](https://tiptap.zhcndoc.com/pages/core-concepts/endnotes.md#commands-reference)。 | Command | Parameters | Description | | ------------------------ | --------------------------------------- | --------------------------------- | | `insertEndnote` | none | 在选区插入尾注并打开其编辑器 | | `setEndnotes` | `endnotes: Record` | 使用从 id → 文档映射替换所有尾注内容 | | `openEndnoteEditor` | `{ focusNoteId?: string }` (optional) | 打开尾注编辑器，并可选聚焦某条特定尾注 | | `closeEndnoteEditor` | none | 如果尾注编辑器已打开，则将其关闭 | | `setEndnotesEditable` | `enabled: boolean` | 锁定或解锁尾注编辑（控制 `endnotes.editable`） | | `cleanupOrphanEndnotes` | none | 永久移除其引用已消失的尾注内容 | | `setEndnotesAccentColor` | `color: string` | 设置尾注强调色 | ## 存储引用 从 `editor.storage.pages` 中读取这些内容。标记为 **只读** 的属性不应直接写入；请使用对应的命令。 ### 布局 | Property | Type | Description | | ---------------------------- | --------------------------------- | ----------------------- | | `pageFormat` | `PageFormat` | 当前页面格式 | | `zoom` | `number` | 当前缩放级别（只读，使用 `setZoom`） | | `getZoom` | `() => number` | 当前缩放级别的便捷获取器 | | `pageGap` | `number` | 页面之间的当前间距（px） | | `pageGapBackground` | `string` | 当前页面间距背景颜色 | | `getCurrentPage` | `() => number \| null` | 光标所在的 1 起始页码 | | `getDistanceToNextPagebreak` | `(pos: number) => number \| null` | 从 `pos` 到下一页分页符的像素距离 | | `getDistanceToPrevPagebreak` | `(pos: number) => number \| null` | 从 `pos` 到上一页分页符的像素距离 | ### 页眉和页脚（渲染后的 HTML 和 JSON） 当用户通过覆盖层编辑页眉或页脚后，渲染后的 HTML 和底层的 Tiptap JSON 都会暴露在存储中。导出为 DOCX 时，请使用 JSON 形式进行序列化。HTML 属性始终是字符串（在任何编辑之前默认为 `''`）。JSON 属性在用户首次通过覆盖层编辑对应的页眉或页脚之前为 `null`。 | Property | Type | Description | | -------------------------- | ----------------------------- | -------------------------------------- | | `headerHTML` | `string` | 默认页眉渲染后的 HTML | | `headerJSON` | `Record \| null` | 默认页眉的 Tiptap JSON | | `headerFirstPageHTML` | `string` | 首页页眉渲染后的 HTML | | `headerFirstPageJSON` | `Record \| null` | 首页页眉的 Tiptap JSON | | `headerOddHTML` | `string` | 奇数页页眉渲染后的 HTML | | `headerOddJSON` | `Record \| null` | 奇数页页眉的 Tiptap JSON | | `headerEvenHTML` | `string` | 偶数页页眉渲染后的 HTML | | `headerEvenJSON` | `Record \| null` | 偶数页页眉的 Tiptap JSON | | `footerHTML` | `string` | 默认页脚渲染后的 HTML | | `footerJSON` | `Record \| null` | 默认页脚的 Tiptap JSON | | `footerFirstPageHTML` | `string` | 首页页脚渲染后的 HTML | | `footerFirstPageJSON` | `Record \| null` | 首页页脚的 Tiptap JSON | | `footerOddHTML` | `string` | 奇数页页脚渲染后的 HTML | | `footerOddJSON` | `Record \| null` | 奇数页页脚的 Tiptap JSON | | `footerEvenHTML` | `string` | 偶数页页脚渲染后的 HTML | | `footerEvenJSON` | `Record \| null` | 偶数页页脚的 Tiptap JSON | | `differentFirstPage` | `boolean` | 首页是否不同 | | `differentOddEven` | `boolean` | 奇偶页是否不同 | | `differentFirstPageFooter` | `boolean` | 首页页脚是否不同（独立标志） | | `differentOddEvenFooter` | `boolean` | 奇偶页页脚是否不同（独立标志） | | `editableHeader` | `boolean` | 是否可以打开页眉覆盖层（只读，使用 `setHeaderEditable`） | | `editableFooter` | `boolean` | 是否可以打开页脚覆盖层（只读，使用 `setFooterEditable`） | | `accentColor` | `string` | 当前强调色（两者） | | `headerAccentColor` | `string` | 当前页眉强调色 | | `footerAccentColor` | `string` | 当前页脚强调色 | ### 脚注 完整参考也位于 [脚注](https://tiptap.zhcndoc.com/pages/core-concepts/footnotes.md#storage-reference)。 | Property | Type | Description | | ------------------- | ----------------------------- | ------------------------------------- | | `footnotesJSON` | `Record` | 每个脚注 ID 对应的脚注内容，用于持久化和 DOCX 导出 | | `footnotesHTML` | `Record` | 每个脚注 ID 对应的渲染后 HTML，与页面预览一致 | | `footnoteNumbers` | `Record` | 当前编号（脚注 ID → 1 起始编号） | | `footnotesEnabled` | `boolean` | 脚注是否已启用 | | `editableFootnotes` | `boolean` | 是否已解锁编辑（只读，使用 `setFootnotesEditable`） | ### 尾注 完整参考也位于 [尾注](https://tiptap.zhcndoc.com/pages/core-concepts/endnotes.md#storage-reference)。 | Property | Type | Description | | ------------------ | ----------------------------- | ------------------------------------ | | `endnotesJSON` | `Record` | 每个尾注 ID 对应的尾注内容，用于持久化和 DOCX 导出 | | `endnotesHTML` | `Record` | 每个尾注 ID 对应的渲染后 HTML，与文档一致 | | `endnoteNumbers` | `Record` | 当前编号（尾注 ID → 1 起始编号） | | `endnotesEnabled` | `boolean` | 尾注是否已启用 | | `editableEndnotes` | `boolean` | 是否已解锁编辑（只读，使用 `setEndnotesEditable`） | ### 活动的内部编辑器状态 当页眉、页脚、脚注或尾注覆盖层打开时，这些属性会反映当前激活的是哪一个。对于构建跟随焦点编辑器的工具栏很有用；请参见 [页面页眉和页脚](https://tiptap.zhcndoc.com/pages/core-concepts/page-header-footer.md#active-editor-state) 获取完整工具栏示例。 | Property | Type | Description | | -------------------- | ----------------------------------------------------------- | ------------------------------ | | `activeEditor` | `Editor \| null` | 当前激活的页眉/页脚/脚注/尾注编辑器实例，或 `null` | | `activeEditorType` | `'header' \| 'footer' \| 'footnotes' \| 'endnotes' \| null` | 当前激活的是哪种覆盖层 | | `activePageNumber` | `number \| null` | 正在编辑的页码（页眉/页脚/脚注） | | `headerEditorOn` | `Editor['on'] \| null` | 页眉覆盖层内部编辑器事件的预绑定订阅器 | | `headerEditorOff` | `Editor['off'] \| null` | 页眉覆盖层内部编辑器的预绑定取消订阅器 | | `footerEditorOn` | `Editor['on'] \| null` | 页脚覆盖层内部编辑器事件的预绑定订阅器 | | `footerEditorOff` | `Editor['off'] \| null` | 页脚覆盖层内部编辑器的预绑定取消订阅器 | | `footnotesEditorOn` | `Editor['on'] \| null` | 脚注编辑器事件的预绑定订阅器 | | `footnotesEditorOff` | `Editor['off'] \| null` | 脚注编辑器的预绑定取消订阅器 | | `endnotesEditorOn` | `Editor['on'] \| null` | 尾注编辑器事件的预绑定订阅器 | | `endnotesEditorOff` | `Editor['off'] \| null` | 尾注编辑器的预绑定取消订阅器 | ## 示例用法 ### 内置格式 ```ts import { Editor } from '@tiptap/core' import { ConvertKit } from '@tiptap-pro/extension-convert-kit' import { TableKit } from '@tiptap-pro/extension-pages-tablekit' import { Pages } from '@tiptap-pro/extension-pages' const editor = new Editor({ extensions: [ ConvertKit.configure({ table: false }), TableKit, Pages.configure({ pageFormat: 'A4', pageGap: 40, header: '我的项目', footer: '第 {page} 页，共 {total} 页', pageGapBackground: '#f8f8f8', }), ], }) ``` ### 自定义格式和运行时更改 ```ts import { cmToPixels } from '@tiptap-pro/extension-pages' Pages.configure({ pageFormat: { id: 'custom-page-format', width: cmToPixels(22.94), height: cmToPixels(35.18), margins: { top: cmToPixels(2.54), right: cmToPixels(2.54), bottom: cmToPixels(2.54), left: cmToPixels(2.54), }, }, onPageFormatChange: (pageFormat) => { console.log('页面格式已更改：', pageFormat.id) }, }) // 稍后切换 editor.commands.setPageFormat('Letter') ``` > **页眉和页脚模板标记:** > > `header` 和 `footer` 都接受标记 （当前 1 起始页码）和 > （总页数）。它们会在渲染时替换，并可用于纯 > 字符串、HTML 字符串以及 JSONContent。