Utilisation du composant TEdgeBrowser et modifications apportées au composant TWebBrowser

Remonter à VCL

Dans RAD Studio 10.4 Sydney, le nouveau composant TEdgeBrowser vous permet d'utiliser du contenu web par l'intermédiaire du contrôle de navigation Edge WebView2 basé sur Chromium.

TEdgeBrowser remplace TWebBrowser (qui utilise le contrôle de navigation WebBrowser d'Internet Explorer). Cependant, TWebBrowser figure toujours dans l'ensemble des composants de la VCL, avec des modifications importantes.

Pré-requis pour l'utilisation du composant Edge Browser

TWebBrowser utilisant le contrôle de navigation WebBrowser Internet Explorer fourni par le système d'exploitation, aucune préparation n'est nécessaire. Pour fonctionner, il lui suffit qu'un contrôle Internet Explorer soit disponible dans Windows.

Au contraire, Microsoft Edge n'est pas un composant du système d'exploitation. Vous devez de ce fait vous assurer que ces pré-requis sont installés sur votre ordinateur avant de pouvoir exécuter une application qui les utilise :

• Navigateur Microsoft Edge basé sur Chromium actuellement disponible sur https://www.microsoftedgeinsider.com/download (version Canary Channel tant que le SDK WebView2 est au stade de pre-release, la version minimale requise est 82.0.430.0).

• Contrôle WebView2, actuellement disponible via NuGet sur https://www.nuget.org/packages/Microsoft.Web.WebView2 ou via le Gestionnaire de packages GetIt.

Ces pré-requis s'appliquent à la compilation et à l'exécution de l'application sur votre machine de développement, ainsi que sur la machine de l'utilisateur final.

Ces deux pré-requis étant installés, le composant TEdgeBrowser peut fonctionner et utiliser le contrôle de navigation Edge WebView2 pour restituer du contenu web.

Installation du package Edge WebView2 via GetIt

Pour installer le package WebView2 Microsoft, ouvrez la fenêtre du gestionnaire de packages GetIt dans l'EDI de RAD Studio et recherchez l'entrée correspondante :

Une fois la licence acceptée, GetIt télécharge le package et copie les deux DLL de chargement de WebView2 pour systèmes 32 et 64 bits dans les dossiers Redist concernés, comme l'indique le journal GetIt :

Vous pouvez copier ces fichiers dans vos répertoires EXE cible, dans un dossier du PATH, ou suivre les étapes de la section Configuration d'un projet pour les DLL de chargement WebView2.

Installation manuelle du package Edge WebView2 de NuGet

Le contrôle de navigation Edge WebView2 de NuGet, actuellement disponible via NuGet sur https://www.nuget.org/packages/Microsoft.Web.WebView2 sous le nom Microsoft.Web.WebView2. Le composant est actuellement écrit par rapport à la version 0.9.430.

Sur cette page, https://www.nuget.org/packages/Microsoft.Web.WebView2/0.9.430, vous pouvez cliquer sur le lien Télécharger le package pour télécharger microsoft.web.webview2.0.9.430.nupkg.

Un fichier .nupkg est un fichier .zip doté d'une extension de fichier différente. Vous pouvez le renommer en microsoft.web.webview2.0.9.430.zip et extraire le contenu avec l'Explorateur de fichiers de Windows ou utiliser 7zip pour extraire son contenu et obtenir le fichier requis.

Le fichier dont vous avez besoin est WebView2Loader.dll. Si vous construisez une app Win32, vous devez utiliser build\x86\WebView2Loader.dll. Pour une app Win64, vous devez utiliser build\x64\WebView2Loader.dll.

Configuration de projet pour les DLL de chargement de WebView2

Quel que soit l'endroit où vous souhaitez placer les DLL de chargement WebView2, vous devrez configurer un événement post-build pour le copier dans le répertoire de sortie du projet.

Pour une cible Win32, l'événement post-build doit être comme suit :

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

Pour une cible Win64 :

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

Utilisation du composant Edge Browser

Vous pouvez utiliser le composant TEdgeBrowser de la même façon que vous utilisez un TWebBrowser, car un certain nombre de méthodes et propriétés de TEdgeBrowser sont similaires aux méthodes et propriétés de TWebBrowser.

Déposez le composant sur une fiche VCL et dimensionnez-le comme souhaité.

Pour naviguer sur une URL, transmettez cette URL à la méthode Navigate.

Vous remarquerez que le contrôle WebView2 est créé de façon asynchrone. Vous pouvez lancer la création en appelant la méthode Navigate ou la méthode CreateWebView. A tout moment, vous pouvez savoir si le contrôle a été créé avec succès en utilisant la propriété WebViewCreated.

Voici un exemple succint d'une application fonctionnant avec une seule ligne de code sans aucun autre paramètre de configuration :

De plus, vous pouvez utiliser un gestionnaire d'événement OnCreateWebViewCompleted qui est appelé lorsque la création du contrôle est terminée (qu'elle ait réussit ou échoué).

S'il n'y a pas de gestionnaire d'événement OnCreateWebViewCompleted et que le contrôle de navigation WebView2 ne peut pas être lancé, l'exception EEdgeError est déclenchée dans le thread principal, tout en étant synchronisée sur le thread principal à partir d'une thread de travail.

Il est donc difficile de l'intercepter sans utiliser un gestionnaire d'exception global comme le gestionnaire d'exception OnException d'un composant TApplicationEvents. C'est pourquoi un gestionnaire d'événement OnCreateWebViewCompleted est recommandé pour simplifier cette situation.

Il existe un certain nombre d'événements supplémentaires pour lesquels vous pouvez configurer des gestionnaires d'événements (cela fait principalement se déclencher des événements du contrôle de navigation WebView2 sous-jacent). Par exemple, lorsque vous naviguez vers une URL, l'événement OnNavigationStarting se déclenche plusieurs fois selon le contenu de la page cible. Lorsque la navigation vers une URL a lieu, l'événement OnNavigationCompleted se déclenche.

Migration de TWebBrowser vers TEdgeBrowser

Pour migrer du composant TWebBrowser traditionnel vers TEdgeBrowser, le nouveau composant basé sur Edge, vous devez d'abord évaluer quelles méthodes, propriétés et événements de TWebBrowser vous utilisez actuellement.

Il existe un certain nombre de points communs entre l'interface exposée de TWebBrowser et TEdgeBrowser, mais ils sont relativement limités.

Le tableau ci-dessous indique les équivalents les plus proches pour les membres de classes.

Il faut savoir que le contrôle de navigation sous-jacent utilisé par TEdgeBrowser, le contrôle de navigation WebView2, expose moins d'événements avec un focus restreint que le contrôle de navigation WebBrowser Internet Explorer sous-jacent du composant VCL TWebBrowser.

Méthodes

Méthode TWebBrowser	Méthode TEdgeBrowser
GoBack	GoBack
GoForward	GoForward
GoHome	Pas d'équivalent
GoSearch	Pas d'équivalent
Navigate	Navigate
Navigate2	Navigate
Refresh	Refresh
Refresh2	Refresh
Stop	Stop
Quit	CloseBrowserProcess
ClientToWindow	Pas d'équivalent
PutProperty	Pas d'équivalent
GetProperty	Pas d'équivalent
QueryStatusWB	Pas d'équivalent
ExecWB	Pas d'équivalent
ShowBrowserBar	Pas d'équivalent

Propriétés

Propriété TWebBrowser	Propriété TEdgeBrowser
AddressBar	Pas d'équivalent
Application	Pas d'équivalent
Busy	Pas d'équivalent direct
Container	Pas d'équivalent
ControlInterface	DefaultInterface est l'interface ICoreWebView2
DefaultInterface	DefaultInterface est l'interface ICoreWebView2
Document	Pas d'équivalent
FullName	Pas d'équivalent direct, mais vous pouvez utiliser BrowserProcessID et certaines API Windows
FullScreen	Pas d'équivalent
HWND	Pas d'équivalent direct, mais vous pouvez utiliser Handle et certaines API Windows
LocationName	DocumentTitle
LocationURL	LocationURL
MenuBar	Pas d'équivalent
Name	Pas d'équivalent
Offline	Pas d'équivalent
Parent	Pas d'équivalent
Path	Pas d'équivalent direct, mais vous pouvez utiliser BrowserProcessID et certaines API Windows
ReadyState	Pas d'équivalent direct
RegisterAsBrowser	Pas d'équivalent
RegisterAsDropTarget	Pas d'équivalent
Resizable	Pas d'équivalent direct
Silent	L'inverse de DefaultScriptDialogsEnabled ainsi que l'événement OnScriptDialogOpening
StatusBar	StatusBarEnabled
TheaterMode	Pas d'équivalent
ToolBar	Pas d'équivalent
TopLevelContainer	Pas d'équivalent
Type_	Pas d'équivalent
Visible	Visible

Events

Evénement TWebBrowser	Evénement TEdgeBrowser
OnBeforeNavigate2	OnNavigationStarting
OnBeforeScriptExecute	Pas d'équivalent
OnClientToHostWindow	Pas d'équivalent
OnCommandStateChange	Pas d'équivalent direct mais vous pouvez utiliser OnHistoryChanged
OnDocumentComplete	OnNavigationCompleted
OnDownloadBegin	Pas d'équivalent
OnDownloadComplete	Pas d'équivalent
OnFileDownload	Pas d'équivalent
OnFullScreen	Pas d'équivalent
OnMenuBar	Pas d'équivalent
OnNavigateComplete2	OnNavigationCompleted
OnNavigateError	OnNavigationComplete, en tenant compte du paramètre IsSuccess
OnNewProcess	Pas d'équivalent
OnNewWindow2	OnNewWindowRequested
OnNewWindow3	OnNewWindowRequested
OnPrintTemplateInstantiation	Pas d'équivalent
OnPrintTemplateTeardown	Pas d'équivalent
OnPrivacyImpactedStateChange	Pas d'équivalent
OnProgressChange	Pas d'équivalent
OnPropertyChange	Pas d'équivalent
OnQuit	Pas d'équivalent
OnRedirectXDomainBlocked	Pas d'équivalent
OnShowScriptError	Pas d'équivalent
OnSetPhishingFilterStatus	Pas d'équivalent
OnSetSecureLockIcon	Pas d'équivalent
OnStatusBar	Pas d'équivalent
OnStatusTextChange	Pas d'équivalent
OnTheaterMode	Pas d'équivalent
OnThirdPartyUrlBlocked	Pas d'équivalent
OnTitleChange	OnDocumentTitleChanged
OnToolBar	Pas d'équivalent
OnUpdatePageStatus	Pas d'équivalent
OnVisible	Pas d'équivalent
OnWebWorkerFinsihed	Pas d'équivalent
OnWebWorkerStarted	Pas d'équivalent
OnWindowClosing	Pas d'équivalent
OnWindowSetHeight	Pas d'équivalent
OnWindowSetLeft	Pas d'équivalent
OnWindowSetResizable	Pas d'équivalent
OnWindowSetTop	Pas d'équivalent
OnWindowSetWidth	Pas d'équivalent
OnWindowStateChanged	Pas d'équivalent

Modifications relatives à TWebBrowser

Le composant TWebBrowser de la VCL continue de fonctionner comme avant, son rôle étant de restituer du contenu web en utilisant le contrôle de navigation WebBrowser d'Internet Explorer.

De plus, en supplément de ce comportement par défaut, TWebBrowser possède deux nouvelles propriétés. La première peut être utilisée pour demander d'appliquer le contrôle de navigation WebView2 Edge (Chromium) à la place de ce propre contrôle. Pour cela, vous devez implémenter un composant TEdgeBrowser incorporé.

En utilisant la propriété qui fait appel au contrôle Edge WebView2, vous bénéficiez immédiatement d'un navigateur récent qui présente l'avantage d'intégrer les corrections de sécurité de Microsoft.

L'inconvénient est que le contrôle de navigation WebView2 n'est pas fourni dans toutes les installations de Windows.

La propriété SelectedEngine indique le contrôle de navigation qui doit être utilisé. Les valeurs possibles sont :

• TWebBrowser.TSelectedEngine.IEOnly : le composant TWebBrowser fonctionne comme il l'a toujours fait, en utilisant le contrôle WebBrowser d'Internet Explorer.

• TWebBrowser.TSelectedEngine.EdgeIfAvailable : le TWebBrowser utilise si possible le contrôle de navigation Edge WebView2. Sinon, il fait appel au contrôle WebBrowser d'Internet Explorer.

• TWebBrowser.TSelectedEngine.EdgeOnly : le composant TWebBrowser tente d'utiliser le contrôle de navigation Edge WebView2. Toutefois, si ce n'est pas possible, aucune navigation ne se produira car il n'y a pas d'autre alternative.

Des retours d'information sont disponibles via la propriété ActiveEngine et les valeurs suivantes :

• TWebBrowser.TActiveEngine.None : aucun contrôle de navigation en cours d'utilisation ; si EdgeOnly a été requis via SelectedEngine, le navigateur Edge n'a pas pu être instancié.

• TWebBrowser.TActiveEngine.NoneYet : aucun contrôle de navigation n'est actuellement utilisé, mais une tentative d'initialisation du contrôle de navigation Edge WebView2 est en cours.

• TWebBrowser.TActiveEngine.IE : le contrôle de navigation WebBrowser d'Internet Explorer est utilisé.

• TWebBrowser.TActiveEngine.Edge : le contrôle de navigation Edge WebView2 est utilisé.

Attention: Comme c'est le cas pour le composant TEdgeBrowser, pour que TWebBrowser utilise avec réussite le contrôle de navigation Edge WebView2, les deux exigences suivantes doivent être satisfaites :

• Le navigateur Edge (Chromium) doit être installé.

• La DLL de chargement de contrôle Edge WebView2 (qui fait partie du SDK Microsoft WebView2) doit être disponible, par exemple dans le répertoire de sortie de l'exécutable de votre projet.

Pour installer le contrôle Edge WebView2 de Microsoft, suivez les instructions de la page TEdgeBrowser.

Fonctionnalités relatives à la double personnalité de TWebBrowser

Lorsque vous utilisez TWebBrowser en mode "Personnalité Edge" (SelectedEngine a été défini sur EdgeIfAvailable ou EdgeOnly, et ActiveEngine a été changé en Edge), ses propriétés, méthodes, et événements sont mis à jour pour fonctionner de la façon la plus appropriée possible.

Comme ces propriétés, méthodes et événements proviennent des interfaces de contrôle WebBrowser Internet Explorer, certains renvoient une valeur par défaut ou déclenchent une exception lorsqu'ils sont exécutés en mode Edge.

La liste suivante décrit les différents comportements en cas d'exécution en mode Edge :

Méthodes

GoBack	Accède à la page précédente dans l'historique du navigateur
GoForward	Accède à la page suivante dans l'historique du navigateur
GoHome	Déclenche une exception ENotImplemented
GoSearch	Déclenche une exception ENotImplemented
Navigate	Une surcharge avec un seul paramètre d'URL provoque la navigation vers cette URL, mais les autres surcharges provoquent le déclenchement d'une exception ENotImplemented
Refresh	Recharge la page en cours
Refresh2	Recharge la page en cours
Stop	Arrête l'activité relative à la navigation en cours
Quit	Met fin au processus Edge du contrôle de navigation
ClientToWindow	Déclenche une exception ENotImplemented
PutProperty	Déclenche une exception ENotImplemented
GetProperty	Déclenche une exception ENotImplemented
Navigate2	Une surcharge avec un seul paramètre d'URL provoque la navigation vers cette URL, mais les autres surcharges provoquent le déclenchement d'une exception ENotImplemented
QueryStatusWB	Déclenche une exception ENotImplemented
ExecWB	Déclenche une exception ENotImplemented
ShowBrowserBar	Déclenche une exception ENotImplemented

Propriétés en lecture seule

ControlInterface	Renvoie la valeur nil
DefaultInterface	Renvoie la valeur nil
Application	Renvoie la valeur nil
Parent	Renvoie la valeur nil
Container	Renvoie la valeur nil
Document	Renvoie la valeur nil
TopLevelContainer	Renvoie True
type_	Renvoie une chaîne vide
LocationName	Renvoie le titre du document en cours
LocationURL	Renvoie l'URL en cours
Busy	Renvoie True lorsque la navigation est active, sinon False
Name	Renvoie une chaîne vide
HWND	Renvoie le handle de fenêtre du contrôle de navigation WebView2
FullName	Renvoie le chemin complet de l'exécutable du processus du navigateur Edge utilisé par le contrôle WebView2
Path	Renvoie le chemin complet du dossier du processus du navigateur Edge utilisé par le contrôle WebView2
ReadyState	Renvoie l'un des sous-ensembles de valeurs possibles, selon l'état du contrôle Edge : READYSTATE_UNINITIALIZED, READYSTATE_LOADING ou READYSTATE_COMPLETE

Propriétés en lecture-écriture publiées

Visible	Définit et renvoie la propriété Visible du composant Edge incorporé
StatusBar	Définit et renvoie la propriété StatusBarEnabled du composant Edge incorporé
StatusText	Ignore la valeur définie et renvoie une chaîne vide
ToolBar	Ignore la valeur définie et renvoie 0
MenuBar	Ignore la valeur définie et renvoie False
FullScreen	Ignore la valeur définie et renvoie False
Offline	Ignore la valeur définie et renvoie False
Silent	Définit et renvoie la valeur inverse de la propriété DefaultScriptDialogsEnabled du composant Edge incorporé.
RegisterAsBrowser	Ignore la valeur définie et renvoie False
RegisterAsDropTarget	Ignore la valeur définie et renvoie False
TheaterMode	Ignore la valeur définie et renvoie False
AddressBar	Ignore la valeur définie et renvoie False
Resizable	Ignore la valeur définie et renvoie True

Events

OnStatusTextChange	Non appelé
OnProgressChange	Non appelé
OnCommandStateChange	Déclenché lorsque l'événement OnHistoryChanged du composant Edge est déclenché
OnDownloadBegin	Non appelé
OnDownloadComplete	Non appelé
OnTitleChange	Déclenché lorsque l'événement OnDocumentTitleChanged du composant Edge est déclenché
OnPropertyChange	Non appelé
OnBeforeNavigate2	Déclenché lorsque l'événement OnNavigationStarting du composant Edge est déclenché
OnNewWindow2	Déclenché lorsque l'événement OnNewWindowRequested du composant Edge est déclenché
OnNavigateComplete2	Déclenché lorsque l'événement OnNavigationCompleted du composant Edge est déclenché
OnDocumentComplete	Déclenché lorsque l'événement OnNavigationCompleted du composant Edge est déclenché
OnQuit	Non appelé
OnVisible	Non appelé
OnToolBar	Non appelé
OnMenuBar	Non appelé
OnStatusBar	Non appelé
OnFullScreen	Non appelé
OnTheaterMode	Non appelé
OnWindowSetResizable	Non appelé
OnWindowSetLeft	Non appelé
OnWindowSetTop	Non appelé
OnWindowSetWidth	Non appelé
OnWindowSetHeight	Non appelé
OnWindowClosing	Non appelé
OnClientToHostWindow	Non appelé
OnSetSecureLockIcon	Non appelé
OnFileDownload	Non appelé
OnNavigateError	Non appelé
OnPrintTemplateInstantiation	Non appelé
OnPrintTemplateTeardown	Non appelé
OnUpdatePageStatus	Non appelé
OnPrivacyImpactedStateChange	Non appelé
OnNewWindow3	Déclenché lorsque l'événement OnNewWindowRequested du composant Edge est déclenché
OnSetPhishingFilterStatus	Non appelé
OnWindowStateChanged	Non appelé
OnNewProcess	Non appelé
OnThirdPartyUrlBlocked	Non appelé
OnRedirectXDomainBlocked	Non appelé
OnBeforeScriptExecute	Non appelé
OnWebWorkerStarted	Non appelé
OnWebWorkerFinsihed	Non appelé
OnShowScriptError	Non appelé

Nouveaux exemples de démos pour Edge

Des fichiers de démonstration installés avec le produit illustrent le nouveau composant Edge et le composant TWebBrowser. Ils se trouvent dans les dossiers suivants :

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