Partilhar via


Introdução ao WebView2 em aplicativos WinUI 2 (UWP)

Neste tutorial, você:

  • Configure suas ferramentas de desenvolvimento para criar aplicativos UWP que usam o WebView2 para exibir conteúdo da Web.
  • Crie um aplicativo Inicial WinUI 2 (UWP).
  • Instale o pacote Microsoft.UI.Xaml (WinUI 2) para o projeto.
  • Adicione um controle WebView2 que exibe o conteúdo da página da Web.
  • Saiba mais sobre os conceitos do WebView2 ao longo do caminho.

Use o modelo de projeto C# Blank App (Universal Windows) e instale o pacote Microsoft.UI.Xaml (WinUI 2) para este projeto. A instalação desse pacote instala o pacote Microsoft.Web.WebView2 (o SDK do WebView2) como uma dependência.

O pacote Microsoft.UI.Xaml (WinUI 2) faz parte da Biblioteca de Interface do Usuário do Windows. Este pacote fornece recursos da interface do usuário do Windows, incluindo:

  • Controles XAML UWP.
  • Estilos de controle densos.
  • Estilos e materiais fluentes.

Plataformas

Este artigo se aplica ao Windows e ao Xbox.

O WinUI 2 dá suporte apenas à UWP. Esses controles são compatíveis com o inverso.

Veja também:

Projeto concluído

Uma versão concluída deste projeto de Introdução (solução) está no repositório WebView2Samples. Você pode usar a solução concluída (do repositório ou de fazer as etapas abaixo) como uma linha de base para adicionar mais código WebView2 e outros recursos.

Uma versão concluída deste projeto tutorial está disponível no repositório WebView2Samples :

  • Nome da amostra: WinUI2_Sample
  • Diretório de repositório: WinUI2_GettingStarted
  • Arquivo de solução: MyUWPGetStartApp.sln

Siga as principais seções etapa na sequência, abaixo.

Sobre WinUI e WebView2

Em aplicativos WinUI 2 (UWP), o WebView2 é exposto como um controle XAML. Depois de inserir o controle XAML em seu aplicativo como um controle nomeado, você poderá consultar esse controle XAML nos arquivos C#.

Apenas um subconjunto de interfaces/funções do WebView2 são expostos no WinUI:

  • O WebView2 objeto XAML expõe a CoreWebView2 interface, juntamente com a funcionalidade mais importante.

  • Interfaces como CoreWebView2Controller estão ocultas, pois o WinUI cuida do ambiente e da criação de janelas nos bastidores.

Confira também a limitação XAML abaixo.

Etapa 1 – Instalar o Visual Studio

Este artigo mostra etapas e capturas de tela para o Visual Studio 2022 Community Edition. O Microsoft Visual Studio 2019 versão 16.9 ou posterior é necessário. Não há suporte para o Visual Studio 2017.

  1. Se uma versão adequada do Microsoft Visual Studio ainda não estiver instalada, em uma nova janela ou guia, consulte Instalar o Visual Studio em Configurar seu ambiente de desenvolvimento para WebView2. Siga as etapas nessa página para fazer uma instalação padrão básica do Visual Studio, como o Visual Studio 2022 Community Edition.

    Em seguida, retorne a esta página e continue abaixo.

  2. Se o Visual Studio não mostrar números de linha no editor de código, talvez você queira ativar números de linha. Para fazer isso, selecione Opções de Ferramentas>> Editor >de TextoTodos osNúmeros de Linha de Idiomas>. Clique em OK.

Etapa 2 – Instalar cargas de trabalho para área de trabalho .NET, área de trabalho C++ e ferramentas de desenvolvimento UWP

  1. Abra o Microsoft Visual Studio. A janela de opção de abertura é exibida:

    Janela de opção de abertura do Visual Studio 2022

  2. No canto inferior direito, clique em Continuar sem código. Visual Studio abre, vazio:

    Visual Studio 2022 vazio

  3. Selecione Ferramentas>Obter Ferramentas e Recursos. A janela Instalador do Visual Studio é aberta e, em seguida, a janela Modificando - Visual Studio abre sobre ela:

    A janela Modificando o Visual Studio, o estado inicial

Se a janela Modificar o Visual Studio não estiver aberta, na janela Instalador do Visual Studio, clique no botão Modificar.

  1. Na guia Cargas de Trabalho , role até e clique nos cartões a seguir para selecioná-los; Verifique se uma marca de seleção está em cada um desses cartões:

    • Desenvolvimento da área de trabalho do .NET
    • Desenvolvimento da área de trabalho com C++
    • desenvolvimento Plataforma Universal do Windows
  2. À direita, na seção Detalhes da instalação, expanda Plataforma Universal do Windows desenvolvimento e selecione C++ (v143) Plataforma Universal do Windows ferramentas:

    A caixa de diálogo 'Modificando o Visual Studio 2019' exibe cartões e detalhes da instalação

    Se todos esses componentes já tiverem sido instalados, clique no botão Fechar, feche a janela Instalador do Visual Studio e pule para a próxima seção principal das etapas abaixo.

  3. Clique no botão Modificar .

    Uma janela Controle de Conta de Usuário é exibida, perguntando "Você deseja permitir que este aplicativo faça alterações em seu dispositivo? Instalador do Visual Studio. Publicador verificado: Microsoft Corporation. Origem do arquivo: disco rígido neste computador. Mostrar mais detalhes (botão)".

  4. Clique no botão Sim .

  5. Uma caixa de diálogo é exibida: "Antes de começarmos, feche o Visual Studio":

    caixa de diálogo: antes de começarmos, feche o Visual Studio

  6. Clique no botão Continuar .

    O Visual Studio baixa, verifica e instala os pacotes selecionados:

    Instalador do Visual Studio funcionando

    Esta captura de tela mostra Visual Studio Professional 2022, embora este artigo tenha sido realmente atualizado usando Visual Studio Community 2022.

    A instalação pode levar vários minutos. O Visual Studio é exibido com um Gerenciador de Soluções vazio.

  7. Pressione Alt+Tab para alternar para a janela Instalador do Visual Studio e feche a janela Instalador do Visual Studio.

Etapa 3 – Criar um aplicativo UWP

  1. Se o Visual Studio estiver aberto, selecione Arquivo>Novo>Projeto. A caixa de diálogo Criar um novo projeto é aberta.

    Ou, se o Visual Studio estiver fechado, abra-o e, na tela de inicialização do Visual Studio, clique no cartão Criar um novo projeto:

    A tela de inicialização do Visual Studio: clique no cartão 'Criar um novo projeto'

  2. Na caixa de texto Pesquisar modelos na parte superior, insira Aplicativo em Branco C# (Windows Universal) e selecione o Aplicativo em Branco C# (Windows Universal) cartão:

    A caixa de diálogo 'Criar um novo projeto' exibe o aplicativo em branco (Windows Universal) cartão

  3. Clique no botão Avançar .

    A caixa de diálogo Configurar seu novo projeto é exibida para um aplicativo em branco (Windows Universal):

    A caixa de diálogo 'Configurar seu novo projeto' exibe caixas de texto para um aplicativo em branco (Windows Universal)

  4. Na caixa de texto Nome do projeto , insira um nome de projeto, como MyUWPGetStartApp.

  5. Na caixa de texto Local , insira um caminho, como C:\Users\myusername\Documents\MyWebView2Projects.

  6. Clique no botão Criar .

    A caixa de diálogo Novo Projeto do Windows é exibida:

    A caixa de diálogo 'Novo Projeto do Windows'

  7. Aceite os padrões e clique no botão OK .

  8. Se a seção Janela Modo do Desenvolvedor for exibida, nessa seção, clique em Ativar. Se você ainda não definiu seu computador como Modo de Desenvolvedor, a caixa de diálogo Usar recursos do desenvolvedor será aberta para confirmar a ativação do modo de desenvolvedor.

    • Clique em Sim para ativar o Modo de Desenvolvedor para seu computador e feche a janela Configurações .

    O Visual Studio exibe a solução e o projeto recém-criados:

    Visual Studio, que contém o projeto WinUI 2 (UWP) recém-criado

Etapa 4 – Criar e executar o projeto vazio

Antes de adicionar o código Do WebView2, confirme se o projeto funciona e veja como é o aplicativo vazio, da seguinte maneira:

  1. Crie e execute o projeto vazio. Para fazer isso, selecione Depurar>Iniciar Depuração (F5). A janela do aplicativo é aberta, exibe temporariamente uma grade e exibe o conteúdo do aplicativo:

    O projeto vazio antes de adicionar o código WebView2

    Este é um aplicativo WinUI 2 (UWP) de linha de base, sem WebView2 ainda.

  2. Feche o aplicativo.

Em seguida, você configurou este novo projeto WinUI 2 (UWP) para hospedar o controle WebView2 e usar a API do WebView2.

Etapa 5 – Instalar o SDK do WinUI 2 (Microsoft.UI.Xaml)

Em seguida, instale o pacote Microsoft.UI.Xaml para este projeto. Microsoft.UI.Xaml é WinUI 2.

  1. Em Gerenciador de Soluções, clique com o botão direito do mouse no projeto (não no nó da solução acima dele) e selecione Gerenciar Pacotes NuGet.

    O painel Gerenciador de Pacotes do NuGet é aberto no Visual Studio.

  2. No Gerenciador de Pacotes do NuGet, clique na guia Procurar .

  3. Desmarque a caixa Incluir marcar de pré-lançamento.

  4. Na caixa Pesquisar, insira Microsoft.UI.Xaml e selecione a cartão Microsoft.UI.Xaml abaixo da caixa de pesquisa:

    O gerenciador de pacotes Do NuGet para instalar o Microsoft.UI.Xaml

    Para a versão 2.8.0 ou posterior, na seção Dependências na parte inferior, Microsoft.Web.WebView2 está listado.

    Para HoloLens 2 desenvolvimento, o pacote Microsoft.Web.WebView2 deve ser a versão 1.0.1722.45 ou superior, que pode ser maior que o padrão. O WebView2 no HoloLens 2 está em Versão Prévia e está sujeito a alterações antes da disponibilidade geral. O WebView2 só tem suporte em dispositivos HoloLens 2 que executam a atualização Windows 11. Para obter mais informações, consulte Atualizar HoloLens 2.

  5. No painel do meio, na lista suspensa Versão , verifique se o mais recente estável está selecionado, versão 2.8.0 ou posterior.

  6. Clique no botão Instalar .

    A caixa de diálogo Alterações de Visualização é exibida:

    A caixa de diálogo 'Alterações de Visualização' para instalar o pacote Microsoft.UI.Xaml

  7. Clique no botão OK .

  8. A caixa de diálogo Aceitação de Licença é exibida:

    A caixa de diálogo 'Aceitação de Licença' para instalar o pacote Microsoft.UI.Xaml

  9. Clique no botão Aceito . No Visual Studio, o readme.txt arquivo é exibido, dizendo que você instalou o pacote WinUI:

    O arquivo readme.txt depois de instalar o pacote Microsoft.UI.Xaml, informa que você instalou o pacote WinUI NuGet

    O readme lista algumas linhas de código semelhantes ao que vamos adicionar.

  10. SelecioneSalvar todos osarquivos> (Ctrl+Shift+S).

Agora você instalou o pacote Microsoft.UI.Xaml, que é WinUI 2, para seu projeto. O SDK do WinUI 2 (Microsoft.UI.Xaml) inclui o SDK do WebView2, portanto, você não precisa instalar separadamente o pacote NuGet para o SDK do WebView2.

Etapa 6 – Instanciar o controle WebView2 no código XAML

Agora você está pronto para adicionar o código WebView2 ao projeto. Primeiro, adicione uma referência de namespace para o controle WebView2, da seguinte maneira:

  1. Em Gerenciador de Soluções, expanda seu projeto e clique duas vezes em MainPage.xaml.

    MainPage.xaml abre em um designer com um editor de código abaixo:

    MainPage.xaml code and Designer window

  2. No editor de código, dentro da <Page> marca <Pageinicial do elemento , adicione o seguinte atributo, abaixo dos outros xmlns: atributos:

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

    Adicione um controle WebView2 à grade XAML da seguinte maneira:

  3. MainPage.xaml No arquivo, no <Grid> elemento (que ainda não contém outros elementos), adicione um controle WebView2, adicionando o seguinte elemento:

    <controls:WebView2 x:Name="WebView2" Source="https://bing.com"/>
    
  4. Pressione Ctrl+S para salvar o arquivo.

    Acima do MainPage.xaml arquivo no editor de código, uma visualização do conteúdo do controle WebView2 pode ser exibida ou pode permanecer em branco (branco) até que você crie o aplicativo pela primeira vez:

    Visualização do conteúdo do WebView2

    O sublinhado ondulado desaparece depois de criar e executar o aplicativo, na próxima etapa.

Etapa 7 – Criar e executar o projeto que contém o controle WebView2

  1. Clique em Depurar>Iniciar Depuração (F5). (Se for criado para HoloLens 2, consulte Usando o Visual Studio para implantar e depurar). A janela do aplicativo é aberta, mostrando brevemente a grade WebUI do WebView2:

    Durante a depuração, a grade WebUI do WebView2 é exibida brevemente

  2. Após um momento, a janela do aplicativo mostra o site do Bing no controle WebView2 para WebUI 2:

    O aplicativo de exemplo exibe o site do Bing

  3. No Visual Studio, selecione Depurar>Parar Depuração para fechar a janela do aplicativo.

Parabéns, você criou seu primeiro aplicativo WebView2!

Agora você pode alterar o conteúdo do controle WebView2 para adicionar seu próprio conteúdo.

Saiba mais sobre eventos de navegação

Em seguida, saiba mais sobre eventos de navegação, que são essenciais para aplicativos WebView2. Inicialmente, o aplicativo navega para https://bing.com.

Considerações especiais para o WebView2 no WinUI 2 (UWP)

O controle UWP (WebView2 WinUI 2) está em desenvolvimento.

Interface do usuário de preenchimento automático

A interface do usuário de preenchimento automático ainda não foi implementada para WebView2 para aplicativos UWP.

Veja também:

Imprimir em PDF requer que o aplicativo tenha acesso a um local gravável na UWP, como uma pasta local. Para obter uma lista completa de caminhos acessíveis ao UWP, consulte Permissões de acesso ao arquivo.

Veja também:

  • Impressão em Visão geral de recursos e APIs do WebView2.

Impressão padrão

A impressão padrão está desabilitada para WebView2 para aplicativos UWP. No entanto, você pode capturar e imprimir o modo de exibição atual chamando CapturePreview.

Veja também:

Smartscreen

O WebView2 envia URLs que são navegadas em seu aplicativo para o serviço SmartScreen , para garantir que seus clientes permaneçam seguros. Se você quiser desabilitar essa navegação, poderá fazê-lo por meio de uma variável de ambiente:

  • Environment.SetEnvironmentVariable("WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS", "--disable-features=msSmartScreenProtection");

Essa variável de ambiente deve ser definida antes da CoreWebView2 criação, que ocorre quando a propriedade WebView2.Source é inicialmente definida ou o método WebView2.EnsureCoreWebView2Async é inicialmente chamado.

Baixar arquivos

Há algumas limitações conhecidas para o comportamento de downloads atuais para WebView2 na UWP.

Salvar como

Salvar arquivos por meio do Save As está funcionando e está habilitado para WebView2 para aplicativos UWP. Os arquivos serão salvos na pasta selecionada pelo usuário.

Qual pasta os arquivos são baixados para

Se o host não alterar o ResultFilePath do arquivo baixado, os arquivos baixados serão baixados em uma subpasta com o nome do pacote de aplicativo na Downloads pasta.

Se o host alterar o ResultFilePath do arquivo baixado, o arquivo só será baixado se o aplicativo tiver acesso a esse caminho de arquivo por padrão. Se você quiser usar um local de arquivo ao qual o aplicativo não tem acesso por padrão, você deve definir o recurso correspondente. Consulte Declarações de funcionalidade do aplicativo na documentação UWP.

Downloads Hub

A abertura de arquivos e pastas do Hub de Downloads está desabilitada. Clicar no ícone de arquivo ou pasta não abrirá o respectivo arquivo/pasta.

Veja também:

  • Downloads em Visão geral de recursos e APIs do WebView2.

Limitação XAML

O suporte à Ilha XAML requer trabalho adicional e pode ser considerado para versões futuras.

Configuração DefaultBackgroundColor

No WinUI 2, a DefaultBackgroundColor propriedade não é exposta diretamente. Você pode definir a cor padrão em segundo plano definindo uma variável de ambiente, da seguinte maneira:

Environment.SetEnvironmentVariable("WEBVIEW2_DEFAULT_BACKGROUND_COLOR", "FF000000");

Veja também:

Configurando transparência

No WinUI 2, a transparência é obtida definindo a cor como 00FFFFFF.

Cursores CSS

No WinUI 2 (UWP), os cursores CSS têm as seguintes limitações.

URLs de imagem

O cursor CSS não pode ser uma URL de imagem, como cursor: url(https://contoso.com/cursor.png), pointer;. Consulte CSS – o cursor carregado da URL não funciona.

Cursores CSS predefinidos

No WinUI 2 (UWP), não há suporte para alguns dos cursores de CSS predefinidos. Você pode usar cursores CSS para alterar o cursor para alguns dos cursores predefinidos, como cursor: wait; ou cursor: crosshair;, mas não para outros, como cursor: progress ou cursor: none.

Palavra-chave Com suporte?
Geral
Automático ✔️
Padrão. ✔️
none
Links & status
context-menu ✔️
Ajuda ✔️
Ponteiro ✔️
progresso
Esperar ✔️
Selection
célula
Mira ✔️
texto ✔️
vertical-text
Arrastar & queda
alias
Cópia
move ✔️
no-drop ✔️
não permitido ✔️
Agarrar
Agarrando
Redimensionamento & rolagem
all-scroll ✔️
col-resize
redimensionamento de linha
n-redimensionar ✔️
redimensionamento eletrônico ✔️
s-redimensionar ✔️
w-resize ✔️
ne-redimensionar ✔️
nw-resize ✔️
se-redimensionar ✔️
sw-resize ✔️
ew-resize ✔️
ns-redimensionar ✔️
nesw-resize ✔️
nwse-resize ✔️
Zoom
zoom-in
zoom-out

Veja também:

  • Cursores CSS – a seção Valores descreve os valores palavra-chave acima.

Ferramentas de Desenvolvedor do Microsoft Edge

No WinUI 2, o Microsoft Edge DevTools não pode ser iniciado dentro de um aplicativo WebView2 WinUI 2 (UWP) assinado na loja. No entanto, você pode contornar isso usando a depuração remota. Consulte Aplicativos Depuração remota do WebView2 WinUI 2 (UWP).

Limitações de API

As seguintes classes não estão acessíveis no WinUI 2:

  • CoreWebView2EnvironmentOptions
  • CoreWebView2ControllerOptions

Confira também

Github: