wkhtmltopdf 页面方向与尺寸控制完整指南：从 --orientation 到自定义纸张一步到位-开发者社区

wkhtmltopdf 页面方向与尺寸控制完整指南：从 --orientation 到自定义纸张一步到位

【免费下载链接】wkhtmltopdfConvert HTML to PDF using Webkit (QtWebKit)项目地址: https://gitcode.com/gh_mirrors/wk/wkhtmltopdf

生成 PDF 时页面朝向、纸张尺寸对不上，是 wkhtmltopdf 用户最常碰到的排版问题。本文从一条最短命令讲到源码字段，覆盖方向、尺寸、批量三类控制，帮你不再为页面方向翻车。

30 秒跑通：把整份文档转成横向

本节解决"最快让一份文档变成横向"。

# 全局横向：这份 PDF 的所有页面都按 Landscape 输出 wkhtmltopdf --orientation Landscape input.html output.pdf # 不写 --orientation 时，默认就是纵向 Portrait，等价于下面这条 wkhtmltopdf input.html output.pdf

记住三点：--orientation只接受Landscape（横向）和Portrait（纵向）两个值，大小写不敏感；不传时缺省是Portrait；它作用于整份PDF 的所有页面。下面拆开看它到底改了源码里的什么。

--orientation 落在哪：参数 → 源码 → 行为

本节解决"方向参数最终改动了源码里哪个字段"。

命令参数	源码定义	行为影响
`--orientation`	`PdfGlobal::orientation`（类型`QPrinter::Orientation`），见 src/lib/pdfsettings.hh	存为全局设置，稍后写入`QPrinter`
合法取值	`strToOrientation()`，见 src/lib/pdfsettings.cc	只认 Landscape / Portrait，不区分大小写，其余判为无效
默认值	`PdfGlobal`构造函数里`orientation(QPrinter::Portrait)`，见 src/lib/pdfsettings.cc	不传参数时整份 PDF 纵向输出
参数注册	`addarg("orientation","O",...)`，见 src/pdf/pdfarguments.cc	注册在 Global Options，只能放在全局区

字符串到枚举的转换逻辑很短，一眼能看完：

// src/lib/pdfsettings.cc：把命令行字符串解析为 Qt 枚举 QPrinter::Orientation strToOrientation(const char * s, bool * ok) { if (ok) *ok = true; if (!strcasecmp(s,"Landscape")) return QPrinter::Landscape; // 横向 if (!strcasecmp(s,"Portrait")) return QPrinter::Portrait; // 纵向 if (ok) *ok = false; // 其它取值标记为无效 return QPrinter::Portrait; }

真正"落到纸面"的一步在 src/lib/pdfconverter.cc：QPrinter建好后调用printer->setOrientation(settings.orientation);，一次性写入整条打印流。这也是为什么它是全局行为——它不能挂在某个page对象上单独改朝向。这一点直接决定了下一节能做什么、不能做什么。

自定义纸张：--page-width 和 --page-height 必须成对

本节解决"改了方向，纸张尺寸会不会变、怎么自定义"。

方向不会改变纸张尺寸本身。Landscape 只是把同尺寸纸张旋转 90°，可读宽度变大、高度变小。所以宽表格切到横向后，一行通常能塞下更多列。

--page-size选标准纸张（A4、Letter 等），默认 A4，对应 src/lib/pdfsettings.cc 里Size::Size()的pageSize(QPrinter::A4)。
自定义尺寸用--page-width/--page-height，字段是UnitReal（数值 + 单位，如210mm），定义在 src/lib/pdfsettings.hh 的struct Size里。

⚠️ 这里是最大的坑：源码用if ((height.first != -1) && (width.first != -1))判断，宽和高必须同时给。只给一个，条件不成立，直接回退到--page-size，等于没改。

# 方向 + 自定义纸张：宽、高必须成对出现 wkhtmltopdf --orientation Landscape \ --page-width 210mm --page-height 148mm \ input.html output.pdf # 只写宽不写高：宽度被忽略，仍按 A4 输出 wkhtmltopdf --page-width 300mm input.html output.pdf

一份 PDF 能不能混排横竖两种方向

本节解决"封面纵向、内页横向"这类混排需求能不能一条命令搞定。

不能。--orientation是全局参数，一份 PDF 只有一个朝向。想要横竖混排，把文档拆成两段各自转换，再合并成一份：

# 封面纵向 wkhtmltopdf --orientation Portrait cover.html cover.pdf # 正文横向 wkhtmltopdf --orientation Landscape body.html body.pdf # 用 PDF 合并工具拼接（qpdf、pdfunite 均可） qpdf --empty --show-pages cover.pdf body.pdf merged.pdf

这条路比在单条命令里硬塞参数更可靠，也更容易在 CI 里复现。

方向相关踩坑对照表

本节解决"看到某个现象时，怎么快速定位原因并修复"。

现象	原因	修复
只改了宽，纸张没变	`--page-width`/`--page-height`必须成对，缺一即回退`--page-size`	两个参数一起写，或改用`--page-size`选标准纸
宽表格切横向仍被截断	页面按原视口渲染，可用宽度没跟着内容走	用`--viewport-size`指定渲染窗口，或在 HTML 里固定 body 宽度
横竖切换后页眉/页脚错位	页边距与方向独立，切向后可读区高度变小	切向后重新核对`--margin-*`与页眉页脚 spacing
想要横竖混排却只有单一朝向	`--orientation`是全局参数，一份 PDF 只一个朝向	拆成多次转换，再用 PDF 合并工具拼接

按场景选策略：个人、团队、批量

本节解决"不同使用强度下，方向与尺寸参数该怎么管理"。

个人 / 一次性脚本：命令行直接写--orientation+--page-size，改完即跑，最省事。
团队：把方向、纸张、边距固化进脚本或 CI 配置，参数集中管理，避免各自随手传参导致产物不一致。
批量生产：大量文档用--read-args-from-stdin，每条转换命令写一行、逐行喂给同一个进程，省掉反复启动的开销，入口说明见 docs/usage/wkhtmltopdf.txt。

# 每行一次独立转换，共用一个进程，省去重复启动 echo "cover.html cover.pdf" > cmds.txt echo "--orientation Landscape body.html body.pdf" >> cmds.txt wkhtmltopdf --read-args-from-stdin < cmds.txt

延伸方向与可执行清单

本节给出后续可深挖的入口，和一份能直接照做的清单。

可继续下钻的三个方向：

页眉页脚占位符：--header-right "[page]/[toPage]"这类写法，变量替换逻辑对应 src/lib/pdfsettings.hh 的HeaderFooter结构。
目录（TOC）：toc对象 +--toc-header-text，通过 XSLT 渲染，用--dump-default-toc-xsl可导出默认样式。
渲染视口：--viewport-size决定 JS 和媒体查询看到的窗口尺寸，相关处理见 src/lib/pdfconverter.cc。

✅ 改完方向后，照这份清单过一遍：