Microsoft Edge WebView2 en Delphi

· Componentes

TsgcWebView2 es un nuevo componente visual de Delphi que envuelve Microsoft Edge WebView2, dándote un motor de navegador moderno basado en Chromium dentro de cualquier aplicación VCL. Añádelo a un formulario, establece una URL y tendrás un navegador embebido completo — con gestión de cookies, control de descargas, integración con JavaScript, soporte de impresión y más.

A diferencia del TEdgeBrowser incorporado que viene con las versiones recientes de Delphi, TsgcWebView2 admite todas las versiones de Delphi desde Delphi 7 hasta Delphi 13 — el soporte de versiones más amplio de cualquier wrapper de WebView2 disponible. Forma parte de la biblioteca sgcWebSockets de eSeGeCe.

Este artículo cubre su conjunto de características, muestra ejemplos prácticos de código, lo compara cara a cara con TEdgeBrowser y explica su arquitectura interna.

Resumen de características

TsgcWebView2 expone una amplia superficie del WebView2 SDK mediante eventos y métodos Delphi limpios. Estos son los doce grupos principales de capacidades:

Navegación
Navigate, GoBack, GoForward, Reload, Stop. Admite navegación POST con cabeceras personalizadas y cuerpos de petición. 		Ejecución de JavaScript
Ejecuta JavaScript de forma asíncrona o síncrona. Registra init scripts que se ejecutan automáticamente en cada carga de página. 		Gestión de cookies
Obtén, añade, actualiza y elimina cookies por código. Acceso completo a los atributos de cookie incluyendo dominio, ruta y caducidad.
Control de descargas
Eventos para inicio, progreso y finalización de descargas. Redirige descargas a rutas personalizadas o cancélalas por completo. 		Gestión de perfiles
Soporte multi-perfil para sesiones de navegación aisladas. Borra los datos de navegación (caché, cookies, historial) por perfil. 		Soporte de impresión
Imprime la página actual a PDF o muestra el diálogo de impresión del sistema. Controla tamaño, orientación y márgenes del papel.
Control de audio / silencio
Detecta cuándo el documento reproduce audio. Activa o desactiva el silencio por código sin afectar al volumen del sistema. 		Gestión de certificados
Responde a peticiones de certificado de cliente y errores de certificado de servidor mediante eventos dedicados. 		Menú contextual
Intercepta y personaliza por completo el menú contextual del clic derecho. Añade, elimina o sustituye elementos del menú con tus propias acciones.
Acceso al favicon
Recupera el URI del favicon de la página actual. Reacciona a cambios de favicon mediante un evento dedicado. 		Mapeo de hosts virtuales
Asocia hostnames personalizados a carpetas locales. Sirve archivos HTML/CSS/JS locales como si vinieran de un servidor web real. 		Captura de pantalla
Guarda el contenido visible de la página como imagen PNG o JPEG. Útil para miniaturas, informes o pruebas automatizadas.

Primeros pasos

La forma más sencilla de usar TsgcWebView2 es añadirlo a un formulario VCL y llamar a Navigate. El componente gestiona automáticamente la creación del entorno WebView2, la inicialización del controlador y el binding de la vista.

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

El evento OnNavigationCompleted se dispara cuando la página termina de cargarse, indicando si la navegación tuvo éxito y el código de estado de error correspondiente. Es el lugar natural para actualizar tu interfaz — el título de la ventana, la barra de estado, el estado de los botones atrás/adelante — en función de la página cargada.

Nota. El componente crea el entorno WebView2 de forma perezosa en el primer uso. Si necesitas configurar opciones de entorno (carpeta del navegador, idioma, flags de línea de comandos), establécelas mediante la propiedad EnvironmentOptions antes de llamar a Navigate.

Gestión de cookies

El sub-objeto CookieManager expone toda la API de cookies de WebView2. Puedes listar las cookies de la URL actual, añadir o actualizar cookies con atributos concretos, y eliminar cookies individuales o borrarlas todas de una vez.

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

Cuando llamas a GetCookies, los resultados llegan de forma asíncrona en el evento OnCookiesReceived. Cada cookie incluye su nombre, valor, dominio, ruta, fecha de caducidad, flag secure y flag HTTP-only. Esta es una de las características que TEdgeBrowser no expone en absoluto.

Consejo. Utiliza AddOrUpdateCookie para inyectar tokens de autenticación antes de navegar a una página protegida. Así evitas tener que pasar por un formulario de login en escenarios de navegador embebido.

Integración con JavaScript

TsgcWebView2 ofrece tres enfoques para ejecutar JavaScript, cada uno pensado para un caso de uso distinto:

Ejecución asíncrona

Llama a ExecuteScript y gestiona el resultado en el evento OnScriptExecuted. Este es el enfoque estándar, no bloqueante.

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

Ejecución síncrona

Cuando necesitas el resultado inmediatamente, utiliza ExecuteScriptSync. Bloquea el hilo llamante hasta que el script termina y devuelve el resultado directamente.

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

Init Scripts

Los init scripts se registran una vez y se ejecutan automáticamente en cada carga de página. Se ejecutan antes que cualquier JavaScript de la página, lo que los hace ideales para inyectar configuración global o polyfills.

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

Gestión de descargas

Las descargas se gestionan mediante un modelo basado en eventos. Cuando empieza una descarga, el evento OnDownloadStarting te permite redirigir el archivo a una ruta personalizada, cancelarla o dejar que continúe con los valores por defecto. Un evento independiente OnDownloadCompleted se dispara cuando la descarga finaliza.

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. El parámetro aState en OnDownloadCompleted indica si la descarga tuvo éxito, fue cancelada o se produjo un error. Comprueba este valor antes de procesar el archivo descargado.

Navegación POST y cabeceras personalizadas

La navegación estándar carga una URL con una petición GET. Para probar APIs, enviar formularios o cualquier escenario que requiera otro método HTTP, NavigateWithPostData te permite especificar el método, el cuerpo y las cabeceras en una sola llamada.

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

El parámetro de cabeceras admite una cadena delimitada por CRLF, siguiendo el mismo formato que usan las cabeceras HTTP. Es útil para inyectar tokens de autorización, tipos de contenido o cabeceras personalizadas que tu servidor espera.

Comparación con TEdgeBrowser

Delphi incluye TEdgeBrowser a partir de Delphi 10.4 Sydney (disponible vía GetIt desde XE7+). Proporciona un wrapper básico de WebView2, pero deja muchas características del SDK sin exponer. La siguiente tabla muestra exactamente en qué va más allá TsgcWebView2.

Característica TEdgeBrowser TsgcWebView2
Versiones de Delphi compatibles Solo XE7+ De D7 a D13
Gestión de cookies ✗ ✓ API completa
Eventos de progreso de descarga ✗ ✓ Inicio / Progreso / Finalización
Perfil / borrado de datos de navegación ✗ ✓
Control de audio / silencio ✗ ✓
Acceso al favicon ✗ ✓
Eventos de certificado ✗ ✓
Eventos de Basic Auth ✗ ✓
Texto de la barra de estado ✗ ✓
Mapeo de hosts virtuales ✗ ✓
Shared Buffer ✗ ✓
ExecuteScript síncrono ✓ ✓
Captura de pantalla ✓ ✓
Init Script ✓ ✓
Navegación POST ✓ ✓
Soporte de impresión ✓ ✓
Propiedades de diseño Lanza excepción si el WebView no está creado ✓ Propiedades TPersistent seguras
Menú contextual Merge de PopupMenu Control total por eventos
Degradación elegante ✗ ✓ Comprobaciones de versión por característica
Acceso COM directo ✓ ✓

TsgcWebView2 cubre todo lo que ofrece TEdgeBrowser y añade doce características adicionales — gestión de cookies, eventos de descarga, control de perfiles, audio/silencio, acceso al favicon, gestión de certificados, eventos de Basic Auth, texto de la barra de estado, mapeo de hosts virtuales, shared buffer, control total del menú contextual y degradación elegante. Además, admite versiones de Delphi desde Delphi 7, mientras que TEdgeBrowser requiere XE7 como mínimo.

Importante. TEdgeBrowser guarda sus ajustes directamente en las interfaces COM. Si configuras una propiedad en tiempo de diseño antes de que se cree el entorno WebView2, lanza una access violation. TsgcWebView2 lo evita por completo utilizando sub-objetos TPersistent que almacenan los ajustes y los aplican cuando el entorno está listo.

Características avanzadas

Impresión a PDF

Genera un PDF de la página actual con una sola llamada al método. El archivo de salida se crea de forma asíncrona y puedes controlar el tamaño del papel, los márgenes y la orientación mediante parámetros.

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

Captura de pantalla

Captura el área visible de la página como una imagen PNG o JPEG. El segundo parámetro especifica el formato de imagen: 0 para PNG, 1 para JPEG.

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

Mapeo de hosts virtuales

Asocia un hostname personalizado a una carpeta local para que tu navegador embebido pueda cargar archivos locales mediante URLs HTTPS estándar. Evitas problemas de CORS y haces que el contenido local se comporte exactamente como contenido remoto.

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

Consejo. El mapeo de hosts virtuales es especialmente útil para aplicaciones single-page. Empaqueta tu HTML, CSS y JavaScript junto con tu aplicación Delphi y cárgalo a través de un hostname mapeado para tener acceso completo a las web APIs que requieren un origen seguro.

Control de audio y silencio

Detecta cuándo el documento cargado está reproduciendo audio y silencia sin afectar al volumen del sistema. Es útil para aplicaciones que embeben contenido con mucho contenido multimedia.

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

Arquitectura y diseño

TsgcWebView2 se construye sobre una arquitectura limpia en tres capas que separa responsabilidades manteniendo simple la API que ve el desarrollador:

Para usuarios avanzados que necesiten acceso a características del SDK aún no envueltas por el componente, las interfaces COM directas están disponibles a través de las propiedades WebView, Controller y Environment. Puedes invocar cualquier método COM directamente sin perder la gestión del ciclo de vida del componente.

Degradación elegante

No todas las características de WebView2 están disponibles en todas las versiones del runtime de Edge. TsgcWebView2 comprueba la versión del runtime instalada al arrancar y expone un método Supports() para que puedas consultar la disponibilidad de una característica antes de invocarla. Esto evita errores en tiempo de ejecución en máquinas con versiones antiguas de Edge.

Seguridad en tiempo de diseño

Todos los ajustes configurables se exponen como sub-objetos TPersistent. Puedes configurar el componente con seguridad en tiempo de diseño desde el Object Inspector sin disparar la inicialización de COM. Los ajustes se almacenan y se aplican automáticamente cuando se crea el entorno WebView2 en tiempo de ejecución.

Requisitos

Para utilizar TsgcWebView2 en tu aplicación necesitas:

Nota. Puedes comprobar si el runtime de WebView2 está instalado antes de crear el componente. Si no lo está, puedes indicar al usuario que lo instale o recurrir a un control de navegador alternativo.

Conclusión

TsgcWebView2 es el wrapper de WebView2 más completo disponible para Delphi. Es un superconjunto estricto de TEdgeBrowser, añadiendo doce características que el componente integrado de Embarcadero no expone — gestión de cookies, eventos de descarga, control de perfiles, detección de audio, acceso al favicon, gestión de certificados, autenticación básica, texto de la barra de estado, mapeo de hosts virtuales, shared buffer, control total del menú contextual y degradación elegante.

Admite el rango más amplio de versiones de Delphi de cualquier wrapper de WebView2, desde Delphi 7 hasta Delphi 13. Tanto si mantienes una aplicación heredada en un compilador antiguo como si construyes un nuevo proyecto en el último Delphi, el mismo componente y la misma API funcionan en cualquier sitio.

La API está pensada para ser fácil de aprender — suelta el componente en un formulario, llama a Navigate y gestiona los eventos — pero a la vez es lo suficientemente potente para escenarios avanzados gracias al acceso COM directo y a la comprobación de versiones por característica. Para los desarrolladores Delphi que necesitan un navegador embebido moderno, TsgcWebView2 es la elección natural.