遥遥领先

wkhtmltopdf

https://blog.csdn.net/shijue98/article/details/119864987open in new window

wkhtmltopdf 0.12.6 中文文档

# 可以看到页码
wkhtmltopdf --header-right "[page]/[topage]"   --page-size A4  container_a4.html  container_a4.pdf
# 看不到页码
wkhtmltopdf --header-right 'Page: [page] / [topage]' --page-size A4 --margin-bottom 0 --margin-left 0 --margin-right 0 --margin-top 0   container_a4.html container_a4.pdf

wkhtmltopdf 0.12.6 中文文档 说明 **示例的测试代码均在 Windows10 的 Linux 子系统 中进行； 原文档地址：https://wkhtmltopdf.org/usage/wkhtmltopdf.txt 版本名称： wkhtmltopdf 0.12.6 (with patched qt) **

概述 wkhtmltopdf patched qt 是将一个或多个 HTML 页面合并为一个 PDF 文档的应用程序。

基本语法

wkhtmltopdf [GLOBAL OPTION]... [OBJECT]... <output file>
  • GLOBAL OPTION ： 全局选项
  • OBJECT： 输入的文档对象，即网页（页面对象）、封面、目录中任何对象
  • output file： 输出的 PDF 文件， 如../dir/file_name.pdf

文档对象

  • wkhtmltopdf 能够将多个对象（页面对象、封面、目录等）合并输出到一个 PDF 文件中，这个对象可以是网页（页面对象）、封面、目录中的任何一个或多个。
  • 这些对象输出到 PDF 文件中的顺序，可以通过命令行中的选项参数配置。
  • 配置选项参数，既可以针对每个对象配置选项参数，也可以配置全局选项。

配置选项参数有两种方式：

  • 配置全局选项

  • 配置页面选项，针对输入的文档对象配置参数 注意：

  • 全局选项只能在 全局选项区域 [GLOBAL OPTION] 处配置，也就是 wkhtmltopdf 后面的位置

  • 只针对某个输入文档对象的配置选项，紧跟在输入对象之后，进行配置

页面对象 页面对象是将输入的单个网页的内容输出到 PDF 文档中。

页面对象的参数可以配置在全局选项区域 [GLOBAL OPTION] 或 页面选项区域 [PAGE OPTION] 的位置。 在下方的【页面选项】、【页眉页脚选项】部分，可以找到适合你需求的选项配置。

语法

(page)? <input url/file name> [PAGE OPTION]...
  • input url/file name： 输入的页面文件对象
  • PAGE OPTION：页面选项

示例

wkhtmltopdf https://www.baidu.com/ --no-images /mnt/d/pdf/baidu.pdf

封面对象 封面对象是将输入的单个网页的内容输出到 PDF 文档中。

  • 封面对象生成的 PDF 页面，不会出现在目录中，也没有页眉和页脚。
  • 所有页面对象的选项（页面选项），对于封面对象同样也适用。

语法

cover <input url/file name> [PAGE OPTION]... 1 示例

wkhtmltopdf --footer-center '页脚内容' cover https://www.baidu.com/ --no-images https://www.baidu.com/more/ --no-images /mnt/d/pdf/baidu.pdf

目录对象 目录对象是将内容中的 <h?> 标签生成目录，然后把目录的内容输出到 PDF 文档中。

  • 所有页面对象的选项（页面选项），对于目录对象同样也适用，另外目录对像还有自己对应的专门【目录选项】。
  • 目录是通过 XSLT 样式表生成的，这意味着可以对其进行自定义样式设置，使其外观符合您的样式要求。
  • 要想了解目录如何自定义样式，可以通过 wkhtmltopdf --dump-default-toc-xsl 选项，查看默认样式配置，然后可以通过--dump-outline 选项，将生成的大纲（目录）保存到文件中，进行查看修改对应样式。要想了解更多内容，请查看【大纲选项】。
  • 语法

toc [TOC OPTION]...

全局选项

帮助与输出

  • 选项 描述 默认/值 可选值
  • -h, --help 显示帮助
  • -H, --extended-help 显示详细的帮助说明
  • –htmldoc 输出 HTML 格式的帮助
  • –readme 输出 readme 文档
  • –license 输出许可证信息并退出
  • -V, --version 输出版本信息并退出
  • –manpage 输出 man 配置说明
  • –log-level 设置日志级别 info none, error, warn，info
  • -q, --quiet 不输出任何日志，（同 --log-level none）

页面尺寸与方向

  • -B, --margin-bottom 设置页面下边距 0

  • -L, --margin-left 设置页面左边距 10mm

  • -R, --margin-right 设置页面右边距 10mm

  • -T, --margin-top 设置页面上边距 0

  • –page-width 页面宽度，值需带单位

  • –page-height 页面高度，值需带单位

  • -s, --page-size 页面尺寸 A4 A4, Letter, 等

  • -O, --orientation 设置纸张方向 Portrait Landscape（横向） ， Portrait（纵向）

    输出 PDF 数量

  • –copies 输出副本的数量，也就是说一次性输出几份 PDF 1

  • –collate 输出多个副本时进行校验 默认选项

  • –no-collate 输出多个副本时不校验

颜色图像分辨率

  • -d, --dpi 设置分辨率（基于 X11 的系统无效） 96
  • -g, --grayscale PDF 输出颜色为黑白色
  • –image-dpi PDF 中嵌入的图像，缩放到该分辨率 600
  • –image-quality jpeg 图片压缩到这个质量 94

其他

  • –cookie-jar 读取和写入 cookie，从 jar 文件中 存放 jar 文件路径
  • -l, --lowquality 生成低质量文档；减少存储空间
  • –no-pdf-compression 不压缩 PDF 文档（不建议使用）
  • –read-args-from-stdin 从标准输入中读取命令行参数， 并应用到每个命令行，用于批处理
  • –title 生成 PDF 文档标题（不指定则使用第一个文档的标题） ？？？
  • –use-xserver 使用 X 服务器（没有 X11，某些插件和其他东西可能无法工作）

页面选项

HTTP、代理、cookie

  • –cookie 设置 cookie，value 应为 url 编码 可重复
  • –custom-header 设置 HTTP 请求头 可重复
  • –custom-header-propagation 为每个加载的资源设置 HTTP 请求头，请求头的参数由–custom-header 指定
  • –no-custom-header-propagation 不为每个加载的资源设置 HTTP 请求头
  • –bypass-proxy-for 可重复
  • -p, --proxy 使用代理
  • –proxy-hostname-lookup 使用这个（ --proxy）代理解析主机名
  • –username http 授权用户名
  • –password Http 认证密码，访问带账号密码的页面
  • –post 添加额外的 POST 字段 可重复
  • –post-file 添加额外的文件 可重复
  • –ssl-crt-path OpenSSL PEM 格式的 ssl 客户端证书公钥的路径，optionally followed by intermediate ca and trusted certs
  • –ssl-key-password SSL 客户端证书私钥密码
  • –ssl-key-path OpenSSL PEM 格式的 ssl 客户端证书私钥的路径

javascript 相关

  • –debug-javascript 输出 javascript 调试信息
  • –no-debug-javascript 不输出 javascript 调试信息 默认选项
  • -n, --disable-javascript web 页面禁用 javascript
  • –enable-javascript web 页面加载 javascript 默认选项
  • –javascript-delay 等待 javascript 完成的时间 200 单位毫秒
  • –run-script 页面加载完成后，运行此 javascript
  • –stop-slow-scripts 停止运行缓慢的 javascripts 默认选项
  • –no-stop-slow-scripts 等待运行缓慢的 javascripts
  • –window-status 等待 window.status 等于此字符串时，打印 PDF 页面

样式、显示、编码

  • –user-style-sheet 指定样式表，应用到每个页面
  • –default-header 设置一个默认页眉，左侧是页面名称，右侧是页码；相当于设置 --header-left=’[webpage]’ --header-right=’[page]/[toPage]’ --top 2cm --header-line
  • –page-offset 设置起始页码 0
  • –minimum-font-size 设置最小字号
  • –print-media-type 使用 print 媒体类型代替 screen 类型
  • –no-print-media-type 禁止用 print 媒体类型代替 screen 类型 默认选项
  • –viewport-size <> 设置视口大小，如果有自定义滚动条或 css 属性 overflow 模拟窗口
  • –disable-smart-shrinking 禁止使用 WebKit pixel/dpi 比值非恒定的智能缩放策略
  • –enable-smart-shrinking 允许使用 WebKit pixel/dpi 比值非恒定的智能缩放策略 默认选项
  • –zoom 设置生成 PDF 时，web 页面的缩放比例 1
  • –exclude-from-outline 禁止当前页面添加到目录和大纲中
  • –include-in-outline 允许当前页面添加到目录和大纲中 默认选项
  • –encoding 设置输入文本的默认编码

HTML、图片、背景

  • –checkbox-checked-svg 复选框选中状态，应用此 svg 文件
  • –checkbox-svg 复选框未选中状态，应用此 svg 文件
  • –radiobutton-checked-svg 复选框选中状态，应用此 svg 文件
  • –radiobutton-svg 复选框未选中状态，应用此 svg 文件
  • –disable-forms 禁止将 HTML 表单字段转换为 pdf 表单字段 默认选项
  • –enable-forms 允许将 HTML 表单字段转换为 pdf 表单字段
  • –background 打印 PDF 背景 默认选项
  • –no-background 不打印 PDF 背景
  • –images 允许加载并打印图片 默认选项
  • –no-images 禁止加载并打印图片

链接挑转

  • –disable-external-links 禁用 PDF 文档中的外部链接生成超链接
  • –enable-external-links 允许 PDF 文档中的外部链接生成超链接 默认选项
  • –disable-internal-links 禁止 PDF 文档中的内部链接生成超链接
  • –enable-internal-links 允许 PDF 文档中的内部链接生成超链接 默认选项
  • –keep-relative-links 相对路径的外部链接，生成相对路径超链接
  • –resolve-relative-links 相对路径的外部链接，生成绝对路径超链接 默认选项
  • –disable-toc-back-links 禁止从节标题链接到目录 默认选项
  • –enable-toc-back-links 允许从节标题链接到目录

文件、缓存、文件加载失败、插件

  • –allow 加载文件夹中的一个或多个文件 可重复
  • –disable-local-file-access 禁止本地文件读取加载其他本地文件，除非设置–allow 默认选项
  • –enable-local-file-access 允许本地文件读取加载其他本地文件
  • –cache-dir Web 缓存目录
  • –load-error-handling web 页面加载失败的处理方式 abort abort, ignore，skip
  • –load-media-error-handling 媒体文件加载失败的处理方式 ignore abort, ignore，skip
  • –disable-plugins 禁用插件 默认选项
  • –enable-plugins 允许使用插件，但是插件可能不工作

页眉页脚通用

  • –replace 用 value 值替换[name]变量，适用页眉页脚，不适用–footer-html 可重复

页眉 选项 描述 默认/值 可选值

  • –header-font-name 设置页眉字体 Arial
  • –header-font-size 设置页眉字号 12
  • –header-left 页眉左侧插入文本
  • –header-center 页眉中间插入文本
  • –header-right 页眉右侧插入文本
  • –header-html 添加 html 页面作为页眉
  • –header-line 页眉下方的显示分割线
  • –no-header-line 页眉下方的不显示分割线 默认选项
  • –header-spacing 页眉与内容之间的间距 0 单位 mm

页脚

  • –footer-font-name 设置页脚字体 Arial
  • –footer-font-size 设置页脚字号 12
  • –footer-left 页脚左侧插入文本
  • –footer-center 页脚中间插入文本
  • –footer-right 页脚右侧插入文本
  • –footer-html 添加 html 页面作为页脚
  • –footer-line 页脚上方的显示分割线
  • –no-footer-line 页脚上方的不显示分割线 默认选项
  • –footer-spacing 页脚与内容之间的间距 0 单位 mm

大纲选项（Outline） 大纲就是 PDF 阅读器中，用于显示导航跳转的部分

  • –dump-default-toc-xsl 输出默认目录的 xsl 样式表到命令行面板
  • –dump-outline 保存大纲内容到文件中
  • –outline PDF 文件中包含大纲 默认选项
  • –no-outline 禁止 PDF 文件阅读器显示大纲内容
  • –outline-depth PDF 文件中大纲的层级深度 4

xsl 是 XML 样式表，相当于 CSS 是 HTML 样式表

目录选项（TOC） TOC 是 英文 table of contents 的缩写。

目录是 PDF 文件中的一个页面，和我们书本中的目录是一个意思。

  • –disable-dotted-lines 目录中标题与页码之间不使用点线
  • –toc-header-text 目录的头部文字，一般设置为“目录” Table of Contents
  • –toc-level-indentation 目录中每一级标题，缩进的宽度 1em
  • –disable-toc-links 禁止从目录连接到节标题
  • –toc-text-size-shrink 目录中每一级标题的字号，缩放比例 0.8
  • –xsl-style-sheet 指定目录使用的 xsl 样式表，可以自定义目录样式

解释说明

页面尺寸 默认的页面尺寸是 A4 纸大小，但是通过–page-size 选项可以修改为其他的任何尺寸，例如 A3、Letter、Legal。

更多页面尺寸查阅：https://doc.qt.io/archives/qt-4.8/qprinter.html#PaperSize-enum

如果要对页面设置其他尺寸大小可以使用 --page-width 和 --page-height 这两个选项。

从标准输入流中读取参数 主要应用于批处理。 如果需要批量转换许多页面，并且感到 wkhtmltopdf 速度很慢，那么可以尝试 --read-args-from-stdin 选项。 当使用--read-args-from-stdin 选项时，批处理的每一行输入命令，都会与--read-args-from-stdin 后的选项参数合并到一起，并应用到每一行命令中。

 echo "https://www.baidu.com/ baidu.pdf" >> cmds
 echo "cover https://www.baidu.com/  http://www.people.com.cn/GB/208743/403202/403212/index.html people.pdf" >> cmds
 wkhtmltopdf --read-args-from-stdin --no-images < cmds

echo 的两行命令用于生成批处理文件 cmds， 最后一行 wkhtmltopdf --read-args-from-stdin --no-images < cmds 用于读取 cmds 中的命令， 并把 --no-images 选项与每一个输入命令合并后，输出 PDF 文件， 以上示例会输出两个 PDF 文件，baidu.pdf 和 people.pdf。

设置代理 默认情况下，代理信息将从环境变量中读取：proxy、 all_proxy 和 http_proxy，

代理设置也能通过 -p, --proxy 选项配置

用 BNF 设置代理如下：

<type> := "http://" | "socks5://"
<serif> := <username> (":" <password>)? "@"
<proxy> := "None" | <type>? <string>? <host> (":" <port>)?


http://user:password@myproxyserver:8080
socks5://myproxyserver
None

页眉页脚 使用 --header-_ and --footer-_ 选项，可以把页眉、页脚添加到 PDF 文档中。

在使用一些选项（如 --header-left）设置页眉、页脚的文本字符串中，可以使用以下变量：

这些变量将被替换为相应的值。

变量 简介 说明

  • [page] 页码 当前正在打印的页数
  • [frompage] 第一页的页码 要打印的第一页的页码，因为第一页的页码可能不是 1
  • [topage] 总页码 要打印的最后一页的页码
  • [webpage] url 地址 当前正在打印页面的 URL 地址
  • [section] 节名 当前正在打印的节名称
  • [subsection] 小节名 当前正在打印的小节名称
  • [date] 当前日期 系统本地格式的当前日期
  • [isodate] 当前日期 ISO 8601 扩展格式的当前日期
  • [time] 当前时间 系统本地格式的当前时间
  • [title] 页面标题 当前页面对象的标题
  • [doctitle] 文档标题 输出文档的标题
  • [sitepage] 站点页码 当前 web 页面中正在转换的页面的编号
  • [sitepages] 站点总页数 当前 web 页面中正在转换的页面数
--header-right "当前是第[page]页|共[topage]页"
  • 例如，通过设置--header-html header.html 选项，header.html 中内容如下：
<!DOCTYPE html>
<html>
  <head>
    <script>
      function subst() {
        var vars = {};
        var query_strings_from_url = document.location.search
          .substring(1)
          .split("&");
        for (var query_string in query_strings_from_url) {
          if (query_strings_from_url.hasOwnProperty(query_string)) {
            var temp_var = query_strings_from_url[query_string].split("=", 2);
            vars[temp_var[0]] = decodeURI(temp_var[1]);
          }
        }
        var css_selector_classes = [
          "page",
          "frompage",
          "topage",
          "webpage",
          "section",
          "subsection",
          "date",
          "isodate",
          "time",
          "title",
          "doctitle",
          "sitepage",
          "sitepages",
        ];
        for (var css_class in css_selector_classes) {
          if (css_selector_classes.hasOwnProperty(css_class)) {
            var element = document.getElementsByClassName(
              css_selector_classes[css_class]
            );
            for (var j = 0; j < element.length; ++j) {
              element[j].textContent = vars[css_selector_classes[css_class]];
            }
          }
        }
      }
    </script>
  </head>
  <body style="border:0; margin: 0;" onload="subst()">
    <table style="border-bottom: 1px solid black; width: 100%">
      <tr>
        <td class="section"></td>
        <td style="text-align:right">
          Page <span class="page"></span> of <span class="topage"></span>
        </td>
      </tr>
    </table>
  </body>
</html>

从示例中可以看出，参数以 GET 方式发送到页眉、页脚的 html 文档,如下形式。

http://www.xxx.com/header.html?page=xxx&frompage=xxx&topage=xxx&webpage=xxx&section=xxx&subsection=xxx&date=xxx&isodate=xxx&time=xxx&title=xxx&doctitle=xxx&sitepage=xxx&sitepages=xxx

页眉、页脚的 html 文档也支持自定义参数--header-html header.html?abc=123，在 html 文档的 url 中，自定义参数将自动与默认参数拼接到一起，如下：

http://www.xxx.com/header.html?page=xxx&frompage=xxx&topage=xxx&webpage=xxx&section=xxx&subsection=xxx&date=xxx&isodate=xxx&time=xxx&title=xxx&doctitle=xxx&sitepage=xxx&sitepages=xxx&abc=123

大纲

  • 大纲就是 PDF 阅读器中，用于显示导航跳转的部分，不属于 PDF 文档中的一部分，主要是方便阅读器浏览导航使用。
  • Wkhtmltopdf 用 patched qt 支持 PDF 大纲（也称为书签），可以通过设置--outline （默认选项）选项实现。
  • 大纲是根据 <h?>(h1–h6) 标签生成的，有关如何实现的详细说明，请参见目录部分。
  • 如果 <h?> 标签在 HTML 文档中嵌套的层级非常深，那么大纲树的层级也会变得非常深。可以通过--outline-depth 选项来设置大纲的层级深度。

目录

  • TOC 是 英文 table of contents 的缩写。
  • 目录是 PDF 文件中的一个页面，和我们书本中的目录是一个意思。
  • 目录是根据 web 文档中的 <h?>(h1–h6) 标签生成。
  • 首先生成一个 XML 文档，然后使用 XSLT 将其转换为 HTML。

生成目录 通过向命令行添加 toc 对象，可以将目录添加到文档中，示例如下：

wkhtmltopdf toc https://doc.qt.io/archives/qt-4.8/qstring.html qstring.pdf

保存大纲到文件中 通过使用 --dump-outline 选项，将生成的 xml 大纲文档转储到文件（示例中：toc.xml）中，可以查看生成的 XML 文档。例如：

wkhtmltopdf --dump-outline toc.xml https://doc.qt.io/archives/qt-4.8/qstring.html qstring.pdf

指定目录样式表

通过使用 --xsl-style-sheet 选项，指定生成目录的 XSLT 样式表文档。

wkhtmltopdf toc --xsl-style-sheet my.xsl https://doc.qt.io/archives/qt-4.8/qstring.html qstring.pdf

查看默认样式表

通过使用 --dump-default-toc-xsl 选项，把默认的 XSLT 样式表输出到命令行面板中。这对于自定义样式表，将是一个很好的参考建议。

 wkhtmltopdf --dump-default-toc-xsl

XML 文档位于命名空间"http://wkhtmltopdf.org/outline"之中，它有一个名为"outline" 的根节点，它包含许多“item”节点。一个“item”节点，可以包含任意数量的“item”节点。这些是项目所代表部分的概要小节。项目节点具有以下属性：

 The XML document is in the namespace "http://wkhtmltopdf.org/outline" it has a
  root node called "outline" which contains a number of "item" nodes. An item
  can contain any number of item. These are the outline subsections to the
  section the item represents. A item node has the following attributes:
  • “title” 章节的名称
  • “page” 章节所在位置的页码
  • “link” 从链接跳转到该章节的 URL。（a URL that links to the section.）
  • “backLink” 从章节返回锚点的链接。（the name of the anchor the section will link back to.）
Last Updated:
Contributors: 刘荣杰