TsgcWebView2 é um novo componente visual Delphi que encapsula o Microsoft Edge WebView2, trazendo um moderno motor de navegador baseado em Chromium para qualquer aplicação VCL. Solte-o em um formulário, defina uma URL e você terá um navegador embutido completo — com gerenciamento de cookies, controle de downloads, integração JavaScript, suporte a impressão e muito mais.
Diferente do TEdgeBrowser integrado que acompanha as versões recentes do Delphi, o TsgcWebView2 suporta todas as versões do Delphi 7 ao Delphi 13 — o suporte de versões mais amplo de qualquer wrapper WebView2 disponível. Ele faz parte da biblioteca sgcWebSockets da eSeGeCe.
Este artigo aborda seus recursos, mostra exemplos práticos de código, compara-o diretamente com o TEdgeBrowser e explica sua arquitetura interna.
Visão Geral dos Recursos
TsgcWebView2 expõe uma ampla superfície do SDK WebView2 por meio de eventos e métodos Delphi limpos. Aqui estão os doze grupos principais de capacidades:
|
Navegação Navigate, GoBack, GoForward, Reload, Stop. Suporta navegação POST com cabeçalhos personalizados e corpos de requisição. |
Execução de JavaScript Execute JavaScript de forma assíncrona ou síncrona. Registre scripts de inicialização que são executados automaticamente a cada carregamento de página. |
Gerenciamento de Cookies Obtenha, adicione, atualize e exclua cookies programaticamente. Acesso completo aos atributos de cookies, incluindo domínio, caminho e expiração. |
|
Controle de Downloads Eventos para início, progresso e conclusão de downloads. Redirecione downloads para caminhos personalizados ou cancele-os completamente. |
Gerenciamento de Perfis Suporte a múltiplos perfis para sessões de navegação isoladas. Limpe dados de navegação (cache, cookies, histórico) por perfil. |
Suporte a Impressão Imprima a página atual em PDF ou exiba o diálogo de impressão do sistema. Controle tamanho do papel, orientação e margens. |
|
Controle de Áudio/Mudo Detecte quando o documento está reproduzindo áudio. Alterne o estado mudo programaticamente sem afetar o volume do sistema. |
Tratamento de Certificados Responda a solicitações de certificado do cliente e erros de certificado do servidor por meio de eventos dedicados. |
Menu de Contexto Intercepte e personalize completamente o menu de contexto do clique direito. Adicione, remova ou substitua itens de menu com suas próprias ações. |
|
Acesso ao Favicon Recupere a URI do favicon da página atual. Reaja a alterações de favicon por meio de um evento dedicado. |
Mapeamento de Host Virtual Mapeie nomes de host personalizados para pastas locais. Sirva arquivos HTML/CSS/JS locais como se viessem de um servidor web real. |
Captura de Tela Salve o conteúdo visível da página como imagem PNG ou JPEG. Útil para miniaturas, relatórios ou testes automatizados. |
Primeiros Passos
A maneira mais simples de usar o TsgcWebView2 é soltá-lo em um formulário VCL e chamar Navigate. O componente cuida automaticamente da criação do ambiente WebView2, inicialização do controlador e vinculação da visualização.
// 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;O evento OnNavigationCompleted é disparado após o carregamento da página, informando se a navegação foi bem-sucedida e qualquer código de status de erro. Este é o lugar natural para atualizar sua interface — título da janela, barra de status, estado dos botões de voltar/avançar — com base na página carregada.
Nota. O componente cria o ambiente WebView2 de forma lazy na primeira utilização. Se você precisar configurar opções de ambiente (pasta do navegador, idioma, switches de linha de comando), defina-as por meio da propriedade EnvironmentOptions antes de chamar Navigate.
Gerenciamento de Cookies
O sub-objeto CookieManager expõe a API completa de cookies do WebView2. Você pode listar cookies para a URL atual, adicionar ou atualizar cookies com atributos específicos e excluir cookies individuais ou limpar todos de uma 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', '/');Quando você chama GetCookies, os resultados chegam de forma assíncrona no evento OnCookiesReceived. Cada cookie inclui nome, valor, domínio, caminho, expiração, flag de segurança e flag HTTP-only. Este é um dos recursos que o TEdgeBrowser não expõe.
Dica. Use AddOrUpdateCookie para injetar tokens de autenticação antes de navegar para uma página protegida. Isso evita a necessidade de um fluxo de formulário de login em cenários de navegador embutido.
Integração com JavaScript
TsgcWebView2 oferece três abordagens para execução de JavaScript, cada uma adequada a um caso de uso diferente:
Execução Assíncrona
Chame ExecuteScript e trate o resultado no evento OnScriptExecuted. Esta é a abordagem padrão, não 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;Execução Síncrona
Quando você precisa do resultado imediatamente, use ExecuteScriptSync. Isso bloqueia a thread chamante até que o script seja concluído e retorna o resultado diretamente.
var
vTitle: string;
begin
vTitle := sgcWebView2.ExecuteScriptSync('document.title');
Caption := vTitle;
end;Scripts de Inicialização
Os scripts de inicialização são registrados uma vez e executados automaticamente a cada carregamento de página. Eles rodam antes de qualquer JavaScript da página, sendo ideais para injetar configurações globais ou polyfills.
// Runs on every page load, before any page scripts
sgcWebView2.AddInitScript('window.appVersion = "1.0";');Gerenciamento de Downloads
Os downloads são tratados por meio de um modelo orientado a eventos. Quando um download começa, o evento OnDownloadStarting permite redirecionar o arquivo para um caminho personalizado, cancelá-lo ou deixá-lo prosseguir com os padrões. Um evento separado OnDownloadCompleted é disparado quando o download termina.
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. O parâmetro aState em OnDownloadCompleted indica se o download foi bem-sucedido, cancelado ou se ocorreu um erro. Verifique este valor antes de processar o arquivo baixado.
Navegação POST e Cabeçalhos Personalizados
A navegação padrão carrega uma URL com uma requisição GET. Para testes de API, envio de formulários ou qualquer cenário que exija um método HTTP diferente, o NavigateWithPostData permite especificar o método, o corpo e os cabeçalhos em uma única chamada.
// 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'
);O parâmetro de cabeçalhos aceita uma string delimitada por CRLF, seguindo o mesmo formato usado pelos cabeçalhos HTTP. Isso é útil para injetar tokens de autorização, tipos de conteúdo ou cabeçalhos personalizados que seu servidor espera.
Comparação com TEdgeBrowser
O Delphi inclui o TEdgeBrowser a partir do Delphi 10.4 Sydney (disponível via GetIt para XE7+). Ele oferece um wrapper básico do WebView2, mas deixa muitos recursos do SDK sem exposição. A tabela a seguir mostra exatamente onde o TsgcWebView2 vai além.
| Recurso | TEdgeBrowser | TsgcWebView2 |
|---|---|---|
| Suporte a versões do Delphi | Somente XE7+ | D7 ao D13 |
| Gerenciamento de Cookies | ✗ | ✓ API completa |
| Eventos de Progresso de Download | ✗ | ✓ Início / Progresso / Conclusão |
| Perfis / Limpar Dados de Navegação | ✗ | ✓ |
| Controle de Áudio/Mudo | ✗ | ✓ |
| Acesso ao Favicon | ✗ | ✓ |
| Eventos de Certificado | ✗ | ✓ |
| Eventos de Autenticação Básica | ✗ | ✓ |
| Texto da Barra de Status | ✗ | ✓ |
| Mapeamento de Host Virtual | ✗ | ✓ |
| Buffer Compartilhado | ✗ | ✓ |
| ExecuteScript Síncrono | ✓ | ✓ |
| Captura de Tela | ✓ | ✓ |
| Script de Inicialização | ✓ | ✓ |
| Navegação POST | ✓ | ✓ |
| Suporte a Impressão | ✓ | ✓ |
| Configurações em Tempo de Design | Gera exceção se o WebView não foi criado | ✓ Propriedades TPersistent seguras |
| Menu de Contexto | Mesclagem de PopupMenu | Controle total por eventos |
| Degradação Elegante | ✗ | ✓ Verificações de versão por recurso |
| Acesso COM Bruto | ✓ | ✓ |
TsgcWebView2 cobre tudo que o TEdgeBrowser oferece e adiciona doze recursos a mais — gerenciamento de cookies, eventos de download, controle de perfis, áudio/mudo, acesso ao favicon, tratamento de certificados, eventos de autenticação básica, texto da barra de status, mapeamento de host virtual, buffer compartilhado, controle total do menu de contexto e degradação elegante. Ele também suporta versões do Delphi desde o Delphi 7, enquanto o TEdgeBrowser requer no mínimo o XE7.
Importante. O TEdgeBrowser armazena suas configurações diretamente nas interfaces COM. Se você definir uma propriedade em tempo de design antes que o ambiente WebView2 seja criado, ele gera uma violação de acesso. O TsgcWebView2 evita isso completamente usando sub-objetos TPersistent que armazenam as configurações e as aplicam quando o ambiente estiver pronto.
Recursos Avançados
Imprimir para PDF
Gere um PDF da página atual com uma única chamada de método. O arquivo de saída é criado de forma assíncrona e você pode controlar o tamanho do papel, margens e orientação por meio de parâmetros.
sgcWebView2.PrintToPdf('C:\output\page.pdf');Captura de Tela
Capture a área visível da página como imagem PNG ou JPEG. O segundo parâmetro especifica o formato da imagem: 0 para PNG, 1 para JPEG.
sgcWebView2.CapturePreviewToFile('C:\screenshots\page.png', 0); // 0 = PNGMapeamento de Host Virtual
Mapeie um nome de host personalizado para uma pasta local, de modo que seu navegador embutido possa carregar arquivos locais usando URLs HTTPS padrão. Isso evita problemas de CORS e faz com que o conteúdo local se comporte exatamente como conteúdo remoto.
// Serve local files via https://app.local/
sgcWebView2.SetVirtualHostNameToFolderMapping(
'app.local', 'C:\MyApp\WebContent', 1);
sgcWebView2.Navigate('https://app.local/index.html');Dica. O mapeamento de host virtual é especialmente útil para aplicações de página única (SPA). Agrupe seu HTML, CSS e JavaScript com sua aplicação Delphi, depois carregue-os por um nome de host mapeado para ter acesso completo às APIs web que requerem uma origem segura.
Controle de Áudio e Mudo
Detecte quando o documento carregado está reproduzindo áudio e alterne o mudo sem afetar o volume do sistema. Isso é útil para aplicações que incorporam conteúdo com muito áudio/vídeo.
sgcWebView2.IsMuted := True;
if sgcWebView2.IsDocumentPlayingAudio then
ShowMessage('Audio is playing');Arquitetura e Design
TsgcWebView2 é construído sobre uma arquitetura limpa de três camadas que separa responsabilidades enquanto mantém a API voltada ao desenvolvedor simples:
- Camada de API (Interfaces COM). Traduções diretas das interfaces COM do Microsoft WebView2 para Delphi. Esses são os blocos de construção brutos — de baixo nível, específicos de versão e não destinados ao uso direto no código da aplicação.
- Camada de Classes (Wrappers). Classes wrapper nativas do Delphi que gerenciam os tempos de vida dos objetos COM, tratam o roteamento de callbacks e fornecem uma API orientada a objetos limpa. Esta camada protege você do trabalho de plomagem COM.
- Camada de Componente (Visual). O próprio componente
TsgcWebView2— um descendente de TWinControl que você solta em um formulário. Ele publica propriedades, eventos e métodos que mapeiam para a camada de classes abaixo.
Para usuários avançados que precisam de acesso a recursos do SDK ainda não encapsulados pelo componente, as interfaces COM brutas estão disponíveis pelas propriedades WebView, Controller e Environment. Você pode chamar qualquer método COM diretamente enquanto ainda se beneficia do gerenciamento de ciclo de vida do componente.
Degradação Elegante
Nem todos os recursos do WebView2 estão disponíveis em todas as versões do runtime Edge. O TsgcWebView2 verifica a versão do runtime instalado na inicialização e expõe um método Supports() para que você possa consultar a disponibilidade de um recurso antes de chamá-lo. Isso evita erros em máquinas com versões mais antigas do Edge.
Segurança em Tempo de Design
Todas as configurações são expostas como sub-objetos TPersistent. Você pode configurar o componente com segurança em tempo de design no Object Inspector sem acionar a inicialização COM. As configurações são armazenadas em buffer e aplicadas automaticamente quando o ambiente WebView2 é criado em tempo de execução.
Requisitos
Para usar o TsgcWebView2 em sua aplicação, você precisa:
- Microsoft Edge WebView2 Runtime. Incluído com o Windows 10 (versão 1803+) e o Windows 11. Para versões mais antigas do Windows ou implantações controladas, baixe o Evergreen Bootstrapper ou o runtime de versão fixa da Microsoft.
- WebView2Loader.dll. Incluído com o componente. Coloque-o ao lado do executável da sua aplicação. Esta pequena DLL cuida da detecção e carregamento do runtime.
- Somente Windows. O WebView2 é uma tecnologia Windows. O componente tem como alvo aplicações VCL no Windows 7 e versões posteriores (Windows 10/11 recomendado para suporte completo a recursos).
Nota. Você pode verificar se o runtime WebView2 está instalado antes de criar o componente. Se não estiver presente, você pode orientar o usuário a instalá-lo ou recorrer a um controle de navegador alternativo.
Conclusão
TsgcWebView2 é o wrapper WebView2 mais completo disponível para Delphi. É um superconjunto estrito do TEdgeBrowser, adicionando doze recursos que o componente integrado da Embarcadero não expõe — gerenciamento de cookies, eventos de download, controle de perfis, detecção de áudio, acesso ao favicon, tratamento de certificados, autenticação básica, texto da barra de status, mapeamento de host virtual, buffer compartilhado, controle total do menu de contexto e degradação elegante.
Suporta a maior variedade de versões do Delphi de qualquer wrapper WebView2, do Delphi 7 ao Delphi 13. Seja para manter uma aplicação legada em um compilador mais antigo ou construir um novo projeto no Delphi mais recente, o mesmo componente e a mesma API funcionam em todo lugar.
A API é projetada para ser fácil de aprender — solte o componente em um formulário, chame Navigate e trate os eventos — enquanto permanece poderosa o suficiente para cenários avançados por meio de acesso COM bruto e verificação de versão por recurso. Para desenvolvedores Delphi que precisam de um navegador embutido moderno, o TsgcWebView2 é a escolha natural.