wkhtmltopdf 參數詳解

本文轉載自查看原文 2020-04-28 11:08 2280

術語定義

文檔對象

“文檔對象”是指PDF文檔中的文檔對象，共有三種類型的“文檔對象”，他們分別是“頁面對象”，“封面對象”和“目錄對象”。

頁面對象

“頁面對象”是指以頁面的形式在PDF文檔中呈現的對象，這個是相對於“封面對象”和“目錄對象”來講的。此類對象會成為PDF文檔中內容。

封面對象

“封面對象”是指以封面的形式在PDF文檔中呈現的對象。這類對象會成為PDF文檔中的封面。

目錄對象

“目錄對象”是以目錄的形式在PDF文檔中呈現的對象，又叫“TOC對象”。這類對象會成為PDF文檔中的目錄。

大綱

“大綱”是指閱讀PDF文檔時的書簽導航。

外鏈

“外鏈”是指所有在這個頁面中且不指向它自身頁面中錨點的超鏈接。

內鏈

“內鏈”是指在這個頁面中且指向的目標頁面是這個頁面本身中的一個錨點的超鏈接。

命令格式

wkhtmltopdf [GLOBAL OPTION]... [OBJECT]... <output file>

上述代碼就是 wkhtmltopdf 的命令行格式，看似簡單，其實在 [GLOBAL OPTION] 和 [OBJECT] 中還別有洞天。預知詳情，且聽我慢慢道來。

文檔對象簡介

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格式輸出當前處理文檔的目錄到指定文件。更多詳細內容請查看后面介紹的 目錄對象參數

命令參數

命令參數包含五部分，分別是“全局參數”，“大綱參數選項”，“頁面對象參數”，“頁眉和頁腳參數選項”和“目錄對象參數”。

全局參數

    --collate             當輸出多個副本時進行校驗(這是默認設置)
    --no-collate          當輸出多個副本時不進行校驗
    --cookie-jar <path>   從提供的JAR文件中讀寫cookie數據
    --copies <number>     設置輸出副本的數量(默認主1)，其實為1就夠了
-d, --dpi <dpi>           指定一個要分辨率(這在 X11 系統中並沒有什么卵用)
-H, --extended-help       相對 -h 參數，顯示更詳細的說明文檔
-g, --grayscale           指定以灰度圖生成PDF文檔。占用的空間更小
-h, --help                顯示幫助信息  
    --htmldoc             輸出程序的html幫助文檔
    --image-dpi <integer> 當頁面中有內嵌的圖片時，
                          會下載此命令行參數指定尺寸的圖片(默認值是 600)
    --image-quality <interger> 當使用 jpeg 算法壓縮圖片時使用這個參數指定的質量(默認為 94)
    --license             輸出授權信息並退出
-l, --lowquality          生成低質量的 PDF/PS ,能夠很好的節約最終生成文檔所占存儲空間
    --manpage             輸出程序的手冊頁
-B, --margin-bottom <unitreal> 設置頁面的 底邊距
-L, --margin-left <unitreal>   設置頁面的 左邊距 (默認是 10mm)
-R, --margin-right <unitreal>  設置頁面的 右邊距 (默認是 10mm)
-T, --margin-top <unitreal>    設置頁面的 上邊距
-O, --orientation <orientation> 設置為“風景(Landscape)”或“肖像(Portrait)”模式,
                                默認是肖像模塊(Portrait)
    --page-height <unitreal>   頁面高度
-s, --page-size <Size>         設置頁面的尺寸，如：A4,Letter等，默認是：A4
    --page-width <unitreal>    頁面寬度
    --no-pdf-compression       不對PDF對象使用丟失少量信息的壓縮算法，不建議使用些參數，
                               因為生成的PDF文件會非常大。
-q, --quiet                    靜態模式，不在標准輸出中打印任何信息
    --read-args-from-stdin     從標准輸入中讀取命令行參數，后續會有針對此指令的詳細介紹，
                               請參見 **從標准輸入獲取參數**
    --readme                   輸出程序的 readme 文檔
    --title <text>             生成的PDF文檔的標題，如果不指定則使用第一個文檔的標題
-V, --version                  輸出版本信息后退出

上述代碼區是所有全局參數及注釋，下面簡單說一下個別參數的意義及用法。

–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 模式下你是無法分辨是否程序死掉了的。

大綱參數選項

--dump-default-toc-xsl     輸出默認的 TOC xsl 樣式表到標准輸出
--dump-outline <file>      輸出“大綱”到指定的文件(文件內容為xml)
--outline                  在生成的PDF文檔中輸出“大綱”(這是默認設置)
--no-outline               不在pdf文檔中輸出大綱
--outline-depth <level>    設置生成大綱的深度(默認為 4)

大綱參數中唯一需要特別說一下的是 --outline-depth ，其他參數默認就好了。

何為大綱

大綱

如上圖所示，其實我更喜歡稱之為目錄或導航。大綱是根據你HTML中的標題(Hn標簽)自動生成的。

–outline-depth

--outline-depth 用來指定生成的大綱的深度。默認值為 4。你可以指定一個大一些的數字，以保證所有在HTML中指定的H標簽都能在大綱中生成對應的項，方便閱讀時快速跳轉。

當指定了 --no-outline 參數時，將不會輸出大綱到PDF文檔，所以再指定 --outline-depth 也就沒有意義了。

頁面對象參數

    --allow <path>                指定加載HTML中相對路徑文件的目錄(可重復使用此參數指定多個
                                  目錄)，這個參數會在后面進行更詳細的講解
    --background                  輸出頁面背景到PDF文檔(這是默認設置)
    --no-background               不輸出頁面背景到PDF文檔
    --cache-dir <path>            網頁的緩存目錄
    --checkbox-checked-svg <path> 使用指定的SVG文件渲染選中的復選框
    --checkbox-svg <path>         使用指定的SVG文件渲染未選中的篩選框
    --cookie <name> <value>       設置訪問網頁時的cookie,value 需要進行url編碼
                                  (可重復使用此參數指定多個cookie)
    --custom-header <name> <value> 設置訪問網頁時的HTTP頭(可重復使用此參數指定多個HTTP頭)
    --custom-header-propagation   為每個要加載的資源添加由 --custom-header 指定的HTTP頭
    --no-custom-header-propagation 不為每個要加載的資源添加由 --custom-header 指定的HTTP頭
    --debug-javascript            顯示javascript調試輸出的信息
    --no-debug-javascript         不顯示javascript調試輸出的信息(這是默認設置)
    --default-header              添加一個默認的“頭”，在頁面的左頭顯示頁面的名字，
                                  在頁面的右頭顯示頁碼，這相對於進行了如下設置：
                                  --header-left='[webpage]'
                                  --header-right='[page]/[toPage]'
                                  --top 2cm
                                  --header-line
    --encoding <encoding>         為輸入的文本設置默認的編碼方式
    --disable-external-links      禁止頁面中的外鏈生成超鏈接
    --enable-external-links       允許頁面中的外鏈生成超鏈接(這是默認設置)
    --disable-forms               不轉換HTML表單為PDF表單(這是默認設置)
    --enable-forms                轉換HTML表單為PDF表單
    --images                      加載圖片並輸出到PDF文檔(這是默認設置)
    --no-images                   在生成的PDF文檔中過濾掉圖片
    --disable-internal-links      禁止頁面中的內鏈生成超鏈接
    --enable-internal-links       允許頁面中的內鏈生成超連接(這是默認設置)
-n, --disable-javascript          禁止WEB頁面執行 javascript
    --enable-javascript           允許WEB頁面執行 javascript(這是默認設置)
    --javascript-delay <msec>     延遲一定的毫秒等待javascript 執行完成(默認值是200)
    --load-error-handling <handler> 指定當頁面加載失敗后的動作，可以指定為：abort(中止)、
                                    ignore(忽略)、skip(跳過)；(默認值是：abort)
    --load-media-error-handling <handler> 指定當媒體文件加載失敗后的動作，可以指定為：
                                          abort(中止)、ignore(忽略)、skip(跳過)；
                                          (默認值是：ignore)
    --disable-local-file-access   不允許一個本地文件加載其他的本地文件，使用命令行參數
                                   `--allow` 指定的目錄除外。
    --enable-local-file-access    允許本地文件加載其他的本地文件(這是默認設置)
    --minimum-font-size <int>     設置最小的字號，除非必要不推薦使用該參數
    --exclude-from-outline        拒絕加載當前頁面到PDF文檔的目錄和大綱中
    --include-in-outline          加載當前頁面到PDF文檔的目錄和大綱中(這是默認設置)
    --page-offset <offset>        設置頁碼的起始值(默認值為0)
    --password <password>         HTTP身份認證的密碼
    --disable-plugins             禁止使用插件(這是默認設置)
    --enable-plugins              允許使用插件，但插件可能並不工作
    --post <name> <value>         添加一個POST字段，可以重復使用該參數添加多個POST字段。
    --post-file <name> <value>    添加一個POST文件，可以重復使用該參數添加多個文件。
    --print-media-type            用顯示媒體類型代替屏幕
    --no-print-media-type         不用顯示媒體類型代替屏幕
-p, --proxy <proxy>               使用代理
--radiobutton-checked-svg <path>  使用指定的SVG文件渲染選中的單選框
--radiobutton-svg <path>          使用指定的SVG文件渲染未選中的單選框
--run-sript <js>                  頁面加載完成后執行一個附加的JS文件，可以重復使用此參數指定
                                  多個要在頁面加載完成后要執行的JS文件。
--disable-smart-shrinking         不使用智能收縮策略
--enable-smart-shrinking          使用智能收縮策略(這是默認設置)
--stop-slow-scripts               停止運行緩慢的javascript代碼(這是默認設置)
--no-stop-slow-scripts            不停止運行緩慢的javascript代碼
--disable-toc-back-links          禁止從標題鏈接到目錄(這是默認設置)
--enable-toc-back-links           允許從標題鏈接到目錄
--user-style-sheet <url>          設置一個在每個頁面都加載的用戶自定義樣式表
--username <username>             HTTP身誰的用戶名
--viewport-size <>                設置窗口大小,需要你自定義滾動條或css屬性來自適應窗口大小。
--window-status <windowStatus>    Wait until window.status is equal to
                                  this string before rendering page
--zoom <float>                    設置轉換成PDF時頁面的縮放比例(默認為1)

上面代碼段中只是對所有 頁面對象參數 做了個大概的說明，下面針對個別主要參數做更詳細的講解。

–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頁面原有的樣式。需要高度自定義頁面新式的同學可以嘗試使用這個參數達到目的。

頁眉和頁腳參數選項

    --footer-center <text>        在頁腳的居中部分顯示頁腳文本 <text>
    --footer-font-name <name>     設置頁腳的字體 (默認為 Arial)
    --footer-font-size <size>     設置頁腳的字體大小 (默認為 12)
    --footer-html <url>           添加一個html作為頁腳
    --footer-left <text>          在頁腳的居左部分顯示頁腳文本 <text>
    --footer-line                 在頁腳上方顯示一條直線分隔正文
    --no-footer-line              不使用直線分隔頁腳與正文(這是默認設置)
    --footer-right <text>         在頁腳的居右部分顯示頁腳文本 <text>
    --footer-spacing <real>       頁腳與正文之間的距離(默認為零)
    
    
    --header-center <text>        在頁眉的居中部分顯示頁眉文本 <text>
    --header-font-name <name>     設置頁眉的字體 (默認為 Arial)
    --header-font-size <size>     設置頁眉的字體大小 (默認為 12)
    --header-html <url>           添加一個html作為頁眉
    --header-left <text>          在頁眉的居左部分顯示頁眉文本 <text>
    --header-line                 在頁眉下方顯示一條直線分隔正文
    --no-header-line              不使用直線分隔頁眉與正文(這是默認設置)
    --header-right <text>         在頁眉的居右部分顯示頁眉文本 <text>
    --header-spacing <real>       頁眉與正文之間的距離(默認為零)

頁眉頁腳的設置比較簡單，看上述代碼段中的解釋已經非常明了，所以不再贅述。后面還有針對頁眉與頁腳的其他相關介紹。

目錄對象參數

    --disable-dotted-lines        在目錄中不使用虛線
    --toc-header-text <text>      設置目錄的頁眉文本
    --toc-level-indentation <width> 第級標題在目錄中的縮進寬度(默認為1em)
    --disable-toc-links           在目錄中不生成指向內容錨點的超鏈接
    --toc-text-size-shrink <real> 在目錄中每級標題的縮放比例(默認為0.8)
    --xsl-style-sheet <file>      使用自定義的 XSL 樣式表顯示目錄內容

“目錄對象”我們一般用不到，上述代碼段中的講解也不難懂，所以不針對每一個具體參數再做詳細的講解。

關於頁面尺寸說明

默認的頁面尺寸是 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 命令。而最終執行的命令中的參數是命令行中參數與此參數讀取的標准輸入流中參數的結合。

下面的代碼段是一個例子:

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

指令一個代理

默認情況下代理信息將讀取環境變量:proxy、all_proxy 和 http_proxy,代理選項還可以通過指定 -p 參數開啟。

使用 BNF 對代理的定義如下：

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

如果你不熟悉 BNF 的話，下面的代碼段中是三個例子:

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

頁眉和頁腳

頁眉和頁腳可以使用參數 --header-* 和 --footer-* 添加到文件中。有些參數(如 --footer-left)需要提供一個字符串text作為參數值。你可以在 text中插入下述變量，他們將會被替換成對應的值。

[page]       當前正在被輸出頁面的頁碼
[frompage]   第一頁在文檔中的頁碼
[topage]     最后一面在文檔中的頁碼
[webpage]    當前正在被輸出頁面的URL
[section]    當前正在被輸出的章節的名字
[subsection] 當前正在被輸出的小節的名字
[date]       本地系統格式的當前日期
[isodate]    ISO 8601 格式的當前日期
[time]       本地系統格式的當前時間
[title]      當前對象的標題
[doctitle]   輸出文檔的標題
[sitepage]   當前正在處理的對象中當前頁面的頁碼
[sitepages]  當前正在處理的對象中的總頁數

舉一個例子來說明吧，--header-right "Page [page] of [toPage]", 會在頁面的右上角生成一個類似 Page x of y 的字符串，其中 x 是當前頁面的頁碼， y 是當前文檔最后一頁的頁碼。

頁眉和頁腳也可以通過 HTML文檔來提供。同樣舉一個例子，使用命令行參數 --header-html header.html 來生成頁眉，而 header.html 的內容如下:

<html><head><script>
function subst() {
  var vars={};
  var x=window.location.search.substring(1).split('&');
  for (var i in x) {var z=x[i].split('=',2);vars[z[0]] = unescape(z[1]);}
  var x=['frompage','topage','page','webpage','section','subsection','subsubsection'];
  for (var i in x) {
    var y = document.getElementsByClassName(x[i]);
    for (var j=0; j<y.length; ++j) y[j].textContent = vars[x[i]];
  }
}
</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>

大綱(Outlines)

wkhtmltopdf 可以使用 --outline 命令行參數來指定在PDF就要中輸出像書本中目錄一樣的“大綱”，“大綱”是基本HTML文檔中H標簽生成的，具體的大綱的層級和嘗試請移步目錄

如果HTML文檔中的H標簽等級比較多，就可以生成深層級樹形結構的“大綱”，而生成“大綱”的真實深度是通過 --outline-depth 參數來控制。