WeasyPrint 中实现动态页码和目录引导线的技巧

动态页码的实现原理

在 WeasyPrint 中实现动态页码功能主要依赖于 CSS 的 target-counter 属性和伪元素选择器。这种技术可以让文档自动生成准确的页码引用，特别适用于长文档的目录制作。

核心代码结构

要实现动态页码，需要以下 HTML 结构和 CSS 样式：

<table>
  <tr>
    <td>
      <a href="#section1">Section Title</a>
    </td>
    <td class="page-number">
      <a href="#section1"></a>
    </td>
  </tr>
</table>

<div id="section1">...</div>

对应的 CSS 样式应为：

.page-number a::before {
  content: target-counter(attr(href), page);
}

版本兼容性注意事项

需要注意的是，不同版本的 WeasyPrint 对 CSS 语法的支持程度不同：

1. 在较新版本中支持嵌套 CSS 语法
2. 旧版本（如通过 apt 安装的 57.2 版本）需要使用传统的 CSS 写法
3. 推荐使用 pipx 安装最新版本以获得完整功能支持

目录引导线的实现方法

在专业文档排版中，目录通常会在标题和页码之间添加引导线（通常是点线）。WeasyPrint 可以通过 CSS 的 leader() 函数实现这一效果。

引导线实现代码

.toc-entry {
  display: flex;
  justify-content: space-between;
}

.toc-entry::after {
  content: leader(dotted) target-counter(attr(href), page);
}

完整目录样式示例

<style>
  .toc {
    width: 100%;
  }
  .toc-entry {
    display: flex;
    justify-content: space-between;
  }
  .toc-entry::after {
    content: leader(dotted) target-counter(attr(href), page);
    float: right;
  }
</style>

<div class="toc">
  <div class="toc-entry">
    <a href="#section1">第一章 介绍</a>
  </div>
  <div class="toc-entry">
    <a href="#section2">第二章 技术细节</a>
  </div>
</div>

实际应用中的最佳实践

1. 版本选择：始终使用最新版本的 WeasyPrint 以获得最佳兼容性
2. 样式测试：在复杂文档中，建议先在小范围测试页码和引导线效果
3. 性能考虑：对于超长文档，动态页码计算可能会增加处理时间
4. 跨页处理：确保目录条目不会在不恰当的位置被分页打断

通过合理运用这些技术，可以创建出专业级别的文档目录和页码系统，大大提升 PDF 文档的可读性和专业性。