webbrowser — u_pbt_webbrowser #

← Referencia de componentes · Índice de la guía

Navegador web integrado en su ventana: visualización de una página, barra de direcciones, historial Atrás / Adelante, menú contextual de navegación.

▶ Verlo en vivo — Aplicación de demostración, mosaico Web browser: la vista previa, el código que lo genera y esta página, uno al lado del otro.

De un vistazo #

Inicio rápido #

// event open de la ventana
uo_browser.ib_address_bar = true    // barra de direcciones + botones de navegacion
uo_browser.is_address = "https://fr.wikipedia.org/wiki/PowerBuilder"

Asignar is_address es el acto de navegación: cada asignación abre la página solicitada. Una dirección sin protocolo ("ejemplo.com") recibe automáticamente https://. Una ruta de disco (C:\carpeta\pagina.html, \\servidor\recurso\pagina.html) se convierte en una dirección file:///. Las palabras que no son una dirección ("factura 2026") van al motor de búsqueda de is_search_url; sin motor, se rechazan y ue_error lo indica. Un nombre de servidor de una sola palabra seguido de /, ? o # (office/, intranet/inicio) es una dirección, igual que una dirección IPv6 entre corchetes ([::1]/x); la palabra sola (intranet) sigue siendo texto libre. Un servidor sin HTTPS se escribe con http:// explícito.

Propiedades #

Métodos #

Eventos #

Navegar #

La barra de direcciones integrada #

Es la solución más rápida: una propiedad, y el usuario dispone de un campo URL y de los botones Atrás / Adelante / Recargar, con el mismo tema que el resto de la aplicación.

// La barra de direcciones, luego la pagina que se abre
uo_browser.ib_address_bar = true
uo_browser.is_address = "https://fr.wikipedia.org/wiki/PowerBuilder"

Los botones se atenúan solos cuando no hay ningún sitio al que ir. En el campo de dirección, F5 (o Ctrl+R) recarga, Alt+← / Alt+→ retroceden y avanzan (invertidos en escritura de derecha a izquierda), Esc restaura la dirección actual tras una escritura abandonada, y el primer clic selecciona toda la dirección. Un texto que no es una dirección se señala: el campo se bordea de rojo, con una información sobre herramientas, hasta la siguiente tecla. Intro en un campo vacío no hace nada: la página se mantiene.

Sus propios botones #

Si prefiere controlar la navegación desde su propia barra de herramientas, oculte la barra integrada y utilice los métodos:

// Botones Atras / Adelante de su ventana
uo_browser.of_go_back()
uo_browser.of_go_forward()

// event ue_load_completed de uo_browser : (string as_url)
// Actualizar el estado de sus botones despues de cada pagina
uo_toolbar.of_item(/*keys*/ "main/back").ib_enabled = uo_browser.of_can_go_back()
uo_toolbar.of_item(/*keys*/ "main/forward").ib_enabled   = uo_browser.of_can_go_forward()

// Y reflejar la direccion real (redirecciones incluidas)
sle_url.text = as_url

El menú contextual de navegación #

ib_context_menu añade con el clic derecho un pequeño menú Atrás / Adelante / Recargar, con tema y representado por la aplicación. Sigue lo que hay bajo el ratón: Copiar sobre un texto seleccionado, Abrir vínculo y Copiar dirección del vínculo sobre un vínculo, Copiar imagen sobre una imagen. Abierto con el teclado (Mayús+F10, tecla Menú), aparece sobre el elemento. Comparte exactamente el mismo historial que la barra de direcciones: los dos permanecen, por tanto, siempre coherentes.

// A small menu on a right click : back, forward, refresh
uo_browser.ib_context_menu = true

Detener una carga #

// Boton Detener : interrumpe una pagina que tarda demasiado
uo_browser.of_stop()

Palabras en lugar de una dirección #

Por defecto, un texto que no es una dirección se rechaza (ue_error), sin retener nada: la dirección siguiente se carga con normalidad. Para convertirlo en una búsqueda, elija el motor:

// Words typed in the address bar go to this engine (%s = the text)
uo_browser.is_search_url = "https://www.bing.com/search?q=%s"
uo_browser.is_address = "PowerBuilder WebView2"

Nuevas ventanas y descargas #

Un enlace «abrir en una pestaña nueva» o una ventana de inicio de sesión abierta tras un clic se muestra en la vista, y ue_new_window se lo indica. Una descarga continúa como en Edge, y ue_download_starting le da la dirección y el archivo. Ambos se convierten en una pregunta cuando usted lo pide:

// Ask before each download
uo_browser.ib_veto_downloads = true

// ue_download_starting event of uo_browser : (string as_url, string as_path)
// Only PDF files may be downloaded
return Lower(Right(as_path, 4)) = ".pdf"

Una ventana de inicio de sesión que dialoga con la página que la abrió (un inicio de sesión OAuth o Microsoft en una ventana emergente) pierde ese vínculo una vez mostrada en la vista, y el inicio de sesión no termina: abra ese inicio de sesión en la propia página (modo de redirección).

Quedarse en sus propios servidores #

Para mantener una aplicación de gestión en sus propios servidores, enumérelos en is_allowed_hosts: toda página de otro host se rechaza, la pida quien la pida — su código, un vínculo, una dirección escrita en la barra, una redirección del servidor —, y ue_navigation_blocked lo indica. La página mostrada se mantiene.

// Only the company servers : any other host is refused, redirections included
uo_browser.is_allowed_hosts = "intranet.example.com|*.example.com"

// ue_navigation_blocked event of uo_browser : (string as_url)
st_message.text = "This site is not allowed : " + as_url

ue_navigating se lanza cada vez que la página pasa a otra — un vínculo, un formulario o un script del sitio, una dirección escrita por el usuario, Abrir vínculo, una ventana nueva —, nunca para una dirección asignada por su código ni para una redirección. Con ib_veto_navigation es una pregunta: devolver false mantiene la página actual. Una página autorizada se vuelve a abrir en la dirección pedida; un formulario enviado por POST pierde sus datos. Compare el host de la dirección, nunca un trozo de la dirección completa: https://evil.test/?next=://intranet.example.com/ contiene el nombre de su servidor.

// Ask before the site leaves for another page
uo_browser.ib_veto_navigation = true

// ue_navigating event of uo_browser : (string as_url)
// Local variables
string ls_host
long ll_cut

// The host of the address : after "://", up to the first "/", "?", "#" or ":"
ls_host = Lower(Mid(as_url, Pos(as_url, "://") + 3))
for ll_cut = 1 to Len(ls_host)
	if Pos("/?#:", Mid(ls_host, ll_cut, 1)) > 0 then exit
next
ls_host = Left(ls_host, ll_cut - 1)

// Only the company server may be opened : the host must be EXACTLY it
return ls_host = "intranet.example.com"

Cámara, micrófono, ubicación #

Cuando un sitio pide la cámara, el micrófono, la ubicación, las notificaciones o leer el portapapeles, decide ue_permission_requested, y la respuesta por defecto es no: un sitio no enciende una cámara mediante un aviso que el usuario no entiende. Es la única pregunta de la biblioteca en la que el silencio vale rechazo. No se recuerda nada: la pregunta vuelve en cada solicitud.

// ue_permission_requested event of uo_browser : (string as_url, string as_kind)
// The video-call page of the company may use the camera and the microphone
if Pos(Lower(as_url), "://visio.example.com/") = 0 then return false
return as_kind = uo_browser.PERMISSION_CAMERA or as_kind = uo_browser.PERMISSION_MICROPHONE

Valores de as_kind: PERMISSION_CAMERA, PERMISSION_MICROPHONE, PERMISSION_GEOLOCATION, PERMISSION_NOTIFICATIONS, PERMISSION_CLIPBOARD, PERMISSION_SENSORS, PERMISSION_DOWNLOADS (varias descargas seguidas), PERMISSION_FILES, PERMISSION_AUTOPLAY, PERMISSION_FONTS, PERMISSION_MIDI, PERMISSION_WINDOWS, PERMISSION_UNKNOWN.

Por qué no se cargó una página #

al_status de ue_load_failed se compara con las constantes LOADSTATUS_* del componente:

// ue_load_failed event of uo_browser : (string as_url, long al_status)
if al_status = uo_browser.LOADSTATUS_HOST_NOT_RESOLVED then
	st_message.text = "Unknown address : " + as_url
end if

Ejecutar un script en la página #

of_execute_javascript lee o modifica la página mostrada (su título, un campo, un contador). No está limitado por la licencia, ni siquiera en una página about:blank o data:: ejecutar un script en la página es la función de un navegador, y el componente es gratuito.

// ue_load_completed event of uo_browser : (string as_url)
// The page title, as JSON : "PowerBuilder - Wikipedia" (quotes included)
sle_title.text = uo_browser.of_execute_javascript(/*script*/ "document.title")

Indicador de carga #

ue_load_started se lanza cuando una página empieza a cargarse — una dirección de su código, un vínculo, un gesto del usuario —, y of_is_loading() devuelve true hasta ue_load_completed o ue_load_failed: lo suficiente para mostrar un reloj de arena o activar su botón Detener.

// ue_load_started event of uo_browser : (string as_url)
// The Stop button works while the page loads
cb_stop.enabled = true

// ue_load_completed event of uo_browser : (string as_url)
// Loaded : nothing left to stop
cb_stop.enabled = uo_browser.of_is_loading()

Zoom #

ii_zoom amplía o reduce el sitio (la barra de direcciones conserva su tamaño), del 25 al 500 %. Se relee en directo: Ctrl+rueda del ratón en el sitio también lo cambia, y su código lo ve.

// A screen read from a distance : the site one and a half times larger
uo_browser.ii_zoom = 150

El certificado de una intranet #

Un servidor cuyo certificado no es válido (certificado interno o caducado) se rechaza, y ue_load_failed da un estado LOADSTATUS_CERT_*. Con ib_certificate_questions, decide ue_certificate_error — y su respuesta predeterminada es no, como para un permiso: aceptar un certificado es una decisión de seguridad. Una respuesta solo vale para la navegación en curso; no se recuerda nada.

// Ask about certificates instead of refusing them at once
uo_browser.ib_certificate_questions = true

// ue_certificate_error event of uo_browser : (string as_url, long al_status)
// Only the test server of the company, whose certificate is internal
return Left(Lower(as_url), 34) = "https://test-intranet.example.com/"

Mensajes entre la página y la aplicación #

Un portal interno puede avisar a la aplicación («expediente guardado», «fila elegida»): abra el puente con ib_web_messages, y enumere en is_message_origins los orígenes autorizados a hablar. Sin origen en la lista, el puente sigue cerrado: ningún sitio de la Web puede llegar a su aplicación. La página envía un valor JSON, ue_web_message lo recibe tal cual; of_post_message responde a la página.

// The company portal may talk with the application
uo_browser.ib_web_messages = true
uo_browser.is_message_origins = "https://portal.example.com"
uo_browser.is_address = "https://portal.example.com/orders"

// In a page of the portal : send a value to the application, and listen to its answers
chrome.webview.postMessage({ order: 4152, action: "open" });
chrome.webview.addEventListener("message", function (e) { console.log(e.data); });

// ue_web_message event of uo_browser : (string as_origin, string as_json)
// Local variables
n_pbt_json lnv_json

// Read the value the page sent, then answer it
lnv_json.of_load(/*json*/ as_json)
if lnv_json.of_get_string(/*path*/ "action") = "open" then
	st_message.text = "Order " + String(lnv_json.of_get_number(/*path*/ "order"))
	uo_browser.of_post_message(/*json*/ '{"opened":true}')
end if

Un origen se escribe con esquema, host y puerto si no es el predeterminado (https://portal.example.com:8443); un subdominio es otro origen, y file:/// designa las páginas del equipo. Un mensaje de más de 64 KB se descarta. of_post_message hacia una página de otro origen lanza ue_error y no envía nada.

Sitios que rechazan la visualización integrada #

Algunos sitios — Google, la mayoría de los bancos, muchas aplicaciones SaaS — envían encabezados de seguridad que prohíben su visualización dentro de otra página. El componente no se ve afectado: nunca muestra un sitio en un marco. La página se abre como documento principal, exactamente como lo hace su propio navegador, y esos encabezados dejan de aplicarse.

Así pues, no hay nada que configurar ni ningún caso particular que tratar en su código.

// Un sitio que rechaza ser integrado en una pagina : nada especial que hacer
uo_browser.ib_address_bar = true
uo_browser.is_address = "https://www.google.com"

A cambio, la página ocupa toda la superficie del componente bajo la barra de direcciones: lo que dibujara por encima (bandas, superposiciones con tema) no se ve durante la navegación.

Contenido HTML sin red #

of_show_html muestra una página HTML construida por su aplicación: la vista previa de una carta, un ticket, una factura o un informe, sin ninguna llamada de red ni archivo temporal. La página se codifica por usted: un color #c00, un ancla, un % o un acento se muestran tal como se escribieron (2 MB como máximo).

// Local variables
string ls_html

// An order summary built by the application : the colour and the "%" come out as written
ls_html = "<html><body>" &
        + "<h1 style='color:#1f6feb'>Order #4152</h1>" &
        + "<p>Discount : 10%</p>" &
        + "</body></html>"
uo_browser.of_show_html(/*html*/ ls_html)

Asignada directamente en is_address, una dirección data:text/html, no se codifica: un # corta ahí la página (todo lo que sigue se toma por un ancla) y un % la estropea. Prefiera of_show_html, o codifique usted mismo (# → %23, % → %25).

Una página así no tiene dirección propia: is_address se relee vacía, igual que la barra de direcciones, y ue_load_completed recibe una dirección vacía. Sin <title>, su título está vacío. Una imagen del disco (file:///) no se muestra en ella: el motor no deja que una página data: lea los archivos del equipo; escriba la imagen en la página (<img src="data:image/png;base64,…">).

Un archivo local se abre del mismo modo con file:///C:/temp/informe.html, o simplemente con su ruta C:\temp\informe.html.

Volver a empezar de cero #

of_reset() no se limita a vaciar la página: también borra el historial de navegación. Un usuario no puede, por tanto, volver con el botón Atrás a una página consultada por el usuario anterior o en otro expediente. No toca lo que los sitios guardaron: cookies, sesiones iniciadas, almacenamiento local, permisos. En un equipo compartido, el usuario siguiente llegaría conectado con la cuenta del anterior — es of_clear_browsing_data() lo que lo borra. Los sitios viven en un perfil de navegación propio, separado de los componentes de la aplicación.

// Local variables
string ls_folder_url

// La direccion del expediente que el usuario acaba de abrir
ls_folder_url = "https://intranet.example.com/files/4152"

// Cambio de expediente : se parte de un navegador virgen, sin historial
uo_browser.of_reset()

// Luego el expediente, con su barra de direcciones
uo_browser.ib_address_bar = true
uo_browser.is_address = ls_folder_url

// The user of the workstation changes : no page, no history, no signed-in session left
uo_browser.of_reset()
uo_browser.of_clear_browsing_data()

Para que nunca se escriba nada en el disco, asigne ib_private = true antes de la primera dirección: las cookies y el almacenamiento desaparecen con la vista.

Es el reflejo que conviene tener cada vez que un mismo componente sirve para mostrar contenidos de contextos diferentes.

Ejemplo completo #

// event open de la ventana : pagina de inicio del portal interno
uo_browser.of_reset()                  // partir de cero (historial incluido)

// Las herramientas de navegacion, luego la pagina de inicio
uo_browser.ib_address_bar  = true      // campo URL + Atras / Adelante / Recargar
uo_browser.ib_context_menu = true      // la misma navegacion con el clic derecho
uo_browser.is_address = "https://intranet.example.com/home"

// event ue_load_completed de uo_browser : (string as_url)
uo_status.of_panel(/*key*/ "main").is_text = "Página cargada: " + as_url

Buenas prácticas #

• Asigne is_address, no llame a ningún método de navegación: es la propiedad la que desencadena la apertura de la página.
• Active ib_address_bar en cuanto el usuario pueda navegar libremente; reserve el control mediante sus propios botones para los recorridos restringidos.
• Fíese de of_can_go_back() / of_can_go_forward() para el estado de sus botones en lugar de contar las páginas usted mismo: las redirecciones falsearían su cuenta.
• Nada que prever para los sitios que rechazan la visualización integrada: la página siempre se abre como documento principal, esos encabezados no se aplican.
• Llame a of_reset() al cambiar de contexto: es la única manera de garantizar que ninguna página anterior sea accesible mediante el botón Atrás. Cuando cambia el usuario del equipo, añada of_clear_browsing_data(): sin él, las cookies y sesiones de los sitios se mantienen.
• El componente necesita el runtime web instalado en el equipo: trate ue_runtime_missing igual que en cualquier otro componente (Instalación).
• Un sitio puede reproducir sonido sin un gesto del usuario: la reproducción automática con sonido está permitida en todo el entorno WebView2 de la aplicación (el reproductor de vídeo y el de sonidos la necesitan, una página oculta no tiene gestos). Una página que lanza un vídeo con sonido al abrirse lo reproducirá; si es un problema, abra direcciones que conozca.
• Para mantener la aplicación en sus propios servidores, enumérelos en is_allowed_hosts: también detiene las redirecciones, que ue_navigating no ve.

Heredado de la base común #

Estos miembros existen en todos los componentes visuales — no son propios de este. Se detallan una sola vez, en los capítulos transversales; esta tabla solo dice dónde leerlos.

Dos ayudas no se heredan: of_icon y of_escape_markup viven en n_pbt_utils. Declare uno — n_pbt_utils lnv_utils, nada que crear — y llámelas sobre él.

← Referencia de componentes · Índice de la guía