页扩展 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

  /** 启用首页使用不同的页眉和页脚（Word 的“首页不同”）。
   *  默认：false。 */
  differentFirstPage?: boolean

  /** 首页页眉内容。默认：''。 */
  headerFirstPage?: PagesHeaderFooter

  /** 首页页脚内容。默认：''。 */
  footerFirstPage?: PagesHeaderFooter

  /** 启用奇数页与偶数页使用不同的页眉和页脚（Word 的“奇偶页不同”）。
   *  默认：false。 */
  differentOddEven?: boolean

  /** 奇数页页眉内容。默认：''。 */
  headerOdd?: PagesHeaderFooter

  /** 偶数页页眉内容。默认：''。 */
  headerEven?: PagesHeaderFooter

  /** 奇数页页脚内容。默认：''。 */
  footerOdd?: PagesHeaderFooter

  /** 偶数页页脚内容。默认：''。 */
  footerEven?: PagesHeaderFooter

  /** 独立启用与 `differentFirstPage` 无关的不同首页页脚。
   *  调用 `setDifferentFirstPage(true)` 时会自动设置。 */
  differentFirstPageFooter?: boolean

  /** 独立启用与 `differentOddEven` 无关的不同奇偶页页脚。
   *  调用 `setDifferentOddEven(true)` 时会自动设置。 */
  differentOddEvenFooter?: boolean

  /** 注册到内部页眉/页脚编辑器上的扩展。
   *  默认为 StarterKit；请镜像主编辑器的扩展栈以保持 schema 对齐。 */
  headerFooterExtensions?: 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
}

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