TsgcWebView2 est un nouveau composant Delphi visuel qui encapsule Microsoft Edge WebView2 : tu obtiens ainsi un moteur de navigateur moderne basé sur Chromium à l'intérieur de n'importe quelle application VCL. Pose-le sur une fiche, définis une URL et tu as un navigateur embarqué complet — gestion des cookies, contrôle des téléchargements, intégration JavaScript, support d'impression et plus.
Contrairement au TEdgeBrowser intégré aux versions récentes de Delphi, TsgcWebView2 prend en charge toutes les versions de Delphi 7 à Delphi 13 — le support de versions le plus large parmi tous les wrappers WebView2 disponibles. Il fait partie de la bibliothèque sgcWebSockets d'eSeGeCe.
Cet article couvre l'ensemble de ses fonctionnalités, montre des exemples de code pratiques, le compare directement à TEdgeBrowser et explique son architecture interne.
Aperçu des fonctionnalités
TsgcWebView2 expose une large surface du SDK WebView2 via des événements et méthodes Delphi propres. Voici les douze grands groupes de capacités :
|
Navigation Navigate, GoBack, GoForward, Reload, Stop. Prend en charge la navigation POST avec en-têtes personnalisés et corps de requête. |
Exécution JavaScript Exécute du JavaScript de façon asynchrone ou synchrone. Enregistre des scripts d'init qui s'exécutent automatiquement à chaque chargement de page. |
Gestion des cookies Récupère, ajoute, met à jour et supprime des cookies par programmation. Accès complet aux attributs des cookies, y compris domaine, chemin et expiration. |
|
Contrôle des téléchargements Événements pour le démarrage, la progression et la fin des téléchargements. Redirige les téléchargements vers des chemins personnalisés ou annule-les entièrement. |
Gestion des profils Support multi-profils pour des sessions de navigation isolées. Efface les données de navigation (cache, cookies, historique) par profil. |
Support d'impression Imprime la page actuelle au format PDF ou affiche la boîte de dialogue d'impression système. Contrôle la taille du papier, l'orientation et les marges. |
|
Contrôle audio / mute Détecte quand le document joue de l'audio. Bascule l'état mute par programmation sans affecter le volume système. |
Gestion des certificats Réponds aux demandes de certificat client et aux erreurs de certificat serveur via des événements dédiés. |
Menu contextuel Intercepte et personnalise entièrement le menu contextuel du clic droit. Ajoute, supprime ou remplace les éléments du menu par tes propres actions. |
|
Accès au favicon Récupère l'URI du favicon de la page actuelle. Réagis aux changements de favicon via un événement dédié. |
Mapping d'hôte virtuel Associe des noms d'hôte personnalisés à des dossiers locaux. Sers des fichiers HTML/CSS/JS locaux comme s'ils venaient d'un vrai serveur web. |
Capture d'écran Sauvegarde le contenu visible de la page comme image PNG ou JPEG. Utile pour les vignettes, les rapports ou les tests automatisés. |
Premiers pas
La façon la plus simple d'utiliser TsgcWebView2 est de le poser sur une fiche VCL et d'appeler Navigate. Le composant gère automatiquement la création de l'environnement WebView2, l'initialisation du contrôleur et la liaison de la vue.
// Drop TsgcWebView2 on your form, then:
procedure TForm1.FormCreate(Sender: TObject);
begin
sgcWebView2.Navigate('https://www.example.com');
end;
procedure TForm1.sgcWebView2NavigationCompleted(Sender: TObject;
aIsSuccess: Boolean; aWebErrorStatus: Integer);
begin
if aIsSuccess then
Caption := sgcWebView2.DocumentTitle;
end;L'événement OnNavigationCompleted se déclenche après la fin du chargement de la page : il indique si la navigation a réussi et le code de statut d'erreur éventuel. C'est l'endroit naturel pour mettre à jour ton interface — titre de fenêtre, barre de statut, état des boutons précédent/suivant — en fonction de la page chargée.
Note. Le composant crée l'environnement WebView2 paresseusement à la première utilisation. Si tu dois configurer des options d'environnement (dossier du navigateur, langue, switches de ligne de commande), définis-les via la propriété EnvironmentOptions avant d'appeler Navigate.
Gestion des cookies
Le sous-objet CookieManager expose l'API complète des cookies WebView2. Tu peux lister les cookies pour l'URL courante, ajouter ou mettre à jour des cookies avec des attributs spécifiques, et supprimer des cookies individuels ou tous les effacer d'un coup.
// List cookies for the current page
sgcWebView2.CookieManager.GetCookies(sgcWebView2.URL);
// Delete all cookies
sgcWebView2.CookieManager.DeleteAllCookies;
// Add a cookie
sgcWebView2.CookieManager.AddOrUpdateCookie(
'session', 'abc123', '.example.com', '/');Quand tu appelles GetCookies, les résultats arrivent de façon asynchrone dans l'événement OnCookiesReceived. Chaque cookie inclut son nom, sa valeur, son domaine, son chemin, son expiration, son flag secure et son flag HTTP-only. C'est l'une des fonctionnalités que TEdgeBrowser n'expose pas du tout.
Astuce. Utilise AddOrUpdateCookie pour injecter des jetons d'authentification avant de naviguer vers une page protégée. Cela évite le besoin d'un flux de formulaire de connexion dans les scénarios de navigateur embarqué.
Intégration JavaScript
TsgcWebView2 propose trois approches d'exécution JavaScript, chacune adaptée à un cas d'usage différent :
Exécution asynchrone
Appelle ExecuteScript et gère le résultat dans l'événement OnScriptExecuted. C'est l'approche standard, non bloquante.
// Async execution — result arrives in OnScriptExecuted event
sgcWebView2.ExecuteScript('document.title');
procedure TForm1.sgcWebView2ScriptExecuted(Sender: TObject;
const aResult: string; aErrorCode: Integer);
begin
if aErrorCode = 0 then
ShowMessage('Title: ' + aResult);
end;Exécution synchrone
Quand tu as besoin du résultat immédiatement, utilise ExecuteScriptSync. Cela bloque le thread appelant jusqu'à ce que le script se termine et renvoie directement le résultat.
var
vTitle: string;
begin
vTitle := sgcWebView2.ExecuteScriptSync('document.title');
Caption := vTitle;
end;Scripts d'init
Les scripts d'init sont enregistrés une fois et s'exécutent automatiquement à chaque chargement de page. Ils s'exécutent avant tout JavaScript de page, ce qui les rend idéaux pour injecter une configuration globale ou des polyfills.
// Runs on every page load, before any page scripts
sgcWebView2.AddInitScript('window.appVersion = "1.0";');Gestion des téléchargements
Les téléchargements sont gérés via un modèle événementiel. Quand un téléchargement commence, l'événement OnDownloadStarting te permet de rediriger le fichier vers un chemin personnalisé, de l'annuler ou de le laisser continuer avec les valeurs par défaut. Un événement distinct OnDownloadCompleted se déclenche à la fin du téléchargement.
procedure TForm1.sgcWebView2DownloadStarting(Sender: TObject;
const aURI, aResultFilePath: string;
var aCancel: Boolean;
var aHandled: Boolean;
var aFilePath: string);
begin
// Redirect download to custom folder
aFilePath := 'C:\Downloads\' + ExtractFileName(aResultFilePath);
aHandled := True;
end;
procedure TForm1.sgcWebView2DownloadCompleted(Sender: TObject;
const aFilePath: string; aState: Integer);
begin
ShowMessage('Download complete: ' + aFilePath);
end;Note. Le paramètre aState dans OnDownloadCompleted indique si le téléchargement a réussi, a été annulé ou a rencontré une erreur. Vérifie cette valeur avant de traiter le fichier téléchargé.
Navigation POST et en-têtes personnalisés
La navigation standard charge une URL avec une requête GET. Pour les tests d'API, la soumission de formulaires ou tout scénario qui nécessite une méthode HTTP différente, NavigateWithPostData te permet de spécifier la méthode, le corps et les en-têtes en un seul appel.
// Navigate with POST data and custom headers
sgcWebView2.NavigateWithPostData(
'https://api.example.com/submit',
'POST',
'{"key":"value"}',
'Content-Type: application/json' + #13#10 +
'Authorization: Bearer token123'
);Le paramètre headers accepte une chaîne délimitée par CRLF, suivant le même format que les en-têtes HTTP. C'est utile pour injecter des jetons d'autorisation, des content-types ou des en-têtes personnalisés attendus par ton serveur.
Comparaison avec TEdgeBrowser
Delphi inclut TEdgeBrowser à partir de Delphi 10.4 Sydney (disponible via GetIt pour XE7+). Il fournit un wrapper WebView2 de base, mais laisse de nombreuses fonctionnalités du SDK non exposées. Le tableau suivant montre exactement où TsgcWebView2 va plus loin.
| Fonctionnalité | TEdgeBrowser | TsgcWebView2 |
|---|---|---|
| Versions de Delphi prises en charge | XE7+ uniquement | D7 à D13 |
| Gestion des cookies | ✗ | ✓ API complète |
| Événements de progression des téléchargements | ✗ | ✓ Démarrage / progression / fin |
| Profil / effacement des données de navigation | ✗ | ✓ |
| Contrôle audio / mute | ✗ | ✓ |
| Accès au favicon | ✗ | ✓ |
| Événements de certificat | ✗ | ✓ |
| Événements d'authentification basic | ✗ | ✓ |
| Texte de la barre de statut | ✗ | ✓ |
| Mapping d'hôte virtuel | ✗ | ✓ |
| Shared Buffer | ✗ | ✓ |
| ExecuteScript synchrone | ✓ | ✓ |
| Capture d'écran | ✓ | ✓ |
| Script d'init | ✓ | ✓ |
| Navigation POST | ✓ | ✓ |
| Support d'impression | ✓ | ✓ |
| Paramètres au design-time | Lève une exception si WebView non créé | ✓ Propriétés TPersistent sûres |
| Menu contextuel | Fusion PopupMenu | Contrôle complet par événement |
| Dégradation gracieuse | ✗ | ✓ Vérifications de version par fonctionnalité |
| Accès COM brut | ✓ | ✓ |
TsgcWebView2 couvre tout ce que propose TEdgeBrowser et ajoute douze fonctionnalités — gestion des cookies, événements de téléchargement, contrôle des profils, audio/mute, accès au favicon, gestion des certificats, événements d'authentification basic, texte de barre de statut, mapping d'hôte virtuel, shared buffer, contrôle complet du menu contextuel et dégradation gracieuse. Il prend également en charge les versions de Delphi jusqu'à Delphi 7, alors que TEdgeBrowser exige au minimum XE7.
Important. TEdgeBrowser stocke ses paramètres directement sur les interfaces COM. Si tu définis une propriété au design-time avant la création de l'environnement WebView2, il lève une violation d'accès. TsgcWebView2 évite cela entièrement en utilisant des sous-objets TPersistent qui mettent en tampon les paramètres et les appliquent quand l'environnement est prêt.
Fonctionnalités avancées
Impression en PDF
Génère un PDF de la page actuelle avec un seul appel de méthode. Le fichier de sortie est créé de façon asynchrone et tu peux contrôler la taille du papier, les marges et l'orientation via les paramètres.
sgcWebView2.PrintToPdf('C:\output\page.pdf');Capture d'écran
Capture la zone visible de la page comme image PNG ou JPEG. Le second paramètre spécifie le format d'image : 0 pour PNG, 1 pour JPEG.
sgcWebView2.CapturePreviewToFile('C:\screenshots\page.png', 0); // 0 = PNGMapping d'hôte virtuel
Associe un nom d'hôte personnalisé à un dossier local pour que ton navigateur embarqué puisse charger des fichiers locaux via des URL HTTPS standard. Cela évite les problèmes CORS et fait en sorte que le contenu local se comporte exactement comme du contenu distant.
// Serve local files via https://app.local/
sgcWebView2.SetVirtualHostNameToFolderMapping(
'app.local', 'C:\MyApp\WebContent', 1);
sgcWebView2.Navigate('https://app.local/index.html');Astuce. Le mapping d'hôte virtuel est particulièrement utile pour les applications single-page. Empaquète ton HTML, CSS et JavaScript avec ton application Delphi, puis charge-les via un nom d'hôte mappé pour obtenir un accès complet aux API web qui exigent une origine sécurisée.
Contrôle audio et mute
Détecte quand le document chargé joue de l'audio et bascule mute sans affecter le volume système. C'est utile pour les applications qui embarquent du contenu média lourd.
sgcWebView2.IsMuted := True;
if sgcWebView2.IsDocumentPlayingAudio then
ShowMessage('Audio is playing');Architecture et conception
TsgcWebView2 est construit sur une architecture propre à trois couches qui sépare les responsabilités tout en gardant l'API tournée vers le développeur simple :
- Couche API (interfaces COM). Traductions directes des interfaces COM Microsoft WebView2 en Delphi. Ce sont les briques de base brutes — bas niveau, spécifiques à une version, et non destinées à être utilisées directement dans le code applicatif.
- Couche classe (wrappers). Classes wrapper natives Delphi qui gèrent la durée de vie des objets COM, gèrent le routage des callbacks et fournissent une API orientée objet propre. Cette couche t'abrite de la plomberie COM.
- Couche composant (visuelle). Le composant
TsgcWebView2lui-même — un descendant de TWinControl que tu poses sur une fiche. Il publie des propriétés, des événements et des méthodes qui se mappent à la couche classe en dessous.
Pour les utilisateurs avancés qui ont besoin d'accéder à des fonctionnalités du SDK pas encore encapsulées par le composant, les interfaces COM brutes sont accessibles via les propriétés WebView, Controller et Environment. Tu peux appeler n'importe quelle méthode COM directement tout en bénéficiant de la gestion du cycle de vie du composant.
Dégradation gracieuse
Toutes les fonctionnalités WebView2 ne sont pas disponibles dans toutes les versions du runtime Edge. TsgcWebView2 vérifie la version du runtime installée au démarrage et expose une méthode Supports() pour interroger la disponibilité d'une fonctionnalité avant de l'appeler. Cela évite les erreurs runtime sur les machines avec des versions Edge plus anciennes.
Sécurité au design-time
Tous les paramètres configurables sont exposés comme sous-objets TPersistent. Tu peux configurer en toute sécurité le composant au design-time dans l'Object Inspector sans déclencher d'initialisation COM. Les paramètres sont mis en tampon et appliqués automatiquement quand l'environnement WebView2 est créé au runtime.
Prérequis
Pour utiliser TsgcWebView2 dans ton application, tu as besoin de :
- Microsoft Edge WebView2 Runtime. Inclus avec Windows 10 (version 1803+) et Windows 11. Pour les versions Windows plus anciennes ou les déploiements contrôlés, télécharge le Evergreen Bootstrapper ou le runtime Fixed Version depuis Microsoft.
- WebView2Loader.dll. Inclus avec le composant. Place-le à côté de l'exécutable de ton application. Cette petite DLL gère la détection et le chargement du runtime.
- Windows uniquement. WebView2 est une technologie Windows. Le composant cible les applications VCL sur Windows 7 et plus récents (Windows 10/11 recommandé pour un support complet).
Note. Tu peux vérifier si le runtime WebView2 est installé avant de créer le composant. S'il n'est pas présent, tu peux orienter l'utilisateur vers son installation ou te rabattre sur un autre contrôle de navigateur.
Conclusion
TsgcWebView2 est le wrapper WebView2 le plus complet disponible pour Delphi. C'est un sur-ensemble strict de TEdgeBrowser, qui ajoute douze fonctionnalités que le composant intégré d'Embarcadero n'expose pas — gestion des cookies, événements de téléchargement, contrôle des profils, détection audio, accès au favicon, gestion des certificats, authentification basic, texte de barre de statut, mapping d'hôte virtuel, shared buffer, contrôle complet du menu contextuel et dégradation gracieuse.
Il prend en charge la plus large plage de versions de Delphi de tous les wrappers WebView2, de Delphi 7 à Delphi 13. Que tu maintiennes une application legacy sur un compilateur plus ancien ou que tu construises un nouveau projet sur le dernier Delphi, le même composant et la même API fonctionnent partout.
L'API est conçue pour être facile à apprendre — pose le composant sur une fiche, appelle Navigate et gère les événements — tout en restant assez puissante pour les scénarios avancés via l'accès COM brut et la vérification de version par fonctionnalité. Pour les développeurs Delphi qui ont besoin d'un navigateur embarqué moderne, TsgcWebView2 est le choix naturel.