10分钟搞定HTML转PDF！零基础入门wkhtmltopdf开发指南
项目地址: https://gitcode.com/gh_mirrors/wk/wkhtmltopdf 你还在为HTML转PDF功能开发烦恼吗？尝试过多个工具却始终达不到理想效果？本文将带你零基础入门wkhtmltopdf，通过10分钟的实操教学，快速掌握HTML转PDF的核心技能，让你轻松应对各类文档转换需求。
读完本文你将学会：
- 快速安装和配置wkhtmltopdf环境
- 使用命令行工具将HTML文件转换为PDF
- 自定义PDF页面大小、边距和页眉页脚
- 处理图片、链接等复杂HTML元素
- 解决常见的转换问题和错误
什么是wkhtmltopdf？
wkhtmltopdf是一个命令行工具，它使用QT WebKit渲染引擎将HTML内容转换为PDF和各种图片格式。这些工具完全"无头"(Headless)运行，不需要显示器或显示服务。
官方定义：README.md
快速安装wkhtmltopdf
安装步骤
- 克隆项目仓库：
git clone https://gitcode.com/gh_mirrors/wk/wkhtmltopdf
- 进入项目目录：
cd wkhtmltopdf
- 根据你的操作系统，参考docs/downloads.md获取预编译版本或编译源代码
基础用法：HTML转PDF的Hello World
最简单的转换命令
将HTML文件转换为PDF的基本命令格式如下：
wkhtmltopdf <输入HTML文件> <输出PDF文件>
例如，将当前目录下的test.html转换为output.pdf：
wkhtmltopdf test.html output.pdf
转换网页为PDF
你还可以直接转换网络上的网页：
wkhtmltopdf https://example.com example.pdf
常用参数与自定义设置
页面大小和方向设置
wkhtmltopdf提供了丰富的页面设置选项，常见的包括：
# 设置页面大小为Letter（默认是A4）
wkhtmltopdf --page-size Letter input.html output.pdf
# 设置横向打印
wkhtmltopdf --orientation Landscape input.html output.pdf
# 自定义页面尺寸（宽度x高度，单位可以是mm、cm、in）
wkhtmltopdf --page-width 210mm --page-height 297mm input.html output.pdf
完整的页面大小选项可参考docs/usage/wkhtmltopdf.txt
边距设置
通过以下参数可以设置页面边距：
# 设置所有边距为10毫米
wkhtmltopdf -B 10mm -L 10mm -R 10mm -T 10mm input.html output.pdf
# 单独设置下边距为20毫米
wkhtmltopdf --margin-bottom 20mm input.html output.pdf
参数说明：docs/usage/wkhtmltopdf.txt
添加页眉和页脚
使用文本页眉页脚
# 添加简单的页眉页脚
wkhtmltopdf --header-center "我的文档标题" --footer-right "页码 [page]/[topage]" input.html output.pdf
使用HTML自定义页眉页脚
创建一个页眉HTML文件header.html：
<!DOCTYPE html>
<html>
<head><meta charset="UTF-8"></head>
<body>
<div style="text-align: center; font-size: 10px;">
文档页眉 - 第 [page] 页 / 共 [topage] 页
</div>
</body>
</html>
然后使用该HTML文件作为页眉：
wkhtmltopdf --header-html header.html input.html output.pdf
页眉页脚详细设置：docs/usage/wkhtmltopdf.txt
高级功能：目录生成
添加目录到PDF
wkhtmltopdf可以根据HTML中的标题标签（h1, h2, h3等）自动生成目录：
# 生成带目录的PDF
wkhtmltopdf toc input.html output.pdf
自定义目录样式
你可以通过XSLT来自定义目录的样式：
# 导出默认的目录XSLT样式
wkhtmltopdf --dump-default-toc-xsl > default-toc.xsl
# 编辑自定义XSLT后使用
wkhtmltopdf toc --xsl-style-sheet custom-toc.xsl input.html output.pdf
目录功能详细说明：docs/usage/wkhtmltopdf.txt
C API使用示例
对于开发人员，wkhtmltopdf提供了C语言API，可以集成到你的应用程序中。
PDF转换API示例：examples/pdf_c_api.c
图片转换API示例：examples/image_c_api.c
核心API定义在：src/lib/pdf.h 和 src/lib/image.h
常见问题解决
中文显示问题
如果PDF中的中文无法正常显示，请确保：
- HTML中指定了正确的字符编码：
<meta charset="UTF-8">
- 确保使用了支持中文的字体：
body { font-family: SimSun, "Microsoft YaHei", sans-serif; }
JavaScript执行问题
如果HTML中的JavaScript未正确执行，可以使用以下参数：
# 设置JavaScript执行延迟时间（毫秒）
wkhtmltopdf --javascript-delay 1000 input.html output.pdf
# 启用JavaScript调试
wkhtmltopdf --debug-javascript input.html output.pdf
更多JavaScript相关参数：docs/usage/wkhtmltopdf.txt
总结与进阶学习
通过本文的介绍，你已经掌握了wkhtmltopdf的基本用法和一些高级功能。要深入学习更多内容，可以参考以下资源：
- 官方文档：docs/docs.md
- 命令行参数完整列表：docs/usage/wkhtmltopdf.txt
- API开发文档：docs/libwkhtmltox/annotated.html
现在，你已经可以使用wkhtmltopdf轻松实现HTML到PDF的转换功能了。尝试使用不同的参数和选项，探索更多高级功能，让PDF转换工作变得更加高效和专业！
如果你有任何问题或建议，请参考docs/support.md获取支持信息。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
