Verwenden der TEdgeBrowser-Komponente und Änderungen der TWebBrowser-Komponente

Nach oben zu VCL

RAD Studio 10.4 Sydney unterstützt die Arbeit mit Webinhalten über das Chromium-basierte Edge WebView2-Browser-Steuerelement in VCL-Anwendungen über die neue TEdgeBrowser-Komponente.

TEdgeBrowser löst die Komponente TWebBrowser ab, die das WebBrowser-Browser-Steuerelement des Internet Explorer verwendet. TWebBrowser verbleibt jedoch im VCL-Komponentensatz mit einigen wichtigen Änderungen.

Vorbereitungen für die Verwendung der Edge-Browser-Komponente

Da TWebBrowser das vom Betriebssystem bereitgestellte WebBrowser-Browser-Steuerelement des Internet Explorer verwendet, ist keine Vorbereitung erforderlich. Es funktioniert überall dort, wo Windows das Internet Explorer-Steuerelement zur Verfügung stellt.

Im Gegensatz dazu ist Microsoft Edge derzeit keine Betriebssystemkomponente. Deshalb müssen Sie sicherstellen, dass diese Elemente auf Ihrem Computer installiert sind, bevor Sie eine Anwendung ausführen, die sie verwendet:

• Der Chromium-basierte Microsoft Edge Browser ist derzeit unter https://www.microsoftedgeinsider.com/download verfügbar (Canary Channel-Version, solange sich das WebView2-SDK in der Vorabversion befindet, derzeit ist die minimal erforderliche Version 82.0.430.0).

• Das WebView2-Steuerelement ist derzeit über NuGet unter https://www.nuget.org/packages/Microsoft.Web.WebView2 oder über den GetIt-Package-Manager verfügbar.

Dies gilt sowohl für das Compilieren und Ausführen der Anwendung auf Ihrem Entwicklungsrechner als auch auf dem Rechner des Endbenutzers.

Wenn diese beiden installiert sind, funktioniert der TEdgeBrowser und verwendet das Edge WebView2-Browser-Steuerelement zum Rendern von Webinhalten.

Installieren des Edge WebView2-Package über GetIt

Öffnen Sie zum Installieren des Microsoft WebView2-Package den GetIt-Package-Manager in der RAD Studio-IDE und suchen Sie nach dem entsprechenden Eintrag:

Nachdem Sie die Lizenz akzeptiert haben, lädt GetIt das Package herunter und kopiert die beiden WebView2-Loader-DLLs, für 32 und 64 Bit, in die entsprechenden Redist-Ordner, wie im GetIt-Protokoll angegeben:

Sie können diese Dateien in Ihre Ziel-EXE-Verzeichnisse oder in einen Ordner in Ihrem Pfad kopieren oder die Schritte im Abschnitt "Projektkonfiguration für WebView2-Loader-DLLs" ausführen.

Manuelles Installieren des Edge WebView2-Package von NuGet

Das Edge WebView2-Browser-Steuerelement ist auf NuGet unter https://www.nuget.org/packages/Microsoft.Web.WebView2 unter dem Namen Microsoft.Web.WebView2 verfügbar. Die Komponente ist derzeit für die Version 0.9.430 geschrieben.

Auf dieser Seite, https://www.nuget.org/packages/Microsoft.Web.WebView2/0.9.430, können Sie auf den Link zum Herunterladen des Package klicken, um microsoft.web.webview2.0.9.430.nupkg herunterzuladen.

Eine .nupkg-Datei ist einfach eine ZIP-Datei mit einer anderen Dateierweiterung, daher können Sie sie in microsoft.web.webview2.0.9.430.zip umbenennen und den Inhalt mit dem Windows Explorer oder mit 7zip extrahieren, um die erforderlichen Dateien zu erhalten.

Sie benötigen aus dem Package die Datei WebView2Loader.dll. Wenn Sie eine Win32-App erstellen, müssen Sie build\x86\WebView2Loader.dll verwenden, und wenn Sie eine Win64-App erstellen, müssen Sie build\x64\WebView2Loader.dll verwenden.

Projektkonfiguration für WebView2-Loader-DLLs

Wo auch immer Sie die WebView2-Loader-DLLs platzieren, Sie müssen ein Post-Build-Ereignis einrichten, um sie in das Ausgabeverzeichnis Ihres Projekts zu kopieren.

Für ein Win32-Ziel sollte das Post-Build-Ereignis etwa so aussehen:

  copy /Y "common_DLL_folder_path\x86\WebView2Loader.dll" $(OUTPUTDIR)

Verwenden Sie für ein Win64-Ziel Folgendes:

  copy /Y "common_DLL_folder_path\x64\WebView2Loader.dll" $(OUTPUTDIR)

Verwenden der Edge-Browser-Komponente

Sie können die TEdgeBrowser-Komponente auf ähnliche Weise wie TWebBrowser verwenden, weil eine Reihe der Methoden und Eigenschaften von TEdgeBrowser den Methoden und Eigenschaften von TWebBrowser sehr ähnlich sind.

Legen Sie die Komponente auf einem VCL-Formular ab und passen Sie die Größe an.

Um zu einer URL zu navigieren, übergeben Sie diese URL einfach an die Methode Navigate.

Beachten Sie, dass das WebView2-Steuerelement asynchron erstellt wird. Sie können die Erstellung entweder durch den Aufruf der Methode Navigate oder durch Aufruf der Methode CreateWebView auslösen. Sie können jederzeit mit der Eigenschaft WebViewCreated feststellen, ob das Steuerelement erfolgreich erstellt wurde.

Dies ist ein minimales Beispiel für eine ausgeführte Anwendung mit einer einzigen Codezeile und keinen weiteren Konfigurationseinstellungen:

Zusätzlich können Sie eine OnCreateWebViewCompleted-Ereignisbehandlungsroutine verwenden, die aufgerufen wird, wenn die Erstellung des Steuerelements entweder erfolgreich oder nicht erfolgreich abgeschlossen ist.

Wenn keine OnCreateWebViewCompleted-Ereignisbehandlungsroutine vorhanden ist und das WebView2-Browser-Steuerelemente nicht initiiert werden kann, dann wird eine EEdgeError-Exception im Haupt-Thread ausgelöst, wird aber von einem Worker-Thread im Haupt-Thread synchronisiert.

Deshalb ist diese Exception ohne einen globalen Exception-Handler, wie z. B. der Ereignisbehandlungsroutine OnException der Komponente TApplicationEvents, schwer abzufangen, daher wird dafür eine OnCreateWebViewCompleted-Ereignisbehandlungsroutine empfohlen.

Es gibt eine Reihe weiterer Ereignisse, die Sie für Ereignisbehandlungsroutinen einrichten können, die meist Ereignisse aus dem zugrundeliegenden WebView2-Browser-Steuerelement abbilden. Wenn Sie beispielsweise zu einer URL navigieren, wird das Ereignis OnNavigationStarting basierend auf dem Inhalt der Zielseite ein oder mehrere Male ausgelöst. Wenn die Navigation zu einer URL beendet ist, wird das Ereignis OnNavigationCompleted ausgelöst.

Migrieren von TWebBrowser zu TEdgeBrowser

Um von der früheren TWebBrowser-Komponente zur neuen Edge-basierten TEdgeBrowser-Komponente zu wechseln, müssen Sie überlegen, welche TWebBrowser-Methoden, -Eigenschaften und -Ereignisse Sie derzeit verwenden.

Es gibt einige Gemeinsamkeiten zwischen dem bereitgestellten Interface von TWebBrowser und TEdgeBrowser, aber diese sind ziemlich begrenzt.

In der folgenden Tabelle finden Sie die nächstgelegenen Entsprechungen von Klassen-Membern, von und zu denen Sie wechseln können.

Beachten Sie, dass das zugrunde liegende Browser-Steuerelement WebView2-Browser, das von TEdgeBrowser verwendet wird, viel weniger Ereignisse mit einem engeren Fokus als das WebBrowser-Browser-Steuerelement des Internet Explorer bereitstellt, das der TWebBrowser-VCL-Komponente zugrundeliegt.

Methoden

TWebBrowser-Methode	TEdgeBrowser-Methode
GoBack	GoBack
GoForward	GoForward
GoHome	Keine Entsprechung
GoSearch	Keine Entsprechung
Navigate	Navigate
Navigate2	Navigate
Refresh	Refresh
Refresh2	Refresh
Stop	Stop
Quit	CloseBrowserProcess
ClientToWindow	Keine Entsprechung
PutProperty	Keine Entsprechung
GetProperty	Keine Entsprechung
QueryStatusWB	Keine Entsprechung
ExecWB	Keine Entsprechung
ShowBrowserBar	Keine Entsprechung

Eigenschaften

TWebBrowser-Eigenschaft	TEdgeBrowser-Eigenschaft
AddressBar	Keine Entsprechung
Application	Keine Entsprechung
Busy	Keine direkte Entsprechung
Container	Keine Entsprechung
ControlInterface	DefaultInterface ist das ICoreWebView2-Interface
DefaultInterface	DefaultInterface ist das ICoreWebView2-Interface
Document	Keine Entsprechung
FullName	Keine direkte Entsprechung, aber Sie können BrowserProcessID und einige Windows-APIs verwenden
FullScreen	Keine Entsprechung
HWND	Keine direkte Entsprechung, aber Sie können Handle und einige Windows-APIs verwenden
LocationName	DocumentTitle
LocationURL	LocationURL
MenuBar	Keine Entsprechung
Name	Keine Entsprechung
Offline	Keine Entsprechung
Parent	Keine Entsprechung
Path	Keine direkte Entsprechung, aber Sie können BrowserProcessID und einige Windows-APIs verwenden
ReadyState	Keine direkte Entsprechung
RegisterAsBrowser	Keine Entsprechung
RegisterAsDropTarget	Keine Entsprechung
Resizable	Keine direkte Entsprechung
Silent	Die Umkehrung von DefaultScriptDialogsEnabled zusammen mit dem Ereignis OnScriptDialogOpening
StatusBar	StatusBarEnabled
TheaterMode	Keine Entsprechung
ToolBar	Keine Entsprechung
TopLevelContainer	Keine Entsprechung
Type_	Keine Entsprechung
Visible	Visible

Ereignisse

TWebBrowser-Ereignis	TEdgeBrowser-Ereignis
OnBeforeNavigate2	OnNavigationStarting
OnBeforeScriptExecute	Keine Entsprechung
OnClientToHostWindow	Keine Entsprechung
OnCommandStateChange	Keine direkte Entsprechung, aber Sie können OnHistoryChanged verwenden
OnDocumentComplete	OnNavigationCompleted
OnDownloadBegin	Keine Entsprechung
OnDownloadComplete	Keine Entsprechung
OnFileDownload	Keine Entsprechung
OnFullScreen	Keine Entsprechung
OnMenuBar	Keine Entsprechung
OnNavigateComplete2	OnNavigationCompleted
OnNavigateError	OnNavigationComplete, wobei der Parameter IsSuccess zu beachten ist
OnNewProcess	Keine Entsprechung
OnNewWindow2	OnNewWindowRequested
OnNewWindow3	OnNewWindowRequested
OnPrintTemplateInstantiation	Keine Entsprechung
OnPrintTemplateTeardown	Keine Entsprechung
OnPrivacyImpactedStateChange	Keine Entsprechung
OnProgressChange	Keine Entsprechung
OnPropertyChange	Keine Entsprechung
OnQuit	Keine Entsprechung
OnRedirectXDomainBlocked	Keine Entsprechung
OnShowScriptError	Keine Entsprechung
OnSetPhishingFilterStatus	Keine Entsprechung
OnSetSecureLockIcon	Keine Entsprechung
OnStatusBar	Keine Entsprechung
OnStatusTextChange	Keine Entsprechung
OnTheaterMode	Keine Entsprechung
OnThirdPartyUrlBlocked	Keine Entsprechung
OnTitleChange	OnDocumentTitleChanged
OnToolBar	Keine Entsprechung
OnUpdatePageStatus	Keine Entsprechung
OnVisible	Keine Entsprechung
OnWebWorkerFinsihed	Keine Entsprechung
OnWebWorkerStarted	Keine Entsprechung
OnWindowClosing	Keine Entsprechung
OnWindowSetHeight	Keine Entsprechung
OnWindowSetLeft	Keine Entsprechung
OnWindowSetResizable	Keine Entsprechung
OnWindowSetTop	Keine Entsprechung
OnWindowSetWidth	Keine Entsprechung
OnWindowStateChanged	Keine Entsprechung

Änderungen in TWebBrowser

Die VCL-Komponente TWebBrowser führt nach wie vor die gleiche Aufgabe wie immer aus, nämlich das Rendern von Webinhalten mit dem WebBrowser-Browser-Steuerelement des Internet Explorer.

Zusätzlich zu diesem Standardverhalten hat TWebBrowser jedoch zwei neue Eigenschaften. Mit der ersten Eigenschaft kann die Verwendung des neueren Edge (Chromium) WebView2-Browser-Steuerelement angefordert werden. Dies wird durch die Implementierung mit einer eingebetteten TEdgeBrowser-Komponente erreicht.

Mithilfe der Eigenschaft für die Verwendung des Edge WebView2-Browser-Steuerelements können Sie sofort von einem aktuellen, gewarteten Browser profitieren, der über von Microsoft bereitgestellte Sicherheitsfixes verfügt.

Die Kehrseite der Medaille ist jedoch, dass das WebView2-Browser-Steuerelement nicht fester Bestandteil jeder Windows-Installation ist.

Die Eigenschaft SelectedEngine gibt an, welches Browser-Steuerelement Sie anfordern. Folgende Werte werden unterstützt:

• TWebBrowser.TSelectedEngine.IEOnly: der TWebBrowser funktioniert wie immer, indem er das IE-WebBrowser-Steuerelement verwendet.

• TWebBrowser.TSelectedEngine.EdgeIfAvailable: der TWebBrowser verwendet, wenn möglich, das Edge WebView2-Browser-Steuerelement, andernfalls greift er auf das traditionelle IE-WebBrowser-Steuerelement zurück.

• TWebBrowser.TSelectedEngine.EdgeOnly: der TWebBrowser versucht, das Edge WebView2-Browser-Steuerelement zu verwenden, wenn dies jedoch nicht erfolgreich ist, ist kein Browsing möglich, da es keine Fallback-Option gibt.

Mit der Eigenschaft ActiveEngine können Sie Feedback abrufen. Folgende Werte werden unterstützt:

• TWebBrowser.TActiveEngine.None: Es wird kein Browser-Steuerelement verwendet. Wenn EdgeOnly über SelectedEngine angefordert wurde, konnte der Edge-Browser nicht instantiiert werden.

• TWebBrowser.TActiveEngine.NoneYet: Es wird noch kein Browser-Steuerelement verwendet, aber es wird versucht, das Edge WebView2-Browser-Steuerelement zu initialisieren.

• TWebBrowser.TActiveEngine.IE: Das WebBrowser-Browser-Steuerelement des Internet Explorer wird verwendet.

• TWebBrowser.TActiveEngine.Edge: Das Edge WebView2-Browser-Steuerelement wird verwendet.

Achtung: Genau wie bei der Komponente TEdgeBrowser gibt es zwei Voraussetzungen, damit TWebBrowser das Edge WebView2-Browser-Steuerelement erfolgreich verwenden kann:

• Der Edge(Chromium)-Browser ist installiert.

• Die Loader-DLL des Edge WebView2-Steuerelements (Teil des Microsoft WebView2 SDK) ist verfügbar, zum Beispiel im Verzeichnis, in das die Ausgabe der ausführbaren Datei Ihres Projekts erfolgt.

Befolgen Sie zum Installieren des Microsoft Edge WebView2-Steuerelements die Anweisungen auf der TEdgeBrowser-Dokumentationsseite.

Duale Personality-Fähigkeiten von TWebBrowser

Wenn Sie TWebBrowser im Modus "Edge-Personality" verwenden (SelectedEngine ist auf EdgeIfAvailable oder EdgeOnly gesetzt, und ActiveEngine wurde in Edge geändert), wurden seine verschiedenen Eigenschaften, Methoden und Ereignisse aktualisiert, damit sie möglichst adäquat funktionieren.

Beachten Sie, dass viele dieser Eigenschaften, Methoden und Ereignisse direkt von den WebBrowser-Steuerelement-Interfaces des Internet Explorer stammen, daher geben Reihe davon jetzt entweder einen Standardwert zurück oder lösen eine Exception im Edge-Modus aus.

In den folgenden Listen ist das Verhalten im Edge-Modus dargestellt:

Methoden

GoBack	Wechselt im Browser-Verlauf zur vorherigen Seite
GoForward	Wechselt im Browser-Verlauf zur nächsten Seite
GoHome	Löst eine ENotImplemented-Exception aus
GoSearch	Löst eine ENotImplemented-Exception aus
Navigate	Die Überladung mit nur einem URL-Parameter navigiert zu dieser URL, aber die anderen Überladungen lösen eine ENotImplemented-Exception aus
Refresh	Lädt die aktuelle Seite neu
Refresh2	Lädt die aktuelle Seite neu
Stop	Hält die aktuelle Navigationsaktivität an
Quit	Beendet den unterstützenden Edge-Prozess des Browser-Steuerelements
ClientToWindow	Löst eine ENotImplemented-Exception aus
PutProperty	Löst eine ENotImplemented-Exception aus
GetProperty	Löst eine ENotImplemented-Exception aus
Navigate2	Die Überladung mit nur einem URL-Parameter navigiert zu dieser URL, aber die anderen Überladungen lösen eine ENotImplemented-Exception aus
QueryStatusWB	Löst eine ENotImplemented-Exception aus
ExecWB	Löst eine ENotImplemented-Exception aus
ShowBrowserBar	Löst eine ENotImplemented-Exception aus

Schreibgeschützte Eigenschaften

ControlInterface	Gibt nil zurück
DefaultInterface	Gibt nil zurück
Application	Gibt nil zurück
Parent	Gibt nil zurück
Container	Gibt nil zurück
Document	Gibt nil zurück
TopLevelContainer	Gibt True zurück
type_	Gibt einen leeren String zurück
LocationName	Gibt den aktuellen Dokumenttitel zurück.
LocationURL	Gibt die aktuelle URL zurück.
Busy	Gibt True zurück, wenn die Navigation aktiv ist, ansonsten False
Name	Gibt einen leeren String zurück
HWND	Gibt das Fenster-Handle des WebView2-Browser-Steuerelements zurück
FullName	Gibt den vollständigen ausführbaren Pfad des Edge-Browser-Prozesses zurück, der vom WebView2-Steuerelement verwendet wird
Path	Gibt den vollständigen Pfad des Ordners des Edge-Browser-Prozesses zurück, der vom WebView2-Steuerelement verwendet wird
ReadyState	Gibt einen aus einer Untermenge der möglichen Werte zurück, basierend auf dem Status des Edge-Steuerelements: READYSTATE_UNINITIALIZED, READYSTATE_LOADING oder READYSTATE_COMPLETE

Published Read/Write-Eigenschaften

Visible	Legt die Eigenschaft Visible der eingebetteten Edge-Komponente fest und gibt sie zurück
StatusBar	Legt die Eigenschaft StatusBarEnabled der eingebetteten Edge-Komponente fest und gibt sie zurück
StatusText	Ignoriert den festgelegten Wert und gibt einen leeren String zurück
ToolBar	Ignoriert den festgelegten Wert und gibt 0 zurück
MenuBar	Ignoriert den festgelegten Wert und gibt False zurück
FullScreen	Ignoriert den festgelegten Wert und gibt False zurück
Offline	Ignoriert den festgelegten Wert und gibt False zurück
Silent	Legt den inversen Wert der Eigenschaft DefaultScriptDialogsEnabled der eingebetteten Edge-Komponente fest und gibt ihn an die/von der Eigenschaft zurück
RegisterAsBrowser	Ignoriert den festgelegten Wert und gibt False zurück
RegisterAsDropTarget	Ignoriert den festgelegten Wert und gibt False zurück
TheaterMode	Ignoriert den festgelegten Wert und gibt False zurück
AddressBar	Ignoriert den festgelegten Wert und gibt False zurück
Resizable	Ignoriert den festgelegten Wert und gibt True zurück

Ereignisse

OnStatusTextChange	Nicht aufgerufen
OnProgressChange	Nicht aufgerufen
OnCommandStateChange	Wird ausgelöst, wenn das Ereignis OnHistoryChanged der Edge-Komponente ausgelöst wird
OnDownloadBegin	Nicht aufgerufen
OnDownloadComplete	Nicht aufgerufen
OnTitleChange	Wird ausgelöst, wenn das Ereignis OnDocumentTitleChanged der Edge-Komponente ausgelöst wird
OnPropertyChange	Nicht aufgerufen
OnBeforeNavigate2	Wird ausgelöst, wenn das Ereignis OnNavigationStarting der Edge-Komponente ausgelöst wird
OnNewWindow2	Wird ausgelöst, wenn das Ereignis OnNewWindowRequested der Edge-Komponente ausgelöst wird
OnNavigateComplete2	Wird ausgelöst, wenn das Ereignis OnNavigationCompleted der Edge-Komponente ausgelöst wird
OnDocumentComplete	Wird ausgelöst, wenn das Ereignis OnNavigationCompleted der Edge-Komponente ausgelöst wird
OnQuit	Nicht aufgerufen
OnVisible	Nicht aufgerufen
OnToolBar	Nicht aufgerufen
OnMenuBar	Nicht aufgerufen
OnStatusBar	Nicht aufgerufen
OnFullScreen	Nicht aufgerufen
OnTheaterMode	Nicht aufgerufen
OnWindowSetResizable	Nicht aufgerufen
OnWindowSetLeft	Nicht aufgerufen
OnWindowSetTop	Nicht aufgerufen
OnWindowSetWidth	Nicht aufgerufen
OnWindowSetHeight	Nicht aufgerufen
OnWindowClosing	Nicht aufgerufen
OnClientToHostWindow	Nicht aufgerufen
OnSetSecureLockIcon	Nicht aufgerufen
OnFileDownload	Nicht aufgerufen
OnNavigateError	Nicht aufgerufen
OnPrintTemplateInstantiation	Nicht aufgerufen
OnPrintTemplateTeardown	Nicht aufgerufen
OnUpdatePageStatus	Nicht aufgerufen
OnPrivacyImpactedStateChange	Nicht aufgerufen
OnNewWindow3	Wird ausgelöst, wenn das Ereignis OnNewWindowRequested der Edge-Komponente ausgelöst wird
OnSetPhishingFilterStatus	Nicht aufgerufen
OnWindowStateChanged	Nicht aufgerufen
OnNewProcess	Nicht aufgerufen
OnThirdPartyUrlBlocked	Nicht aufgerufen
OnRedirectXDomainBlocked	Nicht aufgerufen
OnBeforeScriptExecute	Nicht aufgerufen
OnWebWorkerStarted	Nicht aufgerufen
OnWebWorkerFinsihed	Nicht aufgerufen
OnShowScriptError	Nicht aufgerufen

Neue Demos zu Edge

Mit dem Produkt werden neue Demos installiert, die die neue Edge- und die aktualisierte TWebBrowser-Komponente zeigen. Sie befinden sich in den folgenden Ordnern:

• Demos\Object Pascal\VCL\WebBrowser\Edge
• Demos\Object Pascal\VCL\WebBrowser\InternetExplorer
• Demos\CPP\VCL\WebBrowser\Edge