TWebView2

Fuente: source/classes/twebview2.prg

Overview

TWebView2 embebe Microsoft Edge WebView2 en una ventana o diálogo FiveWin. Sirve para alojar UIs HTML/CSS/JS modernas junto a controles FWH nativos. Requiere el Runtime WebView2.

Desktop + Web con una sola UI

El sample samples/DesktopWeb/login.prg muestra el patrón en el que desktop y navegador comparten el mismo HTML/CSS/JS:

Un servidor HTTP multi-hilo en el puerto 8080 sirve login y dashboard generados en Harbour.
El shell desktop crea TWebView2 y hace Navigate("http://localhost:8080/").
Cualquier navegador abre la misma URL con la misma UI y API.
La validación de credenciales está en PRG (ValidateLogin); sesión con cookie DWSESS.

Compilar con VM multi-hilo: samples\DesktopWeb\build.bat o build_new.bat login hm64 -mt. Demo: admin/1234, demo/demo.

FWH 26.09

La API ampliada, incluidos bOnConsole y EnableConsole, está disponible desde FWH 26.09, día 12 (12 de septiembre de 2026). Son características de la biblioteca FWH, no basta con actualizar el Runtime de Microsoft. Las bibliotecas anteriores pueden carecer del setter DATA _BONCONSOLE y del método EnableConsole.

Referencia de métodos

C = cadena, N = número, L = lógico, HWND = handle de Windows. NIL indica que no se devuelve estado; no es un indicador de éxito. "delegated" indica retorno del método de ventana; "virtual" es un hook vacío. El inicio asíncrono y el éxito final son distintos.

Firma	Retorno	Comportamiento
`New( oWndParent, cUserDataFolder, cBrowserExecutableFolder )`	`Self`	Crea la vista en oWndParent, o una ventana propia si es NIL. Comprueba hWebView si falla la creación. El perfil vacío usa %LOCALAPPDATA%\FWH_webview2_UserData. El tercer argumento selecciona la carpeta del Runtime Fixed Version al crear la vista.
`Navigate( cUrl )`	`NIL`	Inicia la navegación; bOnNavigationCompleted informa de su finalización.
`NavigateEx( cUrl, cMethod, cHeaders, cBody )`	`L`	Envía una petición HTTP. El método vacío usa GET; las cabeceras son líneas Nombre: Valor separadas por CRLF. .T. indica petición iniciada, no éxito HTTP. En runtimes antiguos solo GET simple puede recurrir a Navigate.
`SetHtml( cHtml )`	`NIL`	Carga una cadena HTML.
`Eval( cJavaScript )`	`NIL`	Ejecuta JavaScript en la página; el resultado codificado como JSON llega de forma asíncrona a bOnEval.
`InjectJavascript( cScript )`	`NIL`	Añade un elemento script mediante Eval. La CSP de la página puede bloquearlo; también se procesan los escapes de la plantilla JS. Usa Eval para ejecución directa.
`GoBack()`	`NIL`	Retrocede en el historial.
`GoForward()`	`NIL`	Avanza en el historial.
`Reload()`	`NIL`	Recarga la página actual.
`Stop()`	`NIL`	Detiene la navegación actual.
`Print()`	`NIL`	Llama a window.print() mediante Eval; no devuelve un resultado síncrono de impresión.
`CanGoBack()`	`L`	Indica si hay una entrada anterior en el historial; .F. si no está disponible.
`CanGoForward()`	`L`	Indica si hay una entrada siguiente en el historial; .F. si no está disponible.
`GetSource()`	`C`	Devuelve la URL actual, no el HTML de la página; cadena vacía si no está disponible.
`GetDocumentTitle()`	`C`	Devuelve el título del documento, o una cadena vacía.
`GetBrowserVersion()`	`C`	Lee del registro de Windows la versión del Runtime Evergreen instalado, o una cadena vacía. No consulta la carpeta Fixed Version seleccionada.
`SetZoomFactor( nZoom )`	`NIL`	Ajusta el zoom del navegador solo si 0.1 < nZoom < 10.0.
`GetZoomFactor()`	`N`	Devuelve el zoom del navegador; 1.0 si no hay controlador.
`SetSizeRatio( nRatio )`	`N`	Guarda y devuelve nRatio (inicialmente 1.0); no redimensiona el navegador ni cambia su zoom.
`GetSizeRatio()`	`N`	Devuelve el factor de escala guardado para la aplicación.
`SetSize( nWidth, nHeight )`	`NIL`	Ajusta el tamaño del WebView en píxeles.
`SetTitle( cText )`	`L`	Llama a SetWindowText sobre oWnd; devuelve el indicador de éxito de la API de Windows.
`Center()`	`delegated`	Delega en oWnd:Center(); el retorno pertenece a la clase de ventana.
`Run()`	`delegated`	Delega en oWnd:Activate(); no es un resultado de estado del WebView.
`SetParent( oWnd )`	`HWND`	Guarda el nuevo padre, aplica estilos child/visible y reasigna la ventana. Devuelve el padre anterior de SetParent; cero también puede indicar ausencia de padre anterior.
`GetWindow()`	`HWND`	Devuelve oWnd:hWnd, el handle de la ventana FWH asociada.
`SetUserAgent( cUserAgent )`	`NIL`	Cambia el user agent del navegador.
`SetBackGroundColor( nRgb )`	`NIL`	Ajusta el fondo del controlador con un valor RGB de Windows.
`OpenDevToolsWindow( lOnOff )`	`NIL`	Abre las herramientas de desarrollo con .T.; .F. no cierra una ventana de herramientas ya abierta.
`ShowDownloads( lOnOff )`	`NIL`	Controla si se muestra la interfaz predeterminada al comenzar futuras descargas; .F. las marca atendidas. No abre ni cierra un diálogo de descargas existente.
`SetDefaultScriptDialogs( lOn )`	`NIL`	Activa/desactiva los diálogos JS predeterminados; NIL usa .T. Usa bOnScriptDialog para aceptarlos.
`SetDefaultContextMenus( lOn )`	`NIL`	Activa/desactiva los menús contextuales predeterminados; NIL usa .T.
`CloseWebView()`	`NIL`	Cierra el navegador/controlador; el objeto de la clase permanece.
`Reinitialize()`	`NIL`	Cierra y recrea entorno/controlador y vuelve a asociar eventos. No devuelve indicador de éxito; restaura el estado de página/aplicación por tu cuenta.
`Reregister()`	`NIL`	Vuelve a asociar eventos de zoom, diálogo JS y recursos web; elimina antes los registros anteriores.
`End()`	`NIL`	Destruye la vista nativa, vacía hWebView y elimina el objeto del registro de vistas.
`SetContextMenuExclude( cCsv )`	`C`	Guarda y devuelve la lista CSV (NIL se convierte en vacío). El filtrado por elemento no está implementado con el SDK incluido.
`EnableConsole( lOnOff )`	`L`	Ajusta y devuelve lConsole (NIL usa .T.). Consulta la sección de consola para la inyección y la desactivación.
`CapturePreview( cPngPath )`	`L`	Inicia una captura PNG asíncrona. .F. indica que no se inició; con .T. espera bOnCapturePreview(lOk,cPath,hWebView).
`PrintToPdf( cPdfPath, lLandscape )`	`L`	Inicia una exportación PDF asíncrona (.F./NIL en lLandscape indica vertical). Requiere interfaces compatibles del runtime. El resultado final llega a bOnPrintToPdf(lOk,cPath,hWebView), no al indicador de inicio.
`AddWebResourceRequestedFilter( cUri, nContext )`	`NIL`	Añade un filtro por patrón de URL; NIL en el contexto usa WV_CONTEXT_ALL (0). bOnWebResource recibe las coincidencias.
`RemoveWebResourceRequestedFilter( cUri, nContext )`	`NIL`	Elimina un filtro por patrón de URL; NIL en el contexto usa WV_CONTEXT_ALL (0). bOnWebResource recibe las coincidencias.
`AddHostObject( cName )`	`.F.`	No implementado: no registra un objeto host IDispatch.
`RemoveHostObject( cName )`	`.T.`	Operación de compatibilidad sin efecto; no elimina ningún objeto host nativo.
`ClearBrowsingData( nKinds )`	`.T.`	Encola el borrado JS de cookies accesibles, local/session storage y Cache Storage; NIL en nKinds usa 0. nKinds se incluye en la confirmación, pero no selecciona categorías nativas. El evento asíncrono confirma el script, no que se borró cada elemento.
`ClearSession()`	`.T.`	Alias de ClearBrowsingData(0); no borra todo el perfil.
`ClearAllBrowsingData()`	`.T.`	Alias de ClearBrowsingData(0); pese al nombre no elimina cookies HttpOnly ni todo el 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. Otros valores usan el contador de recursos web; sin vista nativa devuelve -999.
`Terminate()`	`virtual`	Hook virtual vacío; no sustituye End().
`Destroy()`	`virtual`	Hook virtual vacío; no sustituye End().

Bloques de eventos

Asigna bloques con estos argumentos. hWebView es el puntero de la vista nativa, no el objeto FWH; bOnBind recibe oWebView como segundo argumento. Los retornos solo afectan al comportamiento cuando se indica.

Firma	Comportamiento
`bOnBind( uParams, oWebView )`	Recibe argumentos normales de SendToFWH; retorno ignorado. Los arrays de un elemento se desempaquetan; consola/limpieza usan eventos separados.
`bOnEval( cJson, hWebView )`	Resultado JavaScript codificado como JSON; retorno ignorado.
`bOnConsole( cJson, hWebView )`	JSON de consola descrito abajo; retorno ignorado.
`bOnNavigationCompleted( cUrl, hWebView )`	Navegación principal completada. Retorno ignorado.
`bOnSourceChanged( cUrl, hWebView )`	Cambió la URL de origen. Retorno ignorado.
`bOnDocumentTitleChanged( cTitle, hWebView )`	Cambió el título del documento. Retorno ignorado.
`bOnHistoryChanged( lCanBack, lCanFwd, hWebView )`	Cambió la disponibilidad del historial. Retorno ignorado.
`bOnFrameNavCompleted( cUrl, hWebView )`	Navegación de frame completada. Retorno ignorado.
`bOnCapturePreview( lOk, cPath, hWebView )`	Resultado final de captura/escritura PNG. Retorno ignorado.
`bOnPrintToPdf( lOk, cPath, hWebView )`	Resultado final de exportación PDF. Retorno ignorado.
`bOnClearBrowsingData( lOk, cWhat, hWebView )`	Confirmación JS: .T., "javascript"; no prueba un borrado completo del perfil. Retorno ignorado.
`bOnZoomFactorChanged( nZoom, hWebView )`	Cambió el zoom del navegador. Retorno ignorado.
`bOnProcessFailed( nKind, hWebView )`	Fallo del proceso del navegador; tipo WV_FAIL_*. Retorno ignorado.
`bOnFullScreen( lFull, hWebView )`	Cambió el estado HTML de pantalla completa. Retorno ignorado.
`bOnNavigationStarting( cUrl, hWebView )`	Devuelve .T. para cancelar; otros valores, o valores no lógicos, no cancelan.
`bOnFrameNavStarting( cUrl, hWebView )`	Devuelve .T. para cancelar; otros valores, o valores no lógicos, no cancelan.
`bOnNewWindow( cUrl, hWebView )`	Solo notificación: la vista nativa navega a la URL y marca la petición como atendida; el retorno no selecciona otra ventana.
`bOnPermission( cUrl, nKind, hWebView )`	Devuelve WV_PERM_ALLOW (1), WV_PERM_DENY (2), o 0 para el valor predeterminado; nKind es el tipo de permiso del runtime.
`bOnWebResource( cUrl, nContext, hWebView )`	Devuelve .T. o un número distinto de cero para bloquear con HTTP 403 vacío; en otro caso permite. Instala antes los filtros.
`bOnScriptDialog( cUri, nKind, cMsg, cDefault, hWebView )`	Devuelve .T. para Accept; .F. deja la gestión predeterminada (o sin diálogo si está desactivada). Un bloque instalado con retorno no lógico se trata como .T. Tipos WV_DIALOG_*. No se expone cambiar la respuesta de prompt.
`bOnHostObject( cObjName, cMethod, cArg, hWebView )`	Hook reservado con retorno C; el registro nativo de objetos host no está implementado.

Consola JavaScript

EnableConsole(.T.) intercepta console.log/warn/error/info sin quitar la salida original de consola y añade un listener de errores JavaScript. Envía un sobre interno por SendToFWH; bOnConsole recibe la cadena JSON interior, no el sobre externo. args contiene cadenas: los objetos se convierten con JSON.stringify. line aparece en errores de window y no en llamadas normales a console.

Llama a EnableConsole(.T.) tras cada navegación principal: la intercepción se instala una vez por documento. EnableConsole(.F.) detiene la entrega por el despachador de consola, pero no deshace la intercepción JavaScript ya instalada. Su retorno lógico es el indicador guardado, no prueba de inyección correcta. La consola va separada de los mensajes normales de bOnBind.

Ejemplos de JSON recibido

{
  "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
}

Ejemplo de consola

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

Compatibilidad de bibliotecas

Para admitir bibliotecas FWH anteriores, comprueba tanto la asignación del DATA como la llamada a EnableConsole. Usa la misma comprobación al activar la traza tras navegar. Solo se omite el diagnóstico de consola; el tráfico normal SendToFWH/bOnBind no cambia.

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

Límites y requisitos del runtime

AddHostObject no está implementado. SetContextMenuExclude guarda la lista pero no filtra elementos del menú. La limpieza es mediante JavaScript, no borra todo el perfil ni cookies HttpOnly. Comprueba el resultado PNG/PDF asíncrono en sus eventos. Las interfaces disponibles del runtime pueden limitar PDF, descargas y peticiones HTTP. Consulta samples/webview2/wvdemo.prg + pulse.html y las constantes WV_CONTEXT_*, WV_DIALOG_*, WV_PERM_* y WV_FAIL_* en include/WebView2.ch.

See Clases Alfabético for full class list.