TWebView2

Fonte: source/classes/twebview2.prg

Overview

TWebView2 incorpora Microsoft Edge WebView2 numa janela ou diálogo FiveWin. Serve para alojar UIs HTML/CSS/JS modernas junto de controlos FWH nativos. Requer o Runtime WebView2.

Desktop + Web com uma única UI

O sample samples/DesktopWeb/login.prg mostra o padrão em que desktop e browser partilham o mesmo HTML/CSS/JS:

Um servidor HTTP multi-thread na porta 8080 serve login e dashboard gerados em Harbour.
O shell desktop cria TWebView2 e faz Navigate("http://localhost:8080/").
Qualquer browser abre a mesma URL com a mesma UI e API.
A validação de credenciais está em PRG (ValidateLogin); sessão com cookie DWSESS.

Compilar com VM multi-thread: samples\DesktopWeb\build.bat ou build_new.bat login hm64 -mt. Demo: admin/1234, demo/demo.

FWH 26.09

A API ampliada, incluindo bOnConsole e EnableConsole, está disponível desde FWH 26.09, dia 12 (12 de setembro de 2026). São recursos da biblioteca FWH; atualizar apenas o Runtime da Microsoft não basta. Bibliotecas anteriores podem não ter o setter DATA _BONCONSOLE nem o método EnableConsole.

Referência de métodos

C = string, N = número, L = lógico, HWND = handle do Windows. NIL indica ausência de retorno de estado; não é indicador de sucesso. "delegated" indica retorno do método da janela; "virtual" é um hook vazio. Início assíncrono e sucesso final são distintos.

Assinatura	Retorno	Comportamento
`New( oWndParent, cUserDataFolder, cBrowserExecutableFolder )`	`Self`	Cria a vista em oWndParent, ou uma janela própria se for NIL. Verifique hWebView se a criação falhar. O perfil vazio usa %LOCALAPPDATA%\FWH_webview2_UserData. O terceiro argumento seleciona a pasta do Runtime Fixed Version na criação.
`Navigate( cUrl )`	`NIL`	Inicia a navegação; bOnNavigationCompleted informa a conclusão.
`NavigateEx( cUrl, cMethod, cHeaders, cBody )`	`L`	Envia uma requisição HTTP. O método vazio usa GET; os cabeçalhos usam linhas Nome: Valor separadas por CRLF. .T. indica início, não sucesso HTTP. Em runtimes antigos apenas GET simples pode usar Navigate como alternativa.
`SetHtml( cHtml )`	`NIL`	Carrega uma string HTML.
`Eval( cJavaScript )`	`NIL`	Executa JavaScript na página; o resultado codificado em JSON chega de forma assíncrona a bOnEval.
`InjectJavascript( cScript )`	`NIL`	Adiciona um elemento script por Eval. A CSP da página pode bloqueá-lo; os escapes do template JS também são processados. Use Eval para execução direta.
`GoBack()`	`NIL`	Volta no histórico.
`GoForward()`	`NIL`	Avança no histórico.
`Reload()`	`NIL`	Recarrega a página atual.
`Stop()`	`NIL`	Para a navegação atual.
`Print()`	`NIL`	Chama window.print() por Eval; não retorna um resultado síncrono de impressão.
`CanGoBack()`	`L`	Indica se há entrada anterior no histórico; .F. se indisponível.
`CanGoForward()`	`L`	Indica se há entrada seguinte no histórico; .F. se indisponível.
`GetSource()`	`C`	Retorna a URL atual, não o HTML da página; string vazia se indisponível.
`GetDocumentTitle()`	`C`	Retorna o título do documento, ou uma string vazia.
`GetBrowserVersion()`	`C`	Lê no registro do Windows a versão instalada do Runtime Evergreen, ou uma string vazia. Não consulta a pasta Fixed Version selecionada.
`SetZoomFactor( nZoom )`	`NIL`	Ajusta o zoom do navegador apenas se 0.1 < nZoom < 10.0.
`GetZoomFactor()`	`N`	Retorna o zoom do navegador; 1.0 sem controlador.
`SetSizeRatio( nRatio )`	`N`	Armazena e retorna nRatio (inicialmente 1.0); não redimensiona o navegador nem muda o zoom.
`GetSizeRatio()`	`N`	Retorna o fator de escala armazenado para a aplicação.
`SetSize( nWidth, nHeight )`	`NIL`	Ajusta o tamanho do WebView em pixels.
`SetTitle( cText )`	`L`	Chama SetWindowText em oWnd; retorna o indicador de sucesso da API do Windows.
`Center()`	`delegated`	Delega a oWnd:Center(); o retorno pertence à classe da janela.
`Run()`	`delegated`	Delega a oWnd:Activate(); não é um resultado de estado do WebView.
`SetParent( oWnd )`	`HWND`	Armazena o novo pai, aplica estilos child/visible e reatribui a janela. Retorna o pai anterior de SetParent; zero também pode indicar ausência de pai anterior.
`GetWindow()`	`HWND`	Retorna oWnd:hWnd, o handle da janela FWH associada.
`SetUserAgent( cUserAgent )`	`NIL`	Altera o user agent do navegador.
`SetBackGroundColor( nRgb )`	`NIL`	Ajusta o fundo do controlador com um valor RGB do Windows.
`OpenDevToolsWindow( lOnOff )`	`NIL`	Abre as ferramentas de desenvolvimento com .T.; .F. não fecha uma janela de ferramentas já aberta.
`ShowDownloads( lOnOff )`	`NIL`	Controla se a interface padrão aparece ao iniciar futuros downloads; .F. marca-os atendidos. Não abre nem fecha um diálogo de downloads existente.
`SetDefaultScriptDialogs( lOn )`	`NIL`	Ativa/desativa os diálogos JS padrão; NIL usa .T. Use bOnScriptDialog para aceitá-los.
`SetDefaultContextMenus( lOn )`	`NIL`	Ativa/desativa os menus de contexto padrão; NIL usa .T.
`CloseWebView()`	`NIL`	Fecha o navegador/controlador; o objeto da classe permanece.
`Reinitialize()`	`NIL`	Fecha e recria ambiente/controlador e reassocia eventos. Não retorna indicador de sucesso; restaure o estado da página/aplicação.
`Reregister()`	`NIL`	Reassocia eventos de zoom, diálogo JS e recursos web; remove antes os registros antigos.
`End()`	`NIL`	Destrói a vista nativa, limpa hWebView e remove o objeto do registro de vistas.
`SetContextMenuExclude( cCsv )`	`C`	Armazena e retorna a lista CSV (NIL torna-se vazio). O filtro por item não está implementado com o SDK incluído.
`EnableConsole( lOnOff )`	`L`	Ajusta e retorna lConsole (NIL usa .T.). Consulte a seção de console para injeção e desativação.
`CapturePreview( cPngPath )`	`L`	Inicia captura PNG assíncrona. .F. indica que não iniciou; com .T. aguarde bOnCapturePreview(lOk,cPath,hWebView).
`PrintToPdf( cPdfPath, lLandscape )`	`L`	Inicia exportação PDF assíncrona (.F./NIL em lLandscape indica retrato). Requer interfaces compatíveis do runtime. O resultado final chega a bOnPrintToPdf(lOk,cPath,hWebView), não ao indicador de início.
`AddWebResourceRequestedFilter( cUri, nContext )`	`NIL`	Adiciona um filtro por padrão de URL; NIL no contexto usa WV_CONTEXT_ALL (0). bOnWebResource recebe as correspondências.
`RemoveWebResourceRequestedFilter( cUri, nContext )`	`NIL`	Remove um filtro por padrão de URL; NIL no contexto usa WV_CONTEXT_ALL (0). bOnWebResource recebe as correspondências.
`AddHostObject( cName )`	`.F.`	Não implementado: não registra objeto host IDispatch.
`RemoveHostObject( cName )`	`.T.`	Operação de compatibilidade sem efeito; não remove objeto host nativo.
`ClearBrowsingData( nKinds )`	`.T.`	Enfileira remoção JS de cookies acessíveis, local/session storage e Cache Storage; NIL em nKinds usa 0. nKinds consta na confirmação, mas não seleciona categorias nativas. O evento assíncrono confirma o script, não a remoção de cada item.
`ClearSession()`	`.T.`	Alias de ClearBrowsingData(0); não apaga todo o perfil.
`ClearAllBrowsingData()`	`.T.`	Alias de ClearBrowsingData(0); apesar do nome não remove cookies HttpOnly nem todo o perfil.
`Diag( nKind )`	`N`	NIL usa 0. 0/1/2: HRESULT de registro para zoom/diálogo/recurso web. 3/4/5: contadores de eventos. Outros valores usam o contador de recursos web; sem vista nativa retorna -999.
`Terminate()`	`virtual`	Hook virtual vazio; não substitui End().
`Destroy()`	`virtual`	Hook virtual vazio; não substitui End().

Blocos de eventos

Atribua blocos com estes argumentos. hWebView é o ponteiro da vista nativa, não o objeto FWH; bOnBind recebe oWebView como segundo argumento. Retornos afetam o comportamento apenas quando indicado.

Assinatura	Comportamento
`bOnBind( uParams, oWebView )`	Recebe argumentos comuns de SendToFWH; retorno ignorado. Arrays de um elemento são desempacotados; console/limpeza usam eventos separados.
`bOnEval( cJson, hWebView )`	Resultado JavaScript codificado em JSON; retorno ignorado.
`bOnConsole( cJson, hWebView )`	JSON de console descrito abaixo; retorno ignorado.
`bOnNavigationCompleted( cUrl, hWebView )`	Navegação principal concluída. Retorno ignorado.
`bOnSourceChanged( cUrl, hWebView )`	URL de origem alterada. Retorno ignorado.
`bOnDocumentTitleChanged( cTitle, hWebView )`	Título do documento alterado. Retorno ignorado.
`bOnHistoryChanged( lCanBack, lCanFwd, hWebView )`	Disponibilidade do histórico alterada. Retorno ignorado.
`bOnFrameNavCompleted( cUrl, hWebView )`	Navegação do frame concluída. Retorno ignorado.
`bOnCapturePreview( lOk, cPath, hWebView )`	Resultado final da captura/gravação PNG. Retorno ignorado.
`bOnPrintToPdf( lOk, cPath, hWebView )`	Resultado final da exportação PDF. Retorno ignorado.
`bOnClearBrowsingData( lOk, cWhat, hWebView )`	Confirmação JS: .T., "javascript"; não comprova remoção completa do perfil. Retorno ignorado.
`bOnZoomFactorChanged( nZoom, hWebView )`	Zoom do navegador alterado. Retorno ignorado.
`bOnProcessFailed( nKind, hWebView )`	Falha do processo do navegador; tipo WV_FAIL_*. Retorno ignorado.
`bOnFullScreen( lFull, hWebView )`	Estado HTML de tela cheia alterado. Retorno ignorado.
`bOnNavigationStarting( cUrl, hWebView )`	Retorne .T. para cancelar; outros valores, ou valores não lógicos, não cancelam.
`bOnFrameNavStarting( cUrl, hWebView )`	Retorne .T. para cancelar; outros valores, ou valores não lógicos, não cancelam.
`bOnNewWindow( cUrl, hWebView )`	Apenas notificação: a vista nativa navega à URL e marca a requisição como atendida; o retorno não seleciona outra janela.
`bOnPermission( cUrl, nKind, hWebView )`	Retorne WV_PERM_ALLOW (1), WV_PERM_DENY (2), ou 0 para padrão; nKind é o tipo de permissão do runtime.
`bOnWebResource( cUrl, nContext, hWebView )`	Retorne .T. ou número diferente de zero para bloquear com HTTP 403 vazio; caso contrário permite. Instale os filtros antes.
`bOnScriptDialog( cUri, nKind, cMsg, cDefault, hWebView )`	Retorne .T. para Accept; .F. mantém a gestão padrão (ou sem diálogo se desativada). Um bloco instalado com retorno não lógico é tratado como .T. Tipos WV_DIALOG_*. Não é exposta a troca da resposta de prompt.
`bOnHostObject( cObjName, cMethod, cArg, hWebView )`	Hook reservado com retorno C; o registro nativo de objetos host não está implementado.

Console JavaScript

EnableConsole(.T.) intercepta console.log/warn/error/info sem remover a saída original do console e adiciona um listener de erros JavaScript. Envia um envelope interno por SendToFWH; bOnConsole recebe a string JSON interna, não o envelope externo. args contém strings: objetos são convertidos com JSON.stringify. line consta nos erros de window, não nas chamadas comuns a console.

Chame EnableConsole(.T.) após cada navegação principal: a interceptação é instalada uma vez por documento. EnableConsole(.F.) interrompe a entrega pelo despachante do console, mas não desfaz a interceptação JavaScript já instalada. Seu retorno lógico é o indicador armazenado, não prova de injeção correta. O console é separado das mensagens comuns de bOnBind.

Exemplos de JSON recebido

{
  "type": "log",
  "args": [
    "ready",
    "{\"count\":2}"
  ],
  "url": "https://example.com/"
}

{
  "type": "error",
  "args": [
    "Uncaught ReferenceError: x is not defined"
  ],
  "url": "https://example.com/",
  "line": 12
}

Exemplo de console

oWeb := TWebView2():New( oWnd )
IF ! Empty( oWeb:hWebView )
   oWeb:bOnConsole := { | cJson, hWebView | LogConsole( cJson ) }
   oWeb:bOnNavigationCompleted := { | cUrl, hWebView | oWeb:EnableConsole( .T. ) }
   oWeb:Navigate( "https://example.com/" )
ENDIF

STATIC FUNCTION LogConsole( cJson )
   LOCAL hData
   hb_jsonDecode( cJson, @hData )
   IF ValType( hData ) == "H"
      // hData[ "type" ], hData[ "args" ], hData[ "url" ]
      // hData[ "line" ]: only for a window error
      OutputDebugString( cJson )
   ENDIF
RETURN NIL

Compatibilidade de bibliotecas

Para aceitar bibliotecas FWH anteriores, verifique a atribuição do DATA e a chamada a EnableConsole. Use a mesma verificação ao ativar o rastreamento após navegar. Apenas o diagnóstico do console é omitido; o tráfego comum SendToFWH/bOnBind não muda.

IF __objHasMsg( oWeb, "_BONCONSOLE" ) .AND. ;
   __objHasMsg( oWeb, "ENABLECONSOLE" )
   oWeb:bOnConsole := { | cJson, hWebView | LogConsole( cJson ) }
   oWeb:EnableConsole( .T. )
ENDIF

Limites e requisitos do runtime

AddHostObject não está implementado. SetContextMenuExclude armazena a lista mas não filtra itens do menu. A limpeza usa JavaScript, não apaga todo o perfil nem cookies HttpOnly. Verifique o resultado PNG/PDF assíncrono nos eventos. As interfaces disponíveis do runtime podem limitar PDF, downloads e requisições HTTP. Consulte samples/webview2/wvdemo.prg + pulse.html e as constantes WV_CONTEXT_*, WV_DIALOG_*, WV_PERM_* e WV_FAIL_* em include/WebView2.ch.

See Classes Alfabético for full class list.