HTML要素を画像に変換するライブラリ：dom-to-image vs html-to-image vs html2canvas

フロントエンド開発で「画面の一部を画像として保存したい」という要件はよくあります。例えば、グラフの共有、レポート出力、ユーザー生成コンテンツのプレビューなどです。そのようなニーズを満たす代表的なnpmパッケージが dom-to-image、html-to-image、html2canvas です。これらは似た目的を持ちますが、内部実装、対応範囲、メンテナンス状況に大きな違いがあります。この記事では、実際のコード例を交えながら、各ライブラリの特性と選定基準を解説します。

⚠️ メンテナンス状況：非推奨かどうかが重要

まず最初に確認すべきは、パッケージが現在もアクティブにメンテナンスされているかです。

• dom-to-image は npmページ および GitHubリポジトリ で明確に 非推奨（deprecated） とされています。作者は後継として html-to-image を推奨しています。新規プロジェクトでの使用は避けてください。

• html-to-image は dom-to-image のフォークであり、GitHubリポジトリ は活発に更新されており、TypeScript定義やモダンなツールチェーンをサポートしています。

• html2canvas は長年利用されてきた成熟したライブラリで、公式サイト も整備されており、定期的に更新されています。

💡 新規プロジェクトでは、dom-to-image は選択肢から外しましょう。

🖼️ 基本的な使い方：10行で画像生成

各ライブラリの基本的な使い方を比較します。対象は <div id="capture">Hello World</div> という要素とします。

dom-to-image（非推奨）

import domtoimage from 'dom-to-image';

const node = document.getElementById('capture');
domtoimage.toPng(node)
  .then(dataUrl => {
    const img = new Image();
    img.src = dataUrl;
    document.body.appendChild(img);
  });

html-to-image

import { toPng } from 'html-to-image';

const node = document.getElementById('capture');
toPng(node)
  .then(dataUrl => {
    const img = new Image();
    img.src = dataUrl;
    document.body.appendChild(img);
  });

html2canvas

import html2canvas from 'html2canvas';

const node = document.getElementById('capture');
html2canvas(node).then(canvas => {
  const img = new Image();
  img.src = canvas.toDataURL();
  document.body.appendChild(img);
});

見た目は似ていますが、内部の処理は大きく異なります。

🔧 内部実装：SVG vs Canvas

dom-to-image / html-to-image：SVG経由の描画

これらのライブラリは、DOM要素を一時的にSVGに変換し、そのSVGをCanvasに描画して画像データURLを生成します。この方式の利点は、CSSスタイルやWebフォントを比較的正確に再現できることです。

// html-to-image の内部処理イメージ
// 1. DOM → SVG文字列（インラインスタイル付き）
// 2. SVGをBlob URLに変換
// 3. そのURLをImage要素で読み込み
// 4. Canvasに描画 → toDataURL()

ただし、iframe、動的Canvas、video要素などはサポートされません。また、CORSで保護された外部画像は描画されない可能性があります。

html2canvas：CanvasによるDOM再現

html2canvas はブラウザのレンダリングエンジンを模倣し、Canvas APIを使ってDOMノードを1つずつ描画します。つまり、実際のスクリーンショットではなく「再現」 です。

この方式の利点は、iframe以外のほとんどのHTML要素を扱えることです。ただし、以下の制限があります：

• box-shadow、transform、filter などの一部CSSプロパティが正しく描画されない
• 外部ドメインの画像やフォントはCORS設定がないと表示されない
• 動的なCanvasやWebGLコンテンツはキャプチャ不可

🎨 スタイルとフォントの再現性

Webフォントの扱い

html-to-image は、fontEmbedCss オプションでGoogle FontsなどのWebフォントを自動埋め込みます。

import { toPng } from 'html-to-image';

toPng(node, {
  fontEmbedCss: true // デフォルトで有効
});

一方、html2canvas は useCORS: true オプションを指定することで、CORSヘッダー付きのフォント/画像を読み込もうとしますが、サーバー側の設定が必須です。

html2canvas(node, {
  useCORS: true
});

複雑なCSS（例：clip-path）

clip-path や mask といった高度なCSSプロパティは、html-to-image ではSVG互換のもののみ動作し、html2canvas では未対応です。どちらも完全な再現は難しいため、事前に検証が必要です。

📦 オプションとカスタマイズ性

画像形式と品質

• html-to-image は toPng()、toJpeg()、toSvg()、toCanvas() を提供。JPEGでは品質調整可能。

// JPEGで品質80%
toJpeg(node, { quality: 0.8 });

• html2canvas は常にCanvasを返すため、toDataURL('image/jpeg', 0.8) で形式と品質を指定。

html2canvas(node).then(canvas => {
  const dataUrl = canvas.toDataURL('image/jpeg', 0.8);
});

要素の除外や変更

html2canvas は ignoreElements オプションで特定の要素を除外できます。

html2canvas(node, {
  ignoreElements: (el) => el.classList.contains('no-screenshot')
});

html-to-image は skipFonts や cacheBust などの細かい制御が可能ですが、要素単位の除外はできません。代わりに、一時的にDOMを操作してからキャプチャする必要があります。

🚀 パフォーマンスと大規模DOM

• 小〜中規模DOM（例：カード、チャート）：html-to-image が高速で軽量。
• 大規模DOM（例：長文ドキュメント、ダッシュボード）：html2canvas がより安定。ただし、描画時間がかかる場合あり。

html2canvas は scale オプションで解像度を調整でき、高DPIディスプレイ向けに高品質画像を生成可能です。

html2canvas(node, {
  scale: 2 // 通常の2倍の解像度
});

🔄 実際の開発シーンでの選定ガイド

ケース1：シンプルなUIカードをPNGで共有

• ✅ 推奨: html-to-image
• 理由: 軽量、CSS再現性が高い、APIが直感的

import { toPng } from 'html-to-image';

const download = async () => {
  const dataUrl = await toPng(document.getElementById('card'));
  const link = document.createElement('a');
  link.download = 'card.png';
  link.href = dataUrl;
  link.click();
};

ケース2：iframeを含むダッシュボード全体をキャプチャ

• ❌ html-to-image はiframe非対応
• ✅ 推奨: html2canvas（ただしiframe内は空白になる）
• 注意: iframe内のコンテンツは別途キャプチャして合成する必要がある

ケース3：アニメーション中のCanvas要素を含むゲーム画面

• ❌ いずれのライブラリも動的Canvasの内容を直接キャプチャできない
• 対応策: Canvas自体を toDataURL() で取得し、別途合成

📌 まとめ：各ライブラリの特徴

💡 最終的なアドバイス

• 新規プロジェクトでは、まず html-to-image を試してください。シンプルで再現性が高く、TypeScript対応も万全です。
• 複雑なレイアウトや大量のDOM要素がある場合は、html2canvas の挙動を検証しましょう。特に、CSSの制限を事前に把握することが重要です。
• dom-to-image は絶対に新規で使わないでください。既存コードがある場合も、可能なら html-to-image への移行を検討しましょう。

どのライブラリを選ぶにせよ、実際のターゲット環境（ブラウザ、OS、DPR）で必ずテストすることを忘れないでください。画像の再現性は環境によって大きく変わるためです。