本文详细介绍了如何使用 Paged.js 结合 JavaScript 动态生成 HTML 文档的目录（Table of Contents），并自动填充页码。通过定制 Paged.js 的处理器，在内容解析前构建目录结构，然后利用 CSS target-counter 功能实现页码的自动显示，解决了在打印布局中获取元素页码的挑战。
引言：动态目录与 Paged.js 的挑战
在将 HTML 内容转换为可打印的文档时，生成一个带有准确页码的动态目录是一个常见需求。传统的做法是手动更新页码，但这在内容变动时效率低下且易出错。使用像 Paged.js 这样的工具可以自动化这一过程，但直接通过 JavaScript 或 jQuery 访问 DOM 元素来获取其在最终打印布局中的页码并非易事，因为页码是 Paged.js 渲染引擎在布局阶段计算出来的。
本文将深入探讨如何利用 Paged.js 的强大功能，通过其生命周期钩子和 JavaScript 编程，实现一个完全动态且带有页码的目录生成方案。
核心机制：利用 Paged.js 的生命周期钩子
Paged.js 提供了一套生命周期钩子，允许开发者在文档处理的不同阶段介入。对于动态目录生成，最合适的钩子是 beforeParsed。在这个阶段，Paged.js 已经加载了 HTML 内容，但尚未进行布局和分页处理。这意味着我们可以在此时遍历文档中的标题元素，构建目录结构，并为它们添加必要的属性，为后续的页码显示做准备。
Paged.Handler 是 Paged.js 中用于扩展其功能的基类。通过创建一个继承自 Paged.Handler 的自定义类，并重写 beforeParsed 方法，我们可以在 Paged.js 开始解析内容之前执行自定义逻辑。
构建目录结构：JavaScript 实现
动态目录的构建主要通过一个 JavaScript 函数完成，该函数负责识别文档中的标题，为它们生成唯一的标识符（如果不存在），并构建一个链接到这些标题的目录列表。
HTML 基础结构
首先，我们需要在 HTML 文档中定义标题元素和目录的占位符。标题应具有清晰的结构，例如使用 <h1>, <h2> 等。目录占位符通常是一个空的 <ul> 或 <div>，它将通过 JavaScript 填充。
<!-- 文档中的标题 --> <h1 id="pre-digital_era" class="chapter-title" data-title-level="1"> 前数字时代 </h1> <p>此处是章节内容...</p> <h2 id="digital_era" class="chapter-title" data-title-level="2"> 数字时代 </h2> <p>此处是章节内容...</p> <!-- 目录占位符 --> <div id="my-toc-content"> <!-- 动态生成的目录将插入到这里 --> </div>
请注意，为标题添加 id 属性至关重要，因为目录中的链接（<a> 标签的 href 属性）将指向这些 ID。如果标题没有 ID，我们的 JavaScript 函数会为其自动生成。
createToc 函数详解
createToc 函数是实现动态目录的核心。它接收一个配置对象，包含内容的根元素、目录占位符的选择器以及标题元素的选择器数组。
function createToc(config) {
const content = config.content; // 文档内容根元素
const tocElementSelector = config.tocElement; // 目录占位符选择器
const titleElementsSelectors = config.titleElements; // 标题元素选择器数组
// 获取目录占位符元素，并创建一个无序列表作为目录容器
let tocElementDiv = content.querySelector(tocElementSelector);
let tocUl = document.createElement("ul");
tocUl.id = "list-toc-generated";
tocElementDiv.appendChild(tocUl);
// 遍历所有指定标题元素，确保它们有ID并添加辅助类
let tocElementNbr = 0;
for (let i = 0; i < titleElementsSelectors.length; i++) {
let titleHierarchy = i + 1; // 根据选择器数组的顺序确定层级
let titleElements = content.querySelectorAll(titleElementsSelectors[i]);
titleElements.forEach(function (element) {
// 添加通用类和层级数据属性
element.classList.add("title-element");
element.setAttribute("data-title-level", titleHierarchy);
// 如果元素没有ID，则生成一个唯一ID
tocElementNbr++;
if (element.id === "") {
element.id = "title-element-" + tocElementNbr;
}
});
}
// 根据已处理的标题元素创建目录列表项
let processedTocElements = content.querySelectorAll(".title-element");
for (let i = 0; i < processedTocElements.length; i++) {
let tocElement = processedTocElements[i];
let tocNewLi = document.createElement("li");
// 为目录列表项添加层级类
tocNewLi.classList.add("toc-element");
tocNewLi.classList.add(
"toc-element-level-" + tocElement.dataset.titleLevel
);
// 复制标题元素的其他类到目录列表项（可选）
let classTocElement = tocElement.classList;
for (let n = 0; n < classTocElement.length; n++) {
if (classTocElement[n] !== "title-element") {
tocNewLi.classList.add(classTocElement[n]);
}
}
// 创建链接，href指向标题ID，文本内容为标题内容
tocNewLi.innerHTML =
'<a href="#' + tocElement.id + '">' + tocElement.innerHTML + "</a>";
tocUl.appendChild(tocNewLi);
}
}函数参数说明：
- config.content: Paged.js 传递的文档内容根元素，通常是 <body> 或其子元素。
- config.tocElement: 目录占位符的 CSS 选择器，例如 "#my-toc-content"。
- config.titleElements: 一个字符串数组，每个字符串是一个 CSS 选择器，用于匹配不同层级的标题元素，例如 ["h1", "h2", "h3"]。
工作流程：
- 初始化目录容器： 查找目录占位符，并在其中创建一个新的 <ul> 元素。
-
处理标题元素： 遍历 titleElementsSelectors 数组中的每个选择器。
- 对于每个匹配的标题元素，为其添加 title-element 类和 data-title-level 属性，后者指示其在目录中的层级。
- 如果标题元素没有 id 属性，则为其生成一个唯一的 ID。这是确保目录链接可用的关键。
-
生成目录列表： 再次遍历所有带有 title-element 类的标题元素。
- 为每个标题创建一个 <li> 元素。
- 根据标题的 data-title-level 属性为 <li> 添加层级类（例如 toc-element-level-1），便于 CSS 样式控制。
- 创建一个 <a> 标签，其 href 属性设置为标题的 ID，其文本内容为标题的 HTML 内容。
- 将 <li> 元素添加到目录 <ul> 中。
集成到 Paged.js 工作流
createToc 函数本身只是一个独立的 JavaScript 函数。为了让它在 Paged.js 处理文档时自动运行，我们需要将其封装在一个 Paged.Handler 中，并在 beforeParsed 钩子中调用它。
将以下代码添加到 HTML 文档的 <head> 部分，紧随 Paged.js 脚本之后：
<script type="text/javascript" src="path/to/paged.polyfill.js"></script>
<script>
// ... createToc 函数定义 ...
class CustomTocHandler extends Paged.Handler {
constructor(chunker, polisher, caller) {
super(chunker, polisher, caller);
}
// 在 Paged.js 解析内容之前执行
beforeParsed(content) {
createToc({
content: content, // Paged.js 提供的文档内容根元素
tocElement: "#my-toc-content", // 目录占位符的选择器
titleElements: ["h1", "h2"], // 匹配 h1 和 h2 作为目录项
});
}
}
// 注册自定义处理器
Paged.registerHandlers(CustomTocHandler);
</script>在这个示例中，CustomTocHandler 是我们自定义的 Paged.js 处理器。在 beforeParsed 方法中，我们调用 createToc 函数，并传入 Paged.js 提供的 content 对象（代表了待处理的整个文档内容），以及目录占位符和标题选择器。
显示页码：CSS 与 target-counter
上述 JavaScript 代码完成了目录结构的构建，将标题链接到其对应的位置。然而，它并没有直接在目录中插入页码。页码的显示是 Paged.js 结合 CSS target-counter 功能来实现的。
target-counter() 是一个 CSS 函数，它允许你获取文档中某个元素在特定命名计数器（如 page 计数器）上的值。当与目录链接的 href 属性结合使用时，它就能显示链接目标元素的页码。
通常，你会在 CSS 中这样定义页码的显示：
@page {
/* 定义页码计数器 */
counter-increment: page;
@bottom-right {
content: counter(page); /* 在页面底部显示当前页码 */
}
}
/* 为目录列表项添加页码 */
.toc-element a::after {
content: target-counter(attr(href), page); /* 显示链接目标元素的页码 */
float: right; /* 将页码浮动到右侧 */
margin-left: 1em; /* 与标题文字保持距离 */
}通过这种 CSS 规则，当 Paged.js 渲染文档时，它会自动计算每个标题的页码，并通过 target-counter(attr(href), page) 将其注入到目录 <a> 标签的 ::after 伪元素中。
注意事项与最佳实践
- HTML 结构清晰： 确保你的 HTML 标题结构（<h1>, <h2> 等）是语义化的，这有助于 createToc 函数准确识别目录项。
- ID 的唯一性： 尽管 createToc 会为没有 ID 的标题生成 ID，但最好在编写 HTML 时就为关键标题提供有意义且唯一的 ID，以提高可读性和维护性。
- CSS 选择器的准确性： 在 createToc 的 titleElements 配置中，使用精确的 CSS 选择器来匹配你希望包含在目录中的标题。
- Paged.js 依赖： 确保 Paged.js 库已正确加载到你的 HTML 文档中。
- 调试： 在开发过程中，可以使用浏览器的开发者工具检查生成的目录结构和 Paged.js 的控制台输出，以便调试任何问题。
- 样式定制： 利用 toc-element 和 toc-element-level-N 等类，你可以通过 CSS 对生成的目录进行精细的样式控制，例如缩进、字体大小等。
总结
通过 Paged.js 的 beforeParsed 钩子和自定义 JavaScript 函数，我们可以高效地动态生成 HTML 文档的目录。JavaScript 负责构建目录的结构和链接，而 Paged.js 结合 CSS target-counter 则负责在打印布局中自动填充正确的页码。这种方法不仅解决了手动更新页码的痛点，也使得内容更新和布局调整变得更加灵活和自动化，极大地提升了可打印文档的生成效率和用户体验。
