TEdgeBrowser コンポーネントの利用と TWebBrowser コンポーネントへの変更点

提供: RAD Studio
移動先: 案内検索

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です)。

これは、開発マシン上のアプリケーションのコンパイルと実行に、そしてエンド ユーザーのマシンにも適用されます。

これら両方がインストールされた状態で、TEdgeBrowser は機能し、Edge WebView2 ブラウザ コントロールを使用して Web コンテンツをレンダリングすることができます。

新しいパブリック プロパティ UserDataFolder により、開発者はキャッシュに使用されるフォルダを定義することができます。 このプロパティは、URL に移動し、コンポーネントを有効にする前に設定される必要があります。

メモ: Microsoft は、バックグラウンド スレッドで、WebView2 コントロールを初期化する機能を無効にする、ローディング コードを変更しました。 現在は、Navigate への最初の呼び出し時に、メイン UI スレッドで初期化が行われます。

GetIt で Edge WebView2 パッケージをインストールする

Microsoft WebView2 パッケージをインストールするには、GetIt パッケージ マネージャ ウィンドウを RAD Studio IDE で開き、該当するエントリを検索します:

GetIt package manager.png

ライセンス契約を承諾すると、GetIt はパッケージをダウンロードし、2 つの WebView2 ローダー DLL(32 ビット用と 64 ビット用) を該当する Redist フォルダにコピーします。GetIt ログは次のようになります:

EdgeView2 installed.png

それらのファイルを対象の 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 行のみ、その他の設定は変更していません:

Form5Button1.png

さらに、OnCreateWebViewCompleted イベント ハンドラを使用することができ、これは、コントロール作成が完了した際に、成功、失敗にかかわらず、呼び出されます。

OnCreateWebViewCompleted イベント ハンドラがなく、WebView2 ブラウザ コントロールが初期化できない場合、EEdgeError 例外が main スレッドで発生しますが、ワーカー スレッドから main スレッドに同期がとられます。

このため、グローバル例外ハンドラ(たとえば、TApplicationEvents コンポーネントの OnException イベント ハンドラなど)を使用せずに捕捉するのは難しいため、OnCreateWebViewCompleted イベント ハンドラがこのような状況をシンプルにするためにも推奨されます。

イベント ハンドラを設定できる追加イベントはまだあります。これらは主に、基となる WebView2 ブラウザ コントロールからの表層イベントです。たとえば、ある URL へ遷移すると、OnNavigationStarting イベントはターゲット ページ コンテンツに基づいて 1 回以上発生します。ある URL への遷移が完了すると、OnNavigationCompleted イベントが発生します。

キャッシュ管理

RAD Studio 10.4.2 では、新しいパブリック プロパティ UserDataFolder が導入されています。 この新しいプロパティにより、開発者は、キャッシュで使用されるフォルダを定義することができます。 このプロパティは、URL に移動し、コンポーネントを有効にする前に設定される必要があります。

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 ブラウザ コントロールは使用中です。
注意: TEdgeBrowser コンポーネントと同じように、TWebBrowser が継続して Edge WebView2 ブラウザ コントロールを使用するためには、必須事項が 2 つあります:
  • 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 コンポーネントの使用を表します。 また、これらは GitHub リポジトリにもあります: