wkhtmltopdf详细使用

type

status

date

urlname

summary

wkhtmltopdf精讲

(原文) 作者：JSON_NULL

术语定义

文档对象

“文档对象”是指PDF文档中的文档对象，共有三种类型的“文档对象”，他们分别是“页面对象”，“封面对象”和“目录对象”。

页面对象

“页面对象”是指以页面的形式在PDF文档中呈现的对象，这个是相对于“封面对象”和“目录对象”来讲的。此类对象会成为PDF文档中内容。

封面对象

“封面对象”是指以封面的形式在PDF文档中呈现的对象。这类对象会成为PDF文档中的封面。

目录对象

“目录对象”是以目录的形式在PDF文档中呈现的对象，又叫“TOC对象”。这类对象会成为PDF文档中的目录。

大纲

“大纲”是指阅读PDF文档时的书签导航。

外链

“外链”是指所有在这个页面中且不指向它自身页面中锚点的超链接。

内链

“内链”是指在这个页面中且指向的目标页面是这个页面本身中的一个锚点的超链接。

命令格式

上述代码就是 wkhtmltopdf 的命令行格式，看似简单，其实在 [GLOBAL OPTION] 和 [OBJECT] 中还别有洞天。预知详情，且听我慢慢道来。

文档对象简介

wkhtmltopdf 能够把多个“对象”合并生成一个pdf文档，这些“对象”可以是“页面对象”、“封面对象”、或是“目录对象”。这些对象在pdf文档中的顺序可以通过命令行参数来指定。命令行参数包括两部分，一种是针对某一特定“对象”的命令行参数，另一种是全局的命令行参数。并且全局的命令行参数只能放在全局参数区([GLOBAL OPTION])中指定。

页面对象简介

“页面对象”作用是用来把一个网页作为内容输出到PDF文档中。

“页面对象”的参数可以放在“全局参数域([GLOBAL OPTIONS])”和“页面参数域([PAGE OPTIONS])”。程序会根据实际情况在所有参数中找到合适的参数应用到页面、页眉和页脚。

封面对象简介

“封面对象”用来把一个网页作为封面输出到PDF文档中，输出的页面不会在TOC中出现，并且不会包含页眉和页脚。

所有能够在“页面对象”中使用的参数都可以用到“封面对象”

目录对象简介

“目录对象”的作用是输出一个目录到PDF文件中。

所有能够在“页面对象”中使用的参数都可以用到“TOC对象”，并且还有许多的针对“TOC对象”的参数可以应用到“TOC对象”中。目录是通过 XSLT 生成的，这就意味着它可以被定义成任何你想看到的样子。你可以通过命令行参数 --dump-default-toc-xsl 输出默认的 XSLT 文档，通过 --dump-outline 命令行参数可指定以XML格式输出当前处理文档的目录到指定文件。更多详细内容请查看后面介绍的 目录对象参数

命令参数

命令参数包含五部分，分别是“全局参数”，“大纲参数选项”，“页面对象参数”，“页眉和页脚参数选项”和“目录对象参数”。

全局参数

上述代码区是所有全局参数及注释，下面简单说一下个别参数的意义及用法。

-copies N

N 是一个正整数。

这个选项可以先不用关心了，因为你这辈子可能都用不到。他的作用是在生成的PDF文档中，把内容重复输出 N 份。也就是说，你将得到一个PDF文档，这个文档中的大小、内容量都将是不使用此参数时的 N 倍。然而重复的内容对你来说并没有什么卵用。

如果不使用 --copies 参数，那么 --collate 和 --no-collate 参数就不用了解了，因为他们只在 --copies 参数中的 N 大于 1 时才有意义。

g, --grayscale

这个参数非常有用，使用这个参数可以有效压缩生成的PDF所占用的存储空间。当然这个压缩是要付出一定代价的，那就是最终生成的PDF文档将是灰度的，没有任何色彩。如果你能接受灰度PDF文档，并不影响实际使用，那就请使用这个参数吧。生成的PDF文档越大，使用此参数获得的惊喜就越大。

l, --lowquality

这个参数与 -g 参数有异曲同工之妙， -l 参数也会大大压缩PDF文档所占用的存储空间。只是它是通过降低PDF文档的质量来完成这一任务的。这个参数也值得推荐，你最好先尝试一下，看看使用此参数后生成的PDF文档与不使用此参数的区别再做决定。我可以告诉你的是，在纯文字的情况下他们的差别不大，此参数只是降低了PDF文档的质量，看上去是糙了一些，但不会影响阅读。如果你是一个追求感官享受，或是你生成的PDF文档中有大量图片，那就不要使用此参数了。

-no-pdf-compression

这个参数强烈建议不要使用，最好这辈子都不要去了解他的好，因为对于你来说肯定用不到。它的作用就是在输出PDF文档时，不使用任何的压缩。这将会导致输出的PDF文档特别的大，质量是无损的，但是对于人类来说从感观上根本察觉不到压缩前后的质量变化的。如果你的感观超乎于常人，压缩之后的体验对你来说无法接受，那我收回前面的话，你就尽情使用此参数吧。

q, --quiet

使用这个参数后，你将得到一个干净的命令行输出，就连程序处理的进度和状态都没有。这个参数会抑制所有命令行输出，在程序的工作过程中，你看不到任何输出。建议不会使用此参数，因为程序输出一些进度和状态信息还是非常有用的。万一程序工作到某处死了呢(嘿嘿)，在 -q 模式下你是无法分辨是否程序死掉了的。

大纲参数选项

大纲参数中唯一需要特别说一下的是 --outline-depth ，其他参数默认就好了。

何为大纲

大纲

如上图所示，其实我更喜欢称之为目录或导航。大纲是根据你HTML中的标题(Hn标签)自动生成的。

-outline-depth

-outline-depth 用来指定生成的大纲的深度。默认值为 4。你可以指定一个大一些的数字，以保证所有在HTML中指定的H标签都能在大纲中生成对应的项，方便阅读时快速跳转。

当指定了 --no-outline 参数时，将不会输出大纲到PDF文档，所以再指定 --outline-depth 也就没有意义了。

页面对象参数

上面代码段中只是对所有 页面对象参数 做了个大概的说明，下面针对个别主要参数做更详细的讲解。

-allow

这个参数只在“页面对象”是一个文件时有效，在“页面对象”是一个url时此参数无效。

这个参数的作用是为HTML页面中使用相对路径引用的文件指定一个加载文件的基目录。也就是说HTML文件中所有以相对路径指定的文件都会从 --allow 参数指定的目录进行加载。其实在HTML中指定 base 标签可以达到同样的目的。如果两者(--allow参数和base标签)都没有指定，则使用当前处理的HTML文件所在的目录作为基目录加载当前处理的HTML中相对路径指定的文件。

-background AND --no-background

这两个参数是一对，用来指定是否在生成的PDF中应用网页的背景，默认 --background 参数是开启的，也就是说默认生成的PDF文档中是带有HTML页面的背景图片或背景色的。如果开启 --no-backgroupd 参数，则生成的PDF文档中不会有HTML页面中的背景图片和背景色。

-debug-javascript ADN --no-debug-javascript

这两个参数用来指定是否在标准输出中输出javascript的调试信息，默认 --no-debug-javasript 参数是开启的，也就是说默认不会输出javascript的调试信息。下图是打开 --debug-javascript 参数的演示。

-debug-javascript

-disable-external-links AND --enable-external-links

这两个参数是用来设置在页面中的外链是否以超链接的形式出现在PDF文档中。关于“外链”的定义请移架 术语定义 。默认 --enable-external-links 参数被打开，所以默认情况是页面中的外链是以超链接的形式出现的PDF文档中的，点击可以打开指定的网页。

-exclude-from-outline AND --include-in-outline

这两个参数用来设置当前页面对象是否包含到目录和大纲中。默认情况下 --include-in-outline 参数是打开的。也就是说默认情况下生成的PDF文档目录和大纲中是包含当前页面的，如果你不想让当前页面加到目录和大纲中可以打开 --exclude-from-outline 参数。

-post AND --post-file

当目标页面需要接受POST表单才能正确得到响应时，可以用这两个参数。这两个参数都是可以重复使用的。

还有一个应用场景是，用于自动化的WEB应用测试中。可以得到PDF文档作为测试报告。

-post-file 也可以用于自动批量上传文件的场景。

-run-sript

当需要对页面进行一定的预处理后再生成PDF文档的场景，使用该参数再合适不过了。这个参数可以重复使用指定多个需要在页面加载完成后执行的JS代码。你可以在这些JS中对页面的结构和内容进处理，JS执行完成后才会把对应的页面生成PDF文档。

-disable-internal-links AND --enable-internal-links

这两个参数是用来设置在页面中的内链是否以超链接的形式出现在PDF文档中。关于“内链”的定义请移架 术语定义 。默认 --enable-internal-links 参数被打开，所以默认情况是页面中的内链是以超链接的形式出现的PDF文档中的，点击在当前PDF中跳转到指定锚点。

-enable-toc-back-links AND --disable-toc-back-links

这组参数用来设置，是否在PDF内容中的H标签处生成超链接。生成的超链接点击后会跳转到目录和大纲中该H标签对应的锚点位置。默认情况下 --disable-toc-back-links 参数被打开，不会在PDF文档的H标签处生成超链接。

如果你需要在阅读PDF文档的内容时快速回到目录，你可以打开 --enable-toc-back-links 参数。

-user-style-sheet

这个参数用来加载一个用户自定义的样式表，用来改变HTML页面原有的样式。需要高度自定义页面新式的同学可以尝试使用这个参数达到目的。

页眉和页脚参数选项

页眉页脚的设置比较简单，看上述代码段中的解释已经非常明了，所以不再赘述。后面还有针对页眉与页脚的其他相关介绍。

目录对象参数

“目录对象”我们一般用不到，上述代码段中的讲解也不难懂，所以不针对每一个具体参数再做详细的讲解。

关于页面尺寸说明

默认的页面尺寸是 A4，你可以使用 --page-size 参数指定你想要的页面尺寸，如：A3，Letter 和 Legal等。想要查看本程序支持的所有页面尺寸，请访问 http://qt-project.org/doc/qt-4.8/qprinter.html#PaperSize-enum

你还可以使用 --page-height 和 --page-width 对页面尺寸进行更精细的控制。

从标准输入获取参数

如果你需要对许多页面进行批量的处理，并且感觉 wkhtmltopdf 开启比较慢，你可以尝试使用 --read-args-from-stdin 参数。

wkhtmltopdf 命令会为 --read-args-from-stdin 参数发送过来的每一行进行一次单独命令调用。也就是说此参数每读取一行都会执行一次 wkhtmltopdf 命令。而最终执行的命令中的参数是命令行中参数与此参数读取的标准输入流中参数的结合。

下面的代码段是一个例子:

指令一个代理

默认情况下代理信息将读取环境变量:proxy、all_proxy 和 http_proxy,代理选项还可以通过指定 -p 参数开启。

使用 BNF 对代理的定义如下：

如果你不熟悉 BNF 的话，下面的代码段中是三个例子:

页眉和页脚

页眉和页脚可以使用参数 --header-* 和 --footer-* 添加到文件中。有些参数(如 --footer-left)需要提供一个字符串text作为参数值。你可以在 text中插入下述变量，他们将会被替换成对应的值。

举一个例子来说明吧，--header-right "Page [page] of [toPage]", 会在页面的右上角生成一个类似 Page x of y 的字符串，其中 x 是当前页面的页码， y 是当前文档最后一页的页码。

页眉和页脚也可以通过 HTML文档来提供。同样举一个例子，使用命令行参数 --header-html header.html 来生成页眉，而 header.html 的内容如下:

大纲(Outlines)

wkhtmltopdf 可以使用 --outline 命令行参数来指定在PDF就要中输出像书本中目录一样的“大纲”，“大纲”是基本HTML文档中H标签生成的，具体的大纲的层级和尝试请移步目录

如果HTML文档中的H标签等级比较多，就可以生成深层级树形结构的“大纲”，而生成“大纲”的真实深度是通过 --outline-depth 参数来控制。