Nota
O acesso a esta página requer autorização. Podes tentar iniciar sessão ou mudar de diretório.
O acesso a esta página requer autorização. Podes tentar mudar de diretório.
Um controlo de visualização da Web incorpora uma visualização na sua aplicação que processa conteúdo da Web usando o motor de renderização legado do Microsoft Edge. Os hiperlinks também podem aparecer e funcionar em um controle de exibição da Web.
Importante
O WebView2 controlo está disponível como parte do WinUI no Windows App SDK.
WebView2 usa o Microsoft Edge (Chromium) como mecanismo de renderização para exibir conteúdo da Web em aplicativos. Para obter mais informações, consulte Introdução ao Microsoft Edge WebView2, Introdução ao uso de WebView2 em WinUI 3 (Prévia), e WebView2 na referência da API WinUI.
Será este o controlo correto?
Use um controle de exibição da Web para exibir conteúdo HTML ricamente formatado de um servidor Web remoto, código gerado dinamicamente ou arquivos de conteúdo em seu pacote de aplicativo. O conteúdo rico também pode conter código de script e comunicar-se entre o script e o código da sua aplicação.
Recommendations
- Verifique se o site carregado está formatado corretamente para o dispositivo e usa cores, tipografia e navegação consistentes com o restante do aplicativo.
- Os campos de entrada devem ser adequadamente dimensionados. Os usuários podem não perceber que podem aumentar o zoom para inserir texto.
- Se uma vista Web não se parecer com o resto da sua aplicação, considere controlos alternativos ou formas de realizar tarefas relevantes. Se a sua visualização da Web corresponder ao resto do seu aplicativo, os usuários verão tudo como uma experiência perfeita.
Criar uma vista Web
- APIs UWP:classe WebView
- Abra o aplicativo WinUI 2 Gallery e veja o WebView em ação. O aplicativo WinUI 2 Gallery inclui exemplos interativos da maioria dos controles, recursos e funcionalidades do WinUI 2. Obtenha o aplicativo da Microsoft Store ou obtenha o código-fonte no GitHub.
Modificar a aparência de uma exibição da Web
WebView não é uma subclasse Control , portanto, não tem um modelo de controle. No entanto, você pode definir várias propriedades para controlar alguns aspetos visuais da exibição da Web.
- Para restringir a área de exibição, defina as propriedades Width e Height .
- Para converter, dimensionar, inclinar e girar uma visualização web, use a propriedade RenderTransform.
- Para controlar a opacidade da exibição da Web, defina a propriedade Opacity .
- Para especificar uma cor a ser usada como plano de fundo da página da Web quando o conteúdo HTML não especificar uma cor, defina a propriedade DefaultBackgroundColor .
Obter o título da página Web
Você pode obter o título do documento HTML exibido atualmente na visualização da Web usando a propriedade DocumentTitle.
Eventos de entrada e ordem de tabulação
Embora o WebView não seja uma subclasse Control, ele receberá o foco de entrada do teclado e participará da sequência de guias. Ele fornece um método Focus e GotFocus e LostFocus eventos, mas não tem propriedades relacionadas a guias. Sua posição na sequência de tabulação é a mesma que sua posição na ordem do documento XAML. A sequência de tabulação inclui todos os elementos no conteúdo da visualização web que podem receber foco do cursor.
Conforme indicado na tabela Eventos na página de classe
Navegar para o conteúdo
A vista da Web oferece várias APIs para navegação básica: GoBack, GoForward, Stop, Refresh, CanGoBacke CanGoForward. Você pode usá-los para adicionar recursos típicos de navegação na Web ao seu aplicativo.
Para definir o conteúdo inicial da exibição da Web, defina a propriedade Source em XAML. O analisador XAML converte automaticamente a string em um Uri.
<!-- Source file is on the web. -->
<WebView x:Name="webView1" Source="http://www.contoso.com"/>
<!-- Source file is in local storage. -->
<WebView x:Name="webView2" Source="ms-appdata:///local/intro/welcome.html"/>
<!-- Source file is in the app package. -->
<WebView x:Name="webView3" Source="ms-appx-web:///help/about.html"/>
A propriedade Source pode ser definida em código, mas em vez de fazer isso, você normalmente usa um dos métodos Navigate para carregar conteúdo no código.
Para carregar conteúdo da Web, use o método Navigate com um Uri que usa o esquema http ou https.
webView1.Navigate(new Uri("http://www.contoso.com"));
Para navegar até um URI com uma solicitação POST e cabeçalhos HTTP, use o método NavigateWithHttpRequestMessage . Este método suporta apenas HttpMethod.Post e HttpMethod.Get para o valor da propriedade HttpRequestMessage.Method.
Para carregar conteúdo não compactado e não criptografado da LocalFolder do seu aplicativo ou do armazenamento de dados TemporaryFolder, utilize o método Navigate com um Uri que utiliza o esquema ms-appdata. O suporte de exibição da Web para esse esquema requer que você coloque seu conteúdo em uma subpasta sob a pasta local ou temporária. Isso permite a navegação para URIs como ms-appdata:///local/folder/file.html e ms-appdata:///temp/folder/file.html . (Para carregar ficheiros comprimidos ou encriptados, consulte NavigateToLocalStreamUri.)
Cada uma dessas subpastas de primeiro nível está isolada do conteúdo das outras subpastas de primeiro nível. Por exemplo, você pode navegar até ms-appdata:///temp/folder1/file.html, mas não pode ter um link nesse arquivo para ms-appdata:///temp/folder2/file.html. No entanto, você ainda pode vincular ao conteúdo HTML no pacote do aplicativo usando o esquema ms-appx-webe ao conteúdo da Web usando os esquemas http e https URI.
webView1.Navigate(new Uri("ms-appdata:///local/intro/welcome.html"));
Para carregar conteúdo do pacote do seu aplicativo, use o método Navigate com um Uri que usa o esquema ms-appx-web.
webView1.Navigate(new Uri("ms-appx-web:///help/about.html"));
Você pode carregar conteúdo local por meio de um resolvedor personalizado usando o método NavigateToLocalStreamUri. Isso permite cenários avançados, como baixar e armazenar em cache conteúdo baseado na Web para uso offline ou extrair conteúdo de um arquivo compactado.
Responder a eventos de navegação
O controle de exibição da Web fornece vários eventos que você pode usar para responder a estados de navegação e carregamento de conteúdo. Os eventos ocorrem na seguinte ordem para o conteúdo da visualização raiz da web: NavigationStarting, ContentLoading, DOMContentLoaded, NavigationCompleted
NavigationStarting - Ocorre antes de a vista Web navegar para um novo conteúdo. Você pode cancelar a navegação em um manipulador para esse evento definindo a propriedade WebViewNavigationStartingEventArgs.Cancel como true.
webView1.NavigationStarting += webView1_NavigationStarting;
private void webView1_NavigationStarting(object sender, WebViewNavigationStartingEventArgs args)
{
// Cancel navigation if URL is not allowed. (Implementation of IsAllowedUri not shown.)
if (!IsAllowedUri(args.Uri))
args.Cancel = true;
}
ContentLoading - Ocorre quando a visualização da web começa a carregar novo conteúdo.
webView1.ContentLoading += webView1_ContentLoading;
private void webView1_ContentLoading(WebView sender, WebViewContentLoadingEventArgs args)
{
// Show status.
if (args.Uri != null)
{
statusTextBlock.Text = "Loading content for " + args.Uri.ToString();
}
}
DOMContentLoaded - Ocorre quando o visualizador da Web terminou de analisar o conteúdo HTML atual.
webView1.DOMContentLoaded += webView1_DOMContentLoaded;
private void webView1_DOMContentLoaded(WebView sender, WebViewDOMContentLoadedEventArgs args)
{
// Show status.
if (args.Uri != null)
{
statusTextBlock.Text = "Content for " + args.Uri.ToString() + " has finished loading";
}
}
NavigationCompleted - Ocorre quando a visualização da Web terminou de carregar o conteúdo atual ou se a navegação falhou. Para determinar se a navegação falhou, verifique as propriedades IsSuccess e WebErrorStatus da classe WebViewNavigationCompletedEventArgs.
webView1.NavigationCompleted += webView1_NavigationCompleted;
private void webView1_NavigationCompleted(WebView sender, WebViewNavigationCompletedEventArgs args)
{
if (args.IsSuccess == true)
{
statusTextBlock.Text = "Navigation to " + args.Uri.ToString() + " completed successfully.";
}
else
{
statusTextBlock.Text = "Navigation to: " + args.Uri.ToString() +
" failed with error " + args.WebErrorStatus.ToString();
}
}
Eventos semelhantes ocorrem na mesma ordem para cada iframe no conteúdo da vista da Web:
- FrameNavigationStarting - Ocorre antes de um frame no visualizador web navegar para um novo conteúdo.
- FrameContentLoading - Ocorre quando um quadro na exibição da Web começou a carregar novo conteúdo.
- FrameDOMContentLoaded - Ocorre quando um quadro na visualização da Web terminou de analisar seu conteúdo HTML atual.
- FrameNavigationCompleted - Ocorre quando um quadro na visualização da Web terminou de carregar o seu conteúdo.
Resposta a potenciais problemas
Você pode responder a possíveis problemas com o conteúdo, como scripts de longa execução, conteúdo que a exibição da Web não pode carregar e avisos de conteúdo não seguro.
Seu aplicativo pode parecer não responder enquanto os scripts estão em execução. O evento LongRunningScriptDetected ocorre periodicamente enquanto a visualização da Web executa JavaScript e fornece uma oportunidade para interromper o script. Para determinar há quanto tempo o script está sendo executado, verifique a propriedade ExecutionTime do WebViewLongRunningScriptDetectedEventArgs. Para interromper o script, defina o evento args propriedade StopPageScriptExecution como true. O script interrompido não será executado novamente, a menos que seja recarregado durante uma navegação subsequente na visualização da Web.
O controle de exibição da Web não pode hospedar tipos de arquivo arbitrários. Quando é feita uma tentativa de carregar conteúdo que a vista da Web não pode hospedar, ocorre o evento UnviewableContentIdentified . Você pode manipular esse evento e notificar o usuário ou usar a classe Launcher para redirecionar o arquivo para um navegador externo ou outro aplicativo.
Da mesma forma, o evento UnsupportedUriSchemeIdentified ocorre quando um esquema de URI sem suporte é invocado no conteúdo da Web, como fbconnect:// ou mailto://. Você pode manipular esse evento para fornecer um comportamento personalizado em vez de permitir que o iniciador de sistema padrão inicie o URI.
O evento UnsafeContentWarningDisplayingevent ocorre quando a janela de visualização da web mostra uma página de aviso para conteúdo que foi relatado como não seguro pelo Filtro SmartScreen. Se o utilizador optar por continuar a navegação, a navegação seguinte para a página não exibirá o aviso nem acionará o evento.
Tratamento de casos especiais para conteúdo de visualização Web
Você pode usar a propriedade ContainsFullScreenElement e o evento ContainsFullScreenElementChanged para detetar, reagir e permitir experiências em ecrã inteiro em conteúdo da Web, como reprodução de vídeo em ecrã inteiro. Por exemplo, você pode usar o evento ContainsFullScreenElementChanged para redimensionar a exibição da Web para ocupar a totalidade da exibição do seu aplicativo ou, como o exemplo a seguir ilustra, colocar um aplicativo em janela no modo de tela inteira quando uma experiência da Web em tela cheia for desejada.
// Assume webView is defined in XAML
webView.ContainsFullScreenElementChanged += webView_ContainsFullScreenElementChanged;
private void webView_ContainsFullScreenElementChanged(WebView sender, object args)
{
var applicationView = ApplicationView.GetForCurrentView();
if (sender.ContainsFullScreenElement)
{
applicationView.TryEnterFullScreenMode();
}
else if (applicationView.IsFullScreenMode)
{
applicationView.ExitFullScreenMode();
}
}
Você pode usar o evento NewWindowRequested para lidar com casos em que o conteúdo da Web hospedado solicita que uma nova janela seja exibida, como uma janela pop-up. Você pode usar outro controle WebView para exibir o conteúdo da janela solicitada.
Use o evento PermissionRequested para habilitar funcionalidades da web que requerem capacidades especiais. Atualmente, eles incluem geolocalização, armazenamento IndexedDB e áudio e vídeo do usuário (por exemplo, de um microfone ou webcam). Se o seu aplicativo acessar o local do usuário ou a mídia do usuário, ainda será necessário declarar esse recurso no manifesto do aplicativo. Por exemplo, um aplicativo que usa geolocalização precisa das seguintes declarações de capacidade no mínimo em Package.appxmanifest:
<Capabilities>
<Capability Name="internetClient" />
<DeviceCapability Name="location" />
</Capabilities>
Além do aplicativo manipular o evento PermissionRequested , o usuário terá que aprovar caixas de diálogo padrão do sistema para aplicativos que solicitam recursos de localização ou mídia para que esses recursos sejam habilitados.
Aqui está um exemplo de como um aplicativo habilitaria a geolocalização em um mapa do Bing:
// Assume webView is defined in XAML
webView.PermissionRequested += webView_PermissionRequested;
private void webView_PermissionRequested(WebView sender, WebViewPermissionRequestedEventArgs args)
{
if (args.PermissionRequest.PermissionType == WebViewPermissionType.Geolocation &&
args.PermissionRequest.Uri.Host == "www.bing.com")
{
args.PermissionRequest.Allow();
}
}
Se a sua aplicação exigir entrada do utilizador ou outras operações assíncronas para responder a um pedido de permissão, utilize o método Defer de WebViewPermissionRequest para criar um WebViewDeferredPermissionRequest que possa ser acionado posteriormente. Consulte WebViewPermissionRequest.Defer.
Se os usuários precisarem fazer logout com segurança de um site hospedado em uma exibição da Web, ou em outros casos em que a segurança for importante, chame o método estático ClearTemporaryWebDataAsync para limpar todo o conteúdo armazenado em cache localmente de uma sessão de exibição da Web. Isso impede que usuários mal-intencionados acessem dados confidenciais.
Interagindo com o conteúdo da visualização web
Você pode interagir com o conteúdo da exibição da Web usando o método InvokeScriptAsync para invocar ou injetar script no conteúdo da exibição da Web, e o evento ScriptNotify para obter informações de volta desse mesmo conteúdo.
Para invocar JavaScript dentro do conteúdo da exibição da Web, use o método InvokeScriptAsync . O script invocado pode retornar apenas valores de cadeia de caracteres.
Por exemplo, se o conteúdo de uma exibição da Web nomeada webView1 contiver uma função chamada setDate que usa 3 parâmetros, você poderá invocá-la assim.
string[] args = {"January", "1", "2000"};
string returnValue = await webView1.InvokeScriptAsync("setDate", args);
Você pode usar InvokeScriptAsync com a função eval do JavaScript para injetar conteúdo na página da Web.
Aqui, o texto de uma caixa de texto XAML (nameTextBox.Text) é gravado em uma div em uma página HTML hospedada em webView1.
private async void Button_Click(object sender, RoutedEventArgs e)
{
string functionString = String.Format("document.getElementById('nameDiv').innerText = 'Hello, {0}';", nameTextBox.Text);
await webView1.InvokeScriptAsync("eval", new string[] { functionString });
}
Os scripts no conteúdo da exibição da Web podem usar window.external.notify com um parâmetro string para enviar informações de volta ao seu aplicativo. Para receber essas mensagens, manipule o evento ScriptNotify.
Para permitir que uma página Web externa acione o evento ScriptNotify ao chamar window.external.notify, deverá incluir o URI da página na seção ApplicationContentUriRules do manifesto da aplicação. (Você pode fazer isso no Microsoft Visual Studio na guia URIs de conteúdo do designer Package.appxmanifest.) Os URIs nesta lista devem usar HTTPS e podem conter curingas de subdomínio (por exemplo, https://*.microsoft.com), mas não podem conter curingas de domínio (por exemplo, https://*.com e https://*.*). O requisito de manifesto não se aplica ao conteúdo originado do pacote do aplicativo, que usa um URI ms-local-stream:// ou que é carregado usando NavigateToString.
Aceder ao Windows Runtime numa visualização web
Você pode usar o método AddWebAllowedObject para injetar uma instância de uma classe nativa de um componente do Tempo de Execução do Windows no contexto JavaScript da exibição da Web. Isso permite acesso total aos métodos, propriedades e eventos nativos desse objeto no conteúdo JavaScript dessa exibição da Web. A classe deve ser decorada com o atributo AllowForWeb .
Por exemplo, este código injeta uma instância de MyClass importada de um componente do Tempo de Execução do Windows numa vista web.
private void webView_NavigationStarting(WebView sender, WebViewNavigationStartingEventArgs args)
{
if (args.Uri.Host == "www.contoso.com")
{
webView.AddWebAllowedObject("nativeObject", new MyClass());
}
}
Para obter mais informações, consulte WebView.AddWebAllowedObject.
Além disso, o conteúdo JavaScript confiável em uma visualização da web pode ter permissão para acessar diretamente as APIs do Runtime do Windows. Isso fornece recursos nativos poderosos para aplicações web hospedadas em uma visualização web. Para habilitar este recurso, o URI para conteúdo confiável deve ser adicionado à lista de permitidos no ApplicationContentUriRules da aplicação em Package.appxmanifest, com WindowsRuntimeAccess definido especificamente como "all".
Este exemplo mostra uma seção do manifesto do aplicativo. Aqui, um URI local recebe acesso ao Windows Runtime.
<Applications>
<Application Id="App"
...
<uap:ApplicationContentUriRules>
<uap:Rule Match="ms-appx-web:///Web/App.html" WindowsRuntimeAccess="all" Type="include"/>
</uap:ApplicationContentUriRules>
</Application>
</Applications>
Opções para hospedagem de conteúdo web
Você pode usar a propriedade WebView.Settings (do tipo WebViewSettings) para controlar se JavaScript e IndexedDB estão habilitados. Por exemplo, se você usar uma exibição da Web para exibir conteúdo estritamente estático, convém desativar o JavaScript para obter o melhor desempenho.
Capturando conteúdo de exibição da Web
Para ativar a partilha de conteúdo da vista web com outros aplicativos, utilize o método CaptureSelectedContentToDataPackageAsync, que retorna o conteúdo selecionado como um DataPackage. Esse método é assíncrono, portanto, você deve usar um adiamento para impedir que seu manipulador de eventos DataRequested retorne antes que a chamada assíncrona seja concluída.
Para obter uma imagem de visualização do conteúdo atual da vista da web, use o método CapturePreviewToStreamAsync. Esse método cria uma imagem do conteúdo atual e a grava no fluxo especificado.
Comportamento de threads
Por padrão, o conteúdo da visualização web é hospedado no thread da interface do utilizador em dispositivos da família de dispositivos de área de trabalho e fora do thread da interface do utilizador em todos os outros dispositivos. Você pode usar a propriedade estática WebView.DefaultExecutionMode para consultar o comportamento padrão de threading para o cliente atual. Se necessário, você pode usar o construtor WebView(WebViewExecutionMode) para substituir esse comportamento.
Observação Pode haver problemas de desempenho ao hospedar conteúdo no thread da interface do usuário em dispositivos móveis, portanto, certifique-se de testar em todos os dispositivos de destino ao alterar DefaultExecutionMode.
Uma exibição da Web que hospeda conteúdo fora do thread da interface do usuário não é compatível com controles pai que exigem gestos para se propagar do controle de exibição da Web para o pai, como FlipView, ScrollViewere outros controles relacionados. Esses controles não poderão receber gestos iniciados na exibição da Web fora do thread. Além disso, a impressão de conteúdo da Web off-thread não é suportada diretamente – você deve imprimir um elemento com WebViewBrush preenchimento.
Obter o código de exemplo
- Exemplo da Galeria WinUI 2 - Veja todos os controlos XAML num formato interativo.