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 落在哪参数 → 源码 → 行为本节解决方向参数最终改动了源码里哪个字段。命令参数源码定义行为影响--orientationPdfGlobal::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.ccQPrinter建好后调用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结构。目录TOCtoc对象 --toc-header-text通过 XSLT 渲染用--dump-default-toc-xsl可导出默认样式。渲染视口--viewport-size决定 JS 和媒体查询看到的窗口尺寸相关处理见 src/lib/pdfconverter.cc。✅ 改完方向后照这份清单过一遍想整份横向加--orientation Landscape。想自定义纸张--page-width和--page-height成对写。想混排横竖分次转换再用 PDF 合并工具拼接。批量任务改用--read-args-from-stdin逐行喂命令。改完方向复核页边距和页眉/页脚是否仍然合适。【免费下载链接】wkhtmltopdfConvert HTML to PDF using Webkit (QtWebKit)项目地址: https://gitcode.com/gh_mirrors/wk/wkhtmltopdf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
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 落在哪参数 → 源码 → 行为本节解决方向参数最终改动了源码里哪个字段。命令参数源码定义行为影响--orientationPdfGlobal::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.ccQPrinter建好后调用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结构。目录TOCtoc对象 --toc-header-text通过 XSLT 渲染用--dump-default-toc-xsl可导出默认样式。渲染视口--viewport-size决定 JS 和媒体查询看到的窗口尺寸相关处理见 src/lib/pdfconverter.cc。✅ 改完方向后照这份清单过一遍想整份横向加--orientation Landscape。想自定义纸张--page-width和--page-height成对写。想混排横竖分次转换再用 PDF 合并工具拼接。批量任务改用--read-args-from-stdin逐行喂命令。改完方向复核页边距和页眉/页脚是否仍然合适。【免费下载链接】wkhtmltopdfConvert HTML to PDF using Webkit (QtWebKit)项目地址: https://gitcode.com/gh_mirrors/wk/wkhtmltopdf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
