Microsoft Edge WebView2 Delphi

· コンポーネント
Microsoft Edge WebView2 Delphi | eSeGeCe ブログ

TsgcWebView2 は Microsoft Edge WebView2 をラップする新しいビジュアル Delphi コンポーネントで、VCL アプリケーション内でモダンな Chromium ベースのブラウザエンジンを利用できます。フォームにドロップして URL を設定するだけで、Cookie 管理・ダウンロード制御・JavaScript 統合・印刷サポートなどを備えた高機能な組み込みブラウザが完成します。

最近の Delphi バージョンに付属する組み込みの TEdgeBrowser とは異なり、TsgcWebView2 は Delphi 7 から Delphi 13 Florence までのすべての Delphi バージョンをサポートしており、利用可能な WebView2 ラッパーの中で最も広いバージョンサポートを誇ります。eSeGeCe の sgcWebSockets ライブラリの一部です。

この記事では、機能セット、実用的なコード例、TEdgeBrowser との詳細な比較、および内部アーキテクチャについて解説します。

機能概要

TsgcWebView2 は WebView2 SDK の広範な機能をクリーンな Delphi イベントとメソッドで公開します。以下は12の主要な機能グループです：

ナビゲーション
Navigate、GoBack、GoForward、Reload、Stop をサポート。カスタムヘッダーとリクエストボディを使用した POST ナビゲーションにも対応。 		JavaScript 実行
JavaScript を非同期または同期で実行できます。すべてのページ読み込み時に自動実行される初期スクリプトを登録可能。 		Cookie 管理
プログラムで Cookie の取得・追加・更新・削除が可能。ドメイン・パス・有効期限などの Cookie 属性に完全アクセス。
ダウンロード制御
ダウンロードの開始・進行・完了のイベントを提供。ダウンロード先のカスタムパスへのリダイレクトや完全なキャンセルが可能。 		プロファイル管理
分離されたブラウジングセッションのマルチプロファイルサポート。プロファイルごとにブラウジングデータ（キャッシュ・Cookie・履歴）をクリア可能。 		印刷サポート
現在のページを PDF に印刷またはシステム印刷ダイアログを表示。用紙サイズ・向き・余白を制御可能。
音声・ミュート制御
ドキュメントが音声を再生しているかどうかを検出。システム音量に影響せずプログラムでミュート状態を切り替え可能。 		証明書処理
専用イベントを通じてクライアント証明書リクエストとサーバー証明書エラーに対応。 		コンテキストメニュー
右クリックコンテキストメニューのインターセプトと完全カスタマイズが可能。独自のアクションでメニュー項目の追加・削除・置換ができます。
Favicon アクセス
現在のページの Favicon URI を取得。専用イベントで Favicon の変更に反応。 		仮想ホストマッピング
カスタムホスト名をローカルフォルダにマッピング。ローカルの HTML/CSS/JS ファイルを実際の Web サーバーから提供するかのように配信。 		スクリーンショット撮影
表示中のページコンテンツを PNG または JPEG 画像として保存。サムネイル・レポート・自動テストに便利。

はじめに

TsgcWebView2 を使用する最も簡単な方法は、VCL フォームにドロップして Navigate を呼び出すことです。コンポーネントは WebView2 環境の作成・コントローラーの初期化・ビューのバインドを自動的に処理します。

// Drop TsgcWebView2 on your form, then:
procedure TForm1.FormCreate(Sender: TObject);
begin
  sgcWebView2.Navigate('https://www.example.com');
end;
procedure TForm1.sgcWebView2NavigationCompleted(Sender: TObject;
  aIsSuccess: Boolean; aWebErrorStatus: Integer);
begin
  if aIsSuccess then
    Caption := sgcWebView2.DocumentTitle;
end;

OnNavigationCompleted イベントはページの読み込みが完了した後に発火し、ナビゲーションの成否とエラーステータスコードを報告します。読み込まれたページに基づいて UI（ウィンドウタイトル・ステータスバー・戻る/進むボタンの状態）を更新する自然な場所です。

注意。 コンポーネントは最初の使用時に遅延して WebView2 環境を作成します。環境オプション（ブラウザフォルダ・言語・コマンドラインスイッチ）を設定する必要がある場合は、Navigate を呼び出す前に EnvironmentOptions プロパティで設定してください。

CookieManager サブオブジェクトは WebView2 の完全な Cookie API を公開します。現在の URL の Cookie 一覧表示、特定の属性を持つ Cookie の追加・更新、個別の Cookie の削除や一括クリアが可能です。

// List cookies for the current page
sgcWebView2.CookieManager.GetCookies(sgcWebView2.URL);
// Delete all cookies
sgcWebView2.CookieManager.DeleteAllCookies;
// Add a cookie
sgcWebView2.CookieManager.AddOrUpdateCookie(
  'session', 'abc123', '.example.com', '/');

GetCookies を呼び出すと、結果は OnCookiesReceived イベントに非同期で届きます。各 Cookie には名前・値・ドメイン・パス・有効期限・セキュアフラグ・HTTP-only フラグが含まれます。これは TEdgeBrowser がまったく公開していない機能の一つです。

ヒント。 AddOrUpdateCookie を使用して保護されたページに移動する前に認証トークンを注入してください。これにより組み込みブラウザシナリオでのログインフローが不要になります。

JavaScript 統合

TsgcWebView2 は JavaScript 実行に3つのアプローチを提供しており、それぞれ異なるユースケースに適しています：

非同期実行

ExecuteScript を呼び出し、OnScriptExecuted イベントで結果を処理します。これは標準的なノンブロッキングアプローチです。

// Async execution — result arrives in OnScriptExecuted event
sgcWebView2.ExecuteScript('document.title');
procedure TForm1.sgcWebView2ScriptExecuted(Sender: TObject;
  const aResult: string; aErrorCode: Integer);
begin
  if aErrorCode = 0 then
    ShowMessage('Title: ' + aResult);
end;

同期実行

結果をすぐに必要とする場合は ExecuteScriptSync を使用します。スクリプトが完了するまで呼び出しスレッドをブロックし、結果を直接返します。

var
  vTitle: string;
begin
  vTitle := sgcWebView2.ExecuteScriptSync('document.title');
  Caption := vTitle;
end;

初期スクリプト

初期スクリプトは一度登録するとすべてのページ読み込みで自動実行されます。ページの JavaScript より先に実行されるため、グローバル設定やポリフィルの注入に最適です。

// Runs on every page load, before any page scripts
sgcWebView2.AddInitScript('window.appVersion = "1.0";');

ダウンロード管理

ダウンロードはイベント駆動モデルで処理されます。ダウンロードが開始すると、OnDownloadStarting イベントでファイルをカスタムパスにリダイレクト、キャンセル、またはデフォルト処理で続行できます。ダウンロードが完了すると別の OnDownloadCompleted イベントが発火します。

procedure TForm1.sgcWebView2DownloadStarting(Sender: TObject;
  const aURI, aResultFilePath: string;
  var aCancel: Boolean;
  var aHandled: Boolean;
  var aFilePath: string);
begin
  // Redirect download to custom folder
  aFilePath := 'C:\Downloads\' + ExtractFileName(aResultFilePath);
  aHandled := True;
end;
procedure TForm1.sgcWebView2DownloadCompleted(Sender: TObject;
  const aFilePath: string; aState: Integer);
begin
  ShowMessage('Download complete: ' + aFilePath);
end;

注意。 OnDownloadCompleted の aState パラメーターはダウンロードが成功・キャンセル・エラーのいずれであるかを示します。ダウンロードファイルを処理する前にこの値を確認してください。

POST ナビゲーションとカスタムヘッダー

標準のナビゲーションは GET リクエストで URL を読み込みます。API テスト・フォーム送信・異なる HTTP メソッドが必要なシナリオでは、NavigateWithPostData を使用してメソッド・ボディ・ヘッダーを一度の呼び出しで指定できます。

// Navigate with POST data and custom headers
sgcWebView2.NavigateWithPostData(
  'https://api.example.com/submit',
  'POST',
  '{"key":"value"}',
  'Content-Type: application/json' + #13#10 +
  'Authorization: Bearer token123'
);

ヘッダーパラメーターは HTTP ヘッダーと同じ形式の CRLF 区切り文字列を受け付けます。認証トークン・コンテンツタイプ・サーバーが期待するカスタムヘッダーの注入に便利です。

TEdgeBrowser との比較

Delphi には Delphi 10.4 Sydney から TEdgeBrowser が付属しています（XE7+ では GetIt 経由で利用可能）。基本的な WebView2 ラッパーを提供しますが、多くの SDK 機能が公開されていません。以下の表は TsgcWebView2 がどこで優れているかを正確に示します。

機能 TEdgeBrowser TsgcWebView2
Delphi バージョンサポート XE7+ only D7 through D13
Cookie 管理 ✗ ✓ Full API
ダウンロード進行イベント ✗ ✓ 開始 / 進行 / 完了
プロファイル / ブラウジングデータのクリア ✗ ✓
音声 / ミュート制御 ✗ ✓
Favicon アクセス ✗ ✓
証明書イベント ✗ ✓
Basic 認証イベント ✗ ✓
ステータスバーテキスト ✗ ✓
仮想ホストマッピング ✗ ✓
共有バッファ ✗ ✓
同期 ExecuteScript ✓ ✓
スクリーンショット撮影 ✓ ✓
初期スクリプト ✓ ✓
POST ナビゲーション ✓ ✓
印刷サポート ✓ ✓
デザイン時設定 WebView 未作成時に例外をスロー ✓ 安全な TPersistent プロパティ
コンテキストメニュー PopupMenu マージ 完全なイベント制御
グレースフルデグラデーション ✗ ✓ 機能別バージョンチェック
Raw COM アクセス ✓ ✓

TsgcWebView2 は TEdgeBrowser が提供するすべての機能をカバーし、さらに12の機能を追加しています。Cookie 管理・ダウンロードイベント・プロファイル制御・音声/ミュート・Favicon アクセス・証明書処理・Basic 認証イベント・ステータスバーテキスト・仮想ホストマッピング・共有バッファ・完全なコンテキストメニュー制御・グレースフルデグラデーションです。Delphi 7 以降のバージョンもサポートしており、TEdgeBrowser が XE7 以降を要件とするのと対照的です。

重要。 TEdgeBrowser は設定を COM インターフェースに直接保存します。WebView2 環境が作成される前にデザイン時にプロパティを設定するとアクセス違反が発生します。TsgcWebView2 は設定をバッファリングして環境準備後に適用する TPersistent サブオブジェクトを使用することでこれを完全に回避します。

高度な機能

PDF への印刷

単一のメソッド呼び出しで現在のページの PDF を生成します。出力ファイルは非同期で作成され、パラメーターで用紙サイズ・余白・向きを制御できます。

sgcWebView2.PrintToPdf('C:\output\page.pdf');

スクリーンショット撮影

ページの表示領域を PNG または JPEG 画像として撮影します。第2パラメーターで画像形式を指定します：PNG は 0、JPEG は 1。

sgcWebView2.CapturePreviewToFile('C:\screenshots\page.png', 0); // 0 = PNG

仮想ホストマッピング

カスタムホスト名をローカルフォルダにマッピングし、組み込みブラウザが標準の HTTPS URL でローカルファイルを読み込めるようにします。CORS の問題を回避し、ローカルコンテンツをリモートコンテンツとまったく同じように動作させます。

// Serve local files via https://app.local/
sgcWebView2.SetVirtualHostNameToFolderMapping(
  'app.local', 'C:\MyApp\WebContent', 1);
sgcWebView2.Navigate('https://app.local/index.html');

ヒント。 仮想ホストマッピングはシングルページアプリケーションに特に便利です。HTML・CSS・JavaScript を Delphi アプリケーションにバンドルし、マッピングされたホスト名で読み込むことで、セキュアオリジンが必要な Web API に完全アクセスできます。

音声とミュート制御

読み込まれたドキュメントが音声を再生しているかを検出し、システム音量に影響せずにミュートを切り替えます。メディアが多いコンテンツを埋め込むアプリケーションに便利です。

sgcWebView2.IsMuted := True;
if sgcWebView2.IsDocumentPlayingAudio then
  ShowMessage('Audio is playing');

アーキテクチャと設計

TsgcWebView2 は、開発者向け API をシンプルに保ちながら懸念事項を分離するクリーンな3層アーキテクチャで構築されています：

コンポーネントでまだラップされていない SDK 機能へのアクセスが必要なパワーユーザーは、WebView・Controller・Environment プロパティから Raw COM インターフェースを利用できます。コンポーネントのライフサイクル管理の恩恵を受けながら、任意の COM メソッドを直接呼び出せます。

グレースフルデグラデーション

すべての WebView2 機能が Edge ランタイムのすべてのバージョンで利用可能なわけではありません。TsgcWebView2 は起動時にインストールされたランタイムバージョンを確認し、機能を呼び出す前に利用可能かどうかを照会できる Supports() メソッドを提供します。これにより古い Edge バージョンを持つマシンでのランタイムエラーを防止します。

デザイン時の安全性

すべての設定可能な設定は TPersistent サブオブジェクトとして公開されています。COM 初期化をトリガーせずに、Object Inspector でデザイン時に安全にコンポーネントを設定できます。設定はバッファリングされ、実行時に WebView2 環境が作成されたときに自動的に適用されます。

要件

TsgcWebView2 をアプリケーションで使用するには、以下が必要です：

注意。 コンポーネントを作成する前に WebView2 ランタイムがインストールされているかどうかを確認できます。存在しない場合は、ユーザーにインストールを案内するか、代替のブラウザコントロールにフォールバックできます。

まとめ

TsgcWebView2 は Delphi で利用可能な最も完全な WebView2 ラッパーです。TEdgeBrowser の厳密なスーパーセットであり、Embarcadero の組み込みコンポーネントが公開していない12の機能を追加しています。Cookie 管理・ダウンロードイベント・プロファイル制御・音声検出・Favicon アクセス・証明書処理・Basic 認証・ステータスバーテキスト・仮想ホストマッピング・共有バッファ・完全なコンテキストメニュー制御・グレースフルデグラデーションです。

Delphi 7 から Delphi 13 Florence まで、いずれの WebView2 ラッパーよりも広い Delphi バージョン範囲をサポートしています。古いコンパイラでレガシーアプリケーションを保守している場合でも、最新の Delphi で新しいプロジェクトを構築している場合でも、同じコンポーネントと同じ API がどこでも動作します。

API は学習しやすく設計されています — フォームにコンポーネントをドロップし、Navigate を呼び出して、イベントを処理するだけです — 一方で、Raw COM アクセスと機能別バージョンチェックを通じた高度なシナリオにも対応できる十分な機能を備えています。モダンな組み込みブラウザが必要な Delphi 開発者には、TsgcWebView2 が自然な選択です。