--- title: "页面" description: "将你的 Tiptap 编辑器转换为带有页眉、页脚、页面格式和缩放功能的分页文档式布局。" canonical_url: "https://tiptap.zhcndoc.com/pages/getting-started/overview" --- # 页面 将你的 Tiptap 编辑器转换为带有页眉、页脚、页面格式和缩放功能的分页文档式布局。 Tiptap Pages 是 Tiptap 的分页编辑层。它在任何 Tiptap 编辑器之上增加了页面边界、页面格式、页眉、页脚、分页符和缩放功能。有了它，你的读者可以像在文字处理器中一样撰写报告、信件、合同或书籍。 > **Interactive demo:** [ > \<> > \Try Tiptap Pages\，在这个交互式 DOCX 编辑器演示中体验分页、 > 页眉和页脚，以及 DOCX/PDF 导出。 > \ > ](https://template.tiptap.dev/docx) > **Pro 套餐:** > > Pages 是一个 Pro 套餐，包含在 [Tiptap 订阅](https://tiptap.dev/pricing) 中。安装前，请先配置好 [访问 Tiptap 的私有 NPM 仓库](https://tiptap.zhcndoc.com/guides/pro-extensions.md)。 ## 这项功能的作用 - **分页布局**：内容会在所选格式（A4、Letter、自定义）的可视页面之间流动。 - **页面格式和边距**：内置格式提供合理的默认值，自定义格式对象则让你完全掌控。 - **页眉和页脚**：可将其定义为静态文本、HTML 字符串或 Tiptap JSON。它们支持 `{page}` 和 `{total}` 占位符，并且你可以像 Word 一样，为首页或奇偶页分别设置独立的槽位。 - **脚注**：类似 Word 的脚注，会显示在每页页脚上方，自动编号，并在内容重排时跟随其引用位置。参见 [脚注](https://tiptap.zhcndoc.com/pages/core-concepts/footnotes.md)。 - **尾注**：类似 Word 的尾注，收集在文档末尾，使用小写罗马数字、自动编号，并支持就地编辑。参见 [尾注](https://tiptap.zhcndoc.com/pages/core-concepts/endnotes.md)。 - **就地编辑**：双击页眉、页脚、脚注或尾注区域，即可在覆盖层中打开功能完整的 Tiptap 编辑器。 - **缩放**：视觉缩放范围为 `[0.25, 4]`，不会影响文档内容或导出。 - **分页符**：可通过 [PageBreak 扩展](https://tiptap.zhcndoc.com/pages/core-concepts/page-break-node.md) 插入显式分页，或让 Pages 自动处理分页。 ## 随之安装的内容 Pages **不** 自带节点和标记（mark）模式。要使用它，你还需要安装： - **`@tiptap-pro/extension-convert-kit`**：用于 Conversion 和 Pages 工作流的标准编辑器套件。ConvertKit 注册了一个支持 DOCX 的 schema（段落、标题、列表、图片、标记）。 - **`@tiptap-pro/extension-pages-tablekit`**：支持分页安全的表格。必须安装，因为 ConvertKit 内置的表格并不是为分页而设计的。 ```bash npm install @tiptap-pro/extension-convert-kit \ @tiptap-pro/extension-pages-tablekit \ @tiptap-pro/extension-pages ``` ```ts 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', header: '我的文档', footer: '第 {page} 页，共 {total} 页', }), ], }) ``` 完整步骤请参阅 [安装指南](https://tiptap.zhcndoc.com/pages/getting-started/install.md)。 ## 可用内容 - 内置页面格式：A4、A3、A5、Letter、Legal、Tabloid。你也可以定义具有任意尺寸和边距的自定义格式。 - 页眉和页脚内容可以是纯文本、HTML 或 Tiptap JSON，并支持 `{page}` / `{total}` 占位符。 - 首页面以及奇数/偶数页可使用不同的页眉和页脚，类似 Word。 - 类 Word 的 [脚注](https://tiptap.zhcndoc.com/pages/core-concepts/footnotes.md)：每页脚注区域，带自动连续编号，会随其引用重新排版并占用页面空间。 - 类 Word 的 [尾注](https://tiptap.zhcndoc.com/pages/core-concepts/endnotes.md)：文档末尾的单一列表，使用小写罗马数字和自动编号，跨页面流动，并保留完整页面外壳。 - 在专用覆盖层中实时编辑页眉、页脚、脚注和尾注。它们会与主文档一起参与协作。参见 [为 Pages 添加协作](https://tiptap.zhcndoc.com/pages/guides/collaboration-with-pages.md)。 - 程序化控制：打开或关闭页眉/页脚/脚注/尾注编辑器，对页面格式变化作出响应，对缩放变化作出响应。 - 可在配置时或运行时通过 `editableHeader` / `editableFooter` / `footnotes.editable` / `endnotes.editable` 选项以及 `setHeaderEditable` / `setFooterEditable` / `setFootnotesEditable` / `setEndnotesEditable` 命令来锁定或解锁每个覆盖层的编辑。 - 通过 [PagesTableKit](https://tiptap.zhcndoc.com/pages/guides/pages-tablekit.md) 实现分页安全的表格。表格会按比例缩小以适应页面，固定高度的行会被裁剪，声明的宽度会被保留。 - 与 Tiptap Conversion 往返兼容：导入的 DOCX 页眉、页脚、脚注和尾注会自动应用，而导出的 DOCX、PDF、ODT 和 EPUB 文件会保留页眉、页脚和分页信息。DOCX 导出会写入真正的 Word 脚注和尾注。 ## 不可用的内容 这些是真实且已记录的限制，不是 bug。如果你的工作流依赖其中任何一项，请将该约束视为设计边界。 - **大于一页且不可拆分的块会导致无限布局循环。** 这是在采用 Pages 之前最重要的一项限制。表格行、图形、定位容器以及大多数其他块格式化上下文（BFC）元素都不能跨页拆分。布局只能把整个块移到下一页。如果该块本身就比页面还高，它也无法放下，布局就会不断尝试将其继续前移，始终无法稳定。结果就是编辑器无响应。这是当前在页面之间拆分内容的方法所固有的硬限制，不是近期路线图中的功能项。完整说明（包括如何检测和预防）请参见 [限制](https://tiptap.zhcndoc.com/pages/core-concepts/limitations.md#oversized-non-splittable-blocks-cause-an-infinite-layout-loop)。表格相关的具体情况见 [PagesTableKit 的已知问题](https://tiptap.zhcndoc.com/pages/guides/pages-tablekit.md#known-issues)。 - **没有按页样式，也没有页面模板。** 每一页都使用相同的布局和视觉样式。 - **没有浏览器打印集成。** 如需可直接打印的输出，请使用 [Conversion 扩展和 REST 端点](https://tiptap.zhcndoc.com/conversion/getting-started/overview.md)。 ## Expectations - **Beta stage.** Pages is still under active development. If you depend on it, pin the exact package version, because minor versions may introduce breaking changes. - **Pixel values are CSS pixels.** All sizes in the API correspond to standard browser CSS pixels (1 inch = 96 px). The `cmToPixels` and `inchToPixels` utilities can round-trip without loss, so you can create using real-world units. - **What you see is what you edit in collaboration.** Double-clicking the header or footer opens the full Tiptap editor, and that editor is in the same collaborative session as the main document. ## 不要期待的内容 - **Pages 本身并不是一个完整的编辑器。** 它只是一个布局覆盖层。请将其与用于文档 schema 的 `ConvertKit` 以及来自 `extension-pages-tablekit` 的 `TableKit` 搭配使用。 - **Pages 本身不实现 DOCX 的导入或导出。** 它是一个渲染目标。若要与文件往返配合使用，请搭配 [Conversion](https://tiptap.zhcndoc.com/conversion/getting-started/overview.md) 扩展：通过 `extension-import-docx` 导入，通过 `extension-export-docx`、`extension-export-pdf` 等导出。 - **Pages 不负责分页内容的表格渲染。** 请使用 [PagesTableKit](https://tiptap.zhcndoc.com/pages/guides/pages-tablekit.md)，不要使用开源的 `@tiptap/extension-table` 或 ConvertKit 内置表格。 ## 与 Conversion 搭配使用 这两个产品就是为了协同工作而构建的： - [Conversion 概览](https://tiptap.zhcndoc.com/conversion/getting-started/overview.md)：导入/导出流水线。 - [导入 DOCX](https://tiptap.zhcndoc.com/conversion/import/docx/editor-extension.md)：将 Word 文档带入你的分页编辑器（页眉和页脚会自动应用）。 - [导出 DOCX](https://tiptap.zhcndoc.com/conversion/export/docx/editor-extension.md)：导出保留页眉和页脚的分页内容。 - [导出 PDF](https://tiptap.zhcndoc.com/conversion/export/pdf/editor-extension.md)：将分页布局渲染为 PDF。 - [从零到可打印输出](https://tiptap.zhcndoc.com/pages/guides/zero-to-print-ready.md)：完整的端到端演示。 ## 相关内容 - [安装](https://tiptap.zhcndoc.com/pages/getting-started/install.md) - [API 参考](https://tiptap.zhcndoc.com/pages/core-concepts/options.md) - [页面格式](https://tiptap.zhcndoc.com/pages/core-concepts/page-format.md) · [页眉和页脚](https://tiptap.zhcndoc.com/pages/core-concepts/page-header-footer.md) · [页面间距](https://tiptap.zhcndoc.com/pages/core-concepts/page-gap.md) · [缩放](https://tiptap.zhcndoc.com/pages/core-concepts/zoom.md) - [PagesTableKit](https://tiptap.zhcndoc.com/pages/guides/pages-tablekit.md) · [PageKit](https://tiptap.zhcndoc.com/pages/guides/pagekit-usage.md) - [限制](https://tiptap.zhcndoc.com/pages/core-concepts/limitations.md)