WeasyPrint图像宽度控制问题解析与解决方案

问题现象

在使用Python的WeasyPrint库将HTML转换为PDF时，开发者遇到了一个常见问题：HTML中的<img>标签设置的width属性在PDF输出中没有生效，图像总是占据页面100%的宽度，而在浏览器中查看HTML时却能正常显示设置的宽度。

问题分析

这个问题涉及WeasyPrint对HTML属性的处理机制。WeasyPrint默认情况下不会自动处理HTML元素上的表现性属性（presentational hints），包括width、height等属性。这与现代浏览器的行为不同，浏览器通常会解析这些属性并应用到元素样式上。

解决方案

WeasyPrint提供了专门的参数来处理这类表现性属性：

1. 命令行方式：使用--presentational-hints参数
2. Python API方式：在调用write_pdf()方法时设置presentational_hints=True参数

HTML(string=html_content).write_pdf(
    target=filename,
    presentational_hints=True  # 启用表现性属性处理
)

最佳实践建议

虽然可以使用HTML属性控制图像尺寸，但在WeasyPrint项目中更推荐使用CSS样式来控制元素表现：

1. 内联样式：

<img src="..." style="width: 300px;" />

2. 外部/内部样式表：

img.logo {
    width: 300px;
}

使用CSS方式不仅更符合现代Web开发规范，还能提供更精确的控制和更好的维护性。

扩展知识

WeasyPrint的这种设计是有意为之的，它遵循了HTML和CSS分离的原则。表现性属性属于早期的HTML规范，而现代Web开发更强调使用CSS来控制表现。这种设计使得WeasyPrint能够更专注于文档的语义结构，同时通过明确的参数让开发者选择是否需要兼容旧式HTML属性。

对于需要复杂页面布局的情况（如固定页眉页脚），建议参考WeasyPrint的示例文档，使用CSS的@page规则和定位属性来实现专业级的PDF输出效果。