TEdgeBrowser コンポーネントの利用と TWebBrowser コンポーネントへの変更点
VCL への移動
RAD Studio 10.4 Sydney では、新しい TEdgeBrowser コンポーネントにより、VCL アプリケーションにおける Chromium ベースの Edge WebView2 ブラウザ コントロールを介した、Web コンテンツでの作業がサポートされました。
TEdgeBrowser は TWebBrowser （Internet Explorer WebBrowser ブラウザ コントロールを使用）に代わるものです。しかし TWebBrowser は、一部顕著な変更はありますが、VCL コンポーネント セットに存続します。
目次
Edge Browser コンポーネント利用の準備
TWebBrowser はオペレーティング システム供給の Internet Explorer WebBrowser ブラウザ コントロールであるため、準備は特に必要としません。Windows が Internet Explorer コントロールを使用できる場所であればどこでも機能します。
反対に、Microsoft Edge はまずオペレーティング システムのコンポーネントではありません。このため、それらを使用するアプリケーションを実行する前には、次のものがコンピュータにインストールされていることを確認する必要があります。
- Microsoft Edge Chromium ベース ブラウザ。現在、https://www.microsoftedgeinsider.com/download から入手可能です（WebView2 SDK がプレリリースされている間の Canary チャネル版、現在最低限必要なバージョンは82.0.430.0です）。
- WebView2 コントロール。現在、NuGet で https://www.nuget.org/packages/Microsoft.Web.WebView2 から、もしくは GetIt パッケージ マネージャから入手可能です。
これは、開発マシン上のアプリケーションのコンパイルと実行に、そしてエンド ユーザーのマシンにも適用されます。
これら両方がインストールされた状態で、TEdgeBrowser は機能し、Edge WebView2 ブラウザ コントロールを使用して Web コンテンツをレンダリングすることができます。
新しいパブリック プロパティ UserDataFolder により、開発者はキャッシュに使用されるフォルダを定義することができます。 このプロパティは、URL に移動し、コンポーネントを有効にする前に設定される必要があります。
GetIt で Edge WebView2 パッケージをインストールする
Microsoft WebView2 パッケージをインストールするには、GetIt パッケージ マネージャ ウィンドウを RAD Studio IDE で開き、該当するエントリを検索します：
ライセンス契約を承諾すると、GetIt はパッケージをダウンロードし、2 つの WebView2 ローダー DLL（32 ビット用と 64 ビット用） を該当する Redist フォルダにコピーします。GetIt ログは次のようになります：
それらのファイルを対象の EXE ディレクトリにコピーするか、パス上のフォルダにコピーし、 以降のセクション「WebView2 ローダー DLL のプロジェクト設定」での手順に従います。
NuGet から Edge WebView2 パッケージを手動でインストールする
Edge WebView2 ブラウザ コントロールは、https://www.nuget.org/packages/Microsoft.Web.WebView2 の名前 Microsoft.Web.WebView2 以下にある NuGet から入手可能です。コンポーネントは現在、バージョン 0.9.430 で記述されています。
このページ https://www.nuget.org/packages/Microsoft.Web.WebView2/0.9.430 では、［Download］パッケージ リンクをクリックして、microsoft.web.webview2.0.9.430.nupkg をダウンロードすることができます。
.nupkg ファイルは実際のところは、さまざまなファイル拡張子を持つ単なる .zip ファイルであるため、 microsoft.web.webview2.0.9.430.zip に名前を変更することができ、Windows ファイル エクスプローラでコンテンツを抽出したり、7zip を使用してコンテンツを抽出したり、必要なファイルを取得することができます。
このパッケージから必要なファイルは WebView2Loader.dll です。Win32 アプリケーションを構築する場合には、build\x86\WebView2Loader.dll を取得する必要があり、Win64 アプリケーションの場合には、build\x64\WebView2Loader.dll が必要となります。
WebView2 ローダー DLL のプロジェクト設定
WebView2 ローダー DLL をどこに置く場合でも、、post-build イベントを設定し、それをプロジェクトの出力ディレクトリにコピーされるようにする必要があります。
Win32 ターゲットの場合、post-build イベントは次のようになります：
copy /Y "common_DLL_folder_path\x86\WebView2Loader.dll" $(OUTPUTDIR)
Win64 ターゲットの場合：
copy /Y "common_DLL_folder_path\x64\WebView2Loader.dll" $(OUTPUTDIR)
WebView2 のカスタム バージョンの利用
デフォルトでは、コンポーネントはシステム上の WebView2 コントロールの現在のバージョンを使用します。 これを、新しいパブリック プロパティ BrowserExecutableFolder を、ライブラリの場所を参照するように設定することで、特定のバージョンを使用することができます。
Edge ブラウザ コンポーネントの利用
TEdgeBrowser コンポーネントは、TWebBrowser を使用するのと同様の方法で利用することができます。これは、数多くの TEdgeBrowser のメソッドとプロパティが、TWebBrowser のメソッドとプロパティと同じだからです。
コンポーネントを VCL フォーム上に配置し、そのサイズを適切に調整します。
URL を遷移するには、シンプルにその URL を Navigate メソッドに渡します。
WebView2 コントロールは、非同期に作成される点に注意してください。 この作成は、Navigate メソッドを呼び出すか、CreateWebView メソッドを呼び出すことで開始できます。 WebViewCreated を適切に使用することで、コントロールが正常に作成されたかどうか、いつでも伝えることができます。
これは、アプリケーションを実行する最低限のサンプルで、コードは 1 行のみ、その他の設定は変更していません：
さらに、OnCreateWebViewCompleted イベント ハンドラを使用することができ、これは、コントロール作成が完了した際に、成功、失敗にかかわらず、呼び出されます。
OnCreateWebViewCompleted イベント ハンドラがなく、WebView2 ブラウザ コントロールが初期化できない場合、EEdgeError 例外が main スレッドで発生しますが、ワーカー スレッドから main スレッドに同期がとられます。
このため、グローバル例外ハンドラ（たとえば、TApplicationEvents コンポーネントの OnException イベント ハンドラなど）を使用せずに捕捉するのは難しいため、OnCreateWebViewCompleted イベント ハンドラがこのような状況をシンプルにするためにも推奨されます。
イベント ハンドラを設定できる追加イベントはまだあります。これらは主に、基となる WebView2 ブラウザ コントロールからの表層イベントです。たとえば、ある URL へ遷移すると、OnNavigationStarting イベントはターゲット ページ コンテンツに基づいて 1 回以上発生します。ある URL への遷移が完了すると、OnNavigationCompleted イベントが発生します。
キャッシュ管理
RAD Studio 10.4.2 では、新しいパブリック プロパティ UserDataFolder が導入されています。 この新しいプロパティにより、開発者は、キャッシュで使用されるフォルダを定義することができます。 このプロパティは、URL に移動し、コンポーネントを有効にする前に設定される必要があります。
TEdgeBrowser のヒント
さらに TEdgeBrowser は、Edge WebView2 ブラウザ コントロールを使用できるすぐれたツールですが、いくつか制限もあります。 このため、よりよいパフォーマンスのためには、次のヒントを念頭においておいてください：
- WebView2 ランタイムを必ずインストールする。ローカル開発でも GetIt インストーラでは十分でない場合があります。
- Microsoft には、必須の WebView2 ランタイム ファイルのメインストリーム ディストリビューションがあります（インストーラはこちら）。
TWebBrowser から TEdgeBrowser への移行
従来の TWebBrowser コンポーネントから新しい Edge ベースの TEdgeBrowser コンポーネントに移行するには、現在使用している TWebBrowser のメソッド、プロパティ、イベントを見積もる必要があります。
TWebBrowser と TEdgeBrowser の公開されたインターフェイスにはいくつか共通性がありますが、合理的に絞られています。
以下の表は、今回の変更にあたり、クラス メンバーの中で最も近い「同等のもの」を表しています。
TEdgeBrowser が基盤として使用しているブラウザ コントロールである、WebView2 ブラウザ コントロールは、その多くが、TWebBrowser VCL コンポーネントを基とする Internet Explorer WebBrowser ブラウザ コントロールよりも、より狭いフォーカスを持つ、より少ないイベントを公開しています。
メソッド
|
TWebBrowser メソッド |
TEdgeBrowser メソッド |
|
GoBack |
GoBack |
|
GoForward |
GoForward |
|
GoHome |
該当なし |
|
GoSearch |
該当なし |
|
Navigate |
Navigate |
|
Navigate2 |
Navigate |
|
Refresh |
Refresh |
|
Refresh2 |
Refresh |
|
Stop |
Stop |
|
Quit |
CloseBrowserProcess |
|
ClientToWindow |
該当なし |
|
PutProperty |
該当なし |
|
GetProperty |
該当なし |
|
QueryStatusWB |
該当なし |
|
ExecWB |
該当なし |
|
ShowBrowserBar |
該当なし |
プロパティ
|
TWebBrowser プロパティ |
TEdgeBrowser プロパティ |
|
AddressBar |
該当なし |
|
Application |
該当なし |
|
Busy |
直接的な該当なし |
|
Container |
該当なし |
|
ControlInterface |
DefaultInterface は ICoreWebView2 インターフェイス |
|
DefaultInterface |
DefaultInterface は ICoreWebView2 インターフェイス |
|
Document |
該当なし |
|
FullName |
直接的な該当なし。ただし BrowserProcessID および一部の Windows API が使用可能 |
|
FullScreen |
該当なし |
|
HWND |
直接的な該当なし。ただし Handle および一部の Windows API が使用可能 |
|
LocationName |
DocumentTitle |
|
LocationURL |
LocationURL |
|
MenuBar |
該当なし |
|
［名前］ |
該当なし |
|
Offline |
該当なし |
|
Parent |
該当なし |
|
パス |
直接的な該当なし。ただし BrowserProcessID および一部の Windows API が使用可能 |
|
ReadyState |
直接的な該当なし |
|
RegisterAsBrowser |
該当なし |
|
RegisterAsDropTarget |
該当なし |
|
Resizable |
直接的な該当なし |
|
Silent |
OnScriptDialogOpening イベントを伴う DefaultScriptDialogsEnabled の逆 |
|
StatusBar |
StatusBarEnabled |
|
TheaterMode |
該当なし |
|
ToolBar |
該当なし |
|
TopLevelContainer |
該当なし |
|
Type_ |
該当なし |
|
Visible |
Visible |
イベント
|
TWebBrowser イベント |
TEdgeBrowser イベント |
|
OnBeforeNavigate2 |
OnNavigationStarting |
|
OnBeforeScriptExecute |
該当なし |
|
OnClientToHostWindow |
該当なし |
|
OnCommandStateChange |
直接的な該当なし。ただし OnHistoryChanged が使用可能 |
|
OnDocumentComplete |
OnNavigationCompleted |
|
OnDownloadBegin |
該当なし |
|
OnDownloadComplete |
該当なし |
|
OnFileDownload |
該当なし |
|
OnFullScreen |
該当なし |
|
OnMenuBar |
該当なし |
|
OnNavigateComplete2 |
OnNavigationCompleted |
|
OnNavigateError |
OnNavigationComplete。IsSuccess パラメータに注意 |
|
OnNewProcess |
該当なし |
|
OnNewWindow2 |
OnNewWindowRequested |
|
OnNewWindow3 |
OnNewWindowRequested |
|
OnPrintTemplateInstantiation |
該当なし |
|
OnPrintTemplateTeardown |
該当なし |
|
OnPrivacyImpactedStateChange |
該当なし |
|
OnProgressChange |
該当なし |
|
OnPropertyChange |
該当なし |
|
OnQuit |
該当なし |
|
OnRedirectXDomainBlocked |
該当なし |
|
OnShowScriptError |
該当なし |
|
OnSetPhishingFilterStatus |
該当なし |
|
OnSetSecureLockIcon |
該当なし |
|
OnStatusBar |
該当なし |
|
OnStatusTextChange |
該当なし |
|
OnTheaterMode |
該当なし |
|
OnThirdPartyUrlBlocked |
該当なし |
|
OnTitleChange |
OnDocumentTitleChanged |
|
OnToolBar |
該当なし |
|
OnUpdatePageStatus |
該当なし |
|
OnVisible |
該当なし |
|
OnWebWorkerFinsihed |
該当なし |
|
OnWebWorkerStarted |
該当なし |
|
OnWindowClosing |
該当なし |
|
OnWindowSetHeight |
該当なし |
|
OnWindowSetLeft |
該当なし |
|
OnWindowSetResizable |
該当なし |
|
OnWindowSetTop |
該当なし |
|
OnWindowSetWidth |
該当なし |
|
OnWindowStateChanged |
該当なし |
TWebBrowser における変更点
VCL TWebBrowser コンポーネントは、いままでと変わらない処理を実行し、Internet Explorer WebBrowser ブラウザ コントロールを使用して Web コンテンツを描画します。
ただし、このデフォルトの動作に加え、TWebBrowser には 2 つの新しいプロパティが追加されています。最初のプロパティは、新しい Edge (Chromium) WebView2 ブラウザ コントロールを代わりに使用するか問うために使用することができます。これは、組み込み TEdgeBrowser コンポーネントを使用した実装によって実現されます。
プロパティで Edge WebView2 ブラウザ コントロールを使用することにより、メンテナンスされている現行バージョンのブラウザから、利益を即座に享受することができます。これは Microsoft により利用可能なセキュリティ上の修正も含まれています。
ただし、逆に考えると、WebView2 ブラウザ コントロールは、各 Windows インストールに必須部分とはなっていません。
プロパティ SelectedEngine は、希望する、もしくは必要とするブラウザ コントロールがどれかを示します。サポートされる値は次のとおりです：
- TWebBrowser.TSelectedEngine.IEOnly： TWebBrowser は、IE WebBrowser コントロールを使って従来通り機能します。
- TWebBrowser.TSelectedEngine.EdgeIfAvailable： TWebBrowser は、使用可能なら Edge WebView2 ブラウザ コントロールを使用し、それでなければ、従来の IE WebBrowser コントロールに戻ります。
- TWebBrowser.TSelectedEngine.EdgeOnly： TWebBrowser は、Edge WebView2 ブラウザ コントロールを使用しようとしますが、それが不可能だった場合、フォールバック オプションがないため、ブラウジングはできなくなります。
一部のフィードバックは ActiveEngine プロパティを介して利用可能で、これには次の値があります：
- TWebBrowser.TActiveEngine.None： 使用中のブラウザ コントロールはない。EdgeOnly が SelectedEngine を介して要求された場合、Edge ブラウザはインスタンス化されません。
- TWebBrowser.TActiveEngine.NoneYet: 使用中のブラウザ コントロールはまだありませんが、Edge WebView2 ブラウザ コントロールを初期化しようとしています。
- TWebBrowser.TActiveEngine.IE： Internet Explorer WebBrowser ブラウザ コントロールは使用中です。
- TWebBrowser.TActiveEngine.Edge： Edge WebView2 ブラウザ コントロールは使用中です。
- Edge (Chromium) ブラウザがインストールされていること。
- Edge WebView2 コントロール ローダー DLL（Microsoft WebView2 SDK の一部）が利用可能なこと。たとえば、プロジェクトの実行可能ファイルが出力されるディレクトリなどにある。
Microsoft Edge WebView2 コントロールをインストールするには、TEdgeBrowser ドキュメント ページ の説明に従ってください。
TWebBrowser のデュアル パーソナリティ機能
TWebBrowser を「Edge パーソナリティ」モードで使用する場合（SelectedEngine は、EdgeIfAvailable または EdgeOnly に設定され、ActiveEngine は Edge に変更されます）そのさまざまなプロパティ、メソッド、イベントは、できる限り適切に動作するよう更新されます。
これらのプロパティ、メソッド、イベントの多くが、Internet Explorer WebBrowser コントロール インターフェイスから直接引き継いだもので、その多くがデフォルト値を返すか、Edge モードでの実行時に例外を発生させます。
次の一覧は、Edge モードでの実行時の動作を表しています：
メソッド
|
GoBack |
ブラウザの履歴で、前のページに移動 |
|
GoForward |
ブラウザの履歴で、次のページに移動 |
|
GoHome |
ENotImplemented 例外を発生 |
|
GoSearch |
ENotImplemented 例外を発生 |
|
Navigate |
URL パラメータのみを持つオーバーロードはその URL に遷移するが、その他のオーバーロードは ENotImplemented 例外を発生。 |
|
Refresh |
現在のページをリロード |
|
Refresh2 |
現在のページをリロード |
|
Stop |
現在のナビゲーション アクティビティを停止 |
|
Quit |
ブラウザ コントロールの Edge プロセスのサポートを終了 |
|
ClientToWindow |
ENotImplemented 例外を発生 |
|
PutProperty |
ENotImplemented 例外を発生 |
|
GetProperty |
ENotImplemented 例外を発生 |
|
Navigate2 |
URL パラメータのみを持つオーバーロードはその URL に遷移するが、その他のオーバーロードは ENotImplemented 例外を発生。 |
|
QueryStatusWB |
ENotImplemented 例外を発生 |
|
ExecWB |
ENotImplemented 例外を発生 |
|
ShowBrowserBar |
ENotImplemented 例外を発生 |
読み取り専用プロパティ
|
ControlInterface |
nil を返す |
|
DefaultInterface |
nil を返す |
|
Application |
nil を返す |
|
Parent |
nil を返す |
|
Container |
nil を返す |
|
Document |
nil を返す |
|
TopLevelContainer |
True を返す |
|
type_ |
空の文字列を返す |
|
LocationName |
現在のドキュメント タイトルを返す |
|
LocationURL |
現在の URL を返す |
|
Busy |
ナビゲーションがアクティブの場合には True、そうでなければ False を返す |
|
Name |
空の文字列を返す |
|
HWND |
WebView2 ブラウザ コントロールのウィンドウ ハンドルを返す |
|
FullName |
WebView2 コントロールが使用する Edge ブラウザ プロセスの完全実行パスを返す |
|
パス |
WebView2 コントロールが使用する Edge ブラウザ プロセスのフォルダの完全パスを返す |
|
ReadyState |
取り得る値のサブセットのうちの 1 つを、Edge コントロールの状態を元に返す： READYSTATE_UNINITIALIZED、READYSTATE_LOADING、または、READYSTATE_COMPLETE |
公開された読み込み/書き込みプロパティ
|
Visible |
組み込み Edge コンポーネントの Visible プロパティを設定または返す |
|
StatusBar |
組み込み Edge コンポーネントの StatusBarEnabled プロパティを設定または返す |
|
StatusText |
設定された値を無視し、空文字列を返す |
|
ToolBar |
設定された値を無視し、0 を返す |
|
MenuBar |
設定された値を無視し、False を返す |
|
FullScreen |
設定された値を無視し、False を返す |
|
Offline |
設定された値を無視し、False を返す |
|
Silent |
組み込み Edge コンポーネントの DefaultScriptDialogsEnabled プロパティへ、またはプロパティから、逆の値を設定および返す |
|
RegisterAsBrowser |
設定された値を無視し、False を返す |
|
RegisterAsDropTarget |
設定された値を無視し、False を返す |
|
TheaterMode |
設定された値を無視し、False を返す |
|
AddressBar |
設定された値を無視し、False を返す |
|
Resizable |
設定された値を無視し、True を返す |
イベント
|
OnStatusTextChange |
呼び出されない |
|
OnProgressChange |
呼び出されない |
|
OnCommandStateChange |
Edge コンポーネントの OnHistoryChanged イベントが発生した際に発生 |
|
OnDownloadBegin |
呼び出されない |
|
OnDownloadComplete |
呼び出されない |
|
OnTitleChange |
Edge コンポーネントの OnDocumentTitleChanged イベントが発生した際に発生 |
|
OnPropertyChange |
呼び出されない |
|
OnBeforeNavigate2 |
Edge コンポーネントの OnNavigationStarting イベントが発生した際に発生 |
|
OnNewWindow2 |
Edge コンポーネントの OnNewWindowRequested イベントが発生した際に発生 |
|
OnNavigateComplete2 |
Edge コンポーネントの OnNavigationCompleted イベントが発生した際に発生 |
|
OnDocumentComplete |
Edge コンポーネントの OnNavigationCompleted イベントが発生した際に発生 |
|
OnQuit |
呼び出されない |
|
OnVisible |
呼び出されない |
|
OnToolBar |
呼び出されない |
|
OnMenuBar |
呼び出されない |
|
OnStatusBar |
呼び出されない |
|
OnFullScreen |
呼び出されない |
|
OnTheaterMode |
呼び出されない |
|
OnWindowSetResizable |
呼び出されない |
|
OnWindowSetLeft |
呼び出されない |
|
OnWindowSetTop |
呼び出されない |
|
OnWindowSetWidth |
呼び出されない |
|
OnWindowSetHeight |
呼び出されない |
|
OnWindowClosing |
呼び出されない |
|
OnClientToHostWindow |
呼び出されない |
|
OnSetSecureLockIcon |
呼び出されない |
|
OnFileDownload |
呼び出されない |
|
OnNavigateError |
呼び出されない |
|
OnPrintTemplateInstantiation |
呼び出されない |
|
OnPrintTemplateTeardown |
呼び出されない |
|
OnUpdatePageStatus |
呼び出されない |
|
OnPrivacyImpactedStateChange |
呼び出されない |
|
OnNewWindow3 |
Edge コンポーネントの OnNewWindowRequested イベントが発生した際に発生 |
|
OnSetPhishingFilterStatus |
呼び出されない |
|
OnWindowStateChanged |
呼び出されない |
|
OnNewProcess |
呼び出されない |
|
OnThirdPartyUrlBlocked |
呼び出されない |
|
OnRedirectXDomainBlocked |
呼び出されない |
|
OnBeforeScriptExecute |
呼び出されない |
|
OnWebWorkerStarted |
呼び出されない |
|
OnWebWorkerFinsihed |
呼び出されない |
|
OnShowScriptError |
呼び出されない |
新しい Edge 関係のデモ
製品と共にインストールされる新たなデモがあり、新しい Edge と更新された TWebBrowser コンポーネントの使用を表します。これらは、次のフォルダにあります：
- Demos\Object Pascal\VCL\WebBrowser\Edge
- Demos\Object Pascal\VCL\WebBrowser\InternetExplorer
- Demos\CPP\VCL\WebBrowser\Edge