Introdução ao WebView2 em aplicações WinUI 3 (SDK do Aplicativo Windows)
Este artigo aborda como configurar as suas ferramentas de desenvolvimento e criar uma aplicação WebView2 inicial para o WinUI 3 (SDK do Aplicativo Windows) e saber mais sobre os conceitos do WebView2 ao longo do percurso. Primeiro, utilize o modelo de projeto Do Visual Studio Em Branco, Empacotado (WinUI 3 no Ambiente de Trabalho), que utiliza o WindowsAppSDK, que inclui o SDK WebView2. Em seguida, adicione um controlo WebView2, uma Barra de endereço e um botão Ir e lógica de URL para permitir apenas navegar para URLs HTTPS.
Neste tutorial, vai fazer o seguinte:
Configure o ambiente de desenvolvimento.
Utilize o modelo de projeto Do Visual Studio Em Branco, Empacotado (WinUI 3 no Ambiente de Trabalho) para criar um projeto WinUI 3 em branco, que define uma aplicação que contém um botão.
Adicione um controlo WebView2 em vez do botão e navegue inicialmente para a home page da Microsoft. O WebView2 é suportado porque o modelo de projeto utiliza o pacote NuGet Microsoft.WindowsAppSDK , que inclui o SDK WebView2.
Adicione uma Barra de endereço como um controlo de caixa de texto e, em seguida, utilize a cadeia HTTPS introduzida para navegar para uma nova página Web:
Insira JavaScript no controlo WebView2 para apresentar um alerta de aviso (caixa de diálogo) quando o utilizador tentar navegar para um URL que tenha apenas um
http://
prefixo em vez dehttps://
:
Projeto concluído
Está disponível uma versão completa deste projeto de tutorial no repositório WebView2Samples :
- Nome de exemplo: WinUI3GetStarted
- Diretório de repositório: WinUI3_GettingStarted
- Ficheiro de solução: WinUI3GetStarted.sln
Passo 1: Instalar o Visual Studio 2022 mais recente
Certifique-se de que o Visual Studio 2022 está instalado e atualizado.
Para instalar o Visual Studio 2022 mais recente:
Aceda ao Visual Studio: IDE e Code Editor para Programadores de Software e Teams e, em seguida, na secção Visual Studio 2022, clique no botão Transferir e, em seguida, selecione Comunidade 2022 ou outra versão.
No pop-up Transferências , no canto superior direito do Microsoft Edge,
VisualStudioSetup.exe
encontra-se listado. Clique em Abrir ficheiro.Instalador do Visual Studio é aberto.
Siga as instruções e aceite as predefinições. Irá instalar ou atualizar uma carga de trabalho e um componente de uma carga de trabalho no próximo passo.
Passo 2: Instalar a SDK do Aplicativo Windows mais recente
Certifique-se de que a SDK do Aplicativo Windows mais recente está instalada no Visual Studio 2022. O SDK do Aplicativo Windows inclui modelos de projeto do Visual Studio e inclui o SDK WebView2. Estes modelos de projeto incluem o modelo de projeto Aplicação em Branco, Empacotado (WinUI 3 no Ambiente de Trabalho), que utiliza o WindowsAppSDK, incluindo o SDK WebView2.
O SDK do Aplicativo Windows é instalado como o componente SDK do Aplicativo Windows Modelos C# da carga de trabalho desenvolvimento de ambiente de trabalho .NET para Visual Studio. Antes da versão 17.1 do Visual Studio 2022, o SDK do Aplicativo Windows foi instalado como uma extensão do Visual Studio, conforme explicado em Ferramentas de instalação do SDK do Aplicativo Windows.
Para instalar o Visual Studio 2022 mais recente, a SDK do Aplicativo Windows mais recente:
No Windows, prima a tecla Iniciar e, em seguida, escreva Visual Studio 2022.
A aplicação Visual Studio 2022 está listada.
Clique em Abrir.
A caixa de diálogo do Visual Studio 2022 é aberta, com secções que incluem Abrir recentemente e Começar.
Clique em Continuar sem código.
O Visual Studio é aberto.
No menu Ferramentas , selecione Obter Ferramentas e Funcionalidades.
A janela Instalador do Visual Studio é aberta.
Certifique-se de que o separador Cargas de trabalho está selecionado.
Na secção Desktop & Mobile, selecione o card para a carga de trabalho de desenvolvimento de ambiente de trabalho .NET, para que seja apresentada uma marca de verificação:
Na árvore Detalhes de instalação à direita, em Desenvolvimento > de ambiente de trabalho .NETOpcional, selecione a caixa de verificação do componente SDK do Aplicativo Windows Modelos C#, junto à parte inferior da árvore.
Clique no botão Modificar .
É aberta a caixa de diálogo Controlo de Conta de Utilizador .
Clique no botão Sim .
É-lhe pedido para fechar o Visual Studio.
Clique no botão Continuar (partindo do princípio de que não tem trabalho não guardado).
O Visual Studio transfere e instala o componente mais recente SDK do Aplicativo Windows Modelos C#. Na janela de Instalador do Visual Studio, uma mensagem indica que Todas as instalações estão atualizadas e o Visual Studio 2022 é aberto.
Passo 3: Criar um projeto WinUI 3 em branco
Em seguida, crie um projeto que seja uma aplicação WebView2 básica para WinUI 3 (SDK do Aplicativo Windows). Esta aplicação de ambiente de trabalho irá conter uma única janela main. O projeto ainda não conterá nenhum código WebView2.
Para criar uma aplicação WebView2 para WinUI 3 (SDK do Aplicativo Windows):
Se o Visual Studio estiver em execução, selecione Ficheiro>Novo>Projeto. É aberta a caixa de diálogo Criar um novo projeto .
Se o Visual Studio 2022 não estiver em execução:
No Windows, prima a tecla Iniciar e, em seguida, escreva Visual Studio 2022.
A aplicação Visual Studio 2022 está listada.
Clique em Abrir.
A caixa de diálogo de arranque do Visual Studio 2022 é aberta, com secções que incluem Abrir recentemente e Começar.
Na secção Introdução, clique no card Criar um novo projeto. É aberta a janela Criar um novo projeto .
Na janela Criar um novo projeto , no campo Procurar modelos , introduza WinUI 3 no Ambiente de Trabalho:
Os modelos de projeto que foram instalados no passo principal anterior estão listados.
Clique na Aplicação em Branco, Empacotada (WinUI 3 no Ambiente de Trabalho) card para selecioná-la e, em seguida, clique no botão Seguinte.
É apresentada a caixa de diálogo Configurar o novo projeto .
Na caixa de texto Nome do projeto, introduza um nome de projeto, como WinUI3GetStarted:
Na caixa de texto Localização , introduza ou navegue para um diretório, como
C:\Users\myUsername\source\
.Clique no botão Criar .
O projeto é criado:
- Se for apresentada uma caixa de diálogo a indicar "Falha ao instalar o pacote Microsoft.WindowsAppSDK", clique no botão OK .
Passo 4: Atualizar ou instalar o SDK do Aplicativo Windows
Quando cria um novo projeto no Visual Studio, marcar a status dos pacotes NuGet da solução. Certifique-se de que os pacotes NuGet necessários foram instalados pelo modelo de projeto e certifique-se de que os pacotes foram atualizados, para que o projeto tenha as funcionalidades e correções mais recentes.
Para atualizar ou instalar o pacote NuGet SDK do Aplicativo Windows mais recente para o seu projeto:
No Visual Studio, no Gerenciador de Soluções, clique com o botão direito do rato no projeto WinUI3GetStarted e, em seguida, selecione Gerir Pacotes NuGet.
No Visual Studio, é aberto o separador NuGet: WinUI3GetStarted . Se o pacote Microsoft.WindowsAppSDK tiver sido instalado durante a criação do projeto com o modelo de projeto, o separador Instalado está selecionado e esse pacote é listado:
Se o pacote Microsoft.WindowsAppSDK não estiver listado no separador Instalado :
Clique no separador Procurar e, em seguida, na caixa de texto Procurar , introduza Microsoft.WindowsAppSDK.
Selecione o card Microsoft.WindowsAppSDK:
Clique no botão Instalar , à direita.
É aberta a caixa de diálogo Pré-visualizar Alterações .
Clique no botão Aplicar e, em seguida, aceite os termos de licenciamento.
O pacote NuGet Microsoft.WindowsAppSDK está instalado.
No separador NuGet – Solução, clique no separador Atualizações e, opcionalmente, atualize os pacotes aí listados.
Feche o separador NuGet - Solução .
Passo 5: criar e executar o projeto
O novo projeto WinUI 3 permanece aberto no Gerenciador de Soluções no Visual Studio:
O
App.xaml.cs
ficheiro define umaApplication
classe que representa a sua instância de aplicação.O
MainWindow.xaml.cs
ficheiro define umaMainWindow
classe que representa a janela de main que é apresentada pela instância da aplicação. As classes derivam de tipos noMicrosoft.UI.Xaml
espaço de nomes de WinUI.
Para compilar e executar o projeto:
SelecioneGuardar Todos os Ficheiros> (Ctrl+Shift+S).
Selecione Depurar>Iniciar (F5).
A caixa de diálogo Ativar Modo de Programador para Windows pode abrir:
Se essa caixa de diálogo for apresentada, clique em definições para programadores, ative o botão de alternar Modo de Programador , clique no botão Sim e, em seguida, clique no botão Fechar da caixa de diálogo Do Visual Studio. Para obter mais informações sobre o Modo de Programador, consulte Ativar o seu dispositivo para desenvolvimento, em Criar aplicações de ambiente de trabalho para Windows.
O projeto é compilar. A aplicação WinUI Desktop em branco é aberta, sem ainda nenhum controlo WebView2 adicionado:
Clique no botão Clicar em Mim .
A etiqueta do botão muda para Clicado.
Feche a aplicação.
Passo 6: Adicionar um controlo WebView2
O projeto baseia-se no modelo de projeto Aplicação em Branco, Empacotada (WinUI 3 no Ambiente de Trabalho), que utiliza o pacote NuGet Microsoft.WindowsAppSDK , que inclui o SDK WebView2. Assim, podemos adicionar código WebView2. Irá editar os MainWindow.xaml
ficheiros e MainWindow.xaml.cs
para adicionar um controlo WebView2 ao projeto de aplicação WinUI 3 em branco, carregando inicialmente a home page da Microsoft. No ficheiro XAML, o controlo WebView será marcado como:
<controls:WebView2 x:Name="MyWebView" Source="https://www.microsoft.com">
Para adicionar um controlo WebView2 que navegue inicialmente para a home page da Microsoft:
No Visual Studio, no Gerenciador de Soluções, faça duplo clique em
MainWindow.xaml
.O ficheiro é aberto no editor de código.
Copie e cole o seguinte atributo dentro da
<Window>
etiqueta de início, no final da lista de espaços de nomes XML:xmlns:controls="using:Microsoft.UI.Xaml.Controls"
Esse código adiciona o espaço de nomes XAML webView2. Certifique-se de que o código no
MainWindow.xaml
é semelhante ao seguinte:<?xml version="1.0" encoding="utf-8"?> <Window x:Class="MyWebView2WinUI3.MainWindow" xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" xmlns:local="using:MyWebView2WinUI3" xmlns:d="http://schemas.microsoft.com/expression/blend/2008" xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006" xmlns:controls="using:Microsoft.UI.Xaml.Controls" mc:Ignorable="d"> <StackPanel Orientation="Horizontal" HorizontalAlignment="Center" VerticalAlignment="Center"> <Button x:Name="myButton" Click="myButton_Click">Click Me</Button> </StackPanel> </Window>
Elimine o
<StackPanel>
elemento (três linhas).Acima da
</Window>
etiqueta de fim, cole o seguinte<Grid>
elemento:<Grid> <Grid.RowDefinitions> <RowDefinition Height="Auto"/> <RowDefinition Height="*"/> </Grid.RowDefinitions> <Grid.ColumnDefinitions> <ColumnDefinition Width="*"/> <ColumnDefinition Width="Auto"/> </Grid.ColumnDefinitions> <controls:WebView2 x:Name="MyWebView" Grid.Row="1" Grid.ColumnSpan="2" Source="https://www.microsoft.com" HorizontalAlignment="Stretch" VerticalAlignment="Stretch"/> </Grid>
Este
<Grid>
elemento contém um<controls:WebView2>
elemento com o nomeMyWebView
, que tem umSource
atributo que define o URI inicial que é apresentado no controlo WebView2 (https://www.microsoft.com
). Quando a aplicação é aberta, irá apresentar inicialmente o Microsoft.com home page, no controlo WebView2.No Gerenciador de Soluções, expanda
MainWindow.xaml
e, em seguida, faça duplo clique emMainWindow.xaml.cs
.Em
MainWindow.xaml.cs
, elimine a seguinte linha de código C# nomyButton_Click
método :myButton.Content = "Clicked";
O método está vazio por enquanto. Vamos utilizá-lo para o botão Ir da Barra de endereço mais tarde.
SelecioneGuardar Todos os Ficheiros> (Ctrl+Shift+S).
Pressione F5.
O projeto é compilar e a aplicação é aberta:
A aplicação é uma aplicação anfitriã WebView2 que inclui o controlo WebView2. O controlo WebView2 apresenta inicialmente o site
https://www.microsoft.com
. Ainda não existe nenhuma caixa de texto da Barra de endereço ou botão Ir .Feche a aplicação.
Passo 7: Adicionar controlos de navegação
Para permitir que os utilizadores controlem que página Web é apresentada no controlo WebView2, adicione uma Barra de endereço à aplicação, da seguinte forma:
Em
MainWindow.xaml
, cole o seguinte código dentro do<Grid>
elemento, acima do<controls:WebView2>
elemento :<TextBox Name="addressBar" Grid.Column="0"/> <Button x:Name="myButton" Grid.Column="1" Click="myButton_Click">Go</Button>
Certifique-se de que o elemento resultante
<Grid>
noMainWindow.xaml
ficheiro corresponde ao seguinte:<Grid> <Grid.RowDefinitions> <RowDefinition Height="Auto"/> <RowDefinition Height="*"/> </Grid.RowDefinitions> <Grid.ColumnDefinitions> <ColumnDefinition Width="*"/> <ColumnDefinition Width="Auto"/> </Grid.ColumnDefinitions> <TextBox Name="addressBar" Grid.Column="0"/> <Button x:Name="myButton" Grid.Column="1" Click="myButton_Click">Go</Button> <controls:WebView2 x:Name="MyWebView" Grid.Row="1" Grid.ColumnSpan="2" Source="https://www.microsoft.com" HorizontalAlignment="Stretch" VerticalAlignment="Stretch"/> </Grid>
Em
MainWindow.xaml.cs
, cole o seguintetry/catch
bloco no corpo domyButton_Click
método :private void myButton_Click(object sender, RoutedEventArgs e) { try { Uri targetUri = new Uri(addressBar.Text); MyWebView.Source = targetUri; } catch (FormatException ex) { // Incorrect address entered. } }
Este código navega no controlo WebView2 para o URL que o utilizador introduz na Barra de endereço, quando o utilizador clica no botão Ir , ao voltar a definir o valor da
MyWebView.Source
propriedade, que é equivalente aoSource
atributo do<controls:WebView2 x:Name="MyWebView">
elemento.SelecioneGuardar Todos os Ficheiros> (Ctrl+Shift+S).
Pressione F5.
O projeto é compilação e a aplicação é aberta, mostrando inicialmente a home page da Microsoft. Existe agora uma Barra de endereço e um botão Ir .
Introduza um novo URL HTTPS completo na Barra de endereço, como https://www.bing.com, e, em seguida, clique no botão Ir :
O controlo WebView2 na aplicação apresenta o site do Bing. A Barra de endereço apresenta o URL, como
https://www.bing.com
.Introduza um URL incompleto na Barra de endereço, como
bing.com
, e, em seguida, clique no botão Ir .O controlo WebView2 não tenta navegar para esse URL. É emitida uma exceção, porque o URL não começa com
http://
ouhttps://
.try
Na secção, aaddressBar.Text
cadeia não começa comhttp://
ouhttps://
, mas a cadeia não URI é transmitida para o construtor, oUri
que gera umaSystem.UriFormatException
exceção. No Visual Studio, o painel Saída apresenta "Exceção emitida: "System.UriFormatException" no System.Private.Uri.dll". A aplicação continua em execução.Feche a aplicação.
Passo 8: Processar eventos de navegação
Uma aplicação que aloja um controlo WebView2 escuta os seguintes eventos:
NavigationStarting
SourceChanged
ContentLoading
HistoryChanged
NavigationCompleted
Estes eventos são gerados por um controlo WebView2 durante a navegação na página Web. Se ocorrer um redirecionamento HTTP, existem vários NavigationStarting
eventos seguidos. Para obter mais informações, veja Eventos de navegação para aplicações WebView2.
Quando ocorre um erro, são gerados os seguintes eventos e poderá ser apresentada uma página Web de erro:
SourceChanged
ContentLoading
HistoryChanged
Nesta secção, vai adicionar código para importar a biblioteca WebView2 Core, que processa eventos de navegação para aceder a vários tipos de URLs.
Para processar eventos de navegação:
Em
MainWindow.xaml.cs
, adicione a seguinte linha na parte superior, acima das outrasusing
instruções:using Microsoft.Web.WebView2.Core;
Registe um processador para
NavigationStarting
o qual cancele quaisquer pedidos não HTTPS:Em
MainWindow.xaml.cs
, no construtor, adicione a seguinteNavigationStarting
linha:public MainWindow() { this.InitializeComponent(); MyWebView.NavigationStarting += EnsureHttps; }
Essa linha regista o
EnsureHttps
método (adicionado abaixo) como um serviço de escuta doNavigationStarting
evento.Abaixo do construtor, adicione o seguinte
EnsureHttps
método:private void EnsureHttps(WebView2 sender, CoreWebView2NavigationStartingEventArgs args) { String uri = args.Uri; if (!uri.StartsWith("https://")) { args.Cancel = true; } else { addressBar.Text = uri; } }
SelecioneGuardar Todos os Ficheiros> (Ctrl+Shift+S).
Pressione F5.
O projeto é compilar e a aplicação é aberta.
Na aplicação, na barra Endereço, introduza um URL HTTP, como
http://bing.com
, e, em seguida, clique no botão Ir .A aplicação não navega para essa página porque a navegação está bloqueada para sites HTTP. Ainda não adicionámos uma caixa de diálogo para indicar ao utilizador o motivo pelo qual o site apresentado não foi alterado.
Introduza um URL HTTPS, como
https://bing.com
, e, em seguida, clique no botão Ir .A aplicação navega para a página especificada, porque a navegação é permitida para sites HTTPS.
Na aplicação, na barra Endereço, introduza uma cadeia sem um prefixo, como
bing.com
, e, em seguida, clique no botão Ir .A aplicação não navega para essa página. É
UriFormatException
emitida uma exceção, como anteriormente, e é apresentada no painel Saída no Visual Studio.Feche a aplicação.
Passo 9: Inserir JavaScript para alertar o utilizador sobre um endereço não HTTPS
Pode utilizar a aplicação anfitriã para injetar código JavaScript no controlo WebView2 no runtime. Pode fazer uma tarefa do WebView2 para executar JavaScript arbitrário ou adicionar scripts de inicialização. O JavaScript injetado aplica-se a todos os novos documentos de nível superior e a quaisquer frames subordinados, até que o JavaScript seja removido. O JavaScript injetado é executado com temporização específica para:
Execute o JavaScript injetado após a criação do objeto global.
Execute o JavaScript injetado antes de executar qualquer outro script incluído no documento HTML.
Abaixo, adiciona JavaScript que apresenta um alerta quando um utilizador tenta abrir um site não HTTPS. Para tal, injete um script no conteúdo Web que utiliza ExecuteScriptAsync.
Para apresentar um alerta quando o utilizador tenta navegar para um site não HTTPS:
Em
MainWindow.xaml.cs
, noEnsureHttps
método , adicione a seguinteExecuteScriptAsync
linha:private void EnsureHttps(WebView2 sender, CoreWebView2NavigationStartingEventArgs args) { String uri = args.Uri; if (!uri.StartsWith("https://")) { MyWebView.ExecuteScriptAsync($"alert('{uri} is not safe, try an https link')"); args.Cancel = true; } else { addressBar.Text = uri; } }
SelecioneGuardar Todos os Ficheiros> (Ctrl+Shift+S).
Pressione F5.
O projeto é compilar e a aplicação é aberta.
Na Barra de endereço da aplicação, introduza um URL não HTTPS, como
http://www.bing.com
, e, em seguida, clique no botão Ir .O controlo WebView2 da aplicação apresenta uma caixa de diálogo de alerta para sites não HTTPS, indicando que o não HTTPS
uri
não é seguro:Feche a aplicação.
Parabéns, criou uma aplicação WebView2 WinUI 3 (SDK do Aplicativo Windows) !
O WinAppSDK suporta ambientes WebView2 personalizados
O WinAppSDK suporta ambientes WebView2 personalizados, começando pelo WinAppSDK 1.5 (1.5.0-experimental2). Para obter mais informações, veja WinUI3 WebView2 com um CoreWebView2Environment personalizado.
Para instanciar um ambiente WebView2 personalizado, pode inicializar o WebView2 com uma das substituições do WebView2.EnsureCoreWebView2Async
(listado abaixo) e transmitir o seu personalizado CoreWebView2Environment
(e, opcionalmente, personalizado CoreWebView2ControllerOptions
):
public IAsyncAction EnsureCoreWebView2Async (CoreWebView2Environment environment)
public IAsyncAction EnsureCoreWebView2Async (CoreWebView2Environment environment, CoreWebView2ControllerOptions controllerOptions)
Veja também o código de exemplo em Desativar a navegação smartScreen, abaixo.
Referência da API:
- WebView2.EnsureCoreWebView2Async
- CoreWebView2ControllerOptions
- CoreWebView2Ambiente
- CoreWebView2EnvironmentOptions
Considerações especiais do WinUI 3 WebView2
Desativar a navegação do SmartScreen
O WebView2 envia URLs para os quais navegam na sua aplicação para o serviço SmartScreen , para garantir que os seus clientes se mantêm seguros. Se quiser desativar esta navegação, utilize um personalizado CoreWebView2Environment
, da seguinte forma:
CoreWebView2EnvironmentOptions environmentOptions = new CoreWebView2EnvironmentOptions();
environmentOptions.AdditionalBrowserArguments = "--disable-features=msSmartScreenProtection";
string browserFolder = null; // Use null to get default browser folder
string userDataFolder = null; // Use null to get default user data folder
CoreWebView2Environment environment = await CoreWebView2Environment.CreateWithOptionsAsync(
browserFolder, userDataFolder, environmentOptions);
// ...
this.WebView2.EnsureCoreWebView2Async(environment);
Desativar o SmartScreen com uma variável de ambiente
Já não recomendamos a utilização de uma variável de ambiente. Em alternativa, utilize a abordagem baseada em código da API acima.
Environment.SetEnvironmentVariable("WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS", "--disable-features=msSmartScreenProtection");
Esta variável de ambiente tem de ser definida antes da CoreWebView2
criação, o que ocorre quando a propriedade WebView2.Source é inicialmente definida ou o método WebView2.EnsureCoreWebView2Async é inicialmente chamado.
PredefinirBackgroundColor
No WebView2 para WinUI 3, a DefaultBackgroundColor
definição existe no objeto XAML webView2. Por exemplo:
public MainWindow()
{
this.InitializeComponent();
MyWebView.DefaultBackgroundColor = Colors.LightBlue;
}
Transparência
O WinUI 3 não suporta fundos transparentes. Consulte Suporte em segundo plano transparente para WebView2? · Problema n.º 2992.
Suporte do WinAppSDK para ambientes WebView2 personalizados
Veja WinAppSDK suporta ambientes WebView2 personalizados acima.
Confira também
- Referência da API webView2
- Introdução ao Microsoft Edge WebView2 – descrição geral das funcionalidades.
- Gerir pastas de dados do utilizador
-
Código de Exemplo para WebView2 - um guia para o
WebView2Samples
repositório. - Melhores práticas de desenvolvimento para aplicações WebView2Desenvolvimento de melhores práticas
developer.microsoft.com:
- Microsoft Edge WebView2 – introdução inicial às funcionalidades do WebView2 no developer.microsoft.com.
GitHub:
- Introdução com o WebView2 no WinUI3
- Especificação: o controlo Xaml webView2 - a versão WinUI 3.0 do controlo WebView2.
- repositório > microsoft-ui-xaml Problemas – para introduzir erros ou pedidos de funcionalidade específicos do WinUI.