TsgcWebView2 ist eine neue visuelle Delphi-Komponente, die Microsoft Edge WebView2 kapselt und dir eine moderne Chromium-basierte Browser-Engine in jeder VCL-Anwendung verfügbar macht. Lege sie auf ein Formular, setze eine URL und du hast einen voll ausgestatteten eingebetteten Browser — samt Cookie-Verwaltung, Download-Steuerung, JavaScript-Integration, Druckunterstützung und mehr.
Anders als der mit aktuellen Delphi-Versionen mitgelieferte TEdgeBrowser unterstützt TsgcWebView2 jede Delphi-Version von Delphi 7 bis Delphi 13 — die breiteste Versionsunterstützung aller verfügbaren WebView2-Wrapper. Sie ist Teil der sgcWebSockets-Bibliothek von eSeGeCe.
Dieser Artikel zeigt den Funktionsumfang, demonstriert praktische Code-Beispiele, vergleicht direkt mit TEdgeBrowser und erklärt die interne Architektur.
Funktionsübersicht
TsgcWebView2 stellt einen großen Teil des WebView2-SDK über saubere Delphi-Ereignisse und -Methoden bereit. Hier die zwölf wichtigsten Fähigkeitsgruppen:
|
Navigation Navigate, GoBack, GoForward, Reload, Stop. Unterstützt POST-Navigation mit eigenen Headern und Request-Bodies. |
JavaScript-Ausführung Führe JavaScript asynchron oder synchron aus. Registriere Init-Skripte, die bei jedem Seitenladevorgang automatisch ausgeführt werden. |
Cookie-Verwaltung Cookies programmatisch lesen, hinzufügen, aktualisieren und löschen. Voller Zugriff auf Attribute wie Domain, Pfad und Ablaufdatum. |
|
Download-Steuerung Ereignisse für Download-Start, -Fortschritt und -Abschluss. Leite Downloads in eigene Pfade um oder brich sie komplett ab. |
Profilverwaltung Multi-Profil-Unterstützung für isolierte Browser-Sessions. Lösche Browsing-Daten (Cache, Cookies, Verlauf) pro Profil. |
Druckunterstützung Drucke die aktuelle Seite als PDF oder zeige den System-Druckdialog an. Steuere Papierformat, Ausrichtung und Ränder. |
|
Audio-/Stummsteuerung Erkenne, wann das Dokument Audio abspielt. Schalte den Mute-Zustand programmatisch um, ohne die Systemlautstärke zu verändern. |
Zertifikatsverwaltung Reagiere über dedizierte Ereignisse auf Client-Zertifikatsanfragen und Server-Zertifikatsfehler. |
Kontextmenü Fang das Rechtsklick-Kontextmenü ab und passe es vollständig an. Füge eigene Aktionen hinzu, entferne Menüpunkte oder ersetze sie. |
|
Favicon-Zugriff Lies die Favicon-URI der aktuellen Seite aus. Reagiere über ein dediziertes Ereignis auf Favicon-Änderungen. |
Virtual-Host-Mapping Mappe eigene Hostnamen auf lokale Ordner. Liefere lokale HTML-/CSS-/JS-Dateien so aus, als kämen sie von einem echten Webserver. |
Screenshot-Aufnahme Speichere den sichtbaren Seiteninhalt als PNG- oder JPEG-Bild. Nützlich für Thumbnails, Reports oder automatisierte Tests. |
Erste Schritte
Der einfachste Weg, TsgcWebView2 zu nutzen, ist, sie auf ein VCL-Formular zu legen und Navigate aufzurufen. Die Komponente kümmert sich automatisch um die Erstellung der WebView2-Umgebung, die Initialisierung des Controllers und das View-Binding.
// 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;Das Ereignis OnNavigationCompleted wird ausgelöst, nachdem die Seite fertig geladen wurde, und meldet, ob die Navigation erfolgreich war und welcher Fehlerstatus vorliegt. Das ist der natürliche Ort, um deine Oberfläche — Fenstertitel, Statusleiste, Zustand der Back-/Forward-Buttons — basierend auf der geladenen Seite zu aktualisieren.
Hinweis. Die Komponente erzeugt die WebView2-Umgebung lazy beim ersten Zugriff. Wenn du Umgebungsoptionen konfigurieren musst (Browser-Ordner, Sprache, Kommandozeilen-Switches), setze sie über die Eigenschaft EnvironmentOptions, bevor du Navigate aufrufst.
Cookie-Verwaltung
Das Unterobjekt CookieManager stellt die vollständige WebView2-Cookie-API bereit. Du kannst Cookies für die aktuelle URL auflisten, Cookies mit bestimmten Attributen hinzufügen oder aktualisieren und einzelne Cookies löschen oder alle auf einmal entfernen.
// 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', '/');Wenn du GetCookies aufrufst, kommen die Ergebnisse asynchron im Ereignis OnCookiesReceived an. Jedes Cookie enthält Name, Wert, Domain, Pfad, Ablaufzeit, Secure-Flag und HTTP-Only-Flag. Diese Funktion stellt TEdgeBrowser gar nicht bereit.
Tipp. Verwende AddOrUpdateCookie, um Authentifizierungs-Tokens einzuschleusen, bevor du auf eine geschützte Seite navigierst. So vermeidest du in Embedded-Browser-Szenarien einen Login-Formular-Flow.
JavaScript-Integration
TsgcWebView2 bietet drei Ansätze zur JavaScript-Ausführung, jeder für einen anderen Anwendungsfall:
Asynchrone Ausführung
Rufe ExecuteScript auf und behandle das Ergebnis im Ereignis OnScriptExecuted. Das ist der standardmäßige, nicht blockierende Ansatz.
// 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;Synchrone Ausführung
Wenn du das Ergebnis sofort brauchst, verwende ExecuteScriptSync. Das blockiert den aufrufenden Thread, bis das Skript abgeschlossen ist, und gibt das Ergebnis direkt zurück.
var
vTitle: string;
begin
vTitle := sgcWebView2.ExecuteScriptSync('document.title');
Caption := vTitle;
end;Init-Skripte
Init-Skripte werden einmal registriert und automatisch bei jedem Seitenladevorgang ausgeführt. Sie laufen vor jedem Seiten-JavaScript, ideal also, um globale Konfiguration oder Polyfills einzuschleusen.
// Runs on every page load, before any page scripts
sgcWebView2.AddInitScript('window.appVersion = "1.0";');Download-Verwaltung
Downloads werden über ein ereignisgesteuertes Modell behandelt. Wenn ein Download startet, kannst du im Ereignis OnDownloadStarting die Datei in einen eigenen Pfad umleiten, den Download abbrechen oder ihn mit den Standardwerten fortsetzen lassen. Ein separates Ereignis OnDownloadCompleted wird ausgelöst, wenn der Download abgeschlossen ist.
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;Hinweis. Der Parameter aState in OnDownloadCompleted zeigt, ob der Download erfolgreich war, abgebrochen wurde oder einen Fehler hatte. Prüfe diesen Wert, bevor du die heruntergeladene Datei weiterverarbeitest.
POST-Navigation & eigene Header
Die Standard-Navigation lädt eine URL per GET-Request. Für API-Tests, Formularübermittlungen oder Szenarien mit einer anderen HTTP-Methode kannst du mit NavigateWithPostData Methode, Body und Header in einem einzigen Aufruf angeben.
// 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'
);Der Header-Parameter akzeptiert einen CRLF-getrennten String im Format von HTTP-Headern. Praktisch, um Autorisierungs-Tokens, Content-Types oder andere von deinem Server erwartete Header einzuschleusen.
Vergleich mit TEdgeBrowser
Delphi liefert TEdgeBrowser seit Delphi 10.4 Sydney mit aus (über GetIt für XE7+ verfügbar). Es bietet einen einfachen WebView2-Wrapper, lässt aber viele SDK-Funktionen außen vor. Die folgende Tabelle zeigt genau, wo TsgcWebView2 weiter geht.
| Funktion | TEdgeBrowser | TsgcWebView2 |
|---|---|---|
| Delphi-Versionsunterstützung | nur XE7+ | D7 bis D13 |
| Cookie-Verwaltung | ✗ | ✓ vollständige API |
| Download-Fortschrittsereignisse | ✗ | ✓ Start / Fortschritt / Abschluss |
| Profil / Browsing-Daten löschen | ✗ | ✓ |
| Audio-/Mute-Steuerung | ✗ | ✓ |
| Favicon-Zugriff | ✗ | ✓ |
| Zertifikatsereignisse | ✗ | ✓ |
| Basic-Auth-Ereignisse | ✗ | ✓ |
| Statusleisten-Text | ✗ | ✓ |
| Virtual-Host-Mapping | ✗ | ✓ |
| Shared Buffer | ✗ | ✓ |
| Synchrones ExecuteScript | ✓ | ✓ |
| Screenshot-Aufnahme | ✓ | ✓ |
| Init-Skript | ✓ | ✓ |
| POST-Navigation | ✓ | ✓ |
| Druckunterstützung | ✓ | ✓ |
| Entwurfszeit-Einstellungen | wirft eine Exception, wenn WebView nicht erstellt | ✓ sichere TPersistent-Eigenschaften |
| Kontextmenü | PopupMenu-Merge | vollständige Ereignissteuerung |
| Graceful Degradation | ✗ | ✓ pro Funktion Versionsprüfungen |
| Roher COM-Zugriff | ✓ | ✓ |
TsgcWebView2 deckt alles ab, was TEdgeBrowser bietet, und legt zwölf Funktionen obendrauf — Cookie-Verwaltung, Download-Ereignisse, Profilsteuerung, Audio/Mute, Favicon-Zugriff, Zertifikatsbehandlung, Basic-Auth-Ereignisse, Statusleisten-Text, Virtual-Host-Mapping, Shared Buffer, vollständige Kontextmenü-Steuerung und Graceful Degradation. Außerdem unterstützt sie Delphi-Versionen bis zurück zu Delphi 7, während TEdgeBrowser mindestens XE7 voraussetzt.
Wichtig. TEdgeBrowser speichert seine Einstellungen direkt auf den COM-Interfaces. Wenn du eine Eigenschaft zur Entwurfszeit setzt, bevor die WebView2-Umgebung erstellt wurde, fliegt eine Access Violation. TsgcWebView2 vermeidet das vollständig, indem TPersistent-Unterobjekte verwendet werden, die Einstellungen zwischenspeichern und sie anwenden, sobald die Umgebung bereit ist.
Erweiterte Funktionen
Druck als PDF
Erzeuge mit einem einzigen Methodenaufruf ein PDF der aktuellen Seite. Die Ausgabedatei wird asynchron erstellt, und du kannst Papierformat, Ränder und Ausrichtung über Parameter steuern.
sgcWebView2.PrintToPdf('C:\output\page.pdf');Screenshot-Aufnahme
Erfasse den sichtbaren Bereich der Seite als PNG- oder JPEG-Bild. Der zweite Parameter gibt das Bildformat an: 0 für PNG, 1 für JPEG.
sgcWebView2.CapturePreviewToFile('C:\screenshots\page.png', 0); // 0 = PNGVirtual-Host-Mapping
Mappe einen eigenen Hostnamen auf einen lokalen Ordner, sodass dein eingebetteter Browser lokale Dateien über Standard-HTTPS-URLs laden kann. Das vermeidet CORS-Probleme und lässt lokale Inhalte sich genauso verhalten wie entfernte.
// Serve local files via https://app.local/
sgcWebView2.SetVirtualHostNameToFolderMapping(
'app.local', 'C:\MyApp\WebContent', 1);
sgcWebView2.Navigate('https://app.local/index.html');Tipp. Virtual-Host-Mapping ist besonders praktisch für Single-Page-Anwendungen. Bündele HTML, CSS und JavaScript mit deiner Delphi-Anwendung und lade sie dann über einen gemappten Hostnamen, um vollen Zugriff auf Web-APIs zu erhalten, die einen sicheren Ursprung erfordern.
Audio- und Mute-Steuerung
Erkenne, wann das geladene Dokument Audio abspielt, und schalte Mute, ohne die Systemlautstärke zu verändern. Praktisch für Anwendungen, die viel medialastige Inhalte einbetten.
sgcWebView2.IsMuted := True;
if sgcWebView2.IsDocumentPlayingAudio then
ShowMessage('Audio is playing');Architektur & Design
TsgcWebView2 basiert auf einer sauberen Drei-Schichten-Architektur, die Verantwortlichkeiten trennt und gleichzeitig die für Entwickler sichtbare API einfach hält:
- API-Schicht (COM-Interfaces). Direkte Übersetzungen der Microsoft-WebView2-COM-Interfaces nach Delphi. Das sind die rohen Bausteine — low-level, versionsspezifisch und nicht zur direkten Verwendung in Anwendungscode gedacht.
- Klassenschicht (Wrapper). Delphi-native Wrapper-Klassen, die COM-Objektlebenszyklen verwalten, Callback-Routing übernehmen und eine saubere objektorientierte API liefern. Diese Schicht schirmt dich von der COM-Klempnerei ab.
- Komponenten-Schicht (visuell). Die
TsgcWebView2-Komponente selbst — ein TWinControl-Nachfahre, den du auf ein Formular legst. Sie veröffentlicht Eigenschaften, Ereignisse und Methoden, die auf die Klassenschicht darunter abbilden.
Power-User, die Zugriff auf SDK-Funktionen brauchen, die die Komponente noch nicht wrappt, erreichen die rohen COM-Interfaces über die Eigenschaften WebView, Controller und Environment. Du kannst jede COM-Methode direkt aufrufen und profitierst gleichzeitig vom Lifecycle-Management der Komponente.
Graceful Degradation
Nicht jede WebView2-Funktion ist in jeder Version der Edge-Runtime verfügbar. TsgcWebView2 prüft beim Start die installierte Runtime-Version und bietet eine Methode Supports(), mit der du die Verfügbarkeit einer Funktion vor dem Aufruf abfragen kannst. So vermeidest du Laufzeitfehler auf Maschinen mit älteren Edge-Versionen.
Entwurfszeit-Sicherheit
Alle konfigurierbaren Einstellungen werden als TPersistent-Unterobjekte bereitgestellt. Du kannst die Komponente zur Entwurfszeit gefahrlos im Objektinspektor konfigurieren, ohne die COM-Initialisierung auszulösen. Die Einstellungen werden zwischengespeichert und automatisch angewendet, sobald die WebView2-Umgebung zur Laufzeit erzeugt wird.
Voraussetzungen
Um TsgcWebView2 in deiner Anwendung einzusetzen, brauchst du:
- Microsoft Edge WebView2 Runtime. Bereits in Windows 10 (Version 1803+) und Windows 11 enthalten. Für ältere Windows-Versionen oder kontrollierte Deployments lädst du den Evergreen-Bootstrapper oder die Fixed-Version-Runtime von Microsoft herunter.
- WebView2Loader.dll. Mit der Komponente mitgeliefert. Lege sie neben deine Anwendungs-Executable. Diese kleine DLL übernimmt die Erkennung und das Laden der Runtime.
- Nur Windows. WebView2 ist eine Windows-Technologie. Die Komponente richtet sich an VCL-Anwendungen auf Windows 7 und neuer (Windows 10/11 wird für vollen Funktionsumfang empfohlen).
Hinweis. Du kannst vor dem Erstellen der Komponente prüfen, ob die WebView2-Runtime installiert ist. Ist sie nicht vorhanden, kannst du den Nutzer zur Installation auffordern oder auf ein anderes Browser-Control zurückfallen.
Fazit
TsgcWebView2 ist der vollständigste WebView2-Wrapper, der für Delphi verfügbar ist. Sie ist eine strikte Obermenge von TEdgeBrowser und fügt zwölf Funktionen hinzu, die Embarcaderos eingebaute Komponente nicht bereitstellt — Cookie-Verwaltung, Download-Ereignisse, Profilsteuerung, Audio-Erkennung, Favicon-Zugriff, Zertifikatsbehandlung, Basic Authentication, Statusleisten-Text, Virtual-Host-Mapping, Shared Buffer, vollständige Kontextmenü-Steuerung und Graceful Degradation.
Sie unterstützt die breiteste Palette an Delphi-Versionen aller WebView2-Wrapper, von Delphi 7 bis Delphi 13. Egal, ob du eine Altanwendung auf einem älteren Compiler pflegst oder ein neues Projekt auf dem neuesten Delphi baust — dieselbe Komponente und dieselbe API funktionieren überall.
Die API ist so gestaltet, dass sie leicht zu erlernen ist — Komponente auf das Formular legen, Navigate aufrufen und Ereignisse behandeln — und gleichzeitig leistungsstark genug für fortgeschrittene Szenarien dank rohem COM-Zugriff und Versionsprüfung pro Funktion. Für Delphi-Entwickler, die einen modernen eingebetteten Browser brauchen, ist TsgcWebView2 die natürliche Wahl.