Visão geral dos recursos e APIs do WebView2

  • Artigo

Inserir o controle WebView2 em seu aplicativo dá ao aplicativo acesso a vários métodos e propriedades fornecidos por meio das classes ou interfaces do WebView2. O WebView2 tem centenas de APIs que fornecem um vasto conjunto de recursos, desde aprimorar os recursos de plataforma nativa do aplicativo até permitir que seu aplicativo modifique as experiências do navegador. Este artigo fornece um agrupamento de alto nível das APIs Do WebView2 para ajudá-lo a entender as diferentes coisas que você pode fazer usando o WebView2.

Visão geral das áreas de recursos de nível superior

Ao hospedar o controle WebView2, seu aplicativo tem acesso aos seguintes recursos e APIs:

Área de recurso Objetivo
Classes principais: Ambiente, Controlador e Núcleo As CoreWebView2Environmentclasses , CoreWebView2Controllere CoreWebView2 (ou interfaces equivalentes) funcionam juntas para que seu aplicativo possa hospedar um controle do navegador WebView2 e acessar seus recursos do navegador. Essas classes grandes expõem uma ampla gama de APIs que seu aplicativo host pode acessar para fornecer as categorias abaixo de recursos relacionados ao navegador para seus usuários.
Interoperabilidade web/nativo Insira conteúdo da Web em aplicativos nativos. Comunique-se entre código nativo e código Web usando mensagens simples, código JavaScript e objetos nativos.
Recursos do navegador O controle WebView2 fornece ao seu aplicativo acesso a muitos recursos do navegador. Você pode modificar esses recursos do navegador e ativá-los ou desativar.
Gerenciamento de processos Obtenha informações sobre como executar processos do WebView2, processos de saída e processos com falha, para que seu aplicativo possa agir de acordo.
Navegue até páginas e gerencie conteúdo carregado Gerencie a navegação para páginas da Web e gerencie o conteúdo carregado nas páginas da Web.
Iframes Insira outras páginas da Web em sua própria página da Web. Detecte quando páginas da Web inseridas são criadas, detecte quando páginas da Web inseridas estão navegando e, opcionalmente, ignore as opções de quadro x.
Autenticação Seu aplicativo pode lidar com a autenticação básica usando o controle WebView2. A autenticação básica é uma abordagem de autenticação específica que faz parte do protocolo HTTP.
Renderizando o WebView2 em aplicativos não estruturados Use essas APIs para configurar o sistema de renderização Do WebView2 se o aplicativo host não usar uma estrutura de interface do usuário. Essa configuração de renderização controla como o WebView2 renderiza a saída em seu aplicativo host e como o WebView2 lida com entrada, foco e acessibilidade.
Renderizando o WebView2 usando a Composição Para renderização do WebView2 baseada em composição, use CoreWebView2Environment para criar um CoreWebView2CompositionController. CoreWebView2CompositionController fornece as mesmas APIs CoreWebView2Controllerque , mas também inclui APIs para renderização baseada em composição.
Opções de ambiente Dados do usuário: gerenciar a UDF (pasta de dados do usuário), que é uma pasta no computador do usuário. A UDF contém dados relacionados ao aplicativo host e ao WebView2. Os aplicativos WebView2 usam pastas de dados do usuário para armazenar dados do navegador, como cookies, permissões e recursos armazenados em cache. Gerenciar vários perfis em um único UDF.
A seleção de runtime dá suporte a testes de pré-lançamento e auto-hospedagem. Você pode especificar um pedido de pesquisa para canais de visualização do navegador e especificar quais canais de visualização do navegador são pesquisados.
Desempenho e depuração Analisar e depurar o desempenho, manipular eventos relacionados ao desempenho e gerenciar o uso da memória para aumentar a capacidade de resposta do aplicativo.
Protocolo DevTools do Chrome (CDP) Navegadores baseados em instrumentação, inspeção, depuração e perfil Chromium. O CDP (Chrome DevTools Protocol) é a base para o Microsoft Edge DevTools. Use o Protocolo Chrome DevTools para recursos que não são implementados na plataforma WebView2.

Esta página lista apenas APIs que estão em SDKs de versão; ele não lista APIs experimentais ou APIs estáveis que ainda não estão disponíveis em SDKs de versão. Para obter uma lista abrangente de APIs, incluindo APIs experimentais, consulte Notas de Versão para o SDK do WebView2.

Classes principais: Ambiente, Controlador e Núcleo

As CoreWebView2Environmentclasses , CoreWebView2Controllere CoreWebView2 (ou interfaces equivalentes) funcionam juntas para que seu aplicativo possa hospedar um controle do navegador WebView2 e acessar seus recursos do navegador. Essas três classes grandes expõem uma ampla gama de APIs que seu aplicativo host pode acessar para fornecer muitas categorias de recursos relacionados ao navegador para seus usuários.

  • A CoreWebView2Environment classe representa um grupo de controles WebView2 que compartilham o mesmo processo do navegador WebView2, a pasta de dados do usuário e os processos do renderizador. Nesta CoreWebView2Environment classe, você cria pares de CoreWebView2Controller instâncias e CoreWebView2 .
  • A CoreWebView2Controller classe é responsável pela funcionalidade relacionada à hospedagem, como foco de janela, visibilidade, tamanho e entrada, em que seu aplicativo hospeda o controle WebView2.
  • A CoreWebView2 classe é para as partes específicas da Web do controle WebView2, incluindo rede, navegação, script e análise e renderização html.

Veja também:

Interoperabilidade web/nativo

O controle WebView2 do Microsoft Edge permite inserir conteúdo da Web em aplicativos nativos. Você pode se comunicar entre código nativo e código Web usando mensagens simples, código JavaScript e objetos nativos. A seguir estão as APIs main para se comunicar entre web e código nativo.

Subseções abaixo:

Casos de uso comuns para interoperabilidade web/nativo:

  • Atualize o título da janela do host nativo depois de navegar até um site diferente.
  • Envie um objeto de câmera nativo e use seus métodos de um aplicativo Web.
  • Execute um arquivo JavaScript dedicado no lado da Web de um aplicativo.

Veja também:

Compartilhamento de objetos Host/Web

O WebView2 permite que objetos definidos no código nativo sejam passados para o código web do aplicativo. Objetos host são objetos definidos no código nativo que você escolhe passar para o código web do aplicativo.

Os objetos host podem ser projetados no JavaScript para que você possa chamar métodos de objeto nativo (ou outras APIs) do código web do aplicativo. Por exemplo, seu aplicativo pode chamar essas APIs como resultado da interação do usuário no lado da Web do seu aplicativo. Dessa forma, você não precisa reimplementar as APIs de seus objetos nativos, como métodos ou propriedades, no código do lado da Web.

Execução de script

Permite que o aplicativo host adicione código JavaScript no conteúdo da Web no controle WebView2.

Mensagens da Web

Seu aplicativo pode enviar mensagens para o conteúdo da Web que está dentro do controle WebView2 e receber mensagens desse conteúdo da Web. As mensagens são enviadas como cadeias de caracteres ou objetos JSON.

Caixas de diálogo script

Ao hospedar o WebView2, seu aplicativo pode gerenciar caixas de diálogo JavaScript diferentes, suprimi-las ou substituí-las por caixas de diálogo personalizadas.

Buffer compartilhado

A API sharedbuffer dá suporte ao compartilhamento de buffers entre o processo do aplicativo host WebView2 e o processo de renderização do WebView2, com base na memória compartilhada do sistema operacional.

Recursos do navegador

O controle WebView2 fornece ao seu aplicativo acesso a muitos recursos do navegador. Você pode modificar esses recursos do navegador e ativá-los ou desativar.

Subseções abaixo:

Impressão

Você pode imprimir uma página da Web em uma impressora, arquivo PDF ou fluxo PDF configurando configurações de impressão personalizadas.

Veja também:

Cookies

Você pode usar cookies no WebView2 para gerenciar sessões de usuário, armazenar preferências de personalização do usuário e acompanhar o comportamento do usuário.

Veja também:

Captura de imagem

Ao hospedar o WebView2, seu aplicativo pode capturar capturas de tela e indicar qual formato usar para salvar a imagem.

Downloads

Seu aplicativo pode gerenciar a experiência de download no WebView2. Seu aplicativo pode:

  • Permitir ou bloquear downloads com base em metadados diferentes.
  • Altere o local de download.
  • Configure uma interface do usuário de download personalizada.
  • Personalize a interface do usuário padrão.

Geral:

Modificar a experiência padrão:

Experiência de download personalizada:

Permissões

Diferentes páginas da Web podem pedir permissões para acessar alguns recursos privilegiados, como sensor de geolocalização, câmera e microfone. Seu aplicativo host pode responder programaticamente a solicitações de permissões e pode substituir a interface do usuário de permissões padrão por sua própria interface do usuário.

Menus de contexto

O controle WebView2 fornece um menu de contexto padrão (menu com o botão direito do mouse) que você pode personalizar ou desabilitar e também pode criar seu próprio menu de contexto.

Veja também:

Barra de status

Uma barra de status está localizada na parte inferior esquerda da página e exibe o estado da página da Web que está sendo exibida. No WebView2, você pode habilitar/desabilitar a barra de status, obter o texto na barra de status e descobrir quando o texto da barra de status foi alterado.

Agente do Usuário

O agente de usuário é uma cadeia de caracteres que representa a identidade do programa em nome do usuário, como o nome do navegador. No WebView2, você pode definir o agente de usuário.

Veja também:

Preenchimento automático

Seu aplicativo pode controlar independentemente se a funcionalidade de preenchimento automático do navegador está habilitada para informações gerais ou para senhas.

Áudio

Seu aplicativo pode silenciar e desmutar todo o áudio e descobrir quando o áudio está sendo reproduzido.

Teste de sucesso de cliques de mouse em regiões

Fornece resultados de teste de sucesso nas regiões que um WebView2 contém. Útil para aplicativos hospedados visualmente que desejam lidar com eventos de mouse na área não cliente da janela WebView2.

Navegação por gestos de dedo

Ao hospedar o controle WebView2, seu aplicativo pode habilitar ou desabilitar a navegação por gestos de deslizar em dispositivos habilitados para entrada sensível ao toque. Esse gesto permite que os usuários finais:

  • Deslize o dedo para a esquerda/direita (deslize horizontalmente) para navegar até a página anterior ou próxima no histórico de navegação.
  • Puxe para atualizar (deslize verticalmente) a página atual.

Atualmente, esse recurso está desabilitado por padrão no navegador. Para habilitar esse recurso no WebView2, defina a AdditionalBrowserArguments propriedade, especificando a opção --pull-to-refresh .

Habilitar ou desabilitar o navegador respondendo às chaves do acelerador (teclas de atalho)

ICoreWebView2AcceleratorKeyPressedEventArgs tem uma IsBrowserAcceleratorKeyEnabled propriedade para permitir que você controle se o navegador manipula chaves de acelerador (teclas de atalho), como Ctrl+P ou F3.

Veja também:

Fullscreen

No WebView2, você pode descobrir quando um elemento HTML entra ou sai do modo de exibição de tela inteira.

Barra de ferramentas PDF

No visualizador PDF do navegador, há uma barra de ferramentas específica para PDF ao longo da parte superior. No WebView2, você pode ocultar alguns dos itens na barra de ferramentas do visualizador de PDF.

Temas

No WebView2, você pode personalizar o tema de cor como sistema, claro ou escuro.

Idioma

A Language propriedade define a linguagem de exibição padrão para WebView2 que se aplica à interface do usuário do navegador (como menus de contexto e caixas de diálogo), juntamente com a configuração do cabeçalho HTTP que o accept-language WebView2 envia para sites.

A ScriptLocale propriedade permite que o aplicativo host defina a localidade padrão para todas as Intl APIs JavaScript e outras APIs JavaScript que dependem dele, como Intl.DateTimeFormat(), que afeta a formatação de cadeia de caracteres em formatos de hora/data.

Nova janela

O WebView2 fornece funcionalidade para lidar com a função window.open()JavaScript .

Fechar janela

O WebView2 fornece funcionalidade para lidar com a função window.close()JavaScript .

Título do documento

Seu aplicativo pode detectar quando o título do documento de nível superior atual foi alterado.

Favicon

No WebView2, você pode definir um Favicon para um site ou ser notificado quando ele for alterado.

Segurança e privacidade

Prevenção de acompanhamento

O acompanhamento da prevenção permite que o aplicativo host controle o nível de prevenção de rastreamento do controle WebView2 associado ao perfil do usuário.

Smartscreen

Microsoft Defender SmartScreen ("SmartScreen") está habilitado por padrão. A IsReputationCheckingRequired propriedade controla se o SmartScreen está habilitado.

Se você não desabilitar o SmartScreen, deverá fornecer aviso a todos os usuários de que seu software inclui Microsoft Defender SmartScreen e coleta e envia as informações do usuário para a Microsoft, conforme divulgado na Instrução de Privacidade da Microsoft e no Whitepaper de Privacidade do Microsoft Edge.

Veja também:

Relatórios de falha personalizados

Se algum processo do WebView2 falhar, um ou mais arquivos de minidump serão criados e enviados à Microsoft para diagnóstico. Use essa API para personalizar relatórios de falha ao executar diagnóstico e fazer a análise.

  • Para evitar que despejos de falhas sejam enviados para a Microsoft, defina a IsCustomCrashReportingEnabled propriedade como false.
  • Para localizar despejos de falhas e fazer personalização com eles, use a CrashDumpFolderPath propriedade.

Veja também:

Extensões do navegador

Seu aplicativo pode inserir um controle WebView2 que usa extensões de navegador (complementos). Uma extensão do Microsoft Edge é um pequeno aplicativo que os desenvolvedores usam para adicionar ou modificar recursos do Microsoft Edge para melhorar a experiência de navegação de um usuário.

Veja também:

Gerenciamento de processos

Obtenha informações sobre como executar processos do WebView2, processos de saída e processos com falha, para que seu aplicativo possa agir de acordo.

Subseções abaixo:

Informações do processo de quadro

A API de Informações do Processo de Quadro, incluindo GetProcessExtendedInfos, fornece uma coleção instantâneo de todos os quadros que estão sendo executados ativamente no processo de renderizador associado. Essa API permite que seu aplicativo detecte qual parte do WebView2 está consumindo recursos como uso de memória ou CPU.

Navegue até páginas e gerencie conteúdo carregado

Por meio do controle WebView2, seu aplicativo pode gerenciar a navegação para páginas da Web e gerenciar o conteúdo carregado nas páginas da Web.

Subseções abaixo:

Gerenciar conteúdo carregado no WebView2

Essas APIs carregam, param de carregar e recarregam conteúdo para o WebView2. O conteúdo carregado pode ser:

  • Conteúdo de uma URL.
  • Uma cadeia de caracteres de HTML.
  • Conteúdo local por meio do nome do host virtual para mapeamento de pasta local.
  • Conteúdo de uma solicitação de rede construída.

Veja também:

Os métodos de histórico permitem navegação de volta e encaminhamento no WebView2, e os eventos de histórico fornecem informações sobre as alterações no histórico e na fonte atual do WebView2.

NavigationKind obtém o tipo de navegação de cada navegação, como Back/Forward, Reload ou navegação para um novo documento.

Bloquear navegação indesejada

O NavigationStarting evento permite que o aplicativo cancele a navegação para URLs especificadas no WebView2, inclusive para quadros.

Com NavigationStarting e os outros eventos de navegação, o aplicativo pode ser informado do estado da navegação no WebView2. Uma navegação é o processo para carregar uma nova URL.

Veja também:

Gerenciar solicitações de rede no WebView2

O WebResourceRequested evento permite que o aplicativo intercepte e substitua todas as solicitações de rede no WebView2. O WebResourceResponseReceived evento permite que o aplicativo monitore a solicitação enviada e a resposta recebida da rede.

Veja também:

Registro de esquema personalizado

O permite o CustomSchemeRegistration registro de esquemas personalizados no WebView2 para que o aplicativo possa manipular o WebResourceRequested evento para solicitações para essas URLs de esquema personalizado e navegar pelo WebView2 para essas URLs.

Certificados de cliente

No WebView2, você pode usar a API de Certificado do Cliente para selecionar o certificado do cliente no nível do aplicativo. Essa API permite que você:

  • Exiba uma interface do usuário para o usuário, se desejar.
  • Substitua o prompt de caixa de diálogo de certificado do cliente padrão.
  • Consultar programaticamente os certificados.
  • Selecione um certificado na lista para responder ao servidor, quando o WebView2 estiver fazendo uma solicitação a um servidor HTTP que precise de um certificado de cliente para autenticação HTTP.

Certificados de servidor

No WebView2, você pode usar a API de Certificado do Servidor para confiar no certificado TLS do servidor no nível do aplicativo. Dessa forma, seu aplicativo host pode renderizar a página sem avisar o usuário sobre o erro do TLS ou seu aplicativo host pode cancelar automaticamente a solicitação.

Iniciar um esquema de URI externo

Inicie um esquema de URI registrado no sistema operacional.

Iframes

iframes permitem que você insira outras páginas da Web em sua própria página da Web. No WebView2, você pode:

  • Descubra quando os iframes são criados.
  • Descubra quando os iframes estão navegando.
  • Permitir ignorar opções de quadro x.

Veja também:

Autenticação

Seu aplicativo pode lidar com a autenticação básica usando o controle WebView2. A autenticação básica é uma abordagem de autenticação específica que faz parte do protocolo HTTP.

Veja também:

Renderizando o WebView2 em aplicativos não estruturados

Use essas APIs para configurar o sistema de renderização Do WebView2 se o aplicativo host não usar uma estrutura de interface do usuário. Essa configuração de renderização controla como o WebView2 renderiza a saída em seu aplicativo host e como o WebView2 lida com entrada, foco e acessibilidade.

Quando usar essas APIs

  • Estrutura da interface do usuário – Se você estiver usando uma estrutura de interface do usuário para seu aplicativo, use o elemento WebView2 fornecido por essa estrutura de interface do usuário, em vez de usar essas APIs.

  • Nenhuma estrutura de interface do usuário e não usar Composição – se você não estiver usando uma estrutura de interface do usuário para seu aplicativo (por exemplo, se você estiver usando o Win32 puro diretamente) ou se sua estrutura de interface do usuário não tiver um elemento WebView2, você precisará criá-lo CoreWebView2Controller e renderizá-lo em seu aplicativo, usando essas APIs nesta seção.

  • Nenhuma estrutura de interface do usuário e o uso de Composição – Se a interface do usuário do aplicativo for criada usando DirectComposition ou Windows.UI.Composition, você deverá usar CoreWebView2CompositionController em vez de usar essas APIs; confira Renderizando WebView2 usando Composição, abaixo.

Subseções abaixo:

Dimensionamento, posicionamento e visibilidade

CoreWebView2Controller leva um pai HWND. A Bounds propriedade dimensiona e posiciona o WebView2 em relação ao pai HWND. A visibilidade do WebView2 pode ser alternada usando IsVisible.

Zoom

O WebView2 ZoomFactor é usado para dimensionar apenas o conteúdo da Web da janela. O dimensionamento da interface do usuário também é atualizado quando o usuário amplia o conteúdo pressionando Ctrl enquanto gira a roda do mouse.

Escala de rasterização

A API do RasterizationScale dimensiona toda a interface do usuário do WebView2, incluindo menus de contexto, dica de ferramenta e pop-ups. O aplicativo pode definir se o WebView2 deve detectar alterações de escala do monitor e atualizar automaticamente o RasterizationScale. BoundsMode é usado para configurar se a propriedade Bounds é interpretada como pixels brutos ou DIPs (que precisam ser dimensionados por RasterizationScale).

Foco e tabbing

O controle WebView2 gera eventos para informar o aplicativo quando o controle ganha foco ou perde o foco. Para tabbing (pressionando a tecla Tab ), há uma API para mover o foco para WebView2 e um evento para WebView2 para solicitar que o aplicativo retome o foco.

Janela pai

O WebView2 pode ser reparenciado para um identificador de janela pai diferente (HWND). O WebView2 também precisa ser notificado quando a posição do aplicativo na tela for alterada.

Aceleradores de teclado

Quando o WebView2 tem foco, ele recebe diretamente a entrada do usuário. Um aplicativo pode querer interceptar e manipular determinadas combinações de teclas de acelerador (teclas de atalho) ou desabilitar os comportamentos normais da chave do acelerador do navegador.

Consulte também Habilitar ou desabilitar o navegador respondendo às chaves do acelerador (teclas de atalho), acima.

Cor de plano de fundo padrão

O WebView2 pode especificar uma cor de fundo padrão. A cor pode ser qualquer cor opaca ou transparente. Essa cor será usada se a página HTML não definir sua própria cor de fundo.

Renderizando o WebView2 usando a Composição

Para renderização do WebView2 baseada em composição, use CoreWebView2Environment para criar um CoreWebView2CompositionController. CoreWebView2CompositionController fornece as mesmas APIs CoreWebView2Controllerque , mas também inclui APIs para renderização baseada em composição.

Subseções abaixo:

Conectar-se à árvore visual

O WebView2 pode conectar sua árvore de composição a um IDCompositionVisual, IDCompositionTarget ou Windows::UI::Composition::ContainerVisual.

Entrada de encaminhamento

A entrada espacial (mouse, toque, caneta) é recebida pelo aplicativo e deve ser enviada para o WebView2. O WebView2 notifica o aplicativo quando o cursor deve ser atualizado com base na posição do mouse.

Arrastar e soltar

O arrasto de um controle WebView2 para outro aplicativo tem suporte por padrão. No entanto, arrastar para um controle WebView2 requer que, quando o aplicativo host recebe um IDropTarget evento do sistema, o aplicativo host deve encaminhar o evento para o controle WebView2. Arrastar para um controle WebView2 inclui operações de arrastar e soltar que estão inteiramente dentro de um controle WebView2.

Use as APIs a seguir para encaminhar IDropTarget eventos do sistema para o controle WebView2.

Acessibilidade

Por padrão, o WebView2 aparecerá na árvore de acessibilidade como filho do HWND pai, para aplicativos Win32/C++. O WebView2 fornece API para posicionar melhor o conteúdo do WebView2 em relação a outros elementos no aplicativo.

Não aplicável.

Opções de ambiente

Subseções abaixo:

Dados de usuários

Gerencie a UDF (pasta de dados do usuário), que é uma pasta no computador do usuário. A UDF contém dados relacionados ao aplicativo host e ao WebView2. Os aplicativos WebView2 usam pastas de dados do usuário para armazenar dados do navegador, como cookies, permissões e recursos armazenados em cache.

Subseções abaixo:

Veja também:

Limpar dados de navegação:

Vários perfis

Gerencie vários perfis em uma única pasta de dados do usuário.

Veja também:

Create um objeto de opções que define um perfil:

Create um controle WebView2 que usa o perfil:

Acesse e manipule o perfil:

Excluir um perfil

Seu aplicativo pode excluir perfis de usuário para um controle do navegador WebView2.

Veja também:

Seleção de runtime

A seleção de runtime dá suporte a testes de pré-lançamento e auto-hospedagem. Ao criar um ambiente WebView2:

  • Para especificar um pedido de pesquisa para canais de visualização do navegador, use a CoreWebView2EnvironmentOptions.ChannelSearchKind propriedade.
  • Para especificar quais canais de visualização do navegador são pesquisados, use a CoreWebView2EnvironmentOptions.ReleaseChannels propriedade.

Veja também:

Desempenho e depuração

Analisar e depurar o desempenho, manipular eventos relacionados ao desempenho e gerenciar o uso da memória para aumentar a capacidade de resposta do aplicativo.

Subseções abaixo:

Destino de uso de memória

Especifica níveis de consumo de memória, como low ou normal.

Protocolo DevTools do Chrome (CDP)

O PROTOCOLO Chrome DevTools (CDP) fornece APIs para instrumentar, inspecionar, depurar e perfilar navegadores baseados em Chromium. O Protocolo Chrome DevTools é a base para o Microsoft Edge DevTools. Use o Protocolo Chrome DevTools para recursos que não são implementados na plataforma WebView2.

Veja também:

Aberto:

Chamar:

Receptor:

Confira também