Introdução ao WebView2 nas aplicações WinUI 3 (SDK da Aplicação Windows)

Artigo
08/02/2024

Este artigo aborda como configurar as suas ferramentas de desenvolvimento e criar uma aplicação WebView2 inicial para o WinUI 3 (SDK da Aplicação windows) e saber mais sobre os conceitos do WebView2 ao longo do percurso.

Neste tutorial, vai utilizar o modelo de projeto do Visual Studio Aplicação em Branco, Empacotado (WinUI no Ambiente de Trabalho) para criar um projeto WinUI 3 em branco. Esse modelo de projeto utiliza o WindowsAppSDK, que inclui o SDK WebView2. Adiciona um controlo WebView2. Em seguida, adicione uma barra de endereço e lógica para apresentar uma caixa de diálogo de aviso quando o utilizador tentar navegar para um URL com um http:// prefixo.

Aplicação a apresentar o site do Bing

Projeto concluído

Uma versão concluída deste projeto de tutorial (a partir de 2020) está disponível no repositório WebView2Samples :

Nome de exemplo: WinUI3_GettingStarted
Diretório de repositório: WinUI3_GettingStarted
Ficheiro de solução: WinUI_Sample.sln

O tutorial atual é atualizado e cria apenas um projeto individual, não um segundo, projeto "(Pacote)", como em 2020.

Passo 1 – Instalar o Visual Studio e o SDK da Aplicação Windows

Mesmo que tenha o Visual Studio instalado, leia a página seguinte e, possivelmente, atualize o software e instale modelos de projeto.

Numa nova janela ou separador, abra a página Ferramentas de instalação do SDK da Aplicação Windows e, em seguida, siga os passos nessa página para instalar o Microsoft Visual Studio, como o Visual Studio 2022.

Se necessário, numa nova janela ou separador, consulte Instalar o Visual Studio em Configurar o ambiente Dev para WebView2.

Regresse a partir dessa página e continue os passos abaixo.

Para este exemplo, não precisa de instalar separadamente o SDK WebView2. Abaixo, irá selecionar o modelo de projeto Aplicação em Branco, Empacotado (WinUI no Ambiente de Trabalho), que utiliza o WindowsAppSDK, que inclui o SDK WebView2.

Passo 2 – Criar um projeto WinUI 3 em branco

Para criar uma aplicação WebView2, comece por criar um projeto de ambiente de trabalho básico, para criar uma aplicação de ambiente de trabalho que contenha uma única janela principal:

Se o Visual Studio não estiver em execução, inicie o Visual Studio (não o Visual Studio Code). Na janela de arranque do Visual Studio, clique no cartão Criar um novo projeto . É aberta a janela Criar um novo projeto .

Em alternativa, se o Visual Studio estiver em execução, selecione Ficheiro>Novo>Projeto. É aberta a caixa de diálogo Criar um novo projeto .

Ativar o Modo de Programador: Quando o Visual Studio abrir em algum momento durante os passos do artigo atual, poderá ser-lhe pedido para ativar o Modo de Programador para o seu computador. Para obter mais informações, se necessário, consulte Ativar o seu dispositivo para desenvolvimento, em Criar aplicações de ambiente de trabalho para Windows.
Na caixa de diálogo Criar um novo projeto , no campo Procurar modelos , introduza WinUI 3 no Ambiente de Trabalho:
Clique no cartão Aplicação em Branco, Empacotada (WinUI no Ambiente de Trabalho) para selecioná-la e, em seguida, clique no botão Seguinte .

Se os modelos WinUI não estiverem listados, terá de instalar modelos de projeto, conforme mencionado acima, a partir das Ferramentas de instalação do SDK da Aplicação Windows. Sugestões adicionais para que o modelo seja apresentado:

Depois de instalar as opções "predefinidas" para o Visual Studio 2022 Community Edition, no Instalador do Visual Studio, clique no cartão .NET e, à direita, selecione a caixa de verificação Modelos C# do SDK da Aplicação Windows.

Se o modelo de projeto correto continuar a não aparecer: no Instalador do Visual Studio, clique no cartão UWP para o selecionar, selecione a caixa de verificação ferramentas v143 C++ à direita e, em seguida, clique no botão Modificar .

É apresentada a caixa de diálogo Configurar o novo projeto .
Na caixa de texto Nome do projeto, introduza um nome de projeto, como MyWebView2WinUI3:
Na caixa de texto Localização , introduza ou navegue para uma localização, como C:\Users\username\Documents\WebView2.
Clique no botão Criar .

O novo projeto WinUI 3 é aberto no Explorador de Soluções no Visual Studio:
- O App.xaml.cs ficheiro define uma Application classe que representa a sua instância de aplicação.
- O MainWindow.xaml.cs ficheiro define uma MainWindow classe que representa a janela principal apresentada pela instância da aplicação. As classes derivam de tipos no Microsoft.UI.Xaml espaço de nomes de WinUI.
Na lista pendente Configurações de Soluções (no meio da parte superior da janela), selecione Depurar.
Na lista pendente Plataformas de Soluções , selecione uma plataforma, como x64.
SelecioneGuardar Todos os Ficheiros> (Ctrl+Shift+S) para guardar o projeto.
Clique em F5 para compilar e executar o projeto. A aplicação WinUI Desktop em branco é aberta, sem ainda nenhum controlo WebView2 adicionado:
Feche a aplicação.

Atualizar números de versão de destino

Para o passo de compilação acima: se estiver a atualizar um projeto anterior, poderá ter de atualizar os números de versão para a Versão de destino e a Versão mínima. Para tal, em Solução, clique com o botão direito do rato no projeto e, em seguida, selecione Editar Ficheiro de Projeto. O seu .csproj ficheiro é aberto. Certifique-se de que os valores são atualizados da seguinte forma e, em seguida, guarde as alterações e crie o projeto.

    <TargetFramework>net6.0-windows10.0.19041.0</TargetFramework>
    <TargetPlatformMinVersion>10.0.17763.0</TargetPlatformMinVersion>

Os valores acima representam:

Versão de destino: Windows 10, versão 2004 (compilação 19041) ou posterior.
Versão mínima: Windows 10, versão 1809 (compilação 17763).

Passo 3 – Adicionar um controlo WebView2

Este projeto de tutorial baseia-se no modelo de projeto Aplicação em Branco, Empacotada (WinUI no Ambiente de Trabalho). Este modelo de projeto utiliza o WindowsAppSDK, que inclui o SDK WebView2.

Edite os MainWindow.xaml ficheiros e MainWindow.xaml.cs para adicionar um controlo WebView2 ao projeto de aplicação WinUI 3 em branco, da seguinte forma:

No Visual Studio, no Explorador de Soluções, faça duplo clique MainWindow.xaml para abri-lo no editor de código.

Adicione o espaço de nomes XAML webView2 ao inserir o seguinte atributo dentro da <Window> etiqueta de início:

xmlns:controls="using:Microsoft.UI.Xaml.Controls"

Certifique-se de que o código no MainWindow.xaml é semelhante ao seguinte:

<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"
    mc:Ignorable="d">

    <StackPanel Orientation="Horizontal" HorizontalAlignment="Center" VerticalAlignment="Center">
        <Button x:Name="myButton" Click="myButton_Click">Click Me</Button>
    </StackPanel>
</Window>

Para adicionar o controlo WebView2, substitua todo <StackPanel> o elemento pelo seguinte <Grid> código. A Source propriedade, perto da parte inferior, define o URI inicial apresentado no controlo WebView2 (https://www.microsoft.com):

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

No Explorador de Soluções, expanda MainWindow.xaml e, em seguida, abra MainWindow.xaml.cs.
Em MainWindow.xaml.cs, comente a seguinte linha, conforme mostrado:
```
    // myButton.Content = "Clicked";
```
SelecioneGuardar Todos os Ficheiros> (Ctrl+Shift+S) para guardar o projeto.
Prima F5 para compilar e executar o projeto.
A aplicação é uma aplicação anfitriã WebView2 que inclui o controlo WebView2. O controlo WebView2 apresenta o site https://www.microsoft.com:
Feche a aplicação.

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, inicialize o WebView2 com uma das substituições de WebView2.EnsureCoreWebView2Async (listado abaixo) e transmita o seu ambiente 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:

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 que contém o <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> no MainWindow.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 seguinte código em myButton_Click, substituindo o método existente myButton_Click (que está quase vazio). Este código navega no controlo WebView2 para o URL introduzido na barra de endereço.

private void myButton_Click(object sender, RoutedEventArgs e)
{
    try
    {
        Uri targetUri = new Uri(addressBar.Text);
        MyWebView.Source = targetUri;
    }
    catch (FormatException ex)
    {
        // Incorrect address entered.
    }
}

SelecioneGuardar Todos os Ficheiros> (Ctrl+Shift+S) para guardar o projeto.
Clique em F5 para compilar e executar o projeto.
Introduza um novo URL 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, tal 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 .

É ArgumentException emitida uma exceção e é apresentada depois de fechar a aplicação, porque o URL não começa com http:// ou https://.
Feche a aplicação.

Nesta secção, vai adicionar código para importar a biblioteca WebView2 Core.

Em MainWindow.xaml.cs, adicione a seguinte linha na parte superior, acima das outras using instruções:
```
using Microsoft.Web.WebView2.Core;
```
As aplicações que alojam controlos WebView2 escutam os seguintes eventos gerados pelos controlos WebView2 durante a navegação na página Web:
- NavigationStarting
- SourceChanged
- ContentLoading
- HistoryChanged
- NavigationCompleted
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 ocorrem erros, são gerados os seguintes eventos e poderá ser apresentada uma página Web de erro:
- SourceChanged
- ContentLoading
- HistoryChanged
Como exemplo de como utilizar os eventos, registe um processador para NavigationStarting o que cancele quaisquer pedidos não HTTPS, da seguinte forma:
Em MainWindow.xaml.cs, no construtor, adicione a seguinte NavigationStarting linha para registar o EnsureHttps método:
```
public MainWindow()
{
    this.InitializeComponent();
    MyWebView.NavigationStarting += EnsureHttps;
}
```

Em MainWindow.xaml.cs, 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) para guardar o projeto.
Clique em F5 para compilar e executar o projeto.
Na aplicação, na barra Endereço, introduza um URL HTTP, como http://bing.com, e, em seguida, clique no botão Ir .

Não acontece nada, porque a navegação está bloqueada em sites HTTP e ainda não adicionámos uma caixa de diálogo para fornecer feedback.
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.
Feche a aplicação.

Passo 6 – Scripting

Pode utilizar aplicações anfitriãs para injetar código JavaScript em controlos 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.

Por exemplo, em seguida, adiciona scripts que enviam um alerta quando um utilizador tenta abrir sites não HTTPS. Para tal, injete um script no conteúdo Web que utiliza ExecuteScriptAsync.

EnsureHttps No método , adicione a seguinte ExecuteScriptAsync 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) para guardar o projeto.
Clique em F5 para compilar e executar o projeto.
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 a sua primeira aplicação WebView2!

Considerações especiais do WinUI 3 WebView2

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 ao 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.

Compartilhar via