页面扩展 API 参考

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<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
}

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')