页面页眉和页脚
页眉和页脚允许你在每一页的顶部和底部显示一致的内容。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 使用首页设置。
优先顺序:
- 首页(如果启用了
differentFirstPage)- 适用于第 1 页 - 奇偶页(如果启用了
differentOddEven)- 适用于第 2 页及之后 - 默认页眉/页脚 - 后备(仅在该区域未启用
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 (ornull)activeEditorType–'header','footer', ornullactivePageNumber– The page number being edited (ornull)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 获取其屏幕阅读器名称。请参阅屏幕阅读器名称。
Accessing header and footer content
用户通过页眉或页脚编辑器修改内容后,内容会存储在扩展的存储区。这对于保存文档或导出为 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 选项自定义强调色。
| Option | Type | Default | Description |
|---|---|---|---|
header | string | JSONContent | '' | Default header content |
footer | string | JSONContent | '' | Default footer content |
headerTopMargin | number | 50% of top margin | Distance from page top to header content |
footerBottomMargin | number | 50% of bottom margin | Distance from footer content to page bottom |
differentFirstPage | boolean | false | Enable different first page header and footer |
headerFirstPage | PagesHeaderFooter | '' | First page header content |
footerFirstPage | PagesHeaderFooter | '' | First page footer content |
differentOddEven | boolean | false | Enable different odd/even headers and footers |
headerOdd | PagesHeaderFooter | '' | Odd pages header content |
headerEven | PagesHeaderFooter | '' | Even pages header content |
footerOdd | PagesHeaderFooter | '' | Odd pages footer content |
footerEven | PagesHeaderFooter | '' | Even pages footer content |
editableHeader | boolean | true | Whether double-clicking the header opens the inline editor |
editableFooter | boolean | true | Whether double-clicking the footer opens the inline editor |
headerFooterExtensions | Extensions | (ctx) => Extensions | ConvertKit | Extensions 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) => boolean | undefined | Callback to prevent closing header/footer editors on double-click outside |
onDblClickHeaderPreventClose | (event: MouseEvent) => boolean | undefined | Callback to prevent closing header editor on double-click outside |
onDblClickFooterPreventClose | (event: MouseEvent) => boolean | undefined | Callback to prevent closing footer editor on double-click outside |
accentColor | string | '#6366f1' | Accent color for header/footer editor overlays |
headerAccentColor | string | accentColor value | Accent color for header editor overlay |
footerAccentColor | string | accentColor value | Accent color for footer editor overlay |
toolbarGradient | boolean | true | Show the white fade gradient behind the edit-overlay toolbars (header, footer, footnotes, endnotes). false for flat toolbars. |
overlayBackgroundColor | string | undefined(白色) | 页眉、页脚、脚注和尾注叠加层及其工具栏的背景淡入淡出。任何 CSS 颜色,也是 CSS 变量。请参阅叠加背景和 z-index。 |
overlayZIndex | number | undefined (1000) | 页眉、页脚、脚注和尾注覆盖的堆叠顺序。降低它可以在打开的覆盖层上方显示您自己的菜单。 |
placeholders | false | { page?, total? } | undefined | Rename the built-in {page} / {total} tokens or disable substitution. |
Commands reference
| Command | Parameters | Description |
|---|---|---|
setHeader | header: PagesHeaderFooter | 设置默认页眉内容 |
setFooter | footer: PagesHeaderFooter | 设置默认页脚内容 |
setHeaderTopMargin | margin: number | 设置页眉上边距(像素)。拒绝负值和 NaN。 |
resetHeaderTopMargin | none | 清除页眉上边距覆盖;回退到当前格式的默认值(格式顶部边距的 50%)。 |
setFooterBottomMargin | margin: number | 设置页脚下边距(像素)。拒绝负值和 NaN。 |
resetFooterBottomMargin | none | 清除页脚下边距覆盖;回退到当前格式的默认值(格式底部边距的 50%)。 |
setDifferentFirstPage | enabled: boolean | 切换不同的首页(页眉 + 页脚)。首页槽位保持为空,与 Word 一致。如果页眉/页脚覆盖层已打开,则会刷新以显示新变体。 |
setHeaderFirstPage | header: PagesHeaderFooter | 设置首页页眉内容 |
setFooterFirstPage | footer: PagesHeaderFooter | 设置首页页脚内容 |
setDifferentOddEven | enabled: boolean | 切换不同的奇偶页(页眉 + 页脚)。启用时,会将默认页眉/页脚复制到奇数页槽位(如果为空),以保持与 Word 的连续性。如果页眉/页脚覆盖层已打开,则会刷新以显示新变体。 |
setHeaderOdd | header: PagesHeaderFooter | 设置奇数页页眉内容 |
setHeaderEven | header: PagesHeaderFooter | 设置偶数页页眉内容 |
setFooterOdd | footer: PagesHeaderFooter | 设置奇数页页脚内容 |
setFooterEven | footer: PagesHeaderFooter | 设置偶数页页脚内容 |
setHeaderEditable | enabled: boolean | 锁定或解锁页眉覆盖层。为 false 时,双击无效,openHeaderEditor 返回 false,并关闭任何已打开的页眉覆盖层。 |
setFooterEditable | enabled: boolean | 锁定或解锁页脚覆盖层。为 false 时,双击无效,openFooterEditor 返回 false,并关闭任何已打开的页脚覆盖层。 |
openHeaderEditor | { pageNumber: number } | 打开指定页面的页眉编辑器(从 1 开始计数) |
openFooterEditor | { pageNumber: number } | 打开指定页面的页脚编辑器(从 1 开始计数) |
closeHeaderFooterEditors | none | 关闭当前打开的页眉/页脚编辑器 |
closeHeaderEditor | none | 如果页眉编辑器已打开则关闭它 |
closeFooterEditor | none | 如果页脚编辑器已打开则关闭它 |
setAccentColor | color: string | 设置两个编辑器覆盖层的强调色 |
setHeaderAccentColor | color: string | 设置页眉编辑器覆盖层的强调色 |
setFooterAccentColor | color: string | 设置页脚编辑器覆盖层的强调色 |