WeasyPrint中counter-reset导致页码重复问题的解决方案

在使用WeasyPrint进行PDF生成时，开发者可能会遇到一个常见的页码计数问题：当尝试通过CSS的counter-reset属性重置页码时，发现所有页面都显示相同的页码值。这种情况通常发生在需要合并多个HTML文档为一个PDF文件时。

问题现象

当开发者使用以下CSS规则时：

@page {
  counter-reset: page 8;
}

预期效果是让页码从8开始递增，但实际结果却是所有页面都固定显示为8。这与开发者的预期不符，特别是需要将多个文档合并为一个连续页码的PDF时。

问题原因

这个现象的原因是CSS规范中counter-reset的工作机制。上述写法会将所有页面的计数器都重置为指定值，而不是仅对第一页生效。因此，每个页面在渲染时都会将页码重置为8，导致所有页面显示相同页码。

解决方案

正确的做法是使用:first伪类选择器，将计数器重置仅应用于文档的第一页：

@page :first {
  counter-reset: page 8;
}

这样修改后，计数器会在第一页被重置为8，后续页面则会正常递增，实现连续的页码显示。

深入理解

1. 计数器工作原理：CSS计数器是通过counter-reset初始化，counter-increment递增的。在分页媒体中，这些操作可以应用于整个文档或特定页面。

2. :first伪类：这是CSS专门为分页媒体设计的伪类，用于匹配文档的第一页。与之类似的还有:right和:left伪类，用于区分左右页。

3. WeasyPrint的特殊性：作为HTML/CSS转PDF的工具，WeasyPrint严格遵循CSS规范中对分页媒体的定义。理解这些规范细节对于解决类似问题很有帮助。

最佳实践

当需要合并多个HTML文档为一个PDF并保持连续页码时，建议：

1. 对第一个文档使用:first伪类设置初始页码
2. 后续文档不需要特殊处理，页码会自动延续
3. 可以使用WeasyPrint的文档合并API来简化流程

通过正确理解CSS计数器和分页媒体的工作机制，可以避免这类问题，实现预期的页码显示效果。