页面扩展 API 参考

此页面是 Pages 扩展的 选项、命令 和 存储 的权威参考。有关面向任务的逐步指南,请参见 页面格式、页面页眉和页脚、脚注、页面间距、分页节点 和 缩放。

选项接口

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

  /** Background of the header, footer, footnotes and endnotes overlays and of their toolbar
   *  fade. Any CSS color, also a CSS variable. Default: undefined (white). */
  overlayBackgroundColor?: string

  /** Stacking order (z-index) of the header, footer, footnotes and endnotes overlays.
   *  Default: undefined (1000). */
  overlayZIndex?: number

  /** Enable a different header and footer for the first page (Word's "Different First Page").
   *  Default: 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)

  /** 解析以 HTML 提供的页眉和页脚内容。
   * 默认为 `{ preserveWhitespace: 'full' }`。 */
  headerFooterParseOptions?: ParseOptions

  /** 在页眉和页脚覆盖层工具栏中、关闭按钮之前渲染自定义控件。 */
  renderOverlayActions?: RenderOverlayActions

  /** 页眉、页脚、脚注和尾注覆盖层的可翻译标签。 */
  overlayLabels?: OverlayLabels

  /** 当 `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<string, JSONContent>

    /** 在脚注区域上方渲染 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<string, JSONContent>

    /** 在尾注列表上方渲染 Word 风格的分隔线。默认:true。 */
    separator?: boolean

    /** 双击尾注列表时是否打开编辑器。默认:true。 */
    editable?: boolean

    /** 尾注标记和尾注编辑器的强调色。
     *  默认为 `accentColor` 的值。 */
    accentColor?: string
  }

  /** 类似 `onDblClickHeaderFooterPreventClose`,但仅适用于尾注编辑器。
   *  当两者都设置时,优先于回退项。 */
  onDblClickEndnotesPreventClose?: (event: MouseEvent) => boolean

  /** Returns the name screen readers announce for a footnote or endnote marker, for example
   *  to translate it. Receives `{ type, number, marker }`. Default: undefined ("Footnote 3",
   *  "Endnote 3"). */
  noteReferenceLabel?: NoteReferenceLabel
}

选项参考

布局

OptionTypeDefaultNotes
pageFormatPageFormat'A4'参见 页面格式 了解内置格式。
zoomnumber1限制在 [0.25, 4] 范围内。参见 缩放。
pageGapnumber50像素。仅用于视觉显示;不影响导出。
pageGapBackgroundstring'#ffffff'任意 CSS 颜色值。

页眉和页脚

页眉/页脚选项的完整参考位于 页眉和页脚。下表概述了表面层;有关首页、奇偶页、内容类型以及编辑器覆盖层行为,请点击链接查看。

OptionTypeDefaultDescription
headerPagesHeaderFooter''Default header content
footerPagesHeaderFooter''Default footer content
headerTopMarginnumber50% of top marginDistance from page top to header content (px)
footerBottomMarginnumber50% of bottom marginDistance from footer content to page bottom (px)
differentFirstPagebooleanfalseFirst-page header and footer differ from the rest
headerFirstPagePagesHeaderFooter''First-page header content
footerFirstPagePagesHeaderFooter''First-page footer content
differentOddEvenbooleanfalseOdd/even pages have different headers and footers
headerOddPagesHeaderFooter''Odd-pages header content
headerEvenPagesHeaderFooter''Even-pages header content
footerOddPagesHeaderFooter''Odd-pages footer content
footerEvenPagesHeaderFooter''Even-pages footer content
editableHeaderbooleantrueAllow opening the header overlay on double-click
editableFooterbooleantrueAllow opening the footer overlay on double-click
headerFooterExtensionsExtensions | (ctx) => ExtensionsConvertKitExtensions for the inner header/footer editors. Pass a callback to attach Collaboration per subtype (see Adding collaboration to Pages).
headerFooterParseOptionsParseOptions{ preserveWhitespace: 'full' }Parse options for header and footer content given as HTML. Repeated spaces are kept by default.
renderOverlayActions(ctx) => HTMLElement | { element, destroy? } | nullundefinedCustom controls inside the header and footer overlay toolbar. See Customizing the overlay toolbar.
overlayLabelsOverlayLabelsundefinedTranslatable labels for every overlay. See Translating overlay labels.
onDblClickHeaderFooterPreventClose(event: MouseEvent) => booleanundefinedPrevent closing on double-click outside (header + footer)
onDblClickHeaderPreventClose(event: MouseEvent) => booleanundefinedPrevent closing on double-click outside (header only)
onDblClickFooterPreventClose(event: MouseEvent) => booleanundefinedPrevent closing on double-click outside (footer only)
accentColorstring'#6366f1'Accent color for both overlays
headerAccentColorstringaccentColor valueAccent color for the header overlay only
footerAccentColorstringaccentColor valueAccent color for the footer overlay only
toolbarGradientbooleantrueShow the white fade gradient behind the edit-overlay toolbars (header, footer, footnotes, endnotes). Set false for flat toolbars.
overlayBackgroundColorstringundefined(白色)页眉、页脚、脚注和尾注叠加层及其工具栏的背景淡入淡出。任何 CSS 颜色,也是 CSS 变量。请参阅叠加背景和 z-index。
overlayZIndexnumberundefined (1000)页眉、页脚、脚注和尾注覆盖的堆叠顺序。降低它可以在打开的覆盖层上方显示您自己的菜单。
placeholdersfalse | { page?, total? }undefinedRename {page} / {total} tokens, or false to disable

Footnotes

The full reference for footnote options lives on Footnotes. All options below sit under the footnotes key unless noted otherwise.

OptionTypeDefaultDescription
footnotes.enabledbooleanfalseMaster switch for the footnotes feature
footnotes.extensionsExtensions | (ctx) => ExtensionsConvertKitExtensions for the footnotes editor; callback form enables collaboration
footnotes.initialContentRecord<string, JSONContent>undefinedSeed footnote content keyed by note id (non-collaborative only)
footnotes.separatorbooleantrueRender the separator rule above the footnotes area
footnotes.maxHeightRationumber0.5Max fraction of page content height the area may occupy
footnotes.editablebooleantrueAllow opening the footnotes editor on double-click
footnotes.accentColorstringaccentColor valueAccent color for markers and the footnotes editor
onDblClickFootnotesPreventClose(event: MouseEvent) => boolean (top-level option)undefinedPrevent closing the footnotes editor on double-click outside
noteReferenceLabelNoteReferenceLabel(顶级选项)undefined每个脚注和尾注标记的屏幕阅读器名称

尾注

尾注选项的完整参考位于 尾注。以下所有选项都位于 endnotes 键下,除非另有说明。

OptionTypeDefaultDescription
endnotes.enabledbooleanfalseMaster switch for the endnotes feature
endnotes.extensionsExtensions | (ctx) => ExtensionsConvertKitExtensions for the endnotes editor; callback form enables collaboration
endnotes.initialContentRecord<string, JSONContent>undefinedSeed endnote content keyed by note id (non-collaborative only)
endnotes.separatorbooleantrueRender the separator rule above the endnotes list
endnotes.editablebooleantrueAllow opening the endnotes editor on double-click
endnotes.accentColorstringaccentColor valueAccent color for markers and the endnotes editor
onDblClickEndnotesPreventClose(event: MouseEvent) => boolean (top-level option)undefinedPrevent closing the endnotes editor on double-click outside
noteReferenceLabelNoteReferenceLabel(顶级选项)undefined每个脚注和尾注标记的屏幕阅读器名称

回调

OptionTypeDescription
onPageFormatChange(format: PageFormat) => void当通过 configure 或 setPageFormat 更改页面格式时触发。
onZoomChange(zoom: number) => void当通过 setZoom 更改缩放级别时触发。

命令参考

有关每个命令的深入说明,请参见链接的 core-concepts 页面。

布局命令

CommandParametersDescription
setPageFormatpageFormat: PageFormat更改页面格式。触发 onPageFormatChange。
setZoomzoom: number设置缩放(限制在 [0.25, 4])。触发 onZoomChange。
setPageGappageGap: number设置页面间距(px)。必须为正数。
setPageGapBackgroundcolor: string设置页面间距背景颜色(任意 CSS 颜色值)。

页眉 / 页脚命令

完整参考也位于 页面页眉和页脚。

CommandParametersDescription
setHeaderheader: PagesHeaderFooter设置默认页眉内容
setFooterfooter: PagesHeaderFooter设置默认页脚内容
setHeaderTopMarginmargin: number设置页眉上边距(px)
setFooterBottomMarginmargin: number设置页脚下边距(px)
setDifferentFirstPageenabled: boolean切换不同的首页页眉 和 页脚
setDifferentFirstPageFooterenabled: boolean单独切换不同的首页页脚
setHeaderFirstPageheader: PagesHeaderFooter设置首页页眉内容
setFooterFirstPagefooter: PagesHeaderFooter设置首页页脚内容
setDifferentOddEvenenabled: boolean切换不同的奇数/偶数页页眉 和 页脚
setDifferentOddEvenFooterenabled: boolean单独切换不同的奇数/偶数页页脚
setHeaderOddheader: PagesHeaderFooter设置奇数页页眉内容
setHeaderEvenheader: PagesHeaderFooter设置偶数页页眉内容
setFooterOddfooter: PagesHeaderFooter设置奇数页页脚内容
setFooterEvenfooter: PagesHeaderFooter设置偶数页页脚内容
unsetHeaderheaderType?: HeaderType清除页眉插槽;省略参数时清除默认插槽。
unsetFooterfooterType?: FooterType清除页脚插槽;省略参数时清除默认插槽。
setHeaderEditableenabled: boolean锁定或解锁页眉覆盖层(控制 editableHeader)。
setFooterEditableenabled: boolean锁定或解锁页脚覆盖层(控制 editableFooter)。
openHeaderEditor{ pageNumber: number }为特定页面打开页眉编辑器(从 1 开始编号)。
openFooterEditor{ pageNumber: number }为特定页面打开页脚编辑器(从 1 开始编号)。
closeHeaderFooterEditorsnone关闭当前打开的任意页眉/页脚编辑器
closeHeaderEditornone如果页眉编辑器已打开,则将其关闭
closeFooterEditornone如果页脚编辑器已打开,则将其关闭
setAccentColorcolor: string为两个编辑器覆盖层设置强调色
setHeaderAccentColorcolor: string仅为页眉覆盖层设置强调色
setFooterAccentColorcolor: string仅为页脚覆盖层设置强调色

脚注命令

完整参考也位于 脚注。

CommandParametersDescription
insertFootnotenone在选区插入脚注并打开其编辑器
setFootnotesfootnotes: Record<string, JSONContent>使用从 id → 文档映射替换所有脚注内容
openFootnoteEditor{ pageNumber: number, focusNoteId?: string }为某一页面打开脚注编辑器(从 1 开始编号)
closeFootnoteEditornone如果脚注编辑器已打开,则将其关闭
setFootnotesEditableenabled: boolean锁定或解锁脚注编辑(控制 footnotes.editable)
cleanupOrphanFootnotesnone永久移除其引用已消失的脚注内容
setFootnotesAccentColorcolor: string设置脚注强调色

尾注命令

完整参考也位于 尾注。

CommandParametersDescription
insertEndnotenone在选区插入尾注并打开其编辑器
setEndnotesendnotes: Record<string, JSONContent>使用从 id → 文档映射替换所有尾注内容
openEndnoteEditor{ focusNoteId?: string } (optional)打开尾注编辑器,并可选聚焦某条特定尾注
closeEndnoteEditornone如果尾注编辑器已打开,则将其关闭
setEndnotesEditableenabled: boolean锁定或解锁尾注编辑(控制 endnotes.editable)
cleanupOrphanEndnotesnone永久移除其引用已消失的尾注内容
setEndnotesAccentColorcolor: string设置尾注强调色

存储引用

从 editor.storage.pages 中读取这些内容。标记为 只读 的属性不应直接写入;请使用对应的命令。

布局

PropertyTypeDescription
pageFormatPageFormat当前页面格式
zoomnumber当前缩放级别(只读,使用 setZoom)
getZoom() => number当前缩放级别的便捷获取器
pageGapnumber页面之间的当前间距(px)
pageGapBackgroundstring当前页面间距背景颜色
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。

PropertyTypeDescription
headerHTMLstring默认页眉渲染后的 HTML
headerJSONRecord<string, any> | null默认页眉的 Tiptap JSON
headerFirstPageHTMLstring首页页眉渲染后的 HTML
headerFirstPageJSONRecord<string, any> | null首页页眉的 Tiptap JSON
headerOddHTMLstring奇数页页眉渲染后的 HTML
headerOddJSONRecord<string, any> | null奇数页页眉的 Tiptap JSON
headerEvenHTMLstring偶数页页眉渲染后的 HTML
headerEvenJSONRecord<string, any> | null偶数页页眉的 Tiptap JSON
footerHTMLstring默认页脚渲染后的 HTML
footerJSONRecord<string, any> | null默认页脚的 Tiptap JSON
footerFirstPageHTMLstring首页页脚渲染后的 HTML
footerFirstPageJSONRecord<string, any> | null首页页脚的 Tiptap JSON
footerOddHTMLstring奇数页页脚渲染后的 HTML
footerOddJSONRecord<string, any> | null奇数页页脚的 Tiptap JSON
footerEvenHTMLstring偶数页页脚渲染后的 HTML
footerEvenJSONRecord<string, any> | null偶数页页脚的 Tiptap JSON
differentFirstPageboolean首页是否不同
differentOddEvenboolean奇偶页是否不同
differentFirstPageFooterboolean首页页脚是否不同(独立标志)
differentOddEvenFooterboolean奇偶页页脚是否不同(独立标志)
editableHeaderboolean是否可以打开页眉覆盖层(只读,使用 setHeaderEditable)
editableFooterboolean是否可以打开页脚覆盖层(只读,使用 setFooterEditable)
accentColorstring当前强调色(两者)
headerAccentColorstring当前页眉强调色
footerAccentColorstring当前页脚强调色

脚注

完整参考也位于 脚注。

PropertyTypeDescription
footnotesJSONRecord<string, JSONContent>每个脚注 ID 对应的脚注内容,用于持久化和 DOCX 导出
footnotesHTMLRecord<string, string>每个脚注 ID 对应的渲染后 HTML,与页面预览一致
footnoteNumbersRecord<string, number>当前编号(脚注 ID → 1 起始编号)
footnotesEnabledboolean脚注是否已启用
editableFootnotesboolean是否已解锁编辑(只读,使用 setFootnotesEditable)

尾注

完整参考也位于 尾注。

PropertyTypeDescription
endnotesJSONRecord<string, JSONContent>每个尾注 ID 对应的尾注内容,用于持久化和 DOCX 导出
endnotesHTMLRecord<string, string>每个尾注 ID 对应的渲染后 HTML,与文档一致
endnoteNumbersRecord<string, number>当前编号(尾注 ID → 1 起始编号)
endnotesEnabledboolean尾注是否已启用
editableEndnotesboolean是否已解锁编辑(只读,使用 setEndnotesEditable)

活动的内部编辑器状态

当页眉、页脚、脚注或尾注覆盖层打开时,这些属性会反映当前激活的是哪一个。对于构建跟随焦点编辑器的工具栏很有用;请参见 页面页眉和页脚 获取完整工具栏示例。

PropertyTypeDescription
activeEditorEditor | null当前激活的页眉/页脚/脚注/尾注编辑器实例,或 null
activeEditorType'header' | 'footer' | 'footnotes' | 'endnotes' | null当前激活的是哪种覆盖层
activePageNumbernumber | null正在编辑的页码(页眉/页脚/脚注)
headerEditorOnEditor['on'] | null页眉覆盖层内部编辑器事件的预绑定订阅器
headerEditorOffEditor['off'] | null页眉覆盖层内部编辑器的预绑定取消订阅器
footerEditorOnEditor['on'] | null页脚覆盖层内部编辑器事件的预绑定订阅器
footerEditorOffEditor['off'] | null页脚覆盖层内部编辑器的预绑定取消订阅器
footnotesEditorOnEditor['on'] | null脚注编辑器事件的预绑定订阅器
footnotesEditorOffEditor['off'] | null脚注编辑器的预绑定取消订阅器
endnotesEditorOnEditor['on'] | null尾注编辑器事件的预绑定订阅器
endnotesEditorOffEditor['off'] | null尾注编辑器的预绑定取消订阅器

示例用法

内置格式

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',
    }),
  ],
})

自定义格式和运行时更改

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 都接受标记 {page}(当前 1 起始页码)和 {total}(总页数)。它们会在渲染时替换,并可用于纯 字符串、HTML 字符串以及 JSONContent。