webbrowser — u_pbt_webbrowser #

← Referência dos componentes · Índice do guia

Navegador web integrado na janela: apresentação de uma página, barra de endereço, histórico Anterior / Seguinte, menu de contexto de navegação.

▶ Ver ao vivo — Aplicação de demonstração, mosaico Web browser: a pré-visualização, o código que o produz e esta página, lado a lado.

Em resumo #

Início rápido #

// event open da janela
uo_browser.ib_address_bar = true    // barra de endereco + botoes de navegacao
uo_browser.is_address = "https://pt.wikipedia.org/wiki/PowerBuilder"

Atribuir is_address é o ato de navegação: cada atribuição abre a página pedida. Um endereço sem protocolo ("exemplo.com") recebe automaticamente https://. Um caminho de disco (C:\pasta\pagina.html, \\servidor\partilha\pagina.html) torna-se um endereço file:///. Palavras que não são um endereço ("fatura 2026") vão para o motor de pesquisa de is_search_url; sem motor, são recusadas e ue_error indica-o. Um nome de servidor de uma só palavra seguido de /, ? ou # (office/, intranet/inicio) é um endereço, tal como um endereço IPv6 entre parênteses retos ([::1]/x); a palavra sozinha (intranet) continua a ser texto livre. Um servidor sem HTTPS escreve-se com http:// explícito.

Propriedades #

Métodos #

Eventos #

Navegar #

A barra de endereço integrada #

É a solução mais rápida: uma propriedade e o utilizador dispõe de um campo URL e dos botões Anterior / Seguinte / Recarregar, com o tema do resto da aplicação.

// A barra de enderecos, depois a pagina a abrir
uo_browser.ib_address_bar = true
uo_browser.is_address = "https://pt.wikipedia.org/wiki/PowerBuilder"

Os botões ficam inativos automaticamente quando não há para onde ir. No campo de endereço, F5 (ou Ctrl+R) recarrega, Alt+← / Alt+→ recuam e avançam (invertidos na escrita da direita para a esquerda), Esc repõe o endereço atual depois de uma escrita abandonada, e o primeiro clique seleciona todo o endereço. Um texto que não é um endereço é assinalado: o campo fica com uma borda vermelha, com uma dica, até à tecla seguinte. Enter num campo vazio não faz nada: a página mantém-se.

Botões próprios #

Se preferir comandar a navegação a partir de uma barra de ferramentas própria, deve ocultar-se a barra integrada e utilizar os métodos:

// Botoes Anterior / Seguinte da sua janela
uo_browser.of_go_back()
uo_browser.of_go_forward()

// event ue_load_completed de uo_browser : (string as_url)
// Atualizar o estado dos seus botoes apos 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()

// E refletir o endereco real (incluindo redirecionamentos)
sle_url.text = as_url

O menu de contexto de navegação #

ib_context_menu acrescenta ao clique direito um pequeno menu Anterior / Seguinte / Recarregar, com tema e desenhado pela aplicação. Segue o que está sob o rato: Copiar sobre um texto selecionado, Abrir link e Copiar endereço do link sobre um link, Copiar imagem sobre uma imagem. Aberto pelo teclado (Shift+F10, tecla Menu), aparece sobre o elemento. Partilha exatamente o mesmo histórico que a barra de endereço: ambos permanecem, por isso, sempre coerentes.

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

Parar um carregamento #

// Botao Parar : interrompe uma pagina que demora
uo_browser.of_stop()

Palavras em vez de um endereço #

Por omissão, um texto que não é um endereço é recusado (ue_error), sem reter nada: o endereço seguinte carrega normalmente. Para o transformar numa pesquisa, escolha o 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"

Novas janelas e transferências #

Uma ligação «abrir num novo separador» ou uma janela de início de sessão aberta após um clique aparece na vista, e ue_new_window indica-o. Uma transferência continua como no Edge, e ue_download_starting dá-lhe o endereço e o ficheiro. Ambos se tornam uma pergunta quando o pede:

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

Uma janela de início de sessão que dialoga com a página que a abriu (um início de sessão OAuth ou Microsoft numa janela pop-up) perde essa ligação quando apresentada na vista, e o início de sessão não termina: abra esse início de sessão na própria página (modo de redirecionamento).

Ficar nos seus próprios servidores #

Para manter uma aplicação de gestão nos seus próprios servidores, indique-os em is_allowed_hosts: qualquer página de outro anfitrião é recusada, seja quem for que a peça — o seu código, uma ligação, um endereço escrito na barra, um redirecionamento do servidor —, e ue_navigation_blocked indica-o. A página apresentada mantém-se.

// 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 é lançado sempre que a página passa para outra — um link, um formulário ou um script do site, um endereço escrito pelo utilizador, Abrir link, uma nova janela —, nunca para um endereço definido pelo seu código nem para um redirecionamento. Com ib_veto_navigation é uma pergunta: devolver false mantém a página atual. Uma página autorizada é reaberta no endereço pedido; um formulário enviado por POST perde os seus dados. Compare o anfitrião do endereço, nunca um pedaço do endereço inteiro: https://evil.test/?next=://intranet.example.com/ contém o nome do seu servidor.

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

Câmara, microfone, localização #

Quando um site pede a câmara, o microfone, a localização, as notificações ou a leitura da área de transferência, é ue_permission_requested que decide, e a resposta por omissão é não: um site não liga uma câmara através de um aviso que o utilizador não compreende. É a única pergunta da biblioteca em que o silêncio vale recusa. Nada é memorizado: a pergunta volta a cada pedido.

// 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 (várias transferências seguidas), PERMISSION_FILES, PERMISSION_AUTOPLAY, PERMISSION_FONTS, PERMISSION_MIDI, PERMISSION_WINDOWS, PERMISSION_UNKNOWN.

Porque é que uma página não carregou #

al_status de ue_load_failed compara-se com as constantes LOADSTATUS_* do 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

Executar um script na página #

of_execute_javascript lê ou altera a página apresentada (o título, um campo, um contador). Não é limitado pela licença, mesmo numa página about:blank ou data:: executar um script na página é o trabalho de um navegador, e o 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")

Indicador de carregamento #

ue_load_started é lançado quando uma página começa a carregar — um endereço do seu código, uma ligação, um gesto do utilizador —, e of_is_loading() devolve true até ue_load_completed ou ue_load_failed: o suficiente para mostrar uma ampulheta ou ativar o seu botão Parar.

// 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 amplia ou reduz o site (a barra de endereço mantém o seu tamanho), de 25 a 500 %. Relê-se em direto: Ctrl+roda do rato no site também o altera, e o seu código vê-o.

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

O certificado de uma intranet #

Um servidor cujo certificado não é válido (certificado interno ou expirado) é recusado, e ue_load_failed dá um estado LOADSTATUS_CERT_*. Com ib_certificate_questions, decide ue_certificate_error — e a sua resposta predefinida é não, como para uma permissão: aceitar um certificado é uma decisão de segurança. Uma resposta só vale para a navegação em curso; nada é memorizado.

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

Mensagens entre a página e a aplicação #

Um portal interno pode avisar a aplicação («dossiê guardado», «linha escolhida»): abra a ponte com ib_web_messages, e indique em is_message_origins as origens autorizadas a falar. Sem origem na lista, a ponte fica fechada: nenhum site da Web consegue chegar à sua aplicação. A página envia um valor JSON, ue_web_message recebe-o tal como está; of_post_message responde à página.

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

Uma origem escreve-se com esquema, anfitrião e porta se não for a predefinida (https://portal.example.com:8443); um subdomínio é outra origem, e file:/// designa as páginas do posto. Uma mensagem de mais de 64 KB é descartada. of_post_message para uma página de outra origem lança ue_error e não envia nada.

Sites que recusam a apresentação integrada #

Alguns sites — Google, a maioria dos bancos, muitas aplicações SaaS — enviam cabeçalhos de segurança que proíbem a sua apresentação dentro de outra página. O componente não é afetado: nunca apresenta um site numa moldura. A página é aberta como documento principal, exatamente como faz o seu próprio navegador, e esses cabeçalhos deixam de se aplicar.

Não há, portanto, nada a definir nem qualquer caso particular a tratar no seu código.

// Um site que recusa ser integrado numa pagina : nada de especial a fazer
uo_browser.ib_address_bar = true
uo_browser.is_address = "https://www.google.com"

Em contrapartida, a página ocupa toda a superfície do componente sob a barra de endereço: aquilo que desenhasse por cima (faixas, sobreposições com tema) não é visível durante a navegação.

Conteúdo HTML sem rede #

of_show_html apresenta uma página HTML construída pela aplicação: a pré-visualização de uma carta, de um ticket, de uma fatura ou de um relatório, sem qualquer chamada de rede nem ficheiro temporário. A página é codificada por si: uma cor #c00, uma âncora, um % ou um acento aparecem tal como escritos (no máximo 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)

Definido diretamente em is_address, um endereço data:text/html, não é codificado: um # corta ali a página (tudo o que se segue passa por uma âncora) e um % baralha-a. Prefira of_show_html, ou codifique por si (# → %23, % → %25).

Uma página assim não tem endereço próprio: is_address relê-se vazio, tal como a barra de endereço, e ue_load_completed recebe um endereço vazio. Sem <title>, o seu título está vazio. Uma imagem do disco (file:///) não é mostrada nela: o motor não deixa uma página data: ler os ficheiros do posto; escreva a imagem na página (<img src="data:image/png;base64,…">).

Um ficheiro local abre-se da mesma forma com file:///C:/temp/relatorio.html, ou simplesmente com o seu caminho C:\temp\relatorio.html.

Recomeçar do zero #

of_reset() não se limita a esvaziar a página: apaga também o histórico de navegação. Assim, um utilizador não pode regressar, através do botão Anterior, a uma página consultada pelo utilizador anterior ou noutro dossiê. Não toca no que os sites guardaram: cookies, sessões iniciadas, armazenamento local, permissões. Num posto partilhado, o utilizador seguinte chegaria com a sessão do anterior — é of_clear_browsing_data() que a apaga. Os sites vivem num perfil de navegação próprio, separado dos componentes da aplicação.

// Local variables
string ls_folder_url

// O endereco do dossie que o utilizador acabou de abrir
ls_folder_url = "https://intranet.example.com/files/4152"

// Mudanca de dossie : recomeca-se com um navegador virgem, sem historico
uo_browser.of_reset()

// Depois o dossie, com a sua barra de enderecos
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 nada seja alguma vez escrito no disco, defina ib_private = true antes do primeiro endereço: cookies e armazenamento desaparecem com a vista.

É o reflexo a ter sempre que um mesmo componente serve para apresentar conteúdos de contextos diferentes.

Exemplo completo #

// event open da janela : pagina inicial do portal interno
uo_browser.of_reset()                  // recomecar limpo (incluindo o historico)

// As ferramentas de navegacao, depois a pagina inicial
uo_browser.ib_address_bar  = true      // campo URL + Anterior / Seguinte / Recarregar
uo_browser.ib_context_menu = true      // mesma navegacao com o clique direito
uo_browser.is_address = "https://intranet.empresa.pt/inicio"

// event ue_load_completed de uo_browser : (string as_url)
uo_status.of_panel(/*key*/ "main").is_text = "Página carregada: " + as_url

Boas práticas #

• Atribuir is_address, sem chamar qualquer método de navegação: é a propriedade que aciona a abertura da página.
• Deve ativar-se ib_address_bar sempre que o utilizador possa navegar livremente; o comando através de botões próprios fica reservado aos percursos condicionados.
• Convém confiar em of_can_go_back() / of_can_go_forward() para o estado dos botões, em vez de contar as páginas manualmente: os redirecionamentos falseariam essa contagem.
• Nada a prever para os sites que recusam a apresentação integrada: a página é sempre aberta como documento principal, esses cabeçalhos não se aplicam.
• Deve chamar-se of_reset() na mudança de contexto: é a única forma de garantir que nenhuma página anterior fica acessível através do botão Anterior. Quando o utilizador do posto muda, acrescente of_clear_browsing_data(): sem ele, os cookies e sessões dos sites mantêm-se.
• O componente necessita do runtime web instalado no posto: o event ue_runtime_missing deve ser tratado como em qualquer outro componente (Instalação).
• Um site pode tocar som sem um gesto do utilizador: a reprodução automática com som é permitida em todo o ambiente WebView2 da aplicação (o leitor de vídeo e o leitor de sons precisam dela, uma página oculta não tem gestos). Uma página que lança um vídeo com som ao abrir vai tocá-lo; se isso incomodar, abra endereços que conhece.
• Para manter a aplicação nos seus próprios servidores, indique-os em is_allowed_hosts: também trava os redirecionamentos, que ue_navigating não vê.

Herdado da base comum #

Estes membros existem em todos os componentes visuais — não são próprios deste. São detalhados uma só vez, nos capítulos transversais; esta tabela apenas diz onde os ler.

Duas ajudas não são herdadas: of_icon e of_escape_markup vivem em n_pbt_utils. Declare um — n_pbt_utils lnv_utils, nada a criar — e chame-as nele.

← Referência dos componentes · Índice do guia