webbrowser — u_pbt_webbrowser #

← Komponentenreferenz · Inhalt des Handbuchs

Ein in Ihr Fenster integrierter Webbrowser: Anzeige einer Seite, Adressleiste, Verlauf Zurück / Vorwärts, Kontextmenü für die Navigation.

▶ Live ansehen — Demoanwendung, Kachel Web browser: die Vorschau, der zugehörige Code und diese Seite, nebeneinander.

Auf einen Blick #

Schnellstart #

// open-Event des Fensters
uo_browser.ib_address_bar = true    // Adressleiste + Navigationsschaltflaechen
uo_browser.is_address = "https://fr.wikipedia.org/wiki/PowerBuilder"

Das Setzen von is_address ist der Navigationsvorgang: Jede Zuweisung öffnet die angeforderte Seite. Eine Adresse ohne Protokoll ("beispiel.de") erhält automatisch https://. Ein Dateipfad (C:\ordner\seite.html, \\server\freigabe\seite.html) wird zu einer file:///-Adresse. Wörter, die keine Adresse sind ("Rechnung 2026"), gehen an die Suchmaschine von is_search_url; ohne Suchmaschine werden sie abgelehnt, und ue_error meldet es. Ein Servername aus einem Wort, gefolgt von /, ? oder # (office/, intranet/start), ist eine Adresse, ebenso eine IPv6-Adresse in eckigen Klammern ([::1]/x); das Wort allein (intranet) bleibt freier Text. Ein Server ohne HTTPS wird mit ausdrücklichem http:// geschrieben.

Eigenschaften #

Methoden #

Events #

Navigieren #

Die integrierte Adressleiste #

Das ist die schnellste Lösung: eine Eigenschaft, und der Benutzer verfügt über ein URL-Feld sowie die Schaltflächen Zurück / Vorwärts / Neu laden, im Design der übrigen Anwendung.

// Die Adressleiste, dann die zu oeffnende Seite
uo_browser.ib_address_bar = true
uo_browser.is_address = "https://fr.wikipedia.org/wiki/PowerBuilder"

Die Schaltflächen grauen sich von selbst aus, wenn es nirgendwohin zu gehen gibt. Im Adressfeld lädt F5 (oder Strg+R) neu, Alt+← / Alt+→ gehen zurück und vorwärts (bei Schreibrichtung von rechts nach links vertauscht), Esc stellt nach einer abgebrochenen Eingabe die aktuelle Adresse wieder her, und der erste Klick markiert die ganze Adresse. Ein Text, der keine Adresse ist, wird markiert: Das Feld erhält bis zur nächsten Taste einen roten Rahmen mit einer QuickInfo. Eingabe in einem leeren Feld bewirkt nichts: Die Seite bleibt.

Ihre eigenen Schaltflächen #

Wenn Sie die Navigation lieber über Ihre eigene Symbolleiste steuern möchten, blenden Sie die integrierte Leiste aus und verwenden Sie die Methoden:

// Schaltflaechen Zurueck / Vorwaerts Ihres Fensters
uo_browser.of_go_back()
uo_browser.of_go_forward()

// ue_load_completed-Event von uo_browser : (string as_url)
// Den Zustand Ihrer Schaltflaechen nach jeder Seite aktualisieren
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()

// Und die tatsaechliche Adresse widerspiegeln (Weiterleitungen inbegriffen)
sle_url.text = as_url

Das Kontextmenü für die Navigation #

ib_context_menu fügt beim Rechtsklick ein kleines Menü Zurück / Vorwärts / Neu laden hinzu, im Design und von der Anwendung gezeichnet. Es richtet sich nach dem, was unter der Maus liegt: Kopieren auf markiertem Text, Link öffnen und Linkadresse kopieren auf einem Link, Bild kopieren auf einem Bild. Per Tastatur geöffnet (Umschalt+F10, Menütaste) erscheint es am Element. Es teilt sich denselben Verlauf wie die Adressleiste: Beide bleiben also stets konsistent.

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

Einen Ladevorgang abbrechen #

// Schaltflaeche Stopp : bricht eine Seite ab, die zu lange braucht
uo_browser.of_stop()

Wörter statt einer Adresse #

Standardmäßig wird ein Text, der keine Adresse ist, abgelehnt (ue_error), ohne etwas zu blockieren: Die nächste Adresse lädt normal. Um daraus eine Suche zu machen, wählen Sie die Suchmaschine:

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

Neue Fenster und Downloads #

Ein Link „in neuem Tab öffnen“ oder ein nach einem Klick geöffnetes Anmeldefenster wird in der Ansicht angezeigt, und ue_new_window teilt es Ihnen mit. Ein Download läuft wie in Edge weiter, und ue_download_starting nennt Ihnen Adresse und Datei. Beide werden zu einer Rückfrage, wenn Sie es verlangen:

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

Ein Anmeldefenster, das mit der öffnenden Seite kommuniziert (eine OAuth- oder Microsoft-Anmeldung im Popup), verliert diese Verbindung, sobald es in der Ansicht angezeigt wird, und die Anmeldung wird nicht abgeschlossen: Öffnen Sie eine solche Anmeldung in der Seite selbst (Umleitungsmodus).

Auf den eigenen Servern bleiben #

Um eine Geschäftsanwendung auf ihren eigenen Servern zu halten, tragen Sie diese in is_allowed_hosts ein: Jede Seite eines anderen Hosts wird abgelehnt, gleich wer sie anfordert — Ihr Code, ein Link, eine in die Leiste getippte Adresse, eine Umleitung des Servers —, und ue_navigation_blocked meldet es. Die angezeigte Seite bleibt.

// 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 wird jedes Mal ausgelöst, wenn die Seite zu einer anderen wechselt — ein Link, ein Formular oder ein Skript der Website, eine vom Benutzer getippte Adresse, Link öffnen, ein neues Fenster —, nie für eine von Ihrem Code gesetzte Adresse und nie für eine Umleitung. Mit ib_veto_navigation wird es zur Rückfrage: false behält die aktuelle Seite. Eine erlaubte Seite wird unter der angeforderten Adresse neu geöffnet; ein per POST gesendetes Formular verliert dabei seine Daten. Vergleichen Sie den Host der Adresse, nie ein Stück der ganzen Adresse: https://evil.test/?next=://intranet.example.com/ enthält den Namen Ihres Servers.

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

Kamera, Mikrofon, Standort #

Wenn eine Website Kamera, Mikrofon, Standort, Benachrichtigungen oder das Lesen der Zwischenablage verlangt, entscheidet ue_permission_requested, und die Standardantwort ist nein: Eine Website schaltet keine Kamera über eine Rückfrage ein, die der Benutzer nicht versteht. Es ist die einzige Frage der Bibliothek, bei der Schweigen Ablehnung bedeutet. Nichts wird gespeichert: Die Frage kommt bei jeder Anforderung wieder.

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

Werte von as_kind: PERMISSION_CAMERA, PERMISSION_MICROPHONE, PERMISSION_GEOLOCATION, PERMISSION_NOTIFICATIONS, PERMISSION_CLIPBOARD, PERMISSION_SENSORS, PERMISSION_DOWNLOADS (mehrere Downloads hintereinander), PERMISSION_FILES, PERMISSION_AUTOPLAY, PERMISSION_FONTS, PERMISSION_MIDI, PERMISSION_WINDOWS, PERMISSION_UNKNOWN.

Warum eine Seite nicht geladen wurde #

al_status von ue_load_failed wird mit den LOADSTATUS_*-Konstanten der Komponente verglichen:

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

Ein Skript in der Seite ausführen #

of_execute_javascript liest oder ändert die angezeigte Seite (ihren Titel, ein Feld, einen Zähler). Es ist durch die Lizenz nicht eingeschränkt, auch nicht auf einer about:blank- oder data:-Seite: Ein Skript in der Seite auszuführen ist die Aufgabe eines Browsers, und die Komponente ist kostenlos.

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

Ladeanzeige #

ue_load_started wird ausgelöst, wenn eine Seite zu laden beginnt — eine Adresse Ihres Codes, ein Link, eine Geste des Benutzers —, und of_is_loading() gibt bis ue_load_completed oder ue_load_failed true zurück: genug, um eine Sanduhr anzuzeigen oder Ihre Stopp-Schaltfläche zu aktivieren.

// 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 vergrößert oder verkleinert die Website (die Adressleiste behält ihre Größe), von 25 bis 500 %. Er liest sich live zurück: Strg+Mausrad in der Website ändert ihn ebenfalls, und Ihr Code sieht es.

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

Das Zertifikat eines Intranets #

Ein Server mit ungültigem Zertifikat (internes oder abgelaufenes Zertifikat) wird abgelehnt, und ue_load_failed liefert einen Status LOADSTATUS_CERT_*. Mit ib_certificate_questions entscheidet ue_certificate_error — und seine Standardantwort ist Nein, wie bei einer Berechtigung: Ein Zertifikat zu akzeptieren ist eine Sicherheitsentscheidung. Eine Antwort gilt nur für die laufende Navigation; nichts wird gespeichert.

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

Nachrichten zwischen der Seite und der Anwendung #

Ein internes Portal kann der Anwendung etwas mitteilen („Vorgang gespeichert“, „Zeile gewählt“): Öffnen Sie die Brücke mit ib_web_messages, und tragen Sie in is_message_origins die Ursprünge ein, die sprechen dürfen. Ohne eingetragenen Ursprung bleibt die Brücke geschlossen: Keine Website im Web kann Ihre Anwendung erreichen. Die Seite sendet einen JSON-Wert, ue_web_message empfängt ihn unverändert; of_post_message antwortet der Seite.

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

Ein Ursprung besteht aus Schema, Host und Port, wenn dieser nicht der Standardport ist (https://portal.example.com:8443); eine Subdomain ist ein anderer Ursprung, und file:/// steht für die Seiten des Arbeitsplatzes. Eine Nachricht über 64 KB wird verworfen. of_post_message an eine Seite eines anderen Ursprungs löst ue_error aus und sendet nichts.

Websites, die die eingebettete Anzeige verweigern #

Manche Websites — Google, die meisten Banken, viele SaaS-Anwendungen — senden Sicherheits-Header, die die Anzeige innerhalb einer anderen Seite verbieten. Die Komponente ist davon nicht betroffen: Sie zeigt eine Website nie in einem Rahmen. Die Seite wird als Hauptdokument geöffnet, genau wie in Ihrem eigenen Browser, und diese Header greifen dann nicht mehr.

Es gibt also nichts einzustellen und keinen Sonderfall, den Sie in Ihrem Code behandeln müssten.

// Eine Website, die die Einbettung verweigert : nichts Besonderes zu tun
uo_browser.ib_address_bar = true
uo_browser.is_address = "https://www.google.com"

Im Gegenzug füllt die Seite die gesamte Komponente unterhalb der Adressleiste: Was Sie darüber zeichnen würden (Banner, gestaltete Überlagerungen), ist während des Surfens nicht sichtbar.

HTML-Inhalt ohne Netzwerk #

of_show_html zeigt eine von Ihrer Anwendung erzeugte HTML-Seite an: die Vorschau eines Schreibens, eines Tickets, einer Rechnung oder eines Berichts, ganz ohne Netzwerkaufruf und ohne temporäre Datei. Die Seite wird für Sie kodiert: Eine Farbe #c00, ein Anker, ein % oder ein Akzent erscheinen wie geschrieben (höchstens 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)

Direkt in is_address gesetzt, wird eine data:text/html,-Adresse nicht kodiert: Ein # schneidet die Seite dort ab (alles Folgende gilt als Anker), und ein % verfälscht sie. Verwenden Sie lieber of_show_html, oder kodieren Sie selbst (# → %23, % → %25).

Eine solche Seite hat keine eigene Adresse: is_address liest sich leer, ebenso die Adressleiste, und ue_load_completed erhält eine leere Adresse. Ohne <title> ist ihr Titel leer. Ein Bild der Festplatte (file:///) wird darin nicht angezeigt: Die Engine lässt eine data:-Seite keine Dateien des Arbeitsplatzes lesen; schreiben Sie das Bild in die Seite (<img src="data:image/png;base64,…">).

Eine lokale Datei öffnet sich genauso mit file:///C:/temp/bericht.html oder einfach über ihren Pfad C:\temp\bericht.html.

Wieder bei null anfangen #

of_reset() leert nicht nur die Seite: Es löscht auch den Navigationsverlauf. Ein Benutzer kann also nicht über die Zurück-Schaltfläche zu einer Seite gelangen, die vom vorherigen Benutzer oder in einem anderen Vorgang aufgerufen wurde. Was die Websites gespeichert haben, bleibt davon unberührt: Cookies, angemeldete Sitzungen, lokaler Speicher, Berechtigungen. An einem gemeinsam genutzten Arbeitsplatz wäre der nächste Benutzer als der vorherige angemeldet — of_clear_browsing_data() löscht das. Die Websites leben in einem eigenen Browserprofil, getrennt von den Komponenten der Anwendung.

// Local variables
string ls_folder_url

// Die Adresse des Vorgangs, den der Benutzer gerade geoeffnet hat
ls_folder_url = "https://intranet.example.com/files/4152"

// Wechsel des Vorgangs : mit einem leeren Browser ohne Verlauf neu beginnen
uo_browser.of_reset()

// Dann der Vorgang, mit seiner Adressleiste
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()

Damit nie etwas auf die Festplatte geschrieben wird, setzen Sie ib_private = true vor der ersten Adresse: Cookies und Speicher verschwinden mit der Ansicht.

Das ist der Reflex, den man haben sollte, sobald ein und dieselbe Komponente Inhalte aus unterschiedlichen Kontexten anzeigt.

Vollständiges Beispiel #

// open-Event des Fensters : Startseite des internen Portals
uo_browser.of_reset()                  // sauber neu beginnen (Verlauf inbegriffen)

// Die Navigationswerkzeuge, dann die Startseite
uo_browser.ib_address_bar  = true      // URL-Feld + Zurueck / Vorwaerts / Neu laden
uo_browser.ib_context_menu = true      // dieselbe Navigation beim Rechtsklick
uo_browser.is_address = "https://intranet.example.com/home"

// ue_load_completed-Event von uo_browser : (string as_url)
uo_status.of_panel(/*key*/ "main").is_text = "Seite geladen: " + as_url

Best Practices #

• Weisen Sie is_address zu, rufen Sie keine Navigationsmethode auf: Es ist die Eigenschaft, die das Öffnen der Seite auslöst.
• Aktivieren Sie ib_address_bar, sobald der Benutzer frei navigieren darf; die Steuerung über Ihre eigenen Schaltflächen bleibt eingeschränkten Abläufen vorbehalten.
• Verlassen Sie sich für den Zustand Ihrer Schaltflächen auf of_can_go_back() / of_can_go_forward(), statt die Seiten selbst zu zählen: Weiterleitungen würden Ihre Zählung verfälschen.
• Für Websites, die die eingebettete Anzeige verweigern, ist nichts vorzusehen: Die Seite wird stets als Hauptdokument geöffnet, diese Header greifen nicht.
• Rufen Sie of_reset() beim Kontextwechsel auf: Nur so ist gewährleistet, dass keine vorherige Seite über die Zurück-Schaltfläche erreichbar ist. Wechselt der Benutzer des Arbeitsplatzes, ergänzen Sie of_clear_browsing_data(): Ohne diesen Aufruf bleiben Cookies und Sitzungen der Websites erhalten.
• Die Komponente benötigt die auf dem Rechner installierte Web-Runtime: Behandeln Sie ue_runtime_missing wie bei jeder anderen Komponente (Installation).
• Eine Website darf ohne Geste des Benutzers Ton abspielen: die automatische Wiedergabe mit Ton ist in der gesamten WebView2-Umgebung der Anwendung erlaubt (Video- und Tonplayer brauchen sie, eine verborgene Seite hat keine Geste). Eine Seite, die beim Öffnen ein Video mit Ton startet, spielt es ab; stört das, öffnen Sie Adressen, die Sie kennen.
• Um die Anwendung auf ihren eigenen Servern zu halten, tragen Sie diese in is_allowed_hosts ein: Es stoppt auch Umleitungen, die ue_navigating nicht sieht.

Vom gemeinsamen Sockel geerbt #

Diese Mitglieder gibt es bei jeder visuellen Komponente — sie sind nicht dieser eigen. Sie werden einmal in den übergreifenden Kapiteln beschrieben; diese Tabelle sagt nur, wo man sie liest.

Zwei Helfer werden nicht geerbt: of_icon und of_escape_markup liegen auf n_pbt_utils. Deklarieren Sie eines — n_pbt_utils lnv_utils, nichts zu erzeugen — und rufen Sie sie darauf auf.

← Komponentenreferenz · Inhalt des Handbuchs