snapdom

SnapDOM スキル

HTML 要素をスケーラブルな SVG またはラスター画像形式に変換する、高速で依存関係のない DOM 画像キャプチャライブラリです。

このスキルを使用する場面

次のような場合に SnapDOM を使用します。

• HTML 要素を画像（SVG、PNG、JPG、WebP）に変換する
• 疑似要素やシャドウを含む、スタイルが適用された DOM をキャプチャする
• フォントやアイコンを埋め込んで要素を書き出す
• カスタムサイズや倍率でスクリーンショットを作成する
• プロキシのフォールバックを使用して、CORS によってブロックされたリソースに対応する
• プラグインを使ってカスタムレンダリングパイプラインを実装する
• 大きな要素や複雑な要素のパフォーマンスを最適化する

主な機能

多様な書き出し形式

• SVG - すべてのスタイルを埋め込む、スケーラブルなベクター形式
• PNG、JPG、WebP - 品質を設定できるラスター形式
• Canvas - 後続処理に利用できる生の Canvas 要素を取得
• Blob - 独自の処理に利用できる生のバイナリデータ

パフォーマンス

• 超高速キャプチャ（小さな要素では 1.6ms、4000×2000 では約 171ms）
• 依存関係なし - 標準の Web API のみを使用
• 複雑な要素では html2canvas を 10～40 倍上回るパフォーマンス

スタイルのサポート

• 埋め込みフォント（アイコンフォントを含む）
• CSS 疑似要素（::before、::after）
• CSS カウンター
• CSS line-clamp
• Transform とシャドウの効果
• Shadow DOM のコンテンツ

高度な機能

• 同一オリジンの iframe に対応
• ブロックされたアセット向けの CORS プロキシフォールバック
• カスタム変換用のプラグインシステム
• Transform の補正（rotate/translate を削除）
• 特定の要素の除外
• タイトなバウンディングボックスの計算

インストール

NPM/Yarn

npm install @zumer/snapdom
# or
yarn add @zumer/snapdom

CDN（ES モジュール）

<script type="module">
  import { snapdom } from "https://unpkg.com/@zumer/snapdom/dist/snapdom.mjs";
</script>

CDN（UMD）

<script src="https://unpkg.com/@zumer/snapdom/dist/snapdom.umd.js"></script>

クイックスタートの例

再利用可能な基本キャプチャ

// Create reusable capture object
const result = await snapdom(document.querySelector('#target'));

// Export to different formats
const png = await result.toPng();
const jpg = await result.toJpg();
const svg = await result.toSvg();
const canvas = await result.toCanvas();
const blob = await result.toBlob();

// Use the result
document.body.appendChild(png);

1 ステップで書き出し

// Direct export without intermediate object
const png = await snapdom.toPng(document.querySelector('#target'));
const svg = await snapdom.toSvg(element);

要素をダウンロード

// Automatically download as file
await snapdom.download(element, 'screenshot.png');
await snapdom.download(element, 'image.svg');

オプションの指定

const result = await snapdom(element, {
  scale: 2,                    // 2x resolution
  width: 800,                  // Custom width
  height: 600,                 // Custom height
  embedFonts: true,            // Include @font-face
  exclude: '.no-capture',      // Hide elements
  useProxy: true,              // Enable CORS proxy
  straighten: true,            // Remove transforms
  noShadows: false             // Keep shadows
});

const png = await result.toPng({ quality: 0.95 });

主なオプションの一覧

オプション	型	目的
scale	Number	出力の倍率を設定します（例：2 は解像度 2 倍）
width	Number	出力幅をピクセル単位で指定します
height	Number	出力高さをピクセル単位で指定します
embedFonts	Boolean	アイコン以外の @font-face ルールを含めます
useProxy	String|Boolean	CORS プロキシを有効にします（URL、またはデフォルトを使用する場合は true）
exclude	String	非表示にする要素の CSS セレクター
straighten	Boolean	translate/rotate の Transform を削除します
noShadows	Boolean	シャドウ効果を取り除きます

よく使われるパターン

レスポンシブなスクリーンショット

// Capture at different scales
const mobile = await snapdom.toPng(element, { scale: 1 });
const tablet = await snapdom.toPng(element, { scale: 1.5 });
const desktop = await snapdom.toPng(element, { scale: 2 });

要素の除外

// Hide specific elements from capture
const png = await snapdom.toPng(element, {
  exclude: '.controls, .watermark, [data-no-capture]'
});

固定サイズ

// Capture with specific size
const result = await snapdom(element, {
  width: 1200,
  height: 630  // Standard social media size
});

CORS への対応

// Fallback for CORS-blocked resources
const png = await snapdom.toPng(element, {
  useProxy: 'https://cors.example.com/?' // Custom proxy
});

プラグインシステム（ベータ）

// Extend with custom exporters
snapdom.plugins([pluginFactory, { colorOverlay: true }]);

// Hook into lifecycle
defineExports(context) {
  return {
    pdf: async (ctx, opts) => { /* generate PDF */ }
  };
}

// Lifecycle hooks available:
// beforeSnap → beforeClone → afterClone →
// beforeRender → beforeExport → afterExport

パフォーマンス比較

SnapDOM は html2canvas を大幅に上回るパフォーマンスを発揮します。

シナリオ	SnapDOM	html2canvas	改善率
小（200×100）	1.6ms	68ms	42 倍高速
中（800×600）	12ms	280ms	23 倍高速
大（4000×2000）	171ms	1,800ms	10 倍高速

開発

セットアップ

git clone https://github.com/zumerlab/snapdom.git
cd snapdom
npm install

ビルド

npm run compile

テスト

npm test

ブラウザーのサポート

• Chrome/Edge 90+
• Firefox 88+
• Safari 14+
• モバイルブラウザー（iOS Safari 14+、Chrome Mobile）

リソース

ドキュメント

• 公式ウェブサイト： https://snapdom.dev/
• GitHub リポジトリ： https://github.com/zumerlab/snapdom
• NPM パッケージ： https://www.npmjs.com/package/@zumer/snapdom
• ライセンス： MIT

scripts/

自動化用のヘルパースクリプトをここに追加します。例：

• batch-screenshot.js - 複数の要素をキャプチャ
• pdf-export.js - スナップショットを PDF に変換
• compare-outputs.js - SVG と PNG の品質を比較

assets/

テンプレートと例を追加します。

• 一般的なキャプチャシナリオ向けの HTML テンプレート
• snapdom を事前設定した CSS フレームワーク
• snapdom を統合したボイラープレートプロジェクト

関連ツール

• html2canvas - DOM キャプチャの代替ツール（速度は遅いものの、互換性は高めです）
• Orbit CSS Toolkit - Zumerlab による関連ツールキット（https://github.com/zumerlab/orbit）

ヒントとベストプラクティス

1. パフォーマンス：パフォーマンスを向上させるには、width／height の代わりに scale を使用します。
2. フォント：カスタムフォントを正しく表示するには、embedFonts: true を設定します。
3. CORS の問題：画像を読み込めない場合は、useProxy: true を使用します。
4. 大きな要素：複雑なページでは、要素を小さなチャンクに分割します。
5. 品質：PNG／JPG では、最高品質を得るために quality: 0.95 を使用します。
6. SVG ベクター：チャートやグラフィックには SVG エクスポートを推奨します。

トラブルシューティング

要素がレンダリングされない

• 要素に十分な高さ／幅があるか確認します。
• キャプチャの前に CSS がすべて読み込まれていることを確認します。
• トランスフォームが問題の原因になっている場合は、straighten: false を試します。

フォントが見つからない

• embedFonts: true を設定します。
• snapdom を呼び出す前にフォントが読み込まれていることを確認します。
• ブラウザーのコンソールでフォントの読み込みエラーを確認します。

CORS の問題

• useProxy: true を有効にします。
• デフォルトのプロキシで失敗する場合は、カスタムプロキシ URL を使用します。
• リソースが同一オリジンから読み込まれているか確認します。

パフォーマンスの問題

• scale の値を小さくします。
• シャドウのレンダリングをスキップするには、noShadows: true を使用します。
• 大規模なキャプチャは、小さなセクションに分割することを検討します。