html-to-image-render

HTML から画像への変換

ローカルの .html ファイルをリモートの html2image API で画像にレンダリングするタスクでは、このスキルを使用します。

ワークフロー

1. ディスクから HTML ファイルの内容を読み込みます。
2. 必要に応じて、まず references/html-to-image-api.md でインターフェースの仕様を確認します。
3. 入力 HTML のパスと出力画像のパスを渡して、scripts/render-html-to-image.ts を実行します。
4. 生成された画像ファイルが指定した場所に保存されたことを確認します。

スクリプトの説明

付属のスクリプトは、次の処理を行います。

• HTML ファイルを UTF-8 で読み込みます
• POST https://html2image.hanfangyuan.cn/api/html2image を呼び出します
• 返された image_base64 をデコードします
• 画像をローカルディスクに書き込みます

例：

npx -y tsx skills/html-to-image-render/scripts/render-html-to-image.ts \
  --input ./demo/card.html \
  --output ./out/card.png \
  --element-id card \
  --image-type png

このスクリプトの実行には、利用可能な npx がローカル環境に必要です。また、npx -y tsx を使って TypeScript ファイルを一時的に実行します。初回実行時には通常、tsx がダウンロードされます。

パラメーターの説明

必須パラメーター

• --input：入力するローカル HTML ファイルのパスです。
• --output：出力画像ファイルのパスです。

オプションのパラメーター

• --element-id：スクリーンショットを撮る要素の id です。元の id 値を渡し、# は付けないでください。
• --image-type：png と jpeg をサポートしています。
• --device-scale-factor：デバイスのピクセル比です。値を大きくすると鮮明になりますが、通常は画像のサイズも大きくなります。
• --viewport-width / --viewport-height：レンダリングするビューポートのサイズです。
• --render-wait-ms：スクリーンショットを撮る前の追加待機時間です。フォントや画像などの非同期リソースの読み込みを待つ場合に適しています。
• --element-padding：--element-id を指定した場合に、スクリーンショット領域に追加する余白です。デフォルト値は 0 です。

注意事項

• 実行環境で npx が利用可能である必要があります。
• HTML で画像リソースを使用する場合は、パブリックにアクセス可能な画像リンクを使用してください。ローカルの画像パスには対応していません。
• 出力ファイルの拡張子は、--image-type と一致させてください。
• スクリーンショット領域のサイズに、対象の HTML 全体が収まるか確認してください。特に、カードの幅や高さがデフォルトのビューポートを超える場合は、スクリーンショットの切り取りや画像の欠落を防ぐため、--viewport-width と --viewport-height を明示的に調整する必要があります。
• デフォルトのレンダリング結果で要件を満たせない場合にのみ、ビューポートと待機時間のパラメーターを調整してください。ただし、HTML 自体の設計サイズがデフォルトのビューポートを超える場合は、まずビューポートを対象要素のサイズ以上に調整してください。
• API が 400 を返す場合、通常は element_id に対応する要素が存在しません。
• API が 422 を返す場合、通常はパラメーターの範囲が不正です。