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

De RAD Studio
Aller à : navigation, rechercher

Remonter à VCL


Dans RAD Studio 10.4 Alexandria, 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).

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 :

GetIt package manager.png

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 :

EdgeView2 installed.png

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 :

Form5Button1.png

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