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.

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"

Quedarse en sus propios servidores #

ue_navigating se lanza cada vez que el sitio pasa a otra página — un vínculo, un formulario, un script —, nunca para una dirección asignada por su código. 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 por el sitio; un formulario enviado por POST pierde sus datos.

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

// ue_navigating event of uo_browser : (string as_url)
// Only the company servers may be opened
return Pos(Lower(as_url), "://intranet.example.com/") > 0

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")

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).

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.

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

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