webbrowser — u_pbt_webbrowser #

← Riferimento dei componenti · Sommario della guida

Browser web integrato nella Sua finestra: visualizzazione di una pagina, barra degli indirizzi, cronologia Indietro / Avanti, menu contestuale di navigazione.

▶ Vederlo dal vivo — Applicazione dimostrativa, riquadro Web browser: l'anteprima, il codice che lo produce e questa pagina, affiancati.

In breve #

Avvio rapido #

// event open della finestra
uo_browser.ib_address_bar = true    // barra degli indirizzi + pulsanti di navigazione
uo_browser.is_address = "https://fr.wikipedia.org/wiki/PowerBuilder"

Impostare is_address è l'atto di navigazione: ogni assegnazione apre la pagina richiesta. Un indirizzo privo di protocollo ("esempio.it") riceve automaticamente https://. Un percorso su disco (C:\cartella\pagina.html, \\server\condivisione\pagina.html) diventa un indirizzo file:///. Parole che non sono un indirizzo ("fattura 2026") vanno al motore di ricerca di is_search_url; senza motore vengono rifiutate e ue_error lo segnala. Un nome di server di una sola parola seguito da /, ? o # (office/, intranet/home) è un indirizzo, come un indirizzo IPv6 tra parentesi quadre ([::1]/x); la parola da sola (intranet) resta testo libero. Un server senza HTTPS si scrive con http:// esplicito.

Proprietà #

Metodi #

Event #

Navigare #

La barra degli indirizzi integrata #

È la soluzione più rapida: una proprietà, e l'utente dispone di un campo URL e dei pulsanti Indietro / Avanti / Ricarica, a tema come il resto dell'applicazione.

// La barra degli indirizzi, poi la pagina da aprire
uo_browser.ib_address_bar = true
uo_browser.is_address = "https://fr.wikipedia.org/wiki/PowerBuilder"

I pulsanti si disattivano da soli quando non c'è alcun posto dove andare. Nel campo indirizzo, F5 (o Ctrl+R) ricarica, Alt+← / Alt+→ vanno indietro e avanti (invertiti nella scrittura da destra a sinistra), Esc ripristina l'indirizzo corrente dopo una digitazione abbandonata, e il primo clic seleziona l'intero indirizzo. Un testo che non è un indirizzo viene segnalato: il campo si borda di rosso, con una descrizione comando, fino al tasto successivo. Invio su un campo vuoto non fa nulla: la pagina resta.

I Suoi pulsanti personali #

Se preferisce pilotare la navigazione dalla Sua barra degli strumenti, nasconda la barra integrata e utilizzi i metodi:

// Pulsanti Indietro / Avanti della Sua finestra
uo_browser.of_go_back()
uo_browser.of_go_forward()

// event ue_load_completed di uo_browser : (string as_url)
// Aggiornare lo stato dei Suoi pulsanti dopo ogni 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()

// E rispecchiare l'indirizzo reale (redirezioni comprese)
sle_url.text = as_url

Il menu contestuale di navigazione #

ib_context_menu aggiunge al clic destro un piccolo menu Indietro / Avanti / Ricarica, a tema e disegnato dall'applicazione. Segue ciò che si trova sotto il mouse: Copia su un testo selezionato, Apri collegamento e Copia indirizzo collegamento su un collegamento, Copia immagine su un'immagine. Aperto da tastiera (Maiusc+F10, tasto Menu), compare sull'elemento. Condivide esattamente la stessa cronologia della barra degli indirizzi: i due restano quindi sempre coerenti.

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

Interrompere un caricamento #

// Pulsante Stop : interrompe una pagina che tarda
uo_browser.of_stop()

Parole invece di un indirizzo #

Per impostazione predefinita, un testo che non è un indirizzo viene rifiutato (ue_error), senza bloccare nulla: l'indirizzo successivo si carica normalmente. Per farne una ricerca, scelga il motore:

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

Nuove finestre e download #

Un link «apri in una nuova scheda» o una finestra di accesso aperta dopo un clic viene mostrata nella vista, e ue_new_window glielo segnala. Un download prosegue come in Edge, e ue_download_starting Le fornisce indirizzo e file. Entrambi diventano una domanda quando lo richiede:

// 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 finestra di accesso che dialoga con la pagina che l'ha aperta (un accesso OAuth o Microsoft in una finestra a comparsa) perde questo legame una volta mostrata nella vista, e l'accesso non va a buon fine: apra un simile accesso nella pagina stessa (modalità reindirizzamento).

Restare sui propri server #

Per tenere un'applicazione gestionale sui propri server, li elenchi in is_allowed_hosts: ogni pagina di un altro host viene rifiutata, chiunque la richieda — il Suo codice, un collegamento, un indirizzo digitato nella barra, un reindirizzamento del server —, e ue_navigation_blocked lo segnala. La pagina visualizzata resta.

// 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 viene sollevato ogni volta che la pagina passa a un'altra — un collegamento, un modulo o uno script del sito, un indirizzo digitato dall'utente, Apri collegamento, una nuova finestra —, mai per un indirizzo impostato dal Suo codice né per un reindirizzamento. Con ib_veto_navigation diventa una domanda: restituire false mantiene la pagina corrente. Una pagina autorizzata viene riaperta all'indirizzo richiesto; un modulo inviato in POST perde i suoi dati. Confronti l'host dell'indirizzo, mai un pezzo dell'indirizzo intero: https://evil.test/?next=://intranet.example.com/ contiene il nome del Suo server.

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

Fotocamera, microfono, posizione #

Quando un sito chiede la fotocamera, il microfono, la posizione, le notifiche o la lettura degli appunti, decide ue_permission_requested, e la risposta predefinita è no: un sito non accende una fotocamera tramite una richiesta che l'utente non capisce. È l'unica domanda della libreria in cui il silenzio vale rifiuto. Nulla viene memorizzato: la domanda ritorna a ogni richiesta.

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

Valori di as_kind: PERMISSION_CAMERA, PERMISSION_MICROPHONE, PERMISSION_GEOLOCATION, PERMISSION_NOTIFICATIONS, PERMISSION_CLIPBOARD, PERMISSION_SENSORS, PERMISSION_DOWNLOADS (più download di seguito), PERMISSION_FILES, PERMISSION_AUTOPLAY, PERMISSION_FONTS, PERMISSION_MIDI, PERMISSION_WINDOWS, PERMISSION_UNKNOWN.

Perché una pagina non si è caricata #

al_status di ue_load_failed si confronta con le costanti 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

Eseguire uno script nella pagina #

of_execute_javascript legge o modifica la pagina visualizzata (il titolo, un campo, un contatore). Non è limitato dalla licenza, anche su una pagina about:blank o data:: eseguire uno script nella pagina è il mestiere di un browser, e il componente è 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")

Indicatore di caricamento #

ue_load_started viene sollevato quando una pagina inizia a caricarsi — un indirizzo del Suo codice, un collegamento, un gesto dell'utente —, e of_is_loading() restituisce true fino a ue_load_completed o ue_load_failed: quanto basta per mostrare una clessidra o attivare il Suo pulsante Interrompi.

// 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 ingrandisce o riduce il sito (la barra degli indirizzi mantiene la sua dimensione), dal 25 al 500 %. Si rilegge in tempo reale: Ctrl+rotellina nel sito lo cambia anche, e il Suo codice lo vede.

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

Il certificato di una intranet #

Un server il cui certificato non è valido (certificato interno o scaduto) viene rifiutato, e ue_load_failed fornisce uno stato LOADSTATUS_CERT_*. Con ib_certificate_questions, decide ue_certificate_error — e la sua risposta predefinita è no, come per un permesso: accettare un certificato è una decisione di sicurezza. Una risposta vale solo per la navigazione in corso; nulla viene memorizzato.

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

Messaggi tra la pagina e l'applicazione #

Un portale interno può avvisare l'applicazione («pratica salvata», «riga scelta»): apra il ponte con ib_web_messages, ed elenchi in is_message_origins le origini autorizzate a parlare. Senza origine elencata, il ponte resta chiuso: nessun sito del Web può raggiungere la Sua applicazione. La pagina invia un valore JSON, ue_web_message lo riceve tale e quale; of_post_message risponde alla pagina.

// 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'origine si scrive con schema, host e porta se non è quella predefinita (https://portal.example.com:8443); un sottodominio è un'altra origine, e file:/// indica le pagine della postazione. Un messaggio oltre i 64 KB viene scartato. of_post_message verso una pagina di un'altra origine solleva ue_error e non invia nulla.

Siti che rifiutano la visualizzazione integrata #

Alcuni siti — Google, la maggior parte delle banche, molte applicazioni SaaS — inviano intestazioni di sicurezza che vietano la visualizzazione all'interno di un'altra pagina. Il componente non è interessato: non mostra mai un sito in un riquadro. La pagina viene aperta come documento principale, esattamente come fa il Suo browser, e quelle intestazioni non si applicano più.

Non c'è quindi nulla da impostare, né alcun caso particolare da gestire nel Suo codice.

// Un sito che rifiuta di essere integrato in una pagina : niente di speciale da fare
uo_browser.ib_address_bar = true
uo_browser.is_address = "https://www.google.com"

In cambio, la pagina occupa tutta la superficie del componente sotto la barra degli indirizzi: ciò che disegnasse sopra di essa (fasce, sovrapposizioni a tema) non è visibile durante la navigazione.

Contenuto HTML senza rete #

of_show_html mostra una pagina HTML costruita dalla Sua applicazione: l'anteprima di una lettera, di un ticket, di una fattura o di un report, senza alcuna chiamata di rete né file temporaneo. La pagina viene codificata per Lei: un colore #c00, un'ancora, un % o un accento appaiono come scritti (al massimo 2 MB).

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

Impostato direttamente in is_address, un indirizzo data:text/html, non viene codificato: un # taglia lì la pagina (tutto ciò che segue passa per un'ancora) e un % la altera. Preferisca of_show_html, oppure codifichi da sé (# → %23, % → %25).

Una tale pagina non ha un indirizzo proprio: is_address si rilegge vuoto, così come la barra degli indirizzi, e ue_load_completed riceve un indirizzo vuoto. Senza <title>, il suo titolo è vuoto. Un'immagine del disco (file:///) non vi viene mostrata: il motore non lascia che una pagina data: legga i file della postazione; scriva l'immagine nella pagina (<img src="data:image/png;base64,…">).

Un file locale si apre allo stesso modo con file:///C:/temp/rapporto.html, o semplicemente con il suo percorso C:\temp\rapporto.html.

Ripartire da zero #

of_reset() non si limita a svuotare la pagina: cancella anche la cronologia di navigazione. Un utente non può quindi tornare, con il pulsante Indietro, su una pagina consultata dall'utente precedente o in un'altra pratica. Non tocca ciò che i siti hanno memorizzato: cookie, sessioni aperte, archiviazione locale, permessi. Su una postazione condivisa, l'utente successivo arriverebbe connesso con l'account del precedente — è of_clear_browsing_data() a cancellarlo. I siti vivono in un profilo di navigazione a parte, separato dai componenti dell'applicazione.

// Local variables
string ls_folder_url

// L'indirizzo della pratica che l'utente ha appena aperto
ls_folder_url = "https://intranet.example.com/files/4152"

// Cambio di pratica : si riparte da un browser vergine, senza cronologia
uo_browser.of_reset()

// Poi la pratica, con la sua barra degli indirizzi
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()

Perché nulla venga mai scritto su disco, imposti ib_private = true prima del primo indirizzo: cookie e archiviazione scompaiono con la vista.

È il riflesso da avere ogni volta che uno stesso componente serve a mostrare contenuti di contesti differenti.

Esempio completo #

// event open della finestra : pagina iniziale del portale interno
uo_browser.of_reset()                  // ripartire puliti (cronologia compresa)

// Gli strumenti di navigazione, poi la pagina iniziale
uo_browser.ib_address_bar  = true      // campo URL + Indietro / Avanti / Ricarica
uo_browser.ib_context_menu = true      // stessa navigazione con il clic destro
uo_browser.is_address = "https://intranet.example.com/home"

// event ue_load_completed di uo_browser : (string as_url)
uo_status.of_panel(/*key*/ "main").is_text = "Pagina caricata: " + as_url

Buone pratiche #

• Assegni is_address, non chiami un metodo di navigazione: è la proprietà che attiva l'apertura della pagina.
• Attivi ib_address_bar non appena l'utente può navigare liberamente; riservi il pilotaggio tramite i Suoi pulsanti ai percorsi vincolati.
• Si affidi a of_can_go_back() / of_can_go_forward() per lo stato dei Suoi pulsanti anziché contare le pagine da sé: le redirezioni falserebbero il Suo conteggio.
• Nulla da prevedere per i siti che rifiutano la visualizzazione integrata: la pagina viene sempre aperta come documento principale, quelle intestazioni non si applicano.
• Chiami of_reset() cambiando contesto: è l'unico modo per garantire che nessuna pagina precedente sia raggiungibile con il pulsante Indietro. Quando cambia l'utente della postazione, aggiunga of_clear_browsing_data(): senza di esso cookie e sessioni dei siti restano.
• Il componente ha bisogno del runtime web installato sulla postazione: tratti ue_runtime_missing come per qualsiasi altro componente (Installazione).
• Un sito può riprodurre suono senza un gesto dell'utente: la riproduzione automatica con audio è permessa in tutto l'ambiente WebView2 dell'applicazione (il lettore video e il lettore di suoni ne hanno bisogno, una pagina nascosta non ha gesti). Una pagina che avvia un video con audio all'apertura lo riprodurrà; se è un problema, apra indirizzi che conosce.
• Per tenere l'applicazione sui propri server, li elenchi in is_allowed_hosts: blocca anche i reindirizzamenti, che ue_navigating non vede.

Ereditato dalla base comune #

Questi membri esistono su tutti i componenti visivi — non sono propri di questo. Sono descritti una sola volta, nei capitoli trasversali; questa tabella dice solo dove leggerli.

Due aiuti non sono ereditati: of_icon e of_escape_markup vivono su n_pbt_utils. Ne dichiari uno — n_pbt_utils lnv_utils, niente da creare — e li chiami su di esso.

← Riferimento dei componenti · Sommario della guida