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.

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"

Restare sui propri server #

ue_navigating viene sollevato ogni volta che il sito passa a un'altra pagina — un collegamento, un modulo, uno script —, mai per un indirizzo impostato dal Suo codice. Con ib_veto_navigation diventa una domanda: restituire false mantiene la pagina corrente. Una pagina autorizzata viene riaperta all'indirizzo richiesto dal sito; un modulo inviato in POST perde i suoi dati.

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

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

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

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.

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

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