webbrowser — u_pbt_webbrowser #

← Référence des composants · Sommaire du guide

Navigateur web intégré à votre fenêtre : affichage d'une page, barre d'adresse, historique Précédent / Suivant, menu contextuel de navigation.

▶ Le voir en vrai — Application de démonstration, tuile Web browser : l'aperçu, le code qui le produit et cette page, côte à côte.

En bref #

Démarrage rapide #

// event open de la fenetre
uo_browser.ib_address_bar = true    // barre d'adresse + boutons de navigation
uo_browser.is_address = "https://fr.wikipedia.org/wiki/PowerBuilder"

Poser is_address est l'acte de navigation : chaque affectation ouvre la page demandée. Une adresse sans protocole ("exemple.com") reçoit automatiquement https://. Un chemin disque (C:\dossier\page.html, \\serveur\partage\page.html) devient une adresse file:///. Des mots qui ne sont pas une adresse ("facture 2026") partent vers le moteur de recherche de is_search_url ; sans moteur, ils sont refusés et ue_error le dit. Un nom de serveur d'un seul mot suivi de /, ? ou # (office/, intranet/home) est une adresse, comme une adresse IPv6 entre crochets ([::1]/x) ; le mot seul (intranet) reste un texte libre. Un serveur sans HTTPS s'écrit avec http:// explicite.

Propriétés #

Méthodes #

Événements #

Naviguer #

La barre d'adresse intégrée #

C'est la solution la plus rapide : une propriété, et l'utilisateur dispose d'un champ URL et des boutons Précédent / Suivant / Recharger, thémés comme le reste de l'application.

// La barre d'adresse, puis la page a ouvrir
uo_browser.ib_address_bar = true
uo_browser.is_address = "https://fr.wikipedia.org/wiki/PowerBuilder"

Les boutons se grisent tout seuls quand il n'y a nulle part où aller. Dans le champ d'adresse, F5 (ou Ctrl+R) recharge, Alt+← / Alt+→ reviennent et avancent (inversés en écriture de droite à gauche), Échap rend l'adresse courante après une frappe abandonnée, et le premier clic sélectionne toute l'adresse. Un texte qui n'est pas une adresse est signalé : le champ se borde de rouge, avec une infobulle, jusqu'à la frappe suivante. Entrée sur un champ vide ne fait rien : la page reste.

Vos propres boutons #

Si vous préférez piloter la navigation depuis votre propre barre d'outils, masquez la barre intégrée et utilisez les méthodes :

// Boutons Precedent / Suivant de votre fenetre
uo_browser.of_go_back()
uo_browser.of_go_forward()

// event ue_load_completed de uo_browser : (string as_url)
// Mettre a jour l'etat de vos boutons apres chaque page
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()

// Et refleter l'adresse reelle (redirections comprises)
sle_url.text = as_url

Le menu contextuel de navigation #

ib_context_menu ajoute au clic droit un petit menu Précédent / Suivant / Recharger, thémé et rendu par l'application. Il suit ce qui est sous la souris : Copier sur un texte sélectionné, Ouvrir le lien et Copier l'adresse du lien sur un lien, Copier l'image sur une image. Ouvert au clavier (Maj+F10, touche Menu), il se pose sur l'élément. Il partage exactement le même historique que la barre d'adresse : les deux restent donc toujours cohérents.

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

Arrêter un chargement #

// Bouton Stop : interrompt une page qui tarde
uo_browser.of_stop()

Des mots plutôt qu'une adresse #

Par défaut, un texte qui n'est pas une adresse est refusé (ue_error), sans rien bloquer : l'adresse suivante se charge normalement. Pour en faire une recherche, choisissez le moteur :

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

Nouvelles fenêtres et téléchargements #

Un lien « ouvrir dans un nouvel onglet » ou une fenêtre de connexion ouverte après un clic s'affiche dans la vue, et ue_new_window vous le dit. Un téléchargement continue comme dans Edge, et ue_download_starting vous donne l'adresse et le fichier. Les deux se changent en question quand vous le demandez :

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

Une fenêtre de connexion qui dialogue avec la page qui l'a ouverte (une connexion OAuth ou Microsoft en fenêtre surgissante) perd ce lien une fois affichée dans la vue, et la connexion n'aboutit pas : ouvrez une telle connexion dans la page elle-même (mode redirection).

Rester sur ses serveurs #

Pour garder une application métier sur ses serveurs, listez-les dans is_allowed_hosts : toute page d'un autre hôte est refusée, d'où que vienne la demande — votre code, un lien, une adresse tapée dans la barre, une redirection du serveur —, et ue_navigation_blocked le dit. La page affichée reste.

// 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, lui, est levé chaque fois que la page part vers une autre — un lien, un formulaire ou un script du site, une adresse tapée par l'utilisateur, Ouvrir le lien, une nouvelle fenêtre —, jamais pour une adresse posée par votre code ni pour une redirection. Avec ib_veto_navigation, c'est une question : renvoyer false y laisse la page courante. Une page autorisée est rouverte à l'adresse demandée ; un formulaire envoyé en POST y perd ses données. Comparez l'hôte de l'adresse, jamais un morceau de l'adresse entière : https://evil.test/?next=://intranet.example.com/ contient le nom de votre serveur.

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

Caméra, micro, position #

Quand un site demande la caméra, le micro, la position, les notifications ou la lecture du presse-papiers, c'est ue_permission_requested qui décide, et la réponse par défaut est non : un site n'allume pas une caméra par une invite que l'utilisateur ne comprend pas. C'est la seule question de la bibliothèque où le silence vaut refus. Rien n'est retenu : la question revient à chaque demande.

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

Valeurs de as_kind : PERMISSION_CAMERA, PERMISSION_MICROPHONE, PERMISSION_GEOLOCATION, PERMISSION_NOTIFICATIONS, PERMISSION_CLIPBOARD, PERMISSION_SENSORS, PERMISSION_DOWNLOADS (plusieurs téléchargements d'affilée), PERMISSION_FILES, PERMISSION_AUTOPLAY, PERMISSION_FONTS, PERMISSION_MIDI, PERMISSION_WINDOWS, PERMISSION_UNKNOWN.

Pourquoi une page n'a pas chargé #

al_status de ue_load_failed se compare aux constantes LOADSTATUS_* du composant :

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

Exécuter un script dans la page #

of_execute_javascript lit ou modifie la page affichée (son titre, un champ, un compteur). Il n'est pas bridé par la licence, y compris sur une page about:blank ou data: : exécuter un script dans la page est le métier d'un navigateur, et le composant est gratuit.

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

Indicateur de chargement #

ue_load_started est levé quand une page commence à se charger — une adresse de votre code, un lien, un geste de l'utilisateur —, et of_is_loading() rend true jusqu'à ue_load_completed ou ue_load_failed : de quoi montrer un sablier ou activer votre bouton Arrêter.

// 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 agrandit ou réduit le site (la barre d'adresse garde sa taille), de 25 à 500 %. Il se relit en direct : Ctrl+molette dans le site le change aussi, et votre code le voit.

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

Le certificat d'un intranet #

Un serveur dont le certificat n'est pas valide (certificat interne, expiré) est refusé, et ue_load_failed donne un statut LOADSTATUS_CERT_*. Avec ib_certificate_questions, ue_certificate_error décide — et sa réponse par défaut est non, comme pour une permission : accepter un certificat est une décision de sécurité. Une réponse ne vaut que pour la navigation en cours ; rien n'est retenu.

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

Des messages entre la page et l'application #

Un portail interne peut prévenir l'application (« dossier enregistré », « ligne choisie ») : ouvrez le pont avec ib_web_messages, et listez dans is_message_origins les origines qui ont le droit de parler. Sans origine listée, le pont reste fermé : aucun site du Web ne peut atteindre votre application. La page envoie une valeur JSON, ue_web_message la reçoit telle quelle ; of_post_message répond à la page.

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

Une origine s'écrit schéma, hôte et port s'il n'est pas celui par défaut (https://portal.example.com:8443) ; un sous-domaine est une autre origine, et file:/// désigne les pages du poste. Un message de plus de 64 Ko est ignoré. of_post_message vers une page d'une autre origine lève ue_error et n'envoie rien.

Sites qui refusent l'affichage intégré #

Certains sites — Google, la plupart des banques, beaucoup d'applications SaaS — envoient des en-têtes de sécurité qui interdisent leur affichage à l'intérieur d'une autre page. Le composant n'est pas concerné : il n'affiche jamais un site dans un cadre. La page est ouverte comme document principal, exactement comme le fait votre navigateur, et ces en-têtes ne s'appliquent alors plus.

Il n'y a donc rien à régler, et aucun cas particulier à prévoir dans votre code.

// Un site qui refuse d'etre integre dans une page : rien de special a faire
uo_browser.ib_address_bar = true
uo_browser.is_address = "https://www.google.com"

En contrepartie, la page occupe toute la surface du composant sous la barre d'adresse : les habillages posés par-dessus (bandeaux, superpositions thémées) ne sont pas visibles pendant la navigation.

Contenu HTML sans réseau #

of_show_html affiche une page HTML construite par votre application : un aperçu de courrier, un ticket, une facture ou un rapport, sans aucun appel réseau ni fichier temporaire. La page est encodée pour vous : une couleur #c00, une ancre, un % ou un accent s'affichent tels qu'écrits (2 Mo au plus).

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

Posée directement dans is_address, une adresse data:text/html, n'est pas encodée : un # y coupe la page (tout ce qui suit passe pour une ancre) et un % la brouille. Préférez of_show_html, ou encodez vous-même (# → %23, % → %25).

Une telle page n'a pas d'adresse à elle : is_address se relit vide, la barre d'adresse aussi, et ue_load_completed reçoit une adresse vide. Sans <title>, son titre est vide. Une image du disque (file:///) n'y est pas affichée : le moteur ne laisse pas une page data: lire les fichiers du poste ; écrivez l'image dans la page (<img src="data:image/png;base64,…">).

Un fichier local s'ouvre de la même façon avec file:///C:/temp/rapport.html, ou simplement son chemin C:\temp\rapport.html.

Repartir de zéro #

of_reset() ne se contente pas de vider la page : il efface aussi l'historique de navigation. Un utilisateur ne peut donc pas revenir, par le bouton Précédent, sur une page consultée par l'utilisateur précédent ou dans un autre dossier. Il ne touche pas à ce que les sites ont retenu : cookies, sessions ouvertes, stockage local, permissions. Sur un poste partagé, l'utilisateur suivant arriverait connecté sous le compte du précédent — c'est of_clear_browsing_data() qui l'efface. Les sites vivent dans un profil de navigation à part, séparé des composants de l'application.

// Local variables
string ls_folder_url

// L'adresse du dossier que l'utilisateur vient d'ouvrir
ls_folder_url = "https://intranet.example.com/files/4152"

// Changement de dossier : on repart d'un navigateur vierge, sans historique
uo_browser.of_reset()

// Puis le dossier, avec sa barre d'adresse
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()

Pour que rien ne soit jamais écrit sur le disque, posez ib_private = true avant la première adresse : cookies et stockage disparaissent avec la vue.

C'est le réflexe à avoir chaque fois qu'un même composant sert à afficher des contenus de contextes différents.

Exemple complet #

// event open de la fenetre : page d'accueil du portail interne
uo_browser.of_reset()                  // repartir propre (historique compris)

// Les outils de navigation, puis la page d'accueil
uo_browser.ib_address_bar  = true      // champ URL + Precedent / Suivant / Recharger
uo_browser.ib_context_menu = true      // meme navigation au clic droit
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 = "Page chargee : " + as_url

Bonnes pratiques #

• Affectez is_address, n'appelez pas de méthode de navigation : c'est la propriété qui déclenche l'ouverture de la page.
• Activez ib_address_bar dès que l'utilisateur peut naviguer librement ; réservez le pilotage par vos propres boutons aux parcours contraints.
• Fiez-vous à of_can_go_back() / of_can_go_forward() pour l'état de vos boutons plutôt que de compter les pages vous-même : les redirections fausseraient votre compte.
• Rien à prévoir pour les sites qui refusent l'affichage intégré : la page est toujours ouverte comme document principal, ces en-têtes ne s'appliquent pas.
• Appelez of_reset() en changeant de contexte : c'est le seul moyen de garantir qu'aucune page précédente n'est accessible par le bouton Précédent. Quand l'utilisateur du poste change, ajoutez of_clear_browsing_data() : sans lui, cookies et sessions des sites restent.
• Le composant a besoin du runtime web installé sur le poste : traitez ue_runtime_missing comme pour tout autre composant (Installation).
• Un site peut jouer du son sans geste de l'utilisateur : la lecture automatique sonore est permise dans tout l'environnement WebView2 de l'application (le lecteur vidéo et le lecteur de sons en ont besoin, une page cachée n'a pas de geste). Une page qui lance une vidéo sonore à l'ouverture la jouera ; si c'est gênant, ouvrez des adresses que vous connaissez.
• Pour garder l'application sur ses serveurs, listez-les dans is_allowed_hosts : il arrête aussi les redirections, que ue_navigating ne voit pas.

Hérité du socle commun #

Ces membres existent sur tous les composants visuels — ils ne sont pas propres à celui-ci. Ils sont détaillés une seule fois, dans les chapitres transverses ; cette table dit seulement où les lire.

Deux aides ne sont pas héritées : of_icon et of_escape_markup vivent sur n_pbt_utils. Déclarez-en une — n_pbt_utils lnv_utils, rien à créer — et appelez-les dessus.

← Référence des composants · Sommaire du guide