Compartilhar via

Introdução ao WebView2 em aplicações WinForms

  • Artigo

Este artigo é para aprender a escrever o seu próprio código WebView2. Se quiser executar primeiro um exemplo, veja Win32 sample app (Aplicação de exemplo Win32 ) ou outro artigo de aplicação de exemplo, como a aplicação de exemplo WinForms.

Este tutorial ajuda-o a:

  • Configure as suas ferramentas de desenvolvimento.
  • Utilize o modelo de projeto da Aplicação Windows Forms C# (.NET Framework) do Visual Studio para criar um projeto WinForms.
  • Instale o pacote do SDK Microsoft.Web.WebView2 para o projeto WinForms.
  • Saiba mais sobre os conceitos do WebView2 ao longo do percurso.

Passo 1 – clonar ou transferir opcionalmente o repositório WebView2Samples

Siga um destes procedimentos:

  • Crie um novo projeto no Visual Studio a partir de um modelo de projeto com os passos nas secções abaixo. Isto irá fornecer-lhe o código mais recente e a estrutura do projeto.

  • Clone ou transfira o WebView2Samples repositório, abra o projeto concluído no Visual Studio e siga os passos neste artigo para compreender como criar o projeto WinForms e compreender o código WebView2 adicionado. Consulte Transferir o repositório WebView2Samples em Configurar o ambiente Dev para WebView2. Está disponível uma versão concluída deste projeto de tutorial no diretório de repositório WebView2Samples WinForms_GettingStarted.

    • Nome de exemplo: Win32_GettingStarted
    • Diretório de repositório: Win32_GettingStarted
    • Ficheiro de solução: WebView2GettingStarted.sln

O exemplo no repositório pode não estar tão atualizado como um projeto que cria com os modelos de projeto mais recentes do Visual Studio.

Passo 2 – Instalar o Visual Studio

É necessário o Microsoft Visual Studio. O Microsoft Visual Studio Code não é suportado neste tutorial.

  1. Se o Visual Studio ainda não estiver instalado, abra a página Microsoft Visual Studio numa nova janela ou separador e instale o Visual Studio 2017 ou posterior, como o Visual Studio 2022 Professional.

    Em seguida, regresse aqui e continue abaixo.

Passo 3 – Criar uma aplicação de janela única

Comece com um projeto de ambiente de trabalho básico que contenha uma única janela de main.

  1. Abra o Visual Studio.

  2. Selecione Arquivo>Novo>Projeto.

    É apresentada a janela Abrir recentemente do Visual Studio:

    O painel de abertura do Visual Studio apresenta a card Criar um novo projeto

  3. À direita, clique no card Criar um novo projeto. É aberta a janela Criar um novo projeto no Visual Studio.

  4. Na caixa de texto Procurar , cole ou comece a escrever o seguinte:

    C# Windows Forms App (.NET Framework)

    Os resultados da pesquisa são apresentados, listando os tipos de projeto.

  5. Selecione a aplicação de Windows Forms C# (.NET Framework) card. Certifique-se de que o nome corresponde, com um ícone C# e, em seguida, o nome Windows Forms App (.NET Framework). Em seguida, clique no botão Seguinte :

    No painel

  6. Na caixa de texto Nome do projeto, introduza um nome de projeto. Este artigo de tutorial utiliza o nome WinForms_GettingStarted, como o nome do diretório do repositório para o projeto concluído.

  7. Na caixa de texto Localização , introduza um caminho, como "C:\Utilizadores\nomedeutilizador\Documentos\MyWebView2Projetos".

  8. Na lista pendente Estrutura, selecione .NET Framework 4.7.2 ou posterior, como .NET Framework 4.8:

    Preencher a janela

  9. Clique no botão Criar .

    A janela do Visual Studio é aberta, mostrando o projeto WinForms de linha de base no Gerenciador de Soluções e mostrando uma janela Designer formulário:

    A janela do Visual Studio a mostrar o projeto WinForms da linha de base e uma Forms Designer

  10. SelecioneGuardar Todos os Ficheiros> (Ctrl+Shift+S).

  11. Selecione Depurar>Iniciar Depuração (F5).

    É aberta uma janela do Form1 vazia a partir do projeto WinForms novo:

    A janela Formulário1 vazia do projeto WinForms novo

  12. Feche a janela Formulário1 .

Tem agora um projeto WinForms vazio que é executado. Em seguida, configure o projeto para adicionar conteúdo WebView2.

Passo 4 – Instalar o SDK WebView2

Para cada projeto WebView2, utilize o gestor de pacotes NuGet no Visual Studio para adicionar o SDK WebView2 ao projeto. Instale o pacote NuGet do SDK Microsoft.Web.WebView2 para utilização pelo projeto atual.

Utilize o NuGet para adicionar o SDK WebView2 ao projeto, da seguinte forma:

  1. No Gerenciador de Soluções, clique com o botão direito do rato no nome do projeto (não no nome da solução acima) e, em seguida, selecione Gerir Pacotes NuGet:

    Gerir Pacotes NuGet

    O Gestor de Pacotes NuGet é aberto no Visual Studio.

  2. Clique no separador Procurar no canto superior esquerdo.

  3. Desmarque a caixa de verificação Incluir pré-lançamento .

  4. Na barra de pesquisa, escreva WebView2 e, em seguida, abaixo da barra de pesquisa, clique em Microsoft.Web.WebView2 para selecioná-la:

    O Gestor de Pacotes NuGet no Visual Studio, a instalar o pacote NuGet do SDK Microsoft.Web.WebView2 para o projeto atual

    Para ampliar, clique com o botão direito do rato em >Abrir imagem num novo separador.

  5. Clique no botão Instalar (ou Atualizar). É aberta a caixa de diálogo Pré-visualizar Alterações :

    A caixa de diálogo Pré-visualizar Alterações

  6. Clique no botão OK .

  7. SelecioneGuardar Todos os Ficheiros> (Ctrl+Shift+S) para guardar o projeto.

  8. Feche a janela Gestor de Pacotes NuGet.

  9. Selecione Depurar>Iniciar Depuração (F5) para compilar e executar o projeto.

    O projeto em execução apresenta a mesma janela vazia que antes:

    A janela Formulário1 vazia do projeto WinForms novo

  10. Feche a janela Formulário1 .

Adicionou o SDK WebView2 ao projeto, mas ainda não adicionou nenhum código WebView2 ao projeto.

Passo 5 – Criar um único controlo WebView2

Agora que o SDK WebView2 está instalado para o projeto WinForms, adicione um controlo WebView2 à aplicação, da seguinte forma:

O projeto de arranque já tem um Form1.cs formulário, mas vamos adicionar outro, como Form2.cs, para ver como fazê-lo.

  1. Selecione AdicionarFormulário do Projeto > (Windows Forms).

  2. Na janela Adicionar Novo Item, à esquerda, selecione Visual C# Items>Windows Forms.

  3. À direita, selecione Formulário (Windows Forms) e, em seguida, clique no botão Adicionar:

    A janela

    O projeto tem agora um formulário adicional, com o nome Form2.csde ficheiro , apresentado no formulário Designer e no Gerenciador de Soluções:

    O formulário adicionado, Form2.cs, na Designer formulário e no Gerenciador de Soluções

  4. Clique na tela Form1 . Não vamos utilizar o Formulário2.

  5. Selecione Ver Caixa>de Ferramentas.

    Eis onde adiciona conteúdo específico do WebView2 à aplicação:

  6. Na Caixa de Ferramentas, clique em WebView2 Windows Forms Controlo para expandir as opções.

    No Visual Studio 2017, por predefinição, o WebView2 não é apresentado na Caixa de Ferramentas. Para permitir que o WebView2 seja apresentado na Caixa de Ferramentas, selecioneOpções> de Ferramentas>Geral> e defina a definição Preencher Automaticamente a Caixa de Ferramentas como Verdadeiro.

  7. Na Caixa de Ferramentas, clique ou arraste o controlo WebView2 para a tela Forms Designer do controlo que adicionou, como Form2.cs:

    Caixa de ferramentas a apresentar o WebView2

  8. Arraste os lados do controlo WebView2 para que preencha quase toda a tela.

  9. Certifique-se de que o novo controlo WebView2 no formulário está selecionado. No painel Propriedades , na secção Estrutura , defina a propriedade (Nome) como webView (minúsculas "w", "V" maiúscula, sem sufixo numérico). Inicialmente, o controlo pode ter outro nome, como webView21. Utilize os botões de opção De ordenação Categorizada e Alfabética conforme necessário para localizar propriedades:

    Propriedades do controlo WebView2

  10. No painel Propriedades , na secção Misc , defina a propriedade Origem como https://www.microsoft.com. A propriedade Origem define o URL inicial que será apresentado no controlo WebView2.

  11. SelecioneGuardar Todos os Ficheiros> (Ctrl+Shift+S) para guardar o projeto.

  12. Clique em F5 para compilar e executar o projeto.

    O controlo WebView2 apresenta conteúdo de https://www.microsoft.com, num controlo WebView2 no formulário Windows Forms, com uma ligação Ignorar para main conteúdo se premir Alt+Tecla de Tabulação para mudar para a janela:

    Alt+Tecla de Tabulação faz com que a aplicação de exemplo apresente inicialmente uma ligação

  13. Se necessário, clique na ligação Ignorar para main conteúdo.

    O controlo WebView2 apresenta conteúdo de https://www.microsoft.com, num controlo WebView2 no formulário de Windows Forms:

    A aplicação de exemplo apresenta o site da Microsoft

  14. Feche a janela Formulário1 .

Se estiver a trabalhar num monitor de alta resolução, poderá ter de configurar a sua aplicação Windows Forms para um suporte de PPP elevado.

Passo 6 – Adicionar controlos e eventos de redimensionamento da janela de processos

Adicione mais controlos ao seu formulário de Windows Forms a partir da caixa de ferramentas e, em seguida, redimensione os eventos da janela de processos, da seguinte forma.

  1. Selecione Ver>Caixa de Ferramentas ou clique no separador Caixa de Ferramentas à esquerda.

  2. Na Caixa de Ferramentas, clique em Controlos Comuns.

    Adicione um controlo de caixa de texto da seguinte forma:

  3. Arraste o controlo Caixa de Texto para a tela Designer formulário Form1.cs.

  4. Certifique-se de que o controlo Caixa de Texto tem o foco.

  5. No painel Propriedades , na secção Estrutura , altere o (Nome) ( provavelmente de textBox1) para a Barra de Endereços.

    Adicione um controlo de botão, da seguinte forma:

  6. Arraste um controlo Botão para a tela Designer formulário Form1.cs.

  7. Certifique-se de que o controlo de botão tem o foco.

  1. No painel Propriedades , na secção Aspeto a negrito (cerca de 15 propriedades para baixo), altere a propriedade Texto (provavelmente do botão1) para Ir!

    Alinhe a caixa de texto e o botão existente, da seguinte forma:

  2. Posicione a caixa de texto no lado esquerdo do formulário, alinhada verticalmente com o botão, conforme mostrado abaixo:

    Estruturador winforms

  3. Redimensione a caixa de texto conforme mostrado:

    Caixa de texto e botão do estruturador WinForms

  4. Clique em Ver>Código para abrir Form1.cs.

    Defina Form_Resize para manter os controlos implementados quando a janela da aplicação for redimensionada, da seguinte forma.

  5. Elimine o seguinte código:

       public Form1()
{
   InitializeComponent();
}

  6. Cole este código na mesma localização:

    public Form1()
{
   InitializeComponent();
   this.Resize += new System.EventHandler(this.Form_Resize);
}

private void Form_Resize(object sender, EventArgs e)
{
   webView.Size = this.ClientSize - new System.Drawing.Size(webView.Location);
   goButton.Left = this.ClientSize.Width - goButton.Width;
   addressBar.Width = goButton.Left - addressBar.Left;
}

    Form_Resize código adicionado

  7. SelecioneGuardar Todos os Ficheiros> (Ctrl+Shift+S) para guardar o projeto.

  8. Clique em F5 para compilar e executar o projeto.

    É apresentada uma janela Do Formulário1, que apresenta o conteúdo da página Web a partir de https://www.microsoft.com:

    Uma janela WinForm do Formulário1 a apresentar conteúdos de páginas Web de microsoft.com

    Se premir Alt+Tecla de Tabulação para mudar para a janela Formulário1, poderá ter de clicar na ligação Ignorar para main conteúdo adicionado.

  9. Desloque a janela para cima e para baixo com a roda do rato. Os controlos de entrada permanecem no local.

  10. Arraste o canto da janela para o redimensionar. A caixa de texto altera a largura.

  11. Feche a janela Formulário1 .

Passo 7 – Navegação

Permitir que os utilizadores alterem o URL que o controlo WebView2 apresenta, ao ler o texto introduzido na caixa de texto, para servir como uma barra de endereço.

  1. Selecione Ver>Código para que Form1.cs seja aberto no editor de código.

  2. No Form1.cs, adicione o CoreWebView2 espaço de nomes ao inserir o seguinte código na parte superior do ficheiro como linha 1:

    using Microsoft.Web.WebView2.Core;

  3. Selecione o separador Form1.cs [Estrutura] e, em seguida, faça duplo clique no Go! botão. O goButton_Click método é adicionado ao Form1.cs ficheiro.

  4. Cole o seguinte código no ficheiro para substituir o método vazio goButton_Click , para que o corpo do método seja o seguinte:

    private void goButton_Click(object sender, EventArgs e)
{
   if (webView != null && webView.CoreWebView2 != null)
   {
      webView.CoreWebView2.Navigate(addressBar.Text);
   }
}

    Agora, a goButton_Click função irá navegar no controlo WebView2 para o URL introduzido na caixa de texto da barra de endereço.

  5. SelecioneGuardar Todos os Ficheiros> (Ctrl+Shift+S) para guardar o projeto.

  6. Clique em F5 para compilar e executar o projeto.

  7. Na barra de endereço, introduza um URL que comece com https, como https://www.bing.com, e, em seguida, clique no botão Ir! :

    bing.com

    O controlo WebView2 mostra o conteúdo da página Web do URL.

  8. Na barra de endereço, introduza uma cadeia que não comece com http, como www.bing.com, e, em seguida, clique no botão Ir! .

    Exceção de argumento devido à introdução de um não URL

    É ArgumentException emitido um se o URL não começar com http:// ou https://.

  9. Selecione Depurar>Parar Depuração ou clique em Continuar. A janela Formulário1 é fechada.

Passo 8 – Eventos de navegação

Durante a navegação na página Web, o controlo WebView2 gera eventos. A aplicação que aloja controlos WebView2 escuta os seguintes eventos:

  • NavigationStarting
  • SourceChanged
  • ContentLoading
  • HistoryChanged
  • NavigationCompleted

Para obter mais informações, veja Eventos de navegação para aplicações WebView2.

Eventos de navegação

Quando ocorre um erro, os seguintes eventos são gerados e podem depender da navegação para uma página Web de erro:

  • SourceChanged
  • ContentLoading
  • HistoryChanged

Observação

Se ocorrer um redirecionamento HTTP, existem vários NavigationStarting eventos seguidos.

Para demonstrar como utilizar os eventos, comece por registar um processador para NavigationStarting o que cancela quaisquer pedidos que não utilizem HTTPS.

  1. No Form1.cs, atualize o Form1() construtor para corresponder ao seguinte código e adicione também a EnsureHttps(sender, args) função abaixo do construtor, da seguinte forma:

    public Form1()
{
   InitializeComponent();
   this.Resize += new System.EventHandler(this.Form_Resize);

   webView.NavigationStarting += EnsureHttps;
}

void EnsureHttps(object sender, CoreWebView2NavigationStartingEventArgs args)
{
   String uri = args.Uri;
   if (!uri.StartsWith("https://"))
   {
      args.Cancel = true;
   }
}

    No construtor, EnsureHttps é registado como o processador de eventos no NavigationStarting evento no controlo WebView2.

  2. SelecioneGuardar Todos os Ficheiros> (Ctrl+Shift+S) para guardar o projeto.

  3. Clique em F5 para compilar e executar o projeto.

  4. Na barra de endereço, introduza um URL que comece com https, como https://www.bing.com, e, em seguida, clique no botão Ir! .

    O URL https é carregado; o conteúdo Web muda da predefinição, Microsoft.com, para Bing.com.

  5. Na barra de endereço, introduza um URL que comece com http, como http://www.microsoft.com, e, em seguida, clique no botão Ir! .

    O URL http não carrega; a página Web Bing.com permanece apresentada. Por outro lado, a http://www.microsoft.com introdução no Microsoft Edge funciona; redireciona para o site https para Microsoft.com.

  6. Na barra de endereço, introduza um URL que comece com https, como https://www.microsoft.com, e, em seguida, clique no botão Ir! .

    O URL https é carregado; a Microsoft.com página Web é agora apresentada, uma vez que adicionou os "s" após "http".

Passo 9 – 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.

  • Execute o JavaScript injetado após a criação do objeto global.

  • Execute o JavaScript injetado antes de qualquer outro script incluído no documento HTML ser executado.

Por exemplo, adicione um script que envia um alerta quando um utilizador navega para um site não HTTPS, da seguinte forma:

  1. Modifique a EnsureHttps função para adicionar a seguinte linha que contém ExecuteScriptAsync:

    void EnsureHttps(object sender, CoreWebView2NavigationStartingEventArgs args)
{
   String uri = args.Uri;
   if (!uri.StartsWith("https://"))
   {
      webView.CoreWebView2.ExecuteScriptAsync($"alert('{uri} is not safe, try an https link')");
      args.Cancel = true;
   }
}

    A linha adicionada injeta um script no conteúdo Web que utiliza o método ExecuteScriptAsync . O script adicionado é:

    alert('{uri} is not safe, try an https link')

  2. Selecione Guardar Todos os Ficheiros>(Ctrl+Shift+S) para guardar o projeto.

  3. Clique em F5 para compilar e executar o projeto.

  4. Tente aceder a http://www.bing.com (com http em vez de https prefixo).

    A aplicação apresenta um alerta:

    Um alerta http, que diz experimentar https em vez disso

Passo 10 – Comunicação entre o anfitrião e o conteúdo Web

O anfitrião e o conteúdo Web podem utilizar postMessage para comunicar entre si da seguinte forma:

  • Os conteúdos Web num controlo WebView2 podem ser utilizados window.chrome.webview.postMessage para publicar uma mensagem no anfitrião. O anfitrião processa a mensagem utilizando qualquer registado WebMessageReceived no anfitrião.

  • Os anfitriões publicam mensagens em conteúdo Web num controlo WebView2 com CoreWebView2.PostWebMessageAsString ou CoreWebView2.PostWebMessageAsJSON. Estas mensagens são capturadas por processadores adicionados ao window.chrome.webview.addEventListener.

O mecanismo de comunicação transmite mensagens de conteúdo Web para o anfitrião através de capacidades nativas.

No seu projeto, quando o controlo WebView2 navega para um URL, apresenta o URL na barra de endereço e alerta o utilizador do URL apresentado no controlo WebView2.

  1. No Form1.cs, atualize o Form1() construtor e crie uma função InitializeAsync() abaixo do mesmo, correspondendo ao seguinte código:

    public Form1()
{
   InitializeComponent();
   this.Resize += new System.EventHandler(this.Form_Resize);
   webView.NavigationStarting += EnsureHttps;
   InitializeAsync();
}

async void InitializeAsync()
{
   await webView.EnsureCoreWebView2Async(null);
}

    A InitializeAsync função aguarda EnsureCoreWebView2Async, porque a inicialização de CoreWebView2 é assíncrona.

    Em seguida, registe um processador de eventos para responder a WebMessageReceived. Este processador de eventos será registado após ser CoreWebView2 inicializado.

  2. No Form1.cs, atualize InitializeAsynce adicione UpdateAddressBar abaixo do mesmo, da seguinte forma:

    async void InitializeAsync()
{
   await webView.EnsureCoreWebView2Async(null);
   webView.CoreWebView2.WebMessageReceived += UpdateAddressBar;
}

void UpdateAddressBar(object sender, CoreWebView2WebMessageReceivedEventArgs args)
{
   String uri = args.TryGetWebMessageAsString();
   addressBar.Text = uri;
   webView.CoreWebView2.PostWebMessageAsString(uri);
}

    Em seguida, para que o WebView2 envie e responda à mensagem Web, depois CoreWebView2 de inicializado, o anfitrião injetará um script no conteúdo Web para:

    • Envie o URL para o anfitrião com postMessage.

    • Registe um processador de eventos para apresentar uma mensagem enviada do anfitrião, numa caixa de alerta, antes de apresentar o conteúdo da página Web.

  3. No Form1.cs, atualize InitializeAsync para corresponder ao seguinte código:

    async void InitializeAsync()
{
   await webView.EnsureCoreWebView2Async(null);
   webView.CoreWebView2.WebMessageReceived += UpdateAddressBar;

   await webView.CoreWebView2.AddScriptToExecuteOnDocumentCreatedAsync("window.chrome.webview.postMessage(window.document.URL);");
   await webView.CoreWebView2.AddScriptToExecuteOnDocumentCreatedAsync("window.chrome.webview.addEventListener(\'message\', event => alert(event.data));");
}

  4. SelecioneGuardar Todos os Ficheiros> (Ctrl+Shift+S) para guardar as alterações.

  5. Clique em F5 para compilar e executar o projeto.

  6. Introduza um URL, como https://www.bing.com:

    O URL da barra de endereço atualizado é apresentado inicialmente numa caixa de alerta

    É apresentado inicialmente um alerta que mostra o URL resultante que é enviado a partir do site do anfitrião.

  7. Clique no botão OK .

    O controlo WebView2 apresenta agora o novo URL na barra de endereço e o conteúdo da página Web do URL é apresentado no controlo WebView2 na janela WinForms:

    A aplicação apresenta o URL na barra de endereço

    • Quando a aplicação é iniciada, o URL predefinido é https://www.microsoft.come o endereço apresentado resultante mostra a região, como https://www.microsoft.com/en-us/.

    • Se introduzir https://www.bing.com, o endereço resultante é uma variante, como https://www4.bing.com/?form=DCDN.

Parabéns, criou a sua primeira aplicação WebView2!

Distribuir uma aplicação WebView2

Se distribuísse a aplicação que resulta deste tutorial, teria de distribuir o WebView2 Runtime juntamente com a sua aplicação. O WebView2 Runtime seria instalado automaticamente em computadores de utilizador. Para obter mais informações, consulte Distribuir a sua aplicação e o WebView2 Runtime.

Confira também