Hospedagem em janela vs. hospedagem visual do WebView2

Há três opções para hospedar o controle WebView2 do Microsoft Edge em seu aplicativo:

O modo de hospedagem em janela.
O modo de hospedagem Window to Visual.
O modo de hospedagem Visual.

Você não precisa ler este artigo se usar a hospedagem em janelas na maioria dos cenários. A hospedagem em janela é um bom ponto de partida para a maioria dos aplicativos. Leia este artigo:

Se você estiver usando a hospedagem em janelas em cenários incomuns e estiver enfrentando problemas persistentes com DPI e dimensionamento. Nesse caso, considere a hospedagem Window to Visual.
Se você deseja fornecer uma experiência de usuário (UX) mais personalizada. Nesse caso, considere a hospedagem Visual.

As diferentes abordagens para hospedar o controle WebView2 em seu aplicativo são semelhantes em funcionalidade, mas atendem a necessidades diferentes, dependendo dos requisitos do aplicativo, da seguinte maneira:

Abordagem	Descrição	Otimizado para
Hospedagem em janela	O controle WebView2 recebe entrada do sistema operacional (SO). O sistema operacional envia a entrada para o WebView2.	Exibindo conteúdo da Web de forma rápida e fácil, sem precisar incluir recursos para entradas, saídas e acessibilidade.
Janela para hospedagem visual	Uma combinação de hospedagem em janelas e visual. Semelhante à hospedagem em janela, exceto que o conteúdo do WebView2 é enviado para um Visual hospedado em uma janela, em vez de ter a saída de conteúdo diretamente para a janela.	Uma experiência de desenvolvedor quase idêntica à hospedagem em janela, mas com manuseio aprimorado de DPI/dimensionamento.
Hospedagem visual	Seu aplicativo host recebe entrada espacial (como mouse ou entrada de toque) do usuário. Seu aplicativo envia essa entrada para o controle WebView2.	Controle mais granular sobre a composição do controle. O aplicativo precisa fazer um tratamento específico de APIs de renderização e gerenciamento de janelas.

Essas abordagens têm diferentes requisitos, restrições e benefícios.

A hospedagem em janelas é mais simples de implementar do que a hospedagem visual.
A hospedagem visual requer todas as chamadas à API que a hospedagem em janelas requer e tem requisitos adicionais para que ela seja renderizada corretamente.

As listas de APIs com suporte estão vinculadas nas seções abaixo:

APIs para hospedagem em janelas
APIs para hospedagem Window to Visual
APIs para hospedagem visual

Hospedagem em janela: para exibir conteúdo de forma rápida e fácil

Hospedagem em janela significa que, em seu aplicativo, o conteúdo do WebView2 é hospedado diretamente em uma janela; ou seja, um HWND. O HWND do WebView2 herda muitas propriedades padrão do sistema operacional (SO). O controle WebView2 recebe entrada do sistema operacional e o sistema operacional envia a entrada para o controle WebView2. Você pode ter vários HWNDs em seu aplicativo, cada um sendo usado como um componente WebView2 para acessar o conteúdo da Web.

O benefício disso é que alguns dos comandos de entrada/saída são tratados para você pelo sistema operacional ou pela estrutura. No entanto, você ainda precisará lidar com alguns aspectos do gerenciamento de janelas.

Para obter informações gerais sobre o gerenciamento e a funcionalidade do HWND Windows, consulte Sobre o Windows.

Vantagens

A hospedagem em janelas permite uma solução que exibe rapidamente o conteúdo da Web sem precisar implementar funcionalidades para entradas, saídas e acessibilidade.
As janelas próprias e filhas (como menus e menus de contexto) são dimensionadas automaticamente para corresponder à escala pai HWND do aplicativo.
A hospedagem em janelas lida com a forma como o controle WebView2 gerencia o foco e a tabulação dentro ou fora de si mesma quando pressionar Tab atinge o elemento final.
Você não precisa gerenciar os vários controles de renderização baseados em composição (como Entradas, Saídas e controles de Acessibilidade) se não quiser.

Desvantagens

O modo de hospedagem em janela pode ter problemas de DPI em alguns cenários, como ao compartilhar uma pasta de dados do usuário (e, portanto, compartilhar um processo do navegador) em diferentes aplicativos com diferentes reconhecimento de DPI.

APIs para hospedagem em janelas

Para obter uma lista de APIs que podem ser usadas ao configurar o WebView2 para hospedagem em janelas (ou para hospedagem de janela para visual), consulte Renderizando WebView2 em aplicativos não estruturais em Visão geral das APIs do WebView2.

Hospedagem Window to Visual: Para uma experiência semelhante à hospedagem Windowed, com benefícios adicionais

Janela para hospedagem Visual significa que o conteúdo WebView2 é gerado para um Visual hospedado em um HWND, em vez de enviar conteúdo diretamente para uma janela ou para um Visual diretamente. Ao hospedar conteúdo em um HWND, a hospedagem Window to Visual é fácil de usar, da mesma forma que a hospedagem Windowed. Mas, ao exibir conteúdo usando um visual, a hospedagem Window to Visual evita alguns problemas de DPI e entrada que podem resultar ao usar a hospedagem em janela.

Em Hospedagem de janela para visual e hospedagem visual, um Visual é uma unidade gráfica básica que pode ser usada para compor experiências gráficas no Windows. As APIs gráficas do Windows que expõem essa funcionalidade e são relevantes para o WebView2 são DirectComposition e Windows.UI.Composition. O "Visual" em "Hospedagem visual" pode ser qualquer um dos IDCompositionVisual, , ou Windows.UI.Composition.Visual, que são Visuais expostos por meio das DirectComposition APIs e Windows.UI.CompositionIDCompositionTarget. (Janela para usos IDCompositionVisual de hospedagem visual especificamente.) Confira:

Conceitos básicos nos documentos do DirectComposition de Desenvolvimento > de Aplicativos do aplicativo do Windows.
Visual de composição nos documentos UWP de Desenvolvimento > de Aplicativos do aplicativo do Windows.

Para habilitar a hospedagem Window to Visual, a variável COREWEBVIEW2_FORCED_HOSTING_MODE de ambiente deve ser definida como o valor COREWEBVIEW2_HOSTING_MODE_WINDOW_TO_VISUAL antes de inicializar seu WebView2.

Recursos e benefícios da hospedagem Window to Visual

A Janela para hospedagem Visual não exige que você use as APIs de hospedagem Visual WebView2.
Diferentes aplicativos que compartilham uma pasta de dados do usuário WebView2 podem ter reconhecimento de DPI diferente.
Diferentes aplicativos que compartilham uma pasta de dados do usuário do WebView2 podem ter diferentes níveis de integridade.
Aplicativos diferentes que compartilham uma pasta de dados do usuário do WebView2 não farão com que um ao outro trave devido a filas de entrada de janela anexadas.
Ao hospedar um WebView2 em um suplemento VSTO, alterar a escala do monitor não fará com que o aplicativo trave. Confira Suplementos VSTO na visão geral de desenvolvimento de soluções do Office (VSTO).
O modo de hospedagem Window to Visual dá suporte ao Manuscrito do Windows Shell no WebView2, definindo o msAbydosForWindowlessWV2 sinalizador. Veja também:
- Sinalizadores do navegador WebView2
- Entrada de tinta - Desenvolvimento > de Aplicativos do aplicativo do Windows Interação do usuário.
- cabeçalho shellhandwriting.h - API Win32.

APIs para hospedagem Window to Visual

Para obter uma lista de APIs que podem ser usadas ao configurar a janela do WebView2 para hospedagem visual (ou para hospedagem em janela), consulte Renderizando o WebView2 em aplicativos não estruturais em Visão geral das APIs do WebView2.

Hospedagem visual: para um controle mais granular sobre o layout

Ao usar a hospedagem Visual, seu aplicativo host recebe entrada espacial (como entrada de mouse ou toque) do usuário e encaminha essa entrada para o controle WebView2. A hospedagem visual requer que o aplicativo faça o mesmo gerenciamento de janelas que a hospedagem em janelas, mas tem requisitos adicionais de gerenciamento de janelas em relação a:

Dimensionando o conteúdo.
Roteamento de entradas espaciais (como mouse, toque ou caneta).

Requisitos para dimensionar o conteúdo

Por renderização baseada em composição, um controle WebView2 faz parte de uma árvore visual, portanto, por padrão, ele é renderizado em uma escala baseada nas escalas de todos os seus visuais ancestrais. Por exemplo, se o Visual ancestral de um WebView2 for dimensionado (ampliado) 2x, o conteúdo do WebView2 também será renderizado em escala 2x. Se o Visual pai do WebView2 for dimensionado 2x e o pai desse Visual também for dimensionado 2x, o WebView2 será dimensionado 4x. Mas como o WebView2 não está dimensionando seu próprio conteúdo, eles estão desfocados.

Para resolver isso, o aplicativo pode desfazer o dimensionamento visual padrão do WebView2 e, em vez disso, usar as APIs de escala de rasterização para aplicar o dimensionamento visual pretendido. Isso resulta na renderização do conteúdo do WebView2 na escala correta. Consulte Escala de rasterização em Visão geral das APIs do WebView2.

Requisitos para roteamento de entradas espaciais (mouse, toque ou caneta)

Se o aplicativo WebView2 usar hospedagem Visual, nenhuma entrada espacial (como mouse, toque ou caneta) será enviada para o controle WebView2, a menos que o aplicativo gerencie essa entrada. A entrada é enviada para o , HWNDe o aplicativo é responsável por encaminhar essa entrada espacial para o WebView2, se a posição da entrada estiver sobre o WebView2.

O aplicativo também é responsável por qualquer transformação necessária das posições de entrada no espaço de coordenadas do WebView2.

Veja também:

Usando a camada Visual em aplicativos da área de trabalho em documentos de desenvolvimento de aplicativos do Windows > .

Vantagens e desvantagens

A hospedagem visual permite (e exige) um controle mais granular do layout. Ao usar essa abordagem, o aplicativo precisa de tratamento específico de APIs de renderização e gerenciamento de janelas.

Por exemplo, se uma ação do usuário fizer com que a árvore visual do WebView2 seja dimensionada, o aplicativo deverá ajustar a escala do WebView2 para renderizar corretamente em relação aos visuais pai.

APIs para hospedagem visual

Para obter uma lista de APIs que podem ser usadas ao configurar o WebView2 em um ambiente de hospedagem visual, consulte Renderizando o WebView2 usando a composição em Visão geral das APIs do WebView2.

Compatibilidade e restrições

As principais limitações de compatibilidade incluem o sistema operacional e a renderização em aplicativos de estrutura e não estrutura.

Sistemas operacionais

Todos os modos de hospedagem são suportados onde quer que o WebView2 seja suportado.