TsgcWebView2 is een nieuwe visuele Delphi-component die Microsoft Edge WebView2 omhult en je een moderne Chromium-gebaseerde browserengine biedt binnen elke VCL-applicatie. Plaats hem op een form, stel een URL in en je hebt een volwaardige ingebedde browser — compleet met cookiebeheer, downloadbeheer, JavaScript-integratie, printondersteuning en meer.
In tegenstelling tot de ingebouwde TEdgeBrowser die met recente Delphi-versies wordt meegeleverd, ondersteunt TsgcWebView2 elke Delphi-versie van Delphi 7 tot en met Delphi 13 — de breedste versie-ondersteuning van alle beschikbare WebView2-wrappers. Hij maakt deel uit van de sgcWebSockets-bibliotheek van eSeGeCe.
Dit artikel beschrijft de functies, toont praktische codevoorbeelden, vergelijkt de component één-op-één met TEdgeBrowser en legt de interne architectuur uit.
Overzicht van functies
TsgcWebView2 maakt een breed deel van de WebView2-SDK toegankelijk via overzichtelijke Delphi-events en -methoden. Hieronder de twaalf belangrijkste capaciteitsgroepen:
|
Navigatie Navigate, GoBack, GoForward, Reload, Stop. Ondersteunt POST-navigatie met aangepaste headers en request-bodies. |
JavaScript-uitvoering Voer JavaScript asynchroon of synchroon uit. Registreer init-scripts die bij elke pagina-laad automatisch worden uitgevoerd. |
Cookiebeheer Cookies programmatisch ophalen, toevoegen, bijwerken en verwijderen. Volledige toegang tot cookie-attributen, inclusief domain, path en expiry. |
|
Downloadbeheer Events voor download-start, voortgang en voltooiing. Stuur downloads om naar aangepaste paden of annuleer ze volledig. |
Profielbeheer Multi-profiel-ondersteuning voor geïsoleerde browsesessies. Wis browsegegevens (cache, cookies, geschiedenis) per profiel. |
Printondersteuning Print de huidige pagina naar PDF of toon het systeemprintdialoogvenster. Beheer papierformaat, oriëntatie en marges. |
|
Audio- en mute-bediening Detecteer wanneer het document audio afspeelt. Schakel de mute-status programmatisch zonder het systeemvolume te beïnvloeden. |
Certificaatafhandeling Reageer op aanvragen voor clientcertificaten en op fouten met servercertificaten via speciale events. |
Contextmenu Onderschep en pas het rechtsklik-contextmenu volledig aan. Voeg menu-items toe, verwijder ze of vervang ze door eigen acties. |
|
Favicon-toegang Haal de favicon-URI van de huidige pagina op. Reageer op favicon-wijzigingen via een speciaal event. |
Virtual host-mapping Koppel aangepaste hostnamen aan lokale mappen. Serveer lokale HTML/CSS/JS-bestanden alsof ze van een echte webserver komen. |
Screenshot maken Sla de zichtbare pagina-inhoud op als PNG- of JPEG-afbeelding. Handig voor thumbnails, rapporten of geautomatiseerde tests. |
Aan de slag
De eenvoudigste manier om TsgcWebView2 te gebruiken, is hem op een VCL-form te plaatsen en Navigate aan te roepen. De component verzorgt automatisch het aanmaken van de WebView2-omgeving, de initialisatie van de controller en de binding met de view.
// Plaats TsgcWebView2 op je form en doe vervolgens:
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;Het OnNavigationCompleted-event wordt afgevuurd nadat de pagina klaar is met laden en geeft aan of de navigatie is geslaagd, plus een eventuele foutstatuscode. Dit is de natuurlijke plek om je UI bij te werken — venstertitel, statusbalk, status van vorige/volgende-knoppen — op basis van de geladen pagina.
Let op. Het component maakt de WebView2-omgeving lui aan bij het eerste gebruik. Als je omgevingsopties moet configureren (browser-map, taal, command-line-switches), stel ze dan in via de EnvironmentOptions-property voordat je Navigate aanroept.
Cookiebeheer
Het CookieManager-subobject biedt toegang tot de volledige WebView2-cookie-API. Je kunt cookies voor de huidige URL opsommen, cookies met specifieke attributen toevoegen of bijwerken en individuele cookies verwijderen of allemaal in één keer wissen.
// Cookies voor de huidige pagina opsommen
sgcWebView2.CookieManager.GetCookies(sgcWebView2.URL);
// Alle cookies verwijderen
sgcWebView2.CookieManager.DeleteAllCookies;
// Een cookie toevoegen
sgcWebView2.CookieManager.AddOrUpdateCookie(
'session', 'abc123', '.example.com', '/');Wanneer je GetCookies aanroept, komen de resultaten asynchroon binnen via het OnCookiesReceived-event. Elke cookie bevat de naam, waarde, domain, path, expiry, secure-flag en HTTP-only-flag. Dit is een van de functies die TEdgeBrowser helemaal niet ontsluit.
Tip. Gebruik AddOrUpdateCookie om authenticatietokens te injecteren voordat je naar een beveiligde pagina navigeert. Zo voorkom je een loginformulier-flow in scenario's met een ingebedde browser.
JavaScript-integratie
TsgcWebView2 biedt drie benaderingen voor JavaScript-uitvoering, elk geschikt voor een ander gebruiksscenario:
Asynchrone uitvoering
Roep ExecuteScript aan en handel het resultaat af in het OnScriptExecuted-event. Dit is de standaard, niet-blokkerende benadering.
// Asynchrone uitvoering — resultaat komt binnen 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 uitvoering
Wanneer je het resultaat onmiddellijk nodig hebt, gebruik je ExecuteScriptSync. Dit blokkeert de aanroepende thread totdat het script klaar is en geeft het resultaat direct terug.
var
vTitle: string;
begin
vTitle := sgcWebView2.ExecuteScriptSync('document.title');
Caption := vTitle;
end;Init-scripts
Init-scripts worden eenmaal geregistreerd en worden automatisch uitgevoerd bij elke pagina-laad. Ze draaien voor alle pagina-JavaScript, waardoor ze ideaal zijn voor het injecteren van globale configuratie of polyfills.
// Wordt uitgevoerd bij elke pagina-laad, voor alle pagina-scripts
sgcWebView2.AddInitScript('window.appVersion = "1.0";');Downloadbeheer
Downloads worden afgehandeld via een event-gedreven model. Wanneer een download begint, kun je via het OnDownloadStarting-event het bestand omleiden naar een aangepast pad, het annuleren of het met standaardinstellingen laten doorgaan. Een apart OnDownloadCompleted-event wordt afgevuurd wanneer de download is voltooid.
procedure TForm1.sgcWebView2DownloadStarting(Sender: TObject;
const aURI, aResultFilePath: string;
var aCancel: Boolean;
var aHandled: Boolean;
var aFilePath: string);
begin
// Download omleiden naar aangepaste map
aFilePath := 'C:\Downloads\' + ExtractFileName(aResultFilePath);
aHandled := True;
end;
procedure TForm1.sgcWebView2DownloadCompleted(Sender: TObject;
const aFilePath: string; aState: Integer);
begin
ShowMessage('Download complete: ' + aFilePath);
end;Let op. De aState-parameter in OnDownloadCompleted geeft aan of de download is geslaagd, geannuleerd of een fout heeft gegeven. Controleer deze waarde voordat je het gedownloade bestand verwerkt.
POST-navigatie en aangepaste headers
Standaardnavigatie laadt een URL met een GET-request. Voor API-tests, formulier-submits of elk scenario waarvoor een andere HTTP-methode nodig is, kun je met NavigateWithPostData de methode, body en headers in één aanroep opgeven.
// Navigeren met POST-data en aangepaste headers
sgcWebView2.NavigateWithPostData(
'https://api.example.com/submit',
'POST',
'{"key":"value"}',
'Content-Type: application/json' + #13#10 +
'Authorization: Bearer token123'
);De headers-parameter accepteert een string gescheiden door CRLF, in hetzelfde formaat als HTTP-headers. Dit is handig voor het injecteren van authorization-tokens, content-types of aangepaste headers die je server verwacht.
Vergelijking met TEdgeBrowser
Delphi wordt vanaf Delphi 10.4 Sydney geleverd met TEdgeBrowser (beschikbaar via GetIt voor XE7+). Deze biedt een basale WebView2-wrapper, maar laat veel SDK-functies onontsloten. De volgende tabel laat precies zien waar TsgcWebView2 verder gaat.
| Functie | TEdgeBrowser | TsgcWebView2 |
|---|---|---|
| Delphi-versie-ondersteuning | Alleen XE7+ | D7 tot en met D13 |
| Cookiebeheer | ✗ | ✓ Volledige API |
| Download-progress-events | ✗ | ✓ Start / voortgang / voltooiing |
| Profielen / browsegegevens wissen | ✗ | ✓ |
| Audio- en mute-bediening | ✗ | ✓ |
| Favicon-toegang | ✗ | ✓ |
| Certificaat-events | ✗ | ✓ |
| Basic-auth-events | ✗ | ✓ |
| Statusbalktekst | ✗ | ✓ |
| Virtual host-mapping | ✗ | ✓ |
| Shared buffer | ✗ | ✓ |
| Synchrone ExecuteScript | ✓ | ✓ |
| Screenshot maken | ✓ | ✓ |
| Init-script | ✓ | ✓ |
| POST-navigatie | ✓ | ✓ |
| Printondersteuning | ✓ | ✓ |
| Design-time-instellingen | Geeft een fout als WebView niet is aangemaakt | ✓ Veilige TPersistent-properties |
| Contextmenu | PopupMenu-samenvoeging | Volledige event-controle |
| Graceful degradation | ✗ | ✓ Versiecontroles per functie |
| Directe COM-toegang | ✓ | ✓ |
TsgcWebView2 dekt alles wat TEdgeBrowser biedt en voegt daar twaalf functies aan toe — cookiebeheer, download-events, profielbeheer, audio en mute, favicon-toegang, certificaatafhandeling, basic-auth-events, statusbalktekst, virtual host-mapping, shared buffer, volledige controle over het contextmenu en graceful degradation. Bovendien ondersteunt het Delphi-versies tot en met Delphi 7, terwijl TEdgeBrowser minimaal XE7 vereist.
Belangrijk. TEdgeBrowser bewaart zijn instellingen direct op de COM-interfaces. Als je tijdens design-time een property instelt voordat de WebView2-omgeving is aangemaakt, krijg je een access violation. TsgcWebView2 voorkomt dit volledig door TPersistent-subobjecten te gebruiken die instellingen bufferen en toepassen wanneer de omgeving klaar is.
Geavanceerde functies
Naar PDF afdrukken
Genereer een PDF van de huidige pagina met één enkele methode-aanroep. Het uitvoerbestand wordt asynchroon aangemaakt en je kunt papierformaat, marges en oriëntatie via parameters bedienen.
sgcWebView2.PrintToPdf('C:\output\page.pdf');Screenshot maken
Leg het zichtbare deel van de pagina vast als PNG- of JPEG-afbeelding. De tweede parameter geeft het afbeeldingsformaat aan: 0 voor PNG, 1 voor JPEG.
sgcWebView2.CapturePreviewToFile('C:\screenshots\page.png', 0); // 0 = PNGVirtual host-mapping
Koppel een aangepaste hostnaam aan een lokale map zodat je ingebedde browser lokale bestanden kan laden via standaard HTTPS-URL's. Zo voorkom je CORS-problemen en gedraagt lokale content zich precies als remote content.
// Lokale bestanden serveren via https://app.local/
sgcWebView2.SetVirtualHostNameToFolderMapping(
'app.local', 'C:\MyApp\WebContent', 1);
sgcWebView2.Navigate('https://app.local/index.html');Tip. Virtual host-mapping is bijzonder nuttig voor single-page-applicaties. Bundel je HTML, CSS en JavaScript met je Delphi-applicatie en laad het vervolgens via een gemapte hostnaam om volledige toegang te krijgen tot web-API's die een secure origin vereisen.
Audio- en mute-bediening
Detecteer wanneer het geladen document audio afspeelt en schakel mute zonder het systeemvolume te beïnvloeden. Dit is nuttig voor applicaties die media-zware content insluiten.
sgcWebView2.IsMuted := True;
if sgcWebView2.IsDocumentPlayingAudio then
ShowMessage('Audio wordt afgespeeld');Architectuur en ontwerp
TsgcWebView2 is gebouwd op een nette drielaagse architectuur die verantwoordelijkheden scheidt en tegelijkertijd de ontwikkelaars-API eenvoudig houdt:
- API-laag (COM-interfaces). Directe vertalingen van de Microsoft WebView2-COM-interfaces naar Delphi. Dit zijn de ruwe bouwstenen — low-level, versie-specifiek en niet bedoeld voor direct gebruik in applicatiecode.
- Klasse-laag (wrappers). Delphi-native wrapper-klassen die de levensduur van COM-objecten beheren, callback-routing afhandelen en een nette objectgeoriënteerde API bieden. Deze laag schermt je af van het COM-werk.
- Component-laag (visueel). Het
TsgcWebView2-component zelf — een TWinControl-afstammeling die je op een form plaatst. Het publiceert properties, events en methodes die afbeelden op de onderliggende klasse-laag.
Voor power-users die toegang nodig hebben tot SDK-functies die nog niet door het component zijn omhuld, zijn de directe COM-interfaces beschikbaar via de WebView-, Controller- en Environment-properties. Je kunt elke COM-methode rechtstreeks aanroepen terwijl je toch profiteert van het lifecycle-beheer van het component.
Graceful degradation
Niet elke WebView2-functie is beschikbaar in elke versie van de Edge-runtime. TsgcWebView2 controleert bij het opstarten de geïnstalleerde runtime-versie en biedt een Supports()-methode zodat je vóór de aanroep kunt opvragen of een functie beschikbaar is. Dit voorkomt runtime-fouten op machines met oudere Edge-versies.
Design-time-veiligheid
Alle configureerbare instellingen worden beschikbaar gemaakt als TPersistent-subobjecten. Je kunt het component veilig tijdens design-time in de Object Inspector configureren zonder COM-initialisatie te triggeren. Instellingen worden gebufferd en automatisch toegepast wanneer de WebView2-omgeving tijdens runtime wordt aangemaakt.
Vereisten
Om TsgcWebView2 in je applicatie te gebruiken, heb je nodig:
- Microsoft Edge WebView2 Runtime. Inbegrepen bij Windows 10 (versie 1803+) en Windows 11. Voor oudere Windows-versies of beheerde deployments download je de Evergreen Bootstrapper of de Fixed Version-runtime bij Microsoft.
- WebView2Loader.dll. Wordt meegeleverd met het component. Plaats deze naast je applicatie-executable. Deze kleine DLL handelt de runtime-detectie en het laden af.
- Alleen Windows. WebView2 is een Windows-technologie. Het component richt zich op VCL-applicaties op Windows 7 en later (Windows 10/11 aanbevolen voor volledige functie-ondersteuning).
Let op. Je kunt controleren of de WebView2-runtime is geïnstalleerd voordat je het component aanmaakt. Als deze niet aanwezig is, kun je de gebruiker doorverwijzen om hem te installeren of terugvallen op een alternatieve browser-control.
Conclusie
TsgcWebView2 is de meest complete WebView2-wrapper die beschikbaar is voor Delphi. Hij is een strikte superset van TEdgeBrowser en voegt twaalf functies toe die de ingebouwde component van Embarcadero niet biedt — cookiebeheer, download-events, profielbeheer, audiodetectie, favicon-toegang, certificaatafhandeling, basisauthenticatie, statusbalktekst, virtual host-mapping, shared buffer, volledige controle over het contextmenu en graceful degradation.
Hij ondersteunt het breedste scala aan Delphi-versies van alle WebView2-wrappers, van Delphi 7 tot en met Delphi 13. Of je nu een legacy-applicatie op een oudere compiler onderhoudt of een nieuw project op de nieuwste Delphi bouwt, dezelfde component en dezelfde API werken overal.
De API is ontworpen om gemakkelijk te leren — plaats de component op een form, roep Navigate aan en handel events af — en is toch krachtig genoeg voor geavanceerde scenario's via directe COM-toegang en per-functie-versiecontrole. Voor Delphi-ontwikkelaars die een moderne ingebedde browser nodig hebben, is TsgcWebView2 de natuurlijke keuze.