Paged.js

Paged.js 的分页预览、CSS 转换与 PDF 输出边界，以及 0.4.3 的 DOM 处理机制。

#javascript #resource #growing #frontend

[!info] related notes

原生打印 CSS · Vue 打印入口

历史表格分页错位记录

[private note]

Paged.js

Paged.js 将 HTML 内容排成浏览器中的分页视图，并转换部分 CSS Paged Media / Generated Content 规则。它支持书籍、报告等 Web 排版；支持范围应以项目文档和目标版本为准，不是完整实现所有 W3C 分页特性的保证。

分页预览与生成 PDF 是不同步骤：浏览器可将预览打印为 PDF，pagedjs-cli 则通过无头浏览器执行输出。Paged.js 本身的 Previewer.preview() 返回分页结果，不直接返回 PDF 字节，也不是 EPUB 导出器。

两种接入方式

自动 polyfill

以下固定到本次核对的 0.4.3，以免示例随 CDN latest 改变：

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="utf-8">
  <title>Paged.js 示例</title>
  <style>
    @page {
      size: A5;
      margin: 20mm;
      @top-center { content: "我的文档"; }
    }
    .chapter-start { break-before: page; }
  </style>
  <script src="https://unpkg.com/pagedjs@0.4.3/dist/paged.polyfill.js"></script>
</head>
<body>
  <h1>第一章</h1>
  <p>第一页的内容。</p>
  <h1 class="chapter-start">第二章</h1>
  <p>从新页开始的内容。</p>
</body>
</html>

polyfill 默认在 DOM ready 后启动，不应把这理解为所有异步数据、图片和字体都已就绪。需手动控制时，在加载脚本前设置 window.PagedConfig = { auto: false }，准备好内容后再等待 window.PagedPolyfill.preview() 完成。

npm 模块与独立输出容器

npm install pagedjs

下面代码用于浏览器侧模块；页面先准备 #print-source 和 #print-output 两个独立元素，并提供实际的 /print.css：

import { Previewer } from 'pagedjs'

const source = document.querySelector('#print-source')
const output = document.querySelector('#print-output')
if (!source || !output) throw new Error('缺少打印源或输出容器')

await document.fonts.ready
const flow = await new Previewer().preview(source.innerHTML, ['/print.css'], output)
console.log(`总页数: ${flow.total}`)

应用还需等待数据与图片、处理分页失败，并在重新生成前清理上次输出。不要把旧分页结果再次当成输入。原内容是否隐藏或显示由应用决定，不能把源 DOM 和分页 DOM 同时打印成重复内容。

分页 DOM 的边界

核对 0.4.3 源码可见：

输出容器是普通 DOM 中的 .pagedjs_pages，不是 Shadow DOM 隔离根。
默认无参数的 preview() 会把 body 内容转入 template[data-ref="pagedjs-content"]，再生成分页结果；不能假设原页面仍保持原有可交互 DOM。
包括第一页在内的页面都经过布局和节点克隆流程；不能以页码判断哪一页是“未经处理的原 DOM”。

因此 Vue/React 中通常应将待打印内容与交互应用隔离。数据更新、事件绑定、表格跨页结构和全局 CSS 都需要实测，不应假定分页 DOM 保持框架组件身份。

页眉、页码与扩展

@page margin boxes 可配合 content、页码计数器和 string-set 等规则组织运行页眉。Handler / registerHandlers 可扩展处理流程，例如检查 afterPageLayout 阶段的结果。不同版本、复杂表格和跨页内容仍可能需要专门处理。

原生打印也有 @page、分页控制和表头重复等能力，支持程度依浏览器而异。不要把它描述成“完全不能分页”，也不要把 Paged.js 描述成“提供全部高级功能”。

PDF 输出与验收

安装独立 CLI 后可使用：

pagedjs-cli index.html -o result.pdf

需要可复现输出时固定库、浏览器、字体与资源版本。验证页数、分页处、长表格、空单元格、签名区和末页；浏览器中的缩放预览不等于最终纸张输出。打印设置中的页眉页脚、背景和边距也应与文档设计一致。

后续学习方向：自定义 Handler，以及与 Eleventy / Jekyll 等静态站点生成器配合的出版流程。

来源

2026-10-06 核对 npm 发布的 pagedjs@0.4.3 README 与实现：