页面页眉和页脚

页眉和页脚允许你在每一页的顶部和底部显示一致的内容。Pages 扩展支持静态文本、HTML 标记、通过占位符实现的动态页码、使用 JSONContent 的富文本格式、首页或奇偶页不同的页眉/页脚,以及通过双击页眉或页脚区域进行交互式编辑。

Imported from DOCX

当你使用 DOCX 导入扩展 导入 .docx 文件时,文档中的页眉和页脚会自动应用到 Pages,包括首页不同以及奇偶页不同的变体。无需额外配置。

页眉内容

  • 将在页面页眉中渲染的内容
  • 默认值:'' – 空字符串

初始配置(字符串)

Pages.configure({
  header: 'Awesome Tiptap header', // 字符串!
})

HTML 字符串中的空白

页眉和页脚 HTML 中的重复空格会被保留。<p>Ref. 2026-09</p> 在 header 和 footer 选项、setHeader 和 setFooter 以及内联编辑器中都会保持三个空格。以 JSON 提供的内容不会重新解析,因此也会保留其中的空格。打开和关闭内联编辑器不会改变存储的内容。

如果希望恢复浏览器默认的空白规则,让连续空格折叠为一个空格,请传入自己的解析选项:

Pages.configure({
  header: '<p>Ref.   2026-09</p>',
  headerFooterParseOptions: { preserveWhitespace: false },
})

模板占位符

使用 {page} 和 {total} 占位符实现动态页码。它们适用于 HTML 字符串和 JSONContent,并会在渲染时替换:

Pages.configure({
  header: () => '<bold>Awesome Tiptap header</bold>', // 返回 HTML 或字符串的函数!
})

当文档通过 ExportDocx 编辑器扩展 导出为 .docx 时,每个 {page} / {total} 都会转换为可在 Word 中实时使用的 PAGE / NUMPAGES 字段,因此 Word 会在打印或重新分页时重新计算这些数字。

重命名或禁用占位符

使用 placeholders 选项可以重命名内置标记,或完全关闭替换。支持三种形式:

// 将 {total} 重命名为 {pages}(保留 {page} 可用)
Pages.configure({
  placeholders: { total: 'pages' },
  footer: 'Page {page} of {pages}',
})

// 重命名两个内置标记
Pages.configure({
  placeholders: { page: 'p', total: 'pages' },
  footer: '{p} / {pages}',
})

// 禁用替换;{page} 和 {total} 将按字面文本渲染
Pages.configure({
  placeholders: false,
  footer: 'Page {page} of {total}',
})

当你重命名内置标记时,原始标记名将不再被识别。替换只会作用于页眉/页脚内容;正文中包含的 {page} / {total} 始终会按字面文本保留。

DOCX import

当 importDocx 将 Word 的 PAGE 和 NUMPAGES 字段转换为文本标记时,标记名称取决于您的页面配置:

  • 默认配置。 导入不发送名称,因此字段返回为 {page} 和 {numpages}。 Pages 渲染 {page},但 {numpages} 在编辑器和 ExportDocx 扩展的导出中保留文字文本。设置placeholders: { total: 'numpages' }进行渲染并导出。 REST DOCX 导出已将 {numpages} 视为总页数。
  • 重命名。 导入会转发您的 placeholders 贴图,因此 { total: 'pages' } 将 NUMPAGES 恢复为 {pages},从而实时渲染并导出为实时字段。您遗漏的键将保留其导入默认值,因此重命名 total 以获取实时总页数。
  • placeholders: false. 导入将 Word 的缓存数字保留为纯文本。

将 placeholders: true 传递到 importDocx 会强制进行转换,即使 Pages 设置了 placeholders: false 也是如此。当有页面重命名时,它会使用您的页面重命名,否则导入默认值。

作为简单 w:fldSimple 字段写入的页码永远不会被转换,无论 placeholders 设置如何,并且导入会删除其缓存的页码。请参阅 REST 导入页面 了解导入识别的字段布局,以及 DOCX 导入 → 页码字段 了解完整情况。

JSONContent

editor.commands.setHeader('我很棒的页眉') // 字符串!
// 或者
editor.commands.Header((page, total) => `${page} / ${total}`) // 返回 HTML 或字符串的函数!

页眉替换模板

当 header 属性使用字符串时,提供了两个便捷的模板替换:

  • {page}:被替换为当前页码。
  • {total}:被替换为文档的总页数。

header 属性也可以接受一个函数,传递相同的信息,这次通过函数参数提供:

Pages.configure({
  header: {
    type: 'doc',
    content: [
      {
        type: 'paragraph',
        content: [{ type: 'text', text: 'Document Title', marks: [{ type: 'bold' }] }],
      },
    ],
  },
})

页眉高度

  • 控制每页顶部页眉区域的高度。
  • 默认值:50(像素)

两种方式都可以设置内容:

使用 configure 的初始设置:

Pages.configure({
  header: '我的文档标题',
  footer: '第 {page} 页,共 {total} 页',
})

使用 commands 的运行时更新:

// 编辑器初始化后更新页眉
editor.commands.setHeader('更新后的页眉')

页眉配置

默认页眉

header 选项设置每页页眉区域显示的内容。

初始配置:

Pages.configure({
  headerHeight: 80, // 让页眉区域更高
})

页眉高度编辑命令

editor.commands.setHeaderHeight(30) // 更小的页眉!

页脚内容

  • 将在页面页脚中渲染的内容
  • 默认值:{page} – 带有页码模板替换的字符串

初始配置(字符串)

Pages.configure({
  footer: 'Awesome Tiptap footer', // 字符串!
})

编辑器命令:

// 覆盖页眉上边距
editor.commands.setHeaderTopMargin(40)

// 清除覆盖并回退到当前格式的默认值
//(该格式顶部边距的 50%)
editor.commands.resetHeaderTopMargin()

输入校验

setHeaderTopMargin 会拒绝负值和 NaN;在这些情况下,该命令会返回 false 并记录警告。

页脚配置

默认页脚

footer 选项设置每页页脚区域显示的内容。

初始配置:

Pages.configure({
  footer: () => '<bold>Awesome Tiptap 页脚</bold>', // 返回 HTML 或字符串的函数!
})

页脚内容编辑命令

editor.commands.setFooter('我的超棒页脚') // 字符串!
// 或者
editor.commands.setFooter((page, total) => `${page} / ${total}`) // 返回 HTML 或字符串的函数!

页脚替换模板

当 footer 属性使用字符串时,提供了两个便捷的模板替换:

  • {page}:被替换为当前页码。
  • {total}:被替换为文档的总页数。

footer 属性也可以接受一个函数,传递相同的信息,这次通过函数参数提供:

Pages.configure({
  footer: (page, total) => `${page} / ${total}` // 示例,显示:"1 / 10"
})

编辑器命令:

// 覆盖页脚下边距
editor.commands.setFooterBottomMargin(40)

// 清除覆盖并回退到当前格式的默认值
//(该格式底部边距的 50%)
editor.commands.resetFooterBottomMargin()

输入验证

setFooterBottomMargin 会拒绝负值和 NaN;在这些情况下,该命令会返回 false 并记录警告。

清除页眉或页脚

unsetHeader 和 unsetFooter 会清空插槽并释放其预留的页面空间。不传参数时清除默认插槽;传入 'first'、'odd' 或 'even' 可清除对应变体。

editor.commands.unsetHeader()
editor.commands.unsetFooter('first')

在协作中,被清除的插槽会像 setHeader 一样同步到每个已连接的客户端。DOCX 导入会对导入文件未携带的每个插槽使用这些命令。

首页不同

editor.commands.setFooterHeight(30) // 更小的页脚!

注意

setDifferentFirstPage() 命令可同时启用首页不同的页眉和页脚,行为类似 Microsoft Word。

首页空白槽位

调用 setDifferentFirstPage(true) 并不会将默认页眉/页脚复制到首页槽位中。它会保持空白,与 Microsoft Word 的行为一致。若要预先填充首页页眉或页脚,可在启用该标志后调用 setHeaderFirstPage / setFooterFirstPage,或者在 Pages.configure() 中设置 headerFirstPage / footerFirstPage。

配置

Pages.configure({
  header: '默认页眉',
  footer: '第 {page} 页',
  differentFirstPage: true,
  headerFirstPage: '标题页',
  footerFirstPage: '', // 首页无页脚
})

命令

// 启用首页不同(同时影响页眉和页脚)
editor.commands.setDifferentFirstPage(true)

// 设置首页页眉和页脚内容
editor.commands.setHeaderFirstPage('欢迎使用我的文档')
editor.commands.setFooterFirstPage('')

奇偶页不同

启用奇数页(1、3、5……)和偶数页(2、4、6……)不同的页眉和/或页脚,类似于微软 Word 的“奇偶页不同”选项。

注意

setDifferentOddEven() 命令可同时启用奇偶页不同的页眉和页脚,行为类似 Microsoft Word。

奇数槽在启用时继承默认值

当你调用 setDifferentOddEven(true) 时,如果奇数槽为空,现有的默认页眉/页脚内容会被复制到 奇数槽中。这与 Microsoft Word 的连续性 行为一致:第 1、3、5……页会继续显示切换标志之前的内容,而 偶数槽会先保持为空,供你填入内容。如果你先关闭再重新开启该标志,之前输入到奇数槽中的内容会被保留(只有在奇数槽 为空时才会发生复制)。

配置

Pages.configure({
  differentOddEven: true,
  headerOdd: '章节标题 – 奇数页',
  headerEven: '书名 – 偶数页',
  footerOdd: '第 {page} 页',
  footerEven: '第 {page} 页',
})

命令

// 启用奇偶页不同(同时影响页眉和页脚)
editor.commands.setDifferentOddEven(true)

// 设置奇数页和偶数页页眉
editor.commands.setHeaderOdd('奇数页页眉')
editor.commands.setHeaderEven('偶数页页眉')

// 设置奇数页和偶数页页脚
editor.commands.setFooterOdd('第 {page} 页')
editor.commands.setFooterEven('第 {page} 页')

首页与奇偶页同时启用

当同时启用 differentFirstPage 和 differentOddEven 时,首页页眉/页脚优先于奇偶页设置,同时页 1 使用首页设置。

优先顺序:

  1. 首页(如果启用了 differentFirstPage)- 适用于第 1 页
  2. 奇偶页(如果启用了 differentOddEven)- 适用于第 2 页及之后
  3. 默认页眉/页脚 - 后备(仅在该区域未启用 differentFirstPage 和 differentOddEven 时使用)

空的特定类型槽位会渲染为空

当启用 differentFirstPage 或 differentOddEven 时,对应的槽位对其覆盖的页面具有 最高优先级,即使为空也是如此。例如,启用 differentFirstPage: true 且 headerFirstPage 为空时,第 1 页会渲染为空页眉(它 不会 静默回退到默认页眉)。这与 Microsoft Word 和 Google Docs 一致。只有当相关标志(differentFirstPage 或 differentOddEven)为 关闭 时,才会使用默认页眉/页脚作为后备。

Pages.configure({
  header: 'Default Header', // 后备
  differentFirstPage: true,
  headerFirstPage: 'Title Page', // 第 1 页
  differentOddEven: true,
  headerOdd: 'Odd Page Header', // 第 3、5、7 页……
  headerEven: 'Even Page Header', // 第 2、4、6 页……
})

可编辑的页眉和页脚

用户可以通过双击页眉或页脚直接编辑它们。这将打开一个功能完备的 Tiptap 编辑器,允许丰富文本编辑。

自定义扩展

页眉/页脚编辑器使用与你在主编辑器中配置的相同扩展。为了匹配 schema(这样相同的 mark、节点和表格行为都能在页眉和页脚中工作),请通过 headerFooterExtensions 传入 ConvertKit 和 TableKit:

import { ConvertKit } from '@tiptap-pro/extension-convert-kit'
import { TableKit } from '@tiptap-pro/extension-pages-tablekit'

Pages.configure({
  header: 'My header',
  headerFooterExtensions: [ConvertKit.configure({ table: false }), TableKit],
})

任何 Tiptap 扩展都可以通过 headerFooterExtensions 选项添加到页眉/页脚编辑器中。与主编辑器的扩展栈保持一致,可以让文档及其页眉页脚之间的 schema、键盘快捷键和渲染效果保持统一。

协作使用回调形式

headerFooterExtensions 也接受一个 (ctx) => Extensions 回调,它会针对每个页眉/页脚子类型触发一次,并传入子编辑器应绑定到的 Y 字段名和 Y.Doc。配置协作功能时请使用这种形式。请参阅 为 Pages 添加协作功能。

活动编辑器状态

当用户双击页眉或页脚进行编辑时,扩展会通过存储暴露当前激活的编辑器。这使你能够构建与页眉/页脚编辑器配合使用的自定义工具栏。

存储属性:

  • activeEditor – The Tiptap Editor instance for the currently open header or footer editor (or null)
  • activeEditorType – 'header', 'footer', or null
  • activePageNumber – The page number being edited (or null)
  • headerEditorOn / headerEditorOff – 订阅/取消订阅默认页眉编辑器上的事件(null,无协作)
  • footerEditorOn / footerEditorOff – 订阅/取消订阅默认页脚编辑器上的事件(null,无协作)

该扩展还侦听来自页眉和页脚内部编辑器的 focus 事件,包括首页、奇数页和偶数页变体。当用户聚焦另一个打开的页眉或页脚编辑器时,activeEditor、activeEditorType 和 activePageNumber 将从活动叠加层刷新,并且主编辑器发出 update。焦点编辑器后面有一个工具栏,上面写着 editor.storage.pages on update。

锁定页眉或页脚

将 editableHeader 或 editableFooter 设置为 false,即可在不提供双击编辑能力的情况下渲染页眉/页脚。锁定后,用户或代码都无法打开覆盖层:cursor: pointer 提示会被移除,openHeaderEditor / openFooterEditor 命令会返回 false,并且任何已打开的覆盖层都会关闭(从而恢复主编辑器的 editable 状态)。

Pages.configure({
  header: 'Page {page} of {total}',
  editableHeader: false, // 在编辑器创建时即锁定
})

可在运行时通过 setHeaderEditable / setFooterEditable 切换:

editor.commands.setHeaderEditable(false) // 锁定
editor.commands.setHeaderEditable(true) // 解锁

editor.commands.setFooterEditable(false)
editor.commands.setFooterEditable(true)

锁定不会隐藏内容

锁定时页眉和页脚仍会正常渲染;只是移除了行内编辑能力。如果你想清除内容,请使用 setHeader('') / setFooter('')。

监听页眉/页脚编辑器事件

页眉和页脚有自己的编辑器。

要显示正在编辑的页眉或页脚,请读取主编辑器的 update 事件上的存储。当焦点在页眉和页脚变体之间移动时(默认编辑器看不到),它也会触发:

import { useEffect, useState } from 'react'

function HeaderFooterStatus({ editor }) {
  const [activeEditorType, setActiveEditorType] = useState(null)
  const [activePageNumber, setActivePageNumber] = useState(null)

  useEffect(() => {
    if (!editor) return

    const syncActiveEditorState = () => {
      const { activeEditorType, activePageNumber } = editor.storage.pages
      setActiveEditorType(activeEditorType)
      setActivePageNumber(activePageNumber)
    }

    editor.on('update', syncActiveEditorState)

    return () => {
      editor.off('update', syncActiveEditorState)
    }
  }, [editor])

  if (!activeEditorType || !activePageNumber) {
    return <span>正在编辑文档</span>
  }

  return (
    <span>
      正在编辑第 {activePageNumber} 页的 {activeEditorType}
    </span>
  )
}

启用协作时,可以使用 headerEditorOn 和 footerEditorOn 监听默认页眉或页脚编辑器及其 Tiptap 编辑器事件,例如 focus、update、selectionUpdate、blur 和 transaction。未启用协作时,这两个回调为 null。Pages 会在创建主编辑器时绑定回调,并在首次打开页眉或页脚时才创建对应编辑器。

构建自定义工具栏

下面是一个 React 组件示例,它为主编辑器和页眉/页脚编辑器提供一个统一的工具栏:

import { useEditor, useEditorState, EditorContent } from '@tiptap/react'
import { useEffect, useState } from 'react'

function DocumentEditor() {
  const [headerFooterEditor, setHeaderFooterEditor] = useState(null)
  const [activeEditorType, setActiveEditorType] = useState(null)
  const [activePageNumber, setActivePageNumber] = useState(null)

  const editor = useEditor({
    extensions: [
      ConvertKit.configure({ table: false }),
      TableKit,
      Pages.configure({
        header: '文档页眉',
        footer: '第 {page} 页',
      }),
    ],
  })

  // 监听页眉/页脚编辑器的激活变化
  useEffect(() => {
    if (!editor) return

    const syncActiveHeaderFooterEditor = () => {
      const { activeEditor, activeEditorType, activePageNumber } = editor.storage.pages
      setHeaderFooterEditor(activeEditor)
      setActiveEditorType(activeEditorType)
      setActivePageNumber(activePageNumber)
    }

    editor.on('update', syncActiveHeaderFooterEditor)

    return () => {
      editor.off('update', syncActiveHeaderFooterEditor)
    }
  }, [editor])

  // 使用激活的编辑器(页眉/页脚或主编辑器)
  const activeEditor = activeEditorType ? headerFooterEditor : editor

  const { isBoldActive } = useEditorState({
    editor: activeEditor,
    selector: ({ editor: e }) => ({
      isBoldActive: e?.isActive('bold') ?? false,
    }),
  })

  return (
    <div>
      <div className="toolbar">
        <span>
          编辑中:{' '}
          {activeEditorType && activePageNumber
            ? `${activeEditorType}(第 ${activePageNumber} 页)`
            : '文档'}
        </span>
        <button
          className={isBoldActive ? 'is-active' : ''}
          onClick={() => activeEditor?.chain().focus().toggleBold().run()}
        >
          加粗
        </button>
      </div>
      <EditorContent editor={editor} />
    </div>
  )
}

自定义覆盖层工具栏

可以通过两种方式添加控件,请根据控件所属位置进行选择。

  • 对于同样适用于文档正文的格式控件,请使用上面的模式,即跟随 editor.storage.pages.activeEditor 的外部工具栏。
  • 对于属于页眉或页脚覆盖层本身、应放在关闭按钮旁边的控件,请使用 renderOverlayActions。

renderOverlayActions 会在每次构建覆盖层工具栏时运行:打开覆盖层、缩放比例变化以及页眉类型变化时都会运行。返回一个元素;如果需要清理钩子(例如卸载 React portal),请返回 { element, destroy }。返回 null 则不渲染任何内容。

Pages.configure({
  renderOverlayActions: ({ innerEditor }) => {
    const button = document.createElement('button')
    button.type = 'button'
    button.textContent = 'Insert date'
    button.onclick = () => {
      innerEditor.chain().focus().insertContent(new Date().toLocaleDateString()).run()
    }
    return button
  },
})

上下文会提供父级 editor、正在编辑的 innerEditor、kind('header' 或 'footer')、subType('default'、'first'、'odd' 或 'even')、pageNumber 和 close()。

请将状态保存在返回元素之外。每次重新构建都会销毁插槽并再次渲染。

翻译覆盖层标签

每个覆盖层标签都通过 overlayLabels 处理。每个标签条目都是一个函数,因此可以使用任意 i18n 库。缺失的条目会保留英文默认值。close 是一个字符串,会成为每个关闭按钮的可访问名称和工具提示。

Pages.configure({
  overlayLabels: {
    header: ({ subType, pageNumber }) =>
      subType === 'first' ? t('pages.header.first') : t('pages.header.page', { pageNumber }),
    footer: ({ subType, pageNumber }) => t('pages.footer', { subType, pageNumber }),
    footnotes: ({ pageNumber }) => t('pages.footnotes', { pageNumber }),
    endnotes: () => t('pages.endnotes'),
    close: t('common.close'),
  },
})

正文中的脚注和尾注标记从单独的选项 noteReferenceLabel 获取其屏幕阅读器名称。请参阅屏幕阅读器名称。

用户通过页眉或页脚编辑器修改内容后,内容会存储在扩展的存储区。这对于保存文档或导出为 DOCX 等格式非常有用。

HTML 内容

访问编辑后的 HTML 内容:

// 默认页眉/页脚
const headerHTML = editor.storage.pages.headerHTML
const footerHTML = editor.storage.pages.footerHTML

// 首页
const headerFirstPageHTML = editor.storage.pages.headerFirstPageHTML
const footerFirstPageHTML = editor.storage.pages.footerFirstPageHTML

// 奇偶页
const headerOddHTML = editor.storage.pages.headerOddHTML
const headerEvenHTML = editor.storage.pages.headerEvenHTML
const footerOddHTML = editor.storage.pages.footerOddHTML
const footerEvenHTML = editor.storage.pages.footerEvenHTML

注意

这些存储值在用户通过相应的页眉/页脚编辑器编辑内容之前均为 null。编辑之前,使用配置中的原始模板。

用于 DOCX 导出的 JSON 内容

对于 DOCX 导出,使用 JSON 版本,它们提供结构化的 Tiptap 文档格式:

// 默认页眉/页脚
const headerJSON = editor.storage.pages.headerJSON
const footerJSON = editor.storage.pages.footerJSON

// 首页
const headerFirstPageJSON = editor.storage.pages.headerFirstPageJSON
const footerFirstPageJSON = editor.storage.pages.footerFirstPageJSON

// 奇偶页
const headerOddJSON = editor.storage.pages.headerOddJSON
const headerEvenJSON = editor.storage.pages.headerEvenJSON
const footerOddJSON = editor.storage.pages.footerOddJSON
const footerEvenJSON = editor.storage.pages.footerEvenJSON

注意

这些存储值在用户通过相应的页眉/页脚编辑器编辑内容之前均为 null。编辑之前,使用配置中的原始模板。

保存页眉和页脚内容

保存页眉和页脚内容是你的责任。保存文档时从存储区获取内容,加载时再恢复。

保存所有页眉和页脚内容:

function getHeaderFooterContent(editor) {
  const { pages } = editor.storage

  return {
    // 默认页眉/页脚
    headerHTML: pages.headerHTML,
    headerJSON: pages.headerJSON,
    footerHTML: pages.footerHTML,
    footerJSON: pages.footerJSON,

    // 首页
    headerFirstPageHTML: pages.headerFirstPageHTML,
    headerFirstPageJSON: pages.headerFirstPageJSON,
    footerFirstPageHTML: pages.footerFirstPageHTML,
    footerFirstPageJSON: pages.footerFirstPageJSON,

    // 奇偶页
    headerOddHTML: pages.headerOddHTML,
    headerOddJSON: pages.headerOddJSON,
    headerEvenHTML: pages.headerEvenHTML,
    headerEvenJSON: pages.headerEvenJSON,
    footerOddHTML: pages.footerOddHTML,
    footerOddJSON: pages.footerOddJSON,
    footerEvenHTML: pages.footerEvenHTML,
    footerEvenJSON: pages.footerEvenJSON,
  }
}

// 保存到后端
const headerFooterData = getHeaderFooterContent(editor)
await saveDocument({ content: editor.getJSON(), headerFooter: headerFooterData })

编程式打开和关闭编辑器

你可以通过编程方式打开和关闭页眉和页脚编辑器。这对于集成自定义 UI 元素、构建导航界面或响应用户操作非常有用。

打开编辑器

使用 openHeaderEditor 和 openFooterEditor 命令为指定页面打开编辑器:

// 打开第 1 页的页眉编辑器
editor.commands.openHeaderEditor({ pageNumber: 1 })

// 打开第 3 页的页脚编辑器
editor.commands.openFooterEditor({ pageNumber: 3 })

这些命令在成功打开编辑器时返回 true,页面不存在时返回 false。

注意

打开一个编辑器时会自动关闭之前打开的任何页眉或页脚编辑器。主文档编辑器在页眉或页脚编辑器打开时不可编辑。

使用场景:

  • 构建页码导航 UI,让用户直接跳转编辑指定页的页眉或页脚
  • 在工具栏中创建“跳转到页眉/页脚”按钮
  • 实现快捷键打开页眉或页脚
  • 响应外部事件时编程打开编辑器

示例:页面导航组件

function PageNavigation({ editor }) {
  const pageCount = editor.storage.pages.getPageCount?.() ?? 1

  return (
    <div>
      {Array.from({ length: pageCount }, (_, i) => (
        <div key={i + 1}>
          <span>第 {i + 1} 页</span>
          <button onClick={() => editor.commands.openHeaderEditor({ pageNumber: i + 1 })}>
            编辑页眉
          </button>
          <button onClick={() => editor.commands.openFooterEditor({ pageNumber: i + 1 })}>
            编辑页脚
          </button>
        </div>
      ))}
    </div>
  )
}

关闭编辑器

使用关闭命令关闭页眉或页脚编辑器:

// 关闭当前打开的任何编辑器
editor.commands.closeHeaderFooterEditors()

// 关闭特定编辑器
editor.commands.closeHeaderEditor()
editor.commands.closeFooterEditor()

防止双击关闭编辑器

默认情况下,在打开的页眉或页脚编辑器外双击会关闭编辑器。你可以使用回调选项防止此行为,这在有工具栏按钮或其他 UI 元素时很有用,避免用户双击时编辑器意外关闭。

配置

提供三种回调选项:

  • onDblClickHeaderFooterPreventClose - 适用于页眉和页脚(回退)
  • onDblClickHeaderPreventClose - 仅适用于页眉(优先于回退)
  • onDblClickFooterPreventClose - 仅适用于页脚(优先于回退)

每个回调函数接收 MouseEvent,返回 true 表示阻止关闭,false 允许关闭。

示例:点击工具栏时防止关闭

Pages.configure({
  header: '我的页眉',
  footer: '第 {page} 页',
  onDblClickHeaderFooterPreventClose: (event) => {
    // 如果点击在工具栏内,保持编辑器打开
    const toolbar = document.querySelector('.my-toolbar')
    return toolbar?.contains(event.target)
  },
})

示例:对页眉和页脚采用不同行为

Pages.configure({
  header: '我的页眉',
  footer: '第 {page} 页',
  // 双击页眉外部永不关闭
  onDblClickHeaderPreventClose: () => true,
  // 仍允许双击页脚外部关闭
  onDblClickFooterPreventClose: () => false,
})

重点强调颜色

可以自定义页眉和页脚编辑器覆盖层的视觉样式,调整强调色包括:

  • 光标颜色 — 编辑器中的文本光标颜色
  • 工具栏边框 — 编辑工具栏的顶部边框(页眉)或底部边框(页脚)
  • 标签背景 — “页眉” 或 “页脚” 标签背景色

配置

在扩展配置时设置强调色:

Pages.configure({
  header: '我的页眉',
  footer: '第 {page} 页',
  // 同时设置页眉和页脚的颜色
  accentColor: '#3b82f6',
})

也可以分别设置页眉和页脚的强调色:

Pages.configure({
  header: '我的页眉',
  footer: '第 {page} 页',
  headerAccentColor: '#3b82f6', // 页眉的蓝色
  footerAccentColor: '#10b981', // 页脚的绿色
})

运行时更新

使用命令动态修改强调色:

// 同时更新页眉和页脚颜色
editor.commands.setAccentColor('#8b5cf6')

// 仅更新页眉颜色
editor.commands.setHeaderAccentColor('#3b82f6')

// 仅更新页脚颜色
editor.commands.setFooterAccentColor('#ef4444')

CSS 颜色值

强调色选项支持任何有效的 CSS 颜色值,包括十六进制(#3b82f6)、rgb(rgb(59, 130, 246))、hsl(hsl(217, 91%, 60%))、oklch 或 CSS 变量(var(--primary-color))。

工具栏渐变

当你打开页眉或页脚覆盖层时出现的编辑工具栏,在其标签和关闭按钮后方会有一个细微的白色渐变淡出效果。可以使用 toolbarGradient 选项将其禁用,从而获得平坦、无渐变的工具栏:

Pages.configure({
  header: '我的页眉',
  footer: '第 {page} 页',
  toolbarGradient: false, // 平坦工具栏;默认值为 true
})

这是一个全局文档设置:它同样适用于页眉、页脚、脚注和尾注编辑工具栏,使它们保持视觉一致。

覆盖背景和 z 索引

页眉、页脚、脚注和尾注覆盖层为白色,默认位于 z-index: 1000。有两个选项可以改变这一点:

  • overlayBackgroundColor 设置叠加层的背景及其工具栏淡入淡出的起始颜色。当您的页面有颜色时使用它,这样打开的叠加层就会与页面匹配,而不是显示白色框。
  • overlayZIndex 设置它们的堆叠顺序。当您自己的菜单或弹出窗口低于 1000 并且必须显示在打开的覆盖层上方时,请降低它。
Pages.configure({
  header: 'My Header',
  footer: 'Page {page}',
  overlayBackgroundColor: 'var(--page-color)',
  overlayZIndex: 50,
})

overlayBackgroundColor 接受任何 CSS 颜色,也是 CSS 变量。覆盖层将添加到编辑器外部的 document.body,因此请定义 body 继承它的变量,例如在 :root 上。当页面颜色在打开时发生变化时,变量使覆盖保持同步:

:root {
  --page-color: #fffbeb;
  /* Pages also paints the pages with this color. */
  --pages-page-background-color: var(--page-color);
}

与 toolbarGradient 一样,这两个选项都适用于页眉、页脚、脚注和尾注覆盖。

Limitations

页眉和页脚编辑器样式

页眉/页脚编辑器使用内置样式。但是,您可以使用 accentColor、headerAccentColor 和 footerAccentColor 选项自定义强调色,并使用 overlayBackgroundColor 和 overlayZIndex 自定义叠加背景和堆叠顺序。

协作功能

页眉和页脚编辑器会与主文档一起参与协作。每个子类型(默认、首页、奇数页、偶数页)都会独立协作,differentFirstPage / differentOddEven 切换会在客户端之间同步,文档级页面几何信息(pageFormat、pageGap、headerTopMargin、footerBottomMargin)也会同步,因此远程调用 setPageFormat 或修改边距会在每个客户端上重新排版。要启用协作,请将 headerFooterExtensions 作为一个回调传入,为每个子编辑器附加 Collaboration 扩展;静态数组形式不会为子编辑器启用协作。完整设置流程请参见为 Pages 添加协作。

协作时省略页眉/页脚默认值

启用协作时,不要在 Pages.configure() 中传入 header / footer 默认值;当其他客户端清空内容后, 它们可能会重新出现。请不要保留这些默认值;如果你需要一个初始值,请在 provider 同步完成后, 通过 editor.commands.setHeader(...) 只设置一次。

页眉/页脚编辑器使用内置样式,但你可通过 accentColor、headerAccentColor 和 footerAccentColor 选项自定义强调色。

OptionTypeDefaultDescription
headerstring | JSONContent''Default header content
footerstring | JSONContent''Default footer content
headerTopMarginnumber50% of top marginDistance from page top to header content
footerBottomMarginnumber50% of bottom marginDistance from footer content to page bottom
differentFirstPagebooleanfalseEnable different first page header and footer
headerFirstPagePagesHeaderFooter''First page header content
footerFirstPagePagesHeaderFooter''First page footer content
differentOddEvenbooleanfalseEnable different odd/even headers and footers
headerOddPagesHeaderFooter''Odd pages header content
headerEvenPagesHeaderFooter''Even pages header content
footerOddPagesHeaderFooter''Odd pages footer content
footerEvenPagesHeaderFooter''Even pages footer content
editableHeaderbooleantrueWhether double-clicking the header opens the inline editor
editableFooterbooleantrueWhether double-clicking the footer opens the inline editor
headerFooterExtensionsExtensions | (ctx) => ExtensionsConvertKitExtensions for the header/footer sub-editors. Pass a static array for non-collab; pass a callback to attach Collaboration per subtype. See Adding collaboration to Pages.
onDblClickHeaderFooterPreventClose(event: MouseEvent) => booleanundefinedCallback to prevent closing header/footer editors on double-click outside
onDblClickHeaderPreventClose(event: MouseEvent) => booleanundefinedCallback to prevent closing header editor on double-click outside
onDblClickFooterPreventClose(event: MouseEvent) => booleanundefinedCallback to prevent closing footer editor on double-click outside
accentColorstring'#6366f1'Accent color for header/footer editor overlays
headerAccentColorstringaccentColor valueAccent color for header editor overlay
footerAccentColorstringaccentColor valueAccent color for footer editor overlay
toolbarGradientbooleantrueShow the white fade gradient behind the edit-overlay toolbars (header, footer, footnotes, endnotes). false for flat toolbars.
overlayBackgroundColorstringundefined(白色)页眉、页脚、脚注和尾注叠加层及其工具栏的背景淡入淡出。任何 CSS 颜色,也是 CSS 变量。请参阅叠加背景和 z-index。
overlayZIndexnumberundefined (1000)页眉、页脚、脚注和尾注覆盖的堆叠顺序。降低它可以在打开的覆盖层上方显示您自己的菜单。
placeholdersfalse | { page?, total? }undefinedRename the built-in {page} / {total} tokens or disable substitution.

Commands reference

CommandParametersDescription
setHeaderheader: PagesHeaderFooter设置默认页眉内容
setFooterfooter: PagesHeaderFooter设置默认页脚内容
setHeaderTopMarginmargin: number设置页眉上边距(像素)。拒绝负值和 NaN。
resetHeaderTopMarginnone清除页眉上边距覆盖;回退到当前格式的默认值(格式顶部边距的 50%)。
setFooterBottomMarginmargin: number设置页脚下边距(像素)。拒绝负值和 NaN。
resetFooterBottomMarginnone清除页脚下边距覆盖;回退到当前格式的默认值(格式底部边距的 50%)。
setDifferentFirstPageenabled: boolean切换不同的首页(页眉 + 页脚)。首页槽位保持为空,与 Word 一致。如果页眉/页脚覆盖层已打开,则会刷新以显示新变体。
setHeaderFirstPageheader: PagesHeaderFooter设置首页页眉内容
setFooterFirstPagefooter: PagesHeaderFooter设置首页页脚内容
setDifferentOddEvenenabled: boolean切换不同的奇偶页(页眉 + 页脚)。启用时,会将默认页眉/页脚复制到奇数页槽位(如果为空),以保持与 Word 的连续性。如果页眉/页脚覆盖层已打开,则会刷新以显示新变体。
setHeaderOddheader: PagesHeaderFooter设置奇数页页眉内容
setHeaderEvenheader: PagesHeaderFooter设置偶数页页眉内容
setFooterOddfooter: PagesHeaderFooter设置奇数页页脚内容
setFooterEvenfooter: PagesHeaderFooter设置偶数页页脚内容
setHeaderEditableenabled: boolean锁定或解锁页眉覆盖层。为 false 时,双击无效,openHeaderEditor 返回 false,并关闭任何已打开的页眉覆盖层。
setFooterEditableenabled: boolean锁定或解锁页脚覆盖层。为 false 时,双击无效,openFooterEditor 返回 false,并关闭任何已打开的页脚覆盖层。
openHeaderEditor{ pageNumber: number }打开指定页面的页眉编辑器(从 1 开始计数)
openFooterEditor{ pageNumber: number }打开指定页面的页脚编辑器(从 1 开始计数)
closeHeaderFooterEditorsnone关闭当前打开的页眉/页脚编辑器
closeHeaderEditornone如果页眉编辑器已打开则关闭它
closeFooterEditornone如果页脚编辑器已打开则关闭它
setAccentColorcolor: string设置两个编辑器覆盖层的强调色
setHeaderAccentColorcolor: string设置页眉编辑器覆盖层的强调色
setFooterAccentColorcolor: string设置页脚编辑器覆盖层的强调色