khtmltopdf
下载
简介
wkhtmltopdf是一款基于 WebKit 引擎的 HTML 转 PDF 工具，支持丰富的命令行参数控制转换过程。以下是常用参数及作用分类说明，方便查阅和使用：
一、基本参数
| 参数 | 作用 | 示例 |
|---|---|---|
| input.html output.pdf | 基础语法：指定输入 HTML 文件（或 URL）和输出 PDF 路径 | 基础语法：指定输入 HTML 文件（或 URL）和输出 PDF 路径 |
| --version | 查看工具版本 | wkhtmltopdf --version |
| --help | 查看所有参数说明 | wkhtmltopdf --help |
二、页面尺寸与布局
| 参数 | 作用 | 示例 |
|---|---|---|
| --page-size | 设置页面尺寸（默认 A4 | --page-size Letter （可选：A3、A4、A5、Legal、Letter 等） |
| --width <宽度> | 自定义页面宽度（单位：mm/cm/in） | -width 210mm |
| --height <高度> | 自定义页面高度 | --height 297mm |
| --orientation <方向> | 设置页面方向（纵向 / 横向） | --orientation Landscape（Landscape 横向，Portrait 纵向默认） |
| --viewport-size <宽x高> | 模拟浏览器视口尺寸（解决响应式样式问题） | --viewport-size 1200x800（强制以 1200px 宽度渲染） |
| --zoom <比例> | 页面缩放比例（默认 1.0） | --zoom 0.9（缩小 10%） |
三、边距设置
| 参数 | 作用 | 示例 |
|---|---|---|
| -L/--margin-left <值> | 左 margin | -L 10mm或--margin-left 1cm |
| -R/--margin-right <值> | 右 margin | -R 0（取消右边距） |
| -T/--margin-top <值> | 上 margin | --margin-top 15mm |
| -B/--margin-bottom <值> | 下 margin | --margin-bottom 2cm |
四、样式与渲染控制
| 参数 | 作用 | 示例 |
|---|---|---|
| --print-media-type | 启用 CSS 中@media print样式 | --print-media-type（优先使用打印样式） |
| --no-print-media-type | 禁用打印样式（默认） | --no-print-media-type |
| --dpi <值> | 设置渲染 DPI（影响图片 / 字体清晰度） | --dpi 300（高清渲染） |
| --grayscale | 生成灰度 PDF（无彩色） | --grayscale |
| --lowquality | 降低质量以减小文件大小 | -lowquality |
| --background | 包含背景颜色和图片（默认开启） | --background |
| --no-background | 不包含背景（节省墨水） | --no-background |
五、JavaScript 与资源控制
| 参数 | 作用 | 示例 |
|---|---|---|
| --enable-javascript | 启用 JavaScript 执行（默认开启） | --enable-javascript |
| --disable-javascript | 禁用 JavaScript | --disable-javascript |
| --javascript-delay <毫秒> | 等待 JavaScript 执行的时间（解决动态内容渲染问题） | --javascript-delay 5000（等待 5 秒） |
| --no-stop-slow-scripts | 不中断缓慢的脚本（避免脚本未执行完就终止） | --no-stop-slow-scripts |
| --stop-slow-scripts | 中断缓慢的脚本（默认） | --stop-slow-scripts |
| --enable-local-file-access | 允许访问本地文件（如图片、CSS） | --enable-local-file-access（处理本地 HTML 时常用） |
| --disable-local-file-access | 禁止访问本地文件 | --disable-local-file-access |
| --load-error-handling <模式> | 处理资源加载错误（ignore/abort/skip） | --load-error-handling ignore（忽略错误继续转换） |
六、页眉页脚设置
| 参数 | 作用 | 示例 |
|---|---|---|
| --header-html <文件> | 自定义页眉（通过 HTML 文件） | --header-html header.html |
| --footer-html <文件> | 自定义页脚（通过 HTML 文件） | --footer-html footer.html |
| --header-center <文本> | 页眉居中文本 | --header-center "报告标题" |
| --header-left <文本> | 页眉左侧文本 | --header-left "日期：[date]" |
| --header-right <文本> | 页眉右侧文本（支持变量） | --header-right "第 [page] 页 / 共 [topage] 页" |
| --footer-center/left/right <文本> | 页脚文本（用法同页眉） | --footer-right "[time]"（显示当前时间） |
| --header-line | 页眉下方添加横线 | --header-line |
| --footer-line | 页脚上方添加横线 | --footer-line |
| --header-spacing <值> | 页眉与内容的间距（mm） | --header-spacing 5 |
| --footer-spacing <值> | 页脚与内容的间距 | --footer-spacing 5 |
- 页眉页脚变量：
[page]（当前页）、[topage]（总页数）、[date]（日期）、[time]（时间）、[title]（页面标题）等。
七、页面内容控制
| 参数 | 作用 | 示例 |
|---|---|---|
| --exclude-from-outline | 排除页面在 PDF 大纲中 | --exclude-from-outline |
| --include-in-outline | 包含页面在大纲中（默认） | --include-in-outline |
| --page-offset <值> | 页码偏移（调整起始页码） | --page-offset 2（从第 2 页开始计数） |
| --no-images | 不加载图片 | --no-images |
| --images | 加载图片（默认开启） | --images |
| --disable-smart-shrinking | 禁用智能缩放（避免内容被自动缩小） | --disable-smart-shrinking |
| --enable-smart-shrinking | 启用智能缩放（默认） | --enable-smart-shrinking |
八、输出控制
| 参数 | 作用 | 示例 |
|---|---|---|
| --quiet | 静默模式（不输出日志） | --quiet |
| --verbose | 详细日志模式 | --verbose |
| --title <标题> | 设置 PDF 文档标题 | --title "企业风险报告" |
| --outline | 生成 PDF 大纲（书签） | --outline |
| --no-outline | 不生成大纲 | --no-outline |
| --outline-depth <级别> | 大纲深度（1-10，默认 4） | --outline-depth 3 |
九、常用组合示例
转换带动态图表的页面（确保 Echarts/Chart.js 渲染完成）：
bash
wkhtmltopdf --enable-javascript --javascript-delay 8000 --print-media-type --viewport-size 1200x800 --enable-local-file-access input.html output.pdf自定义页眉页脚 + 无边缘：
bash
wkhtmltopdf -L 0 -R 0 -T 10mm -B 10mm --header-html header.html --footer-right "第 [page]/[topage] 页" input.html output.pdf高清横向 PDF：
bash
wkhtmltopdf --page-size A4 --orientation Landscape --dpi 300 input.html output.pdf