wkhtmltopdf教程

简介

wkhtmltopdf和wkhtmltoimage是开源(LGPLv3)命令行工具,通过命令行交互、开源免费的将html内容转为pdf或图片的工具,其本质是使用内置浏览器内核渲染目标网页，然后再将网页渲染结果转换为PDF文档或图片。

官方地址为：https://wkhtmltopdf.org/index.html

docker 调用浏览器 docker wkhtmltopdf_服务器

安装

官网下载地址为：https://wkhtmltopdf.org/downloads.html

github地址：https://github.com/wkhtmltopdf/wkhtmltopdf/releases

linux安装

  1. 安装依赖
yum install -y fontconfig libX11 libXext libXrender libjpeg libpng xorg-x11-fonts-75dpi xorg-x11-fonts-Type1
  1. 将下载好的安装包上传的服务器
  2. 安装
rpm -ivh wkhtmltox-0.12.6-1.centos7.x86_64.rpm
  1. 验证服务是否安装成功
wkhtmltopdf https://www.baidu.com/ /tmp/test.pdf

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-wfhSfvyQ-1651797211477)(D:\笔记\笔记\wkhtmltox\中文乱码.png)]

  1. 乱码解决

出现乱码是因为缺少对应的字体，这时候就需要安装对应的字体，这里我准备了一些字体，解压到/usr/share/fonts/路径下

unzip -o  /usr/share/fonts/fonts.zip -d /usr/share/fonts
wkhtmltopdf https://www.baidu.com/ /tmp/test.pdf

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-G3nXL9r6-1651797211479)(D:\笔记\笔记\wkhtmltox\中文乱码解决完成.png)]

windows安装

下载exe文件直接安装就可以使用，如果也出现乱码则下载对应的字体到C:\Windows\Fonts路径下

命令解析

原英文文档地址：https://wkhtmltopdf.org/usage/wkhtmltopdf.txt

语法结构

wkhtmltopdf [GLOBAL OPTION]... [OBJECT]... <output file>
- wkhtmltopdf:生成pdf的执行命令
- GLOBAL OPTION：全局选项
- OBJECT：要生成pdf的原内容
- output file：pdf输出路径

文档对象简介

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

页面对象简介

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

(page)? <input url/file name> [PAGE OPTION]...

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

封面对象简介

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

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

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

目录对象简介

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

toc [TOC OPTION]...

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

命令参数

命令参数包含五部分，分别是Global Options(全局参数)，Outline Options(大纲参数选项)，Page Options(页面对象参数)，**Headers And Footer Options(页眉和页脚参数选项)和TOC Options(目录对象参数)**六部分。

Global Options(全局参数)

重要程度

命令

英文解析

中文解析

示例

重要

-H, --extended-help

Display more extensive help, detailing less common command switches

显示最详细的说明文档

wkhtmltopdf -H

重要

-h, --help

Display help

简洁的帮助文档

wkhtmltopdf -h

重要

–htmldoc

Output program html help

输出程序的html帮助文档

wkhtmltopdf --htmldoc

重要

–page-height

Page height

页面高度（参数的值得单位默认是mm）

wkhtmltopdf --page-width 110 --page-height 110 https://www.baidu.com/ /tmp/test.pdf

重要

-s, --page-size

Set paper size to: 1·, Letter, etc. (default A4)

页面的尺寸，如：A4,Letter等，默认是：A4，详见【打印纸张尺寸】

wkhtmltopdf -s A4 https://www.baidu.com/ /tmp/test.pdf

重要

–page-width

Page width

页面宽度（参数的值得单位默认是mm）

重要

-O, --orientation

Set orientation to Landscape or Portrait (default Portrait)

将方向设置为横向或纵向（默认纵向）

wkhtmltopdf -O Landscape https://www.baidu.com/ /tmp/test.pdf

重要

-B, --margin-bottom

Set the page bottom margin

设置页面的下边距

wkhtmltopdf -B 10 https://www.baidu.com/ /tmp/test.pdf

重要

-L, --margin-left

Set the page left margin (default 10mm)

设置页面的左边距(默认10mm)

wkhtmltopdf -L 10 https://www.baidu.com/ /tmp/test.pdf

重要

-R, --margin-right

Set the page right margin (default 10mm)

设置页面的右边距(默认10mm)

wkhtmltopdf -R 10 https://www.baidu.com/ /tmp/test.pdf

重要

-T, --margin-top

Set the page top margin

设置页面的上边距

wkhtmltopdf -T 10 https://www.baidu.com/ /tmp/test.pdf

重要

–image-dpi

When embedding images scale them down to this dpi (default 600)

嵌入图像时，将其缩小到指定的dpi（默认为600）

wkhtmltopdf --image-dpi 600 https://www.baidu.com/ /tmp/test.pdf

重要

–image-quality

When jpeg compressing images use this quality (default 94)

压缩图像时使用此质量（默认值94）

wkhtmltopdf --image-quality 94 https://www.baidu.com/ /tmp/test.pdf

重要

-l, --lowquality

Generates lower quality pdf/ps. Useful to shrink the result document space

生成较低质量的pdf/ps。有助于缩小结果文档空间（经验证小文档用处不大）

wkhtmltopdf -l https://www.baidu.com/ /tmp/test.pdf

重要

–no-pdf-compression

Do not use lossless compression on pdf objects

不要对pdf对象使用无损压缩

–collate

Collate when printing multiple copies (default)

当输出多个副本时校验(默认)

–no-collate

Do not collate when printing multiple copies

当输出多个副本时不校验

–cookie-jar


Read and write cookies from and to the supplied cookie jar file

从提供的cookie架包文 件读取和写入cookie

–copies

Number of copies to print into the pdf file (default 1)

设置生成该文件的数量（默认1）

wkhtmltopdf --copies 3 https://www.baidu.com/ /tmp/test.pdf

-d, --dpi

Change the dpi explicitly (this has no effect on X11 based systems) (default 96)

改变分辨率（对于x11系统没有影响）

-g, --grayscale

PDF will be generated in graysca

灰色生成pdf

wkhtmltopdf -g https://www.baidu.com/ /tmp/test.pdf

–log-level

Set log level to: none, error, warn or info (default info)

设置日志级别：none, error, warn or info (默认 info)

wkhtmltopdf --log-level info https://www.baidu.com/ /tmp/test.pdf

-q, --quiet

Be less verbose, maintained for backwards compatibility; Same as using --log-level none

静态模式，不在标准输出中打印任何信息

–read-args-from-stdin

Read command line arguments from stdin

从标准输入中读取命令行参数

–readme

Output program readme

输出程序的 readme 文档

–title


The title of the generated pdf file (The title of the first document is used if not specified)

生成的PDF文档的标题，如果不指定则使用第一个文档的标题

–use-xserver

Use the X server (some plugins and other stuff might not work without X11)

使用X服务器（一些插件和其他的东西没有X11可能无法正常工作）

-V, --version

Output version information and exit

输出版本信息

–license

Output license information and exit

输出授权信息并退出

–manpage

Output program man page

输出代码管理者的名称

打印纸张尺寸

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

Constant

Value

Description

QPrinter::A0

5

841 x 1189 mm

QPrinter::A1

6

594 x 841 mm

QPrinter::A2

7

420 x 594 mm

QPrinter::A3

8

297 x 420 mm

QPrinter::A4

0

210 x 297 mm, 8.26 x 11.69 inches

QPrinter::A5

9

148 x 210 mm

QPrinter::A6

10

105 x 148 mm

QPrinter::A7

11

74 x 105 mm

QPrinter::A8

12

52 x 74 mm

QPrinter::A9

13

37 x 52 mm

QPrinter::B0

14

1000 x 1414 mm

QPrinter::B1

15

707 x 1000 mm

QPrinter::B2

17

500 x 707 mm

QPrinter::B3

18

353 x 500 mm

QPrinter::B4

19

250 x 353 mm

QPrinter::B5

1

176 x 250 mm, 6.93 x 9.84 inches

QPrinter::B6

20

125 x 176 mm

QPrinter::B7

21

88 x 125 mm

QPrinter::B8

22

62 x 88 mm

QPrinter::B9

23

33 x 62 mm

QPrinter::B10

16

31 x 44 mm

QPrinter::C5E

24

163 x 229 mm

QPrinter::Comm10E

25

105 x 241 mm, U.S. Common 10 Envelope

QPrinter::DLE

26

110 x 220 mm

QPrinter::Executive

4

7.5 x 10 inches, 190.5 x 254 mm

QPrinter::Folio

27

210 x 330 mm

QPrinter::Ledger

28

431.8 x 279.4 mm

QPrinter::Legal

3

8.5 x 14 inches, 215.9 x 355.6 mm

QPrinter::Letter

2

8.5 x 11 inches, 215.9 x 279.4 mm

QPrinter::Tabloid

29

279.4 x 431.8 mm

QPrinter::Custom

30

Unknown, or a user defined size.

Outline Options(大纲参数选项)

命令

英文解析

中文解析

–dump-default-toc-xsl

Dump the default TOC xsl style sheet to stdout

输出默认的 TOC xsl 样式表到标准输出

–dump-outline

Dump the outline to a file

将大纲转储到文件中

–outline

Put an outline into the pdf (default)

将大纲放入pdf（默认）

–no-outline

Do not put an outline into the pdf

不要在pdf中输入大纲

–outline-depth

Set the depth of the outline (default 4)

设置大纲的深度（默认值4）

Page Options(页面对象参数)

重要程度

命令

英文解析

中文解析

示例

重要

–disable-smart-shrinking

Disable the intelligent shrinking strategy used by WebKit that makes the pixel/dpi ratio non-constant

禁止智能收缩策略

wkhtmltopdf --disable-smart-shrinking https://www.baidu.com/ /tmp/test.pdf

重要

–enable-smart-shrinking

Enable the intelligent shrinking strategy used by WebKit that makes the pixel/dpi ratio non-constant (default)

开启智能收缩策略(默认)

wkhtmltopdf --enable-smart-shrinking https://www.baidu.com/ /tmp/test.pdf

–allow


Allow the file or files from the specified folder to be loaded (repeatable)

指定加载HTML中相对路径文件的目录（可重复使用）

–background

Do print background (default)

输出页面背景（默认）

–no-background

Do not print background

不输出页面背景

–bypass-proxy-for

Bypass proxy for host (repeatable)

绕过主机代理（可重复）

–cache-dir


Web cache directory

网页的缓存目录

–checkbox-checked-svg


Use this SVG file when rendering checked checkboxes

使用指定的SVG文件渲染选中的复选框

–checkbox-svg


Use this SVG file when rendering unchecked checkboxes

使用指定的SVG文件渲染未选中的筛选框

–cookie

Set an additional cookie (repeatable), value should be url encoded.

设置访问网页时的cookie,value 需要进行url编码（可重复）

–custom-header

Set an additional HTTP header (repeatable)

设置访问网页时的HTTP头（可重复）

–custom-header-propagation

Add HTTP headers specified by --custom-header for each resource request.

为每个要加载的资源添加由 --custom-header 指定的HTTP头

–no-custom-header-propagation

Do not add HTTP headers specified by --custom-header for each resource request.

不为每个要加载的资源添加由 --custom-header 指定的HTTP头

–debug-javascript

Show javascript debugging output

显示javascript调试输出的信息

–no-debug-javascript

Do not show javascript debugging output (default)

不显示javascript调试输出的信息（默认）

–default-header

Add a default header, with the name of the page to the left, and the page number to the right, this is short for:

–header-left=‘[webpage]’

–header-right=‘[page]/[toPage]’ --top 2cm

–header-line

添加一个默认的“头”，在页面的左头显示页面的名字， 在页面的右头显示页码，这相对于进行了如下设置： --header-left=‘[webpage]’ --header-right=‘[page]/[toPage]’ --top 2cm --header-line

–encoding

Set the default text encoding, for input

为输入的文本设置默认的编码方式

–disable-external-links

Do not make links to remote web pages

禁止页面中的外链生成超链接

–enable-external-links

Make links to remote web pages (default)

允许页面中的外链生成超链接（默认）

–disable-forms

Do not turn HTML form fields into pdf form fields (default)

不要将HTML表单字段转换为pdf表单字段（默认）

–enable-forms

Turn HTML form fields into pdf form fields

将HTML表单字段转换为pdf表单字段

–images

Do load or print images (default)

加载图片并输出到PDF文档（默认）

–no-images

Do not load or print images

pdf文档中不加载图片

–disable-internal-links

Do not make local links

禁止内部链接

–enable-internal-links

Make local links (default)

开启内部链接（默认）

-n, --disable-javascript

Do not allow web pages to run javascript

禁止javascript执行

–enable-javascript

Do allow web pages to run javascript (default)

允许javascript执行（默认）

–javascript-delay

Wait some milliseconds for javascript finish (default 200)

延迟执行javascript执行

–keep-relative-links

Keep relative external links as relative external links

将相对外部链接保持为相对外部链接

–load-error-handling

Specify how to handle pages that fail to load: abort, ignore or skip (default abort)

指定如何处理未能加载的页面：中止、忽略或跳过（默认中止）

–load-media-error-handling

Specify how to handle media files that fail to load: abort, ignore or skip (default ignore)

指定当媒体文件加载失败后的动作，可以指定为：中止、忽略或跳过（默认忽略）

–disable-local-file-access

Do not allowed conversion of a local file to read in other local files, unless explicitly allowed with --allow (default)

不允许本地文件加载其他本地文件，使用命令行参数 --allow 指定的目录除外。

–enable-local-file-access

Allowed conversion of a local file to read in other local files.

允许本地文件加载其他的本地文件(这是默认设置)

–minimum-font-size

Minimum font size

最小字号

–exclude-from-outline

Do not include the page in the table of contents and outlines

排除该页包含在目录和大纲中

–include-in-outline

Include the page in the table of contents and outlines (default)

加载当前页面到PDF文档的目录和大纲中(默认)

–page-offset

Set the starting page number (default 0)

设置页码的起始值(默认值为0)

–password

HTTP Authentication password

HTTP身份认证的密码

–disable-plugins

Disable installed plugins (default)

禁止使用插件(默认)

–enable-plugins

Enable installed plugins (plugins will likely not work)

允许使用插件，但插件可能并不工作

–post

Add an additional post field (repeatable)

添加一个post字段（可重复）

–post-file


Post an additional file (repeatable)

添加一个POST文件（可重复）

–print-media-type

Use print media-type instead of screen

用显示媒体类型代替屏幕

–no-print-media-type

Do not use print media-type instead of screen (default)

不用显示媒体类型代替屏幕（默认）

-p, --proxy

Use a proxy

使用代理

–proxy-hostname-lookup

Use the proxy for resolving hostnames

使用代理解析主机名

–radiobutton-checked-svg


Use this SVG file when rendering checked radiobuttons

使用指定的SVG文件渲染选中的单选框

–radiobutton-svg


Use this SVG file when rendering unchecked radiobuttons

使用指定的SVG文件渲染未选中的单选框

–resolve-relative-links

Resolve relative external links into absolute links (default)

将相对外部链接解析为绝对链接（默认）

–run-script

Run this additional javascript after the page is done loading (repeatable)

页面加载完成后执行一个附加的JS文件（可重复）

–ssl-crt-path


Path to the ssl client cert public key in OpenSSL PEM format, optionally followed by intermediate ca and trusted certs

OpenSSL PEM格式的ssl客户端证书公钥的路径，可选地后跟中间ca和受信任证书

–ssl-key-password

Password to ssl client cert private key

ssl客户端证书私钥的密码

–ssl-key-path


Path to ssl client cert private key in OpenSSL PEM format

OpenSSL PEM格式的ssl客户端证书私钥路径

–stop-slow-scripts

Stop slow running javascripts (default)

停止运行缓慢的javascript代码（默认）

–no-stop-slow-scripts

Do not Stop slow running javascripts

不停止运行缓慢的javascript代码

–disable-toc-back-links

Do not link from section header to toc(default)

禁止从标题链接到目录(默认)

–enable-toc-back-links

Link from section header to toc

允许从标题链接到目录

–user-style-sheet


Specify a user style sheet, to load with every page

每个页面加载时，指定用户的样式表

–username

HTTP Authentication username

http认证用户名

–viewport-size <>

Set viewport size if you have custom scrollbars or css attribute overflow to emulate window size

如果有自定义滚动条或css属性溢出来模拟窗口大小，请设置视口大小

–window-status

Wait until window.status is equal to this string before rendering page

等到窗户。在呈现页面之前，状态等于此字符串

–zoom

Use this zoom factor (default 1)

使用此缩放因子（默认为1）

Headers And Footer Options(页眉和页脚参数选项)

重要程度

命令

英文解析

中文解析

重要

–footer-center

Centered footer text

页脚文字居中

重要

–footer-font-name

Set footer font name (default Arial)

设置页脚的字体 (默认为 Arial)

重要

–footer-font-size

Set footer font size (default 12)

设置页脚的字体大小 (默认为 12)

重要

–footer-html

Adds a html footer

添加一个html作为页脚

重要

–footer-left

Left aligned footer text

页脚文字居左显示

重要

–footer-line

Display line above the footer

在页脚上方显示一条直线分隔正文

重要

–no-footer-line

Do not display line above the footer (default)

不使用直线分隔页脚与正文(默认)

重要

–footer-right

Right aligned footer text

页脚文字居右显示

重要

–footer-spacing

Spacing between footer and content in mm (default 0)

页脚与正文之间的距离(默认0)

重要

–header-center

Centered header text

页眉文字居中显示

重要

–header-font-name

Set header font name (default Arial)

设置页眉的字体 (默认为 Arial)

重要

–header-font-size

Set header font size (default 12)

设置页眉的字体大小 (默认为 12)

重要

–header-html

Adds a html header

添加一个html作为页眉

重要

–header-left

Left aligned header text

页眉文字居左显示

重要

–header-line

Display line below the header

在页眉下方显示一条直线分隔正文

重要

–no-header-line

Do not display line below the header (default)

不使用直线分隔页眉与正文(默认)

重要

–header-right

Right aligned header text

页眉文字居右显示

重要

–header-spacing

Spacing between header and content in mm (default 0)

页眉与正文之间的距离(默认0)

重要

–replace

Replace [name] with value in header and footer (repeatable)

将[name]替换为页眉和页脚中的值（可重复）

TOC Options(目录对象参数)

命令

英文解析

中文解析

–disable-dotted-lines

Do not use dotted lines in the toc

在目录中不使用虚线

–toc-header-text


The header text of the toc (default Table of Contents)

设置目录的页眉文本

–toc-level-indentation

For each level of headings in the toc indent by this length (default 1em)

第级标题在目录中的缩进宽度(默认为1em)

–disable-toc-links

Do not link from toc to sections

在目录中不生成指向内容锚点的超链接

–toc-text-size-shrink

For each level of headings in the toc the font is scaled by this factor (default 0.8)

在目录中每级标题的缩放比例(默认为0.8)

–xsl-style-sheet

Use the supplied xsl style sheet for printing the table of contents

使用自定义的 XSL 样式表显示目录内容

从标准输入获取参数

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

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

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

官网给出的例子：

echo "http://qt-project.org/doc/qt-4.8/qapplication.html qapplication.pdf" >> cmds
echo "cover google.com http://en.wikipedia.org/wiki/Qt_(software) qt.pdf" >> cmds
wkhtmltopdf --read-args-from-stdin --book < cmds

使用的时候发现–book没有这个命令，使用下面的命令就可以了。

echo "http://www.baidu.com /tmp/test.pdf" >> cmds
echo "http://www.baidu.com /tmp/test1.pdf" >> cmds
wkhtmltopdf --read-args-from-stdin  < cmds

页眉和页脚

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

[page]       当前正在被输出页面的页码
[frompage]   第一页在文档中的页码
[topage]     最后一面在文档中的页码
[webpage]    当前正在被输出页面的URL
[section]    当前正在被输出的章节的名字
[subsection] 当前正在被输出的小节的名字
[date]       本地系统格式的当前日期
[isodate]    ISO 8601 格式的当前日期
[time]       本地系统格式的当前时间
[title]      当前对象的标题
[doctitle]   输出文档的标题
[sitepage]   当前正在处理的对象中当前页面的页码
[sitepages]  当前正在处理的对象中的总页数

大纲

通过在命令行中添加 TOC对象 可以把一个目录添加到生成的PDF文档中，例如下面的代码段：

wkhtmltopdf toc https://blog.csdn.net/u010913170/article/details/124374537  /tmp/test.pdf