Microsoft Edge WebView2 per Delphi

· Componentei

TsgcWebView2 è un nuovo componente visuale Delphi che incapsula Microsoft Edge WebView2, dandoti un motore browser moderno basato su Chromium all'interno di qualsiasi applicazione VCL. Trascinalo su una form, imposta un URL e hai un browser embedded completo — con gestione cookie, controllo dei download, integrazione JavaScript, supporto alla stampa e altro.

A differenza del TEdgeBrowser integrato fornito con le recenti versioni di Delphi, TsgcWebView2 supporta ogni versione di Delphi da Delphi 7 a Delphi 13 — il supporto di versioni più ampio di qualsiasi wrapper WebView2 disponibile. Fa parte della libreria sgcWebSockets di eSeGeCe.

Questo articolo copre il suo set di funzionalità, mostra esempi pratici di codice, lo confronta direttamente con TEdgeBrowser e spiega la sua architettura interna.

Panoramica delle funzionalità

TsgcWebView2 espone un'ampia superficie dell'SDK WebView2 tramite eventi e metodi Delphi puliti. Ecco i dodici principali gruppi di capability:

Navigation
Navigate, GoBack, GoForward, Reload, Stop. Supporta la navigazione POST con header personalizzati e body delle richieste. 		JavaScript Execution
Esegui JavaScript in modo asincrono o sincrono. Registra init script che vengono eseguiti automaticamente a ogni caricamento di pagina. 		Gestione cookie
Ottieni, aggiungi, aggiorna ed elimina cookie a livello programmatico. Accesso completo agli attributi dei cookie inclusi dominio, percorso e scadenza.
Download Control
Eventi per avvio, avanzamento e completamento del download. Reindirizza i download verso percorsi personalizzati o annullali del tutto. 		Profile Management
Supporto multi-profilo per sessioni di navigazione isolate. Cancella i dati di navigazione (cache, cookie, cronologia) per profilo. 		Supporto stampa
Stampa la pagina corrente in PDF o mostra la finestra di dialogo di stampa del sistema. Controlla dimensione del foglio, orientamento e margini.
Controllo audio / mute
Rileva quando il documento sta riproducendo audio. Cambia lo stato di mute a livello programmatico senza influenzare il volume di sistema. 		Certificate Handling
Rispondi alle richieste di certificato client e agli errori di certificato del server tramite eventi dedicati. 		Menu contestuale
Intercetta e personalizza completamente il menu contestuale del tasto destro. Aggiungi, rimuovi o sostituisci le voci di menu con le tue azioni.
Accesso favicon
Recupera l'URI della favicon della pagina corrente. Reagisci alle modifiche della favicon tramite un evento dedicato. 		Mapping virtual host
Mappa hostname personalizzati a cartelle locali. Servi file HTML/CSS/JS locali come se provenissero da un vero web server. 		Cattura screenshot
Salva il contenuto visibile della pagina come immagine PNG o JPEG. Utile per anteprime, report o test automatizzati.

Per iniziare

Il modo piu' semplice per usare TsgcWebView2 e' trascinarlo su una form VCL e chiamare Navigate. Il componente gestisce automaticamente la creazione dell'ambiente WebView2, l'inizializzazione del controller e il binding della view.

// 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'evento OnNavigationCompleted si attiva al termine del caricamento della pagina, riportando se la navigazione ha avuto successo e l'eventuale codice di errore. E' il punto naturale per aggiornare la UI — titolo della finestra, barra di stato, stato dei pulsanti indietro/avanti — in base alla pagina caricata.

Nota. Il componente crea l'ambiente WebView2 in modo lazy al primo utilizzo. Se hai bisogno di configurare le opzioni dell'ambiente (cartella del browser, lingua, switch da riga di comando), impostale tramite la proprieta' EnvironmentOptions prima di chiamare Navigate.

Il sotto-oggetto CookieManager espone l'intera API dei cookie WebView2. Puoi elencare i cookie per l'URL corrente, aggiungerli o aggiornarli con attributi specifici, ed eliminare i singoli cookie o cancellarli tutti in un'unica operazione.

// 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', '/');

Quando chiami GetCookies, i risultati arrivano in modo asincrono nell'evento OnCookiesReceived. Ogni cookie include nome, valore, dominio, percorso, scadenza, flag secure e flag HTTP-only. E' una delle funzionalita' che TEdgeBrowser non espone affatto.

Suggerimento. Usa AddOrUpdateCookie per iniettare token di autenticazione prima di navigare a una pagina protetta. In questo modo eviti la necessita' di un flusso form di login negli scenari con browser embedded.

Integrazione JavaScript

TsgcWebView2 offre tre approcci all'esecuzione di JavaScript, ciascuno adatto a uno scenario diverso:

Esecuzione asincrona

Chiama ExecuteScript e gestisci il risultato nell'evento OnScriptExecuted. E' l'approccio standard, non bloccante.

// 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;

Esecuzione sincrona

Quando ti serve il risultato immediatamente usa ExecuteScriptSync. Blocca il thread chiamante fino al completamento dello script e restituisce direttamente il risultato.

var
  vTitle: string;
begin
  vTitle := sgcWebView2.ExecuteScriptSync('document.title');
  Caption := vTitle;
end;

Init script

Gli init script si registrano una volta sola e vengono eseguiti automaticamente a ogni caricamento di pagina. Vengono eseguiti prima di qualsiasi JavaScript della pagina, e quindi sono ideali per iniettare configurazioni globali o polyfill.

// Runs on every page load, before any page scripts
sgcWebView2.AddInitScript('window.appVersion = "1.0";');

Gestione dei download

I download sono gestiti tramite un modello a eventi. Quando un download inizia, l'evento OnDownloadStarting ti permette di reindirizzare il file verso un percorso personalizzato, annullarlo o lasciarlo proseguire con i default. Un evento separato OnDownloadCompleted si attiva al termine del download.

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;

Nota. Il parametro aState in OnDownloadCompleted indica se il download ha avuto successo, e' stato annullato o ha incontrato un errore. Verifica questo valore prima di elaborare il file scaricato.

POST navigation e header personalizzati

La navigazione standard carica un URL con una richiesta GET. Per il test di API, l'invio di form o qualsiasi scenario che richieda un diverso metodo HTTP, NavigateWithPostData ti permette di specificare metodo, body e header in un'unica chiamata.

// 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'
);

Il parametro headers accetta una stringa delimitata da CRLF, seguendo lo stesso formato degli header HTTP. E' utile per iniettare token di autorizzazione, content type o header personalizzati attesi dal tuo server.

Confronto con TEdgeBrowser

Delphi include TEdgeBrowser a partire da Delphi 10.4 Sydney (disponibile tramite GetIt per XE7+). Fornisce un wrapper WebView2 di base, ma lascia molte funzionalita' dell'SDK non esposte. La tabella seguente mostra esattamente in cosa TsgcWebView2 va oltre.

Funzionalità TEdgeBrowser TsgcWebView2
Supporto versioni Delphi Solo XE7+ Da D7 a D13
Gestione cookie ✗ ✓ API completa
Eventi di avanzamento download ✗ ✓ Avvio / Avanzamento / Completamento
Profilo / Pulisci dati di navigazione ✗ ✓
Controllo audio / mute ✗ ✓
Accesso favicon ✗ ✓
Eventi sui certificati ✗ ✓
Eventi basic auth ✗ ✓
Testo barra di stato ✗ ✓
Mapping virtual host ✗ ✓
Shared buffer ✗ ✓
ExecuteScript sincrono ✓ ✓
Cattura screenshot ✓ ✓
Init script ✓ ✓
Navigazione POST ✓ ✓
Supporto stampa ✓ ✓
Impostazioni a design-time Solleva eccezione se WebView non creato ✓ Proprieta' TPersistent sicure
Menu contestuale Merge PopupMenu Controllo eventi completo
Degradazione graduale ✗ ✓ Controlli di versione per funzionalita'
Accesso COM grezzo ✓ ✓

TsgcWebView2 copre tutto cio' che offre TEdgeBrowser e aggiunge dodici funzionalita' in piu' — gestione cookie, eventi di download, controllo del profilo, audio/mute, accesso alla favicon, gestione dei certificati, eventi di basic auth, testo della barra di stato, mapping virtual host, shared buffer, controllo completo del menu contestuale e degradazione graduale. Inoltre supporta versioni di Delphi fino a Delphi 7 incluso, mentre TEdgeBrowser richiede come minimo XE7.

Importante. TEdgeBrowser memorizza le sue impostazioni direttamente sulle interfacce COM. Se imposti una proprieta' a design time prima che l'ambiente WebView2 venga creato, viene sollevata una access violation. TsgcWebView2 evita del tutto questo problema usando sotto-oggetti TPersistent che bufferizzano le impostazioni e le applicano quando l'ambiente e' pronto.

Funzionalità avanzate

Stampa in PDF

Genera un PDF della pagina corrente con un'unica chiamata di metodo. Il file di output viene creato in modo asincrono e puoi controllare dimensione del foglio, margini e orientamento tramite parametri.

sgcWebView2.PrintToPdf('C:\output\page.pdf');

Cattura screenshot

Cattura l'area visibile della pagina come immagine PNG o JPEG. Il secondo parametro specifica il formato dell'immagine: 0 per PNG, 1 per JPEG.

sgcWebView2.CapturePreviewToFile('C:\screenshots\page.png', 0); // 0 = PNG

Mapping virtual host

Mappa un hostname personalizzato a una cartella locale in modo che il tuo browser embedded possa caricare file locali usando URL HTTPS standard. Questo evita problemi di CORS e fa comportare il contenuto locale come quello remoto.

// Serve local files via https://app.local/
sgcWebView2.SetVirtualHostNameToFolderMapping(
  'app.local', 'C:\MyApp\WebContent', 1);
sgcWebView2.Navigate('https://app.local/index.html');

Suggerimento. Virtual host mapping is particularly useful for single-page applicazioni. Bundle your HTML, CSS, and JavaScript with your Delphi application, then load it through a mapped hostname to get full access to web APIs that require a secure origin.

Controllo audio e mute

Rileva quando il documento caricato sta riproducendo audio e cambia lo stato di mute senza influenzare il volume di sistema. E' utile per applicazioni che incorporano contenuti media-heavy.

sgcWebView2.IsMuted := True;
if sgcWebView2.IsDocumentPlayingAudio then
  ShowMessage('Audio is playing');

Architettura e design

TsgcWebView2 e' costruito su un'architettura pulita a tre layer che separa le responsabilita' mantenendo semplice l'API esposta agli sviluppatori:

Per gli utenti avanzati che hanno bisogno di accedere a funzionalita' dell'SDK non ancora wrappate dal componente, le interfacce COM grezze sono accessibili tramite le proprieta' WebView, Controller ed Environment. Puoi chiamare qualsiasi metodo COM direttamente godendo comunque della gestione del ciclo di vita offerta dal componente.

Degradazione graduale

Non tutte le funzionalita' WebView2 sono disponibili in ogni versione del runtime Edge. TsgcWebView2 verifica la versione del runtime installata all'avvio ed espone un metodo Supports() per consentirti di interrogare la disponibilita' di una funzionalita' prima di chiamarla. Cosi' eviti errori di runtime su macchine con versioni Edge piu' vecchie.

Sicurezza a design-time

Tutte le impostazioni configurabili sono esposte come sotto-oggetti TPersistent. Puoi configurare in sicurezza il componente a design time nell'Object Inspector senza innescare l'inizializzazione COM. Le impostazioni vengono bufferizzate e applicate automaticamente quando l'ambiente WebView2 viene creato a runtime.

Requisiti

Per usare TsgcWebView2 nella tua applicazione hai bisogno di:

Nota. Puoi verificare se il runtime WebView2 e' installato prima di creare il componente. Se non e' presente, puoi indirizzare l'utente a installarlo o ripiegare su un controllo browser alternativo.

Conclusione

TsgcWebView2 e' il wrapper WebView2 piu' completo disponibile per Delphi. E' un superset stretto di TEdgeBrowser, aggiungendo dodici funzionalita' che il componente integrato di Embarcadero non espone — gestione cookie, eventi di download, controllo del profilo, rilevamento audio, accesso favicon, gestione dei certificati, basic authentication, testo della barra di stato, mapping virtual host, shared buffer, controllo completo del menu contestuale e degradazione graduale.

Supporta la gamma piu' ampia di versioni di Delphi di qualsiasi wrapper WebView2, da Delphi 7 fino a Delphi 13. Sia che tu stia mantenendo un'applicazione legacy su un compilatore piu' vecchio sia che tu stia costruendo un nuovo progetto sull'ultima versione di Delphi, lo stesso componente e la stessa API funzionano ovunque.

L'API e' progettata per essere facile da imparare — trascina il componente su una form, chiama Navigate e gestisci gli eventi — pur restando potente per scenari avanzati grazie all'accesso COM grezzo e ai controlli di versione per funzionalita'. Per gli sviluppatori Delphi che hanno bisogno di un browser embedded moderno, TsgcWebView2 e' la scelta naturale.