WeasyPrint 中动态生成带页码的目录实现方法

前言

在使用WeasyPrint生成PDF报告时，自动生成带有正确页码的目录是一个常见需求。本文将详细介绍如何利用WeasyPrint的CSS功能实现这一目标。

基本原理

WeasyPrint通过CSS扩展提供了几个关键功能来实现动态页码：

1. target-counter()：获取目标元素的页码
2. target-text()：获取目标元素的文本内容
3. leader()：生成引导线（如点线）

实现步骤

1. HTML结构设计

首先需要设计合理的HTML结构，包含目录项和对应的内容锚点：

<!-- 目录部分 -->
<table>
  <tr>
    <td><a href="#section1">第一部分</a></td>
    <td class="page-number"><a href="#section1"></a></td>
  </tr>
  <tr>
    <td><a href="#section2">第二部分</a></td>
    <td class="page-number"><a href="#section2"></a></td>
  </tr>
</table>

<!-- 内容部分 -->
<div id="section1">第一部分内容...</div>
<div id="section2">第二部分内容...</div>

2. CSS样式设置

关键CSS样式如下：

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

如果需要更完整的目录样式（带标题和引导线）：

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

3. 注意事项

1. 锚点匹配：确保目录中的href属性值与内容部分的id完全一致
2. CSS选择器：正确选择到包含页码的a标签
3. 分页控制：可以使用break-before: always等属性控制内容分页

常见问题解决方案

1. 页码不显示：

   • 检查CSS选择器是否正确匹配到目标元素
   • 确认href属性值是否正确指向内容锚点
   • 确保内容部分有足够的长度导致分页

2. 样式不生效：

   • 检查CSS规则的优先级
   • 确认没有其他样式覆盖

3. 引导线不显示：

   • 确保leader()函数语法正确
   • 检查内容部分是否有足够的空间显示完整内容

高级应用

对于更复杂的目录需求，可以考虑：

1. 多级目录：通过嵌套列表实现
2. 自定义页码格式：使用@page规则中的counter-style
3. 目录样式美化：添加边框、背景色等装饰

总结

WeasyPrint通过CSS扩展提供了强大的动态页码生成能力，合理利用这些功能可以轻松实现专业级的PDF目录。关键在于正确理解HTML结构与CSS选择器的匹配关系，以及WeasyPrint特有的CSS函数用法。

通过本文介绍的方法，开发者可以灵活地定制各种风格的PDF目录，满足不同场景下的报告生成需求。