画像

<img>とCSSのbackground-imageで画像を埋め込めます。

SVGとGIFは非対応です。

<img>

<img src="logo.png" width="120">
<img src="https://example.com/chart.png" alt="売上推移">
<img src="data:image/png;base64,iVBORw0…">

• <img>はインラインの置換要素として行に載ります。独立した行にしたい場合はdisplay: blockを指定してください
• width/height属性とCSSのwidth/heightに対応します。どちらも無指定なら画像の内在サイズを使い、片方だけ指定すればアスペクト比を保って他方を導出します
• 取得やデコードに失敗した画像は、その要素だけ空として扱い、文書全体の生成は止めません(--load-media-error-handling abortで中断させることもできます)
• 同じ画像を何度使っても、取得・デコード・PDFへの埋め込みは初回の1回だけです

object-fit / object-position

指定した枠に対して画像をどう収めるかを制御します。

img.thumb {
  width: 120px;
  height: 80px;
  object-fit: cover;          /* fill | contain | cover | none | scale-down */
  object-position: 50% 50%;
}

背景画像

.watermark {
  background-image: url("stamp.png");
  background-position: center;
  background-size: contain;
  background-repeat: no-repeat;
}

background-imageに書けるのはurl()だけです。 linear-gradient()などのグラデーション関数と、カンマ区切りの複数背景は非対応です。 既定では画像の内在サイズでタイル配置されます。

border-radiusと背景画像を併用した場合、角丸によるクリップは行われません(角丸は背景色の塗りにのみ効きます)。

リモート画像の取得

既定では無効です。 --allow-remote-assetsで明示的に有効化します。

sghtmltopdf report.html --allow-remote-assets

有効にした場合も、グローバルに到達可能でない宛先へのリクエストは常にブロックされます。 判定は「グローバルなユニキャストだけを通す」方針で、次を拒否します。

IPv4を埋め込むIPv6表記(IPv4-mapped ::ffff:a.b.c.d、IPv4-compatible ::a.b.c.d、NAT64 64:ff9b::/96、6to4 2002::/16)は、埋め込まれたIPv4側で判定します。 これらを素通しするとIPv4側のフィルタを迂回できてしまうためです。

判定は名前解決の結果に対して行うため、DNSリバインディングやリダイレクト経由の迂回も同じ仕組みで防いでいます。

ポート番号は制限しません。 内部サービスはプライベートIP上にあり、そこは上の判定で塞がっています。 公開IPに対する非標準ポート(CDNやAPIの8080など)は正当な用途があるため、塞ぐと実用を損なうわりに得るものがありません。

信頼できないHTMLを変換する場合は、--allowでローカル参照の範囲も併せて絞ってください。

sghtmltopdf untrusted.html --allow /var/app/assets

JPEGはそのまま埋め込まれる

JPEGはデコードせず、サイズ情報だけを読んでPDFへそのまま(DCTDecodeとして)埋め込みます。 再エンコードしないので画質は落ちず、変換も速くなります。

その代わり、--grayscaleを指定してもJPEGとCMYK画像はカラーのまま残ります(デコーダを持たないため)。 グレースケール化が必要な場合は、変換前の画像をグレースケールにしておいてください。

PNGとWebPはフルデコードし、アルファチャンネルがあれば透過画像として埋め込みます。

画像を一切読み込まない

sghtmltopdf invoice.html --no-images

<img>とCSSのbackground-imageの両方を読み込まなくなります。