社区构建的 Tiptap 分页组件

一个社区构建的 Tiptap 分页扩展，提供类似文字处理器的所见即所得页面布局，并支持法律文档格式。

兼容性

• 需要 Tiptap v3.x (@tiptap/core, @tiptap/pm, @tiptap/react)
• 在此仓库中已测试 Tiptap v3.13.x
• 演示中使用了 React 19，但该库作为普通包发布，React 作为对等依赖。

功能特性

• 📄 多种页面格式: 支持 A4、US Letter 和 US Legal 纸张尺寸
• 🔄 纵向和横向: 动态切换方向
• ✂️ 硬分页: 使用 Ctrl+Enter / Cmd+Enter 手动分页
• 🖨️ 打印支持: 正确的 CSS 打印到 PDF 并保持正确的分页
• 📐 孤行控制: 防止单行出现在页面边界处
• ⚡ SSR 安全: 与 Next.js 和其他 SSR 框架兼容
• 🔍 脱敏兼容: 扁平文档结构保留文本流

安装

npm i fz-tiptap-community-pages

CSS (必需)

在您的应用程序中导入一次（例如 Next.js 的 layout.tsx 或应用入口）。这提供了默认的 PageWrapper 布局（包括移动端自适应宽度缩放）和硬分页标记样式：

import "fz-tiptap-community-pages/styles.css";

本地演示安装

npm install

开发

npm run dev

打开 http://localhost:3000 查看演示。

质量检查

npm run lint
npm run type-check
npm test
npm run build

使用方法

基本设置

import { useEditor } from '@tiptap/react'
import { EditorContent } from '@tiptap/react'
import StarterKit from '@tiptap/starter-kit'
import { PageBreak, Pagination } from 'fz-tiptap-community-pages'
import { PageWrapper } from 'fz-tiptap-community-pages/react'

const editor = useEditor({
  extensions: [
    StarterKit,
    PageBreak,
    Pagination.configure({
      pageFormat: 'Letter', // 'A4', 'Letter', 或 'Legal'
      orientation: 'portrait', // 'portrait' 或 'landscape'
      margins: {
        top: 96,    // 1 英寸像素值
        right: 96,
        bottom: 96,
        left: 96,
      },
      onPageCountChange: (count) => console.log(`${count} pages`),
    }),
  ],
  content: '<p>您的内容在这里...</p>',
})

// 包装您的编辑器
<PageWrapper format="Letter" orientation="portrait">
  <EditorContent editor={editor} />
</PageWrapper>

命令

// 动态更改页面格式
editor.commands.setPageFormat("Legal");

// 更改方向
editor.commands.setOrientation("landscape");

// 插入硬分页
editor.commands.setPageBreak();

// 导航到特定页面
editor.commands.goToPage(2);

硬分页渲染为具有稳定标记的块元素，用于导出/导入：

• data-page-break="true"
• .page-break 类（始终包含）

页面格式尺寸

| 格式 | 宽度 | 高度 | 常用场景 | | --------- | ----- | ------ | ---------------------------- | | US Letter | 816px | 1056px | 标准美国文档 | | US Legal | 816px | 1344px | 法律合同、法庭文件 | | A4 | 794px | 1123px | 国际标准 |

所有尺寸均基于 96 DPI（标准屏幕分辨率）

架构

此扩展使用 "连续流"模型:

1. 单文档: 内容保持为单个平面的 ProseMirror 文档
2. 视觉分页: 分页使用 CSS 和 DOM 覆盖渲染
3. 无节点拆分: 文本可以在页面边界之间流动而不破坏文档结构

这种方法确保了：

• 易于数据存储（单个 HTML/JSON 文档）
• 脱敏算法可以找到跨页的文本
• 搜索在文档中无缝工作
• 复制/粘贴保持内容完整性

项目结构

src/
├── extensions/
│   ├── page-format.ts    # 页面尺寸工具
│   ├── page-break.ts     # 硬分页节点
│   ├── pagination.ts     # 主分页扩展
│   └── index.ts          # 扩展导出
├── components/
│   ├── PageWrapper.tsx   # 页面样式包装器
│   ├── PagedEditor.tsx   # 完整编辑器组件
│   ├── Toolbar.tsx       # 格式/方向控件
│   └── index.ts          # 组件导出
└── app/
    ├── page.tsx          # 演示页面
    ├── layout.tsx        # 应用布局
    └── globals.css       # 全局样式 + 打印 CSS

打印支持

扩展包含全面的打印 CSS，其中：

• 隐藏视觉分页指示器
• 强制浏览器分页
• 支持孤行控制
• 按格式设置正确的页面大小

@media print {
  .page-break {
    page-break-after: always;
    break-after: page;
  }
}

键盘快捷键

| 快捷键 | 操作 | | -------------------------- | ----------------- | | Ctrl+Enter / Cmd+Enter | 插入分页符 |

浏览器支持

• Chrome 60+
• Firefox 60+
• Safari 12+
• Edge 79+

许可证

MIT 许可证 - 详情请参见 LICENSE 文件。