Chamar o código WinRT do lado nativo a partir do código do lado da Web

Seu código JavaScript do lado da Web pode acessar métodos e propriedades WinRT do lado nativo, com a ajuda da ferramenta wv2winrt (a ferramenta WebView2 WinRT JS Projection). A ferramenta wv2winrt gera arquivos de código necessários para seu código JavaScript e habilita o uso de métodos e propriedades de qualquer API WinRT, incluindo:

  • As APIs WinRT do aplicativo host WebView2.
  • APIs do Windows WinRT.
  • APIs WinRT de terceiros.

Para obter mais informações sobre por que você deseja que seu código JavaScript do lado da Web acesse os métodos e as propriedades do seu aplicativo host WinRT, consulte a introdução de Chamar código do lado nativo do código do lado da Web.

Por que o WinRT e o .NET usam abordagens diferentes

Este artigo é para APIs WinRT WebView2, não para APIs .NET WebView2. O código C# neste artigo será criado, mas não executado, para APIs do .NET WebView2. Uma chamada AddHostObjectToScript usando o código C# deste artigo para APIs do .NET WebView2 produziria uma mensagem de erro.

A ferramenta wv2winrt (a ferramenta de projeção WebView2 WinRT JS) é necessária ao projetar objetos WinRT, pois o WinRT não dá suporte IDispatch a nenhum outro mecanismo para inspecionar e interagir dinamicamente com objetos WinRT, que as plataformas Win32 e .NET do WebView2 suportam. Para o uso do .NET de AddHostObjectToScript, consulte Chamar código do lado nativo do código do lado da Web em vez deste artigo.

Diferenças de configuração para WinUI 3 versus WinUI 2

Se o seu aplicativo WinRT WebView2 for destinado ao WinUI 3 (SDK do Aplicativo do Windows App) em vez do WinUI 2 (UWP), aqui está uma visão geral das etapas específicas do WinUI 3 que são fornecidas mais adiante:

  • Em um aplicativo não empacotado, você precisa realizar etapas adicionais que estão no artigo "Aprimorando aplicativos da área de trabalho não empacotados usando componentes do Windows Runtime".

  • Adicionar WinRTAdapter ao CsWinRTIncludes.

  • Para aplicativos WinUI 3 (SDK do Aplicativo do Windows App), o projeto de aplicativo principal tem uma referência ao WinAppSDK que inclui diretamente sua própria cópia dos arquivos SDK do WebView2, portanto, você não pode incluir uma referência ao SDK do WebView2 no projeto do aplicativo principal sem produzir mensagens de erro.

  • A versão do adaptador do projeto não precisa corresponder.

  • Depois de instalar as opções "padrão" para o Visual Studio 2022 Community Edition, no Visual Studio Installer, clique no .NET card e, à direita, marque a caixa de seleção SDK do Windows App C# Modelos.

  • Se o modelo de projeto correto ainda não aparecer: no Visual Studio Installer, clique no card UWP para selecioná-lo, marque a caixa de seleção v143 C++ tools à direita e clique no botão Modificar.

Estratégia e objetivo final deste exemplo

Estratégia

Este artigo orienta você pelas seguintes etapas principais:

  1. Crie um projeto WinRTAdapter para a ferramenta wv2winrt (a ferramenta de projeção WebView2 WinRT JS).

  2. Para este exemplo, especifique as seguintes APIs do lado do host para projeção:

  3. Execute a ferramenta wv2winrt para gerar código-fonte C++/WinRT para os namespaces ou classes selecionados.

  4. Chame AddHostObjectToScript, em seu projeto principal do WinUI.

  5. Chame métodos e propriedades no objeto host do seu código JavaScript do lado da Web (ou do Console do DevTools).

Objetivo final

Primeiro, escolheremos algumas APIs do WinRT que estamos interessados em chamar a partir do código JavaScript. Para este exemplo, usaremos a classe WinRT Language , que está no Windows.Globalization namespace, para aplicativos UWP do Windows. A classe Windows.Globalization.Language permite obter informações de idioma do sistema operacional nativo do cliente.

No aplicativo host WebView2, o código JavaScript do lado da Web pode acessar métodos e propriedades no Language objeto que está no código do lado nativo.

Acessar APIs projetadas por meio do Console do DevTools

No final deste passo a passo de exemplo, você usará o Console do DevTools do Microsoft Edge para testar a leitura da propriedade do host displayName da Language classe:

const Windows = chrome.webview.hostObjects.sync.Windows;
(new Windows.Globalization.Language("en-US")).displayName;

O Console do DevTools produzirá English (Estados Unidos), ou outro nome de exibição de idioma, demonstrando que você chamou o código do lado nativo do código JavaScript do lado da Web:

Use o Console do DevTools para testar a chamada de código do lado nativo a partir de código do lado da Web

Da mesma forma, você pode acessar membros do namespace Windows.System.UserProfile .

Acessar APIs projetadas por meio de arquivos de código-fonte

Da mesma forma, em arquivos de código-fonte, em vez de no Console do DevTools, você pode acessar o objeto host projetado. Primeiro, execute o código de configuração para o script:

// early in setup code:
const Windows = chrome.webview.hostObjects.sync.Windows;

Em seguida, no corpo principal do código, você adiciona chamadas a objetos projetados, como a seguir:

(new Windows.Globalization.Language("en-US")).displayName;

Da mesma forma, você pode acessar membros do namespace Windows.System.UserProfile .

Vamos começar!

Etapa 1: Criar ou obter um projeto WebView2 básico

Instalar o Visual Studio

  • Se o Visual Studio 2015 ou posterior ainda não estiver instalado, em uma janela ou guia separada, confira Instalar o Visual Studio em Configurar seu ambiente de Desenvolvimento para WebView2. Siga as etapas nesta seção e, em seguida, retorne a esta página e continue as etapas abaixo. O presente artigo mostra capturas de tela do Visual Studio Community Edition 2022.

Instalar um canal de visualização do Microsoft Edge

  • Se um canal de visualização do Microsoft Edge (Beta, Dev ou Canary) ainda não estiver instalado, em uma janela ou guia separada, consulte Instalar um canal de visualização do Microsoft Edge em Configurar seu ambiente de desenvolvimento para WebView2. Siga as etapas nesta seção e, em seguida, retorne a esta página e continue as etapas abaixo.

Criar ou abrir um projeto básico do WebView2

  1. Faça qualquer uma das seguintes abordagens para obter um projeto inicial de linha de base que contenha algumas linhas de código WebView2 que incorpore o controle WebView2:

  2. Na unidade local, abra o .sln arquivo obtido acima, como a solução de repositório de Exemplos:

    • <your-repos-directory>/WebView2Samples-main/GettingStartedGuides/WinUI2_GettingStarted/MyUWPGetStartApp.sln
    • <your-repos-directory>/WebView2Samples/GettingStartedGuides/WinUI2_GettingStarted/MyUWPGetStartApp.sln

    A solução de exemplo é aberta no Visual Studio:

    Adicionando um novo projeto para a ferramenta wv2winrt

  3. No Visual Studio, selecione Depurar>Iniciar Depuração. Isso compila o projeto e executa a versão de linha de base do projeto. O aplicativo de linha de base é aberto, como a janela MyUWPGetStartApp :

    A janela de exemplo UWP do WinUI 2 WebView2

    É mostrado um aplicativo WinUI 2 (UWP) que tem um controle WebView adicionado, definido para navegar inicialmente para Bing.com. Este é o aplicativo que resulta da execução das etapas em Introdução ao WebView2 em aplicativos WinUI 2 (UWP).

  4. Feche a janela do aplicativo.

Etapa 2: Adicionar um projeto WinRTAdapter para a ferramenta wv2winrt

Em seguida, crie um projeto WinRTAdapter para a ferramenta wv2winrt (a ferramenta WebView2 WinRT JS Projection). Este projeto cria uma biblioteca de código gerada pela execução da ferramenta. Esse código gerado permite que as APIs do WinRT sejam expostas no controle WebView2.

Adicione um projeto para a ferramenta wv2winrt , da seguinte maneira:

  1. No Visual Studio, abra seu projeto WinUI, da etapa anterior.

  2. No Gerenciador de Soluções, clique com o botão direito do mouse na solução (não no projeto) e selecione Adicionar>Novo Projeto. A caixa de diálogo Adicionar um novo projeto é aberta.

  3. Na caixa de texto Pesquisar, insira Componente do Tempo de Execução do Windows Runtime (C++/WinRT).

    Abordagem alternativa: Se você não adicionar um projeto usando o modelo de projeto para Componente do Tempo de Execução do Windows Runtime (C++/WinRT) conforme descrito nas etapas numeradas abaixo, será necessário instalar a carga de trabalho de desenvolvimento da Plataforma Universal do Windows, seguindo as etapas em Aplicativos UWP > Introdução ao C++/WinRT.

  4. Selecione o card do Componente do Windows Runtime (C++/WinRT) e clique no botão Avançar:

    Selecionando o card do componente do Windows Runtime (C++/WinRT) na caixa de diálogo

    Observação: Certifique-se de que o modelo inclua "C++/WinRT" em seu nome. Se esse modelo não estiver listado, instale a carga de trabalho de desenvolvimento da Plataforma Universal do Windows de dentro do Visual Studio Installer. Se você estiver usando o Visual Studio 2019 e ainda não conseguir encontrar o modelo, instale os modelos e o visualizador do C++/WinRT para a extensão VS2019 em Extensões do Visual Studio > Gerenciar > Extensões.

    A janela Configure seu novo projeto é aberta.

Configurando e criando o projeto

  1. Na caixa de texto Nome do projeto , nomeie o projeto, especificamente, WinRTAdapter. Observação: Por enquanto, você deve usar este nome de projeto específico.

    Na janela 'Configurar seu novo projeto', nomeie o projeto como 'WinRTAdapter'

    O caminho na captura de tela acima reflete a abordagem de clonagem do repositório de exemplos.

  2. Clique no botão Criar .

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

    A caixa de diálogo

  3. Clique no botão OK .

    O projeto WinRTAdapter é criado e adicionado ao Gerenciador de Soluções ao lado do projeto principal:

    O projeto WinRTAdapter recém-criado

  4. Selecione Arquivo>, Salvar Tudo (Ctrl+Shift+S).

A ferramenta wv2winrt (a ferramenta de projeção WebView2 WinRT JS) será executada neste projeto WinRTAdapter . Na etapa abaixo, você gerará código para as classes selecionadas neste projeto.

Etapa 3: Instalar a Biblioteca de Implementação do Windows para o projeto WinRTAdapter

No projeto WinRTAdapter, instale a WIL (Biblioteca de Implementação do Windows), da seguinte forma:

  1. No Gerenciador de Soluções, clique com o botão direito do mouse no projeto WinRTAdapter e selecione Gerenciar Pacotes NuGet. A janela do Gerenciador de Pacotes NuGet é aberta no Visual Studio.

  2. Na janela Gerenciador de Pacotes NuGet , clique na guia Procurar .

  3. Na janela Gerenciador de Pacotes NuGet, na caixa Pesquisar, insira Biblioteca de Implementação do Windows e selecione o card da Biblioteca de Implementação do Windows:

    Gerenciador de Pacotes NuGet, selecionando o pacote 'Biblioteca de Implementação do Windows'

  4. Clique no botão Instalar . A caixa de diálogo Visualizar Alterações é aberta:

    A caixa de diálogo Visualizar Alterações do WIL para o projeto WinRTAdapter

  5. Clique no botão OK .

  6. Selecione Arquivo>, Salvar Tudo (Ctrl+Shift+S).

O WIL agora está instalado para o projeto WinRTAdapter . A WIL (Biblioteca de Implementação do Windows) é uma biblioteca C++ somente de cabeçalho para facilitar o uso da codificação COM para Windows. Ele fornece interfaces C++ legíveis e fortemente tipadas para padrões de codificação do Windows COM.

Etapa 4: Instalar o SDK de pré-lançamento do WebView2 para o projeto WinRTAdapter

No projeto WinRTAdapter, instale também uma versão de pré-lançamento do SDK do WebView2, da seguinte forma:

  1. No Gerenciador de Soluções, clique com o botão direito do mouse no projeto WinRTAdapter e selecione Gerenciar Pacotes NuGet. A janela do Gerenciador de Pacotes NuGet é aberta.

  2. Na janela Gerenciador de Pacotes NuGet , clique na guia Procurar .

  3. Marque a caixa de seleção Incluir pré-lançamento .

  4. Na caixa Pesquisar , insira WebView2.

  5. Clique no card Microsoft.Web.WebView2. As informações detalhadas aparecem na área central da janela.

  6. Na lista suspensa Versão , selecione uma versão de pré-lançamento do SDK do WebView2 ou certifique-se de que o Pré-lançamento mais recente esteja selecionado. A versão deve ser 1.0.1243.0 ou superior. Observe o número da versão que você selecionar.

    Gerenciador de Pacotes NuGet, selecionando o pacote SDK do WebView2, para o projeto WinRTAdapter

  7. Clique no botão Instalar . A caixa de diálogo Visualizar Alterações é aberta:

    A caixa de diálogo Visualizar Alterações para adicionar o SDK do WebView2 ao projeto WinRTAdapter

  8. Clique no botão OK .

  9. Selecione Arquivo>, Salvar Tudo (Ctrl+Shift+S).

O SDK de pré-lançamento do WebView2 agora está instalado para o projeto WinRTAdapter .

Etapa 5: instalar o SDK de pré-lançamento do WebView2 (somente WinUI 2)

No projeto principal, como MyUWPGetStartApp, instale a mesma versão de pré-lançamento do SDK do WebView2 que você instalou para o projeto WinRTAdapter , da seguinte maneira:

  1. No Gerenciador de Soluções, clique com o botão direito do mouse no projeto principal, como MyUWPGetStartApp, e selecione Gerenciar Pacotes NuGet. A janela do Gerenciador de Pacotes NuGet é aberta.

  2. Marque a caixa de seleção Incluir pré-lançamento .

  3. Selecione a guia Procurar .

  4. Na caixa Pesquisar , insira WebView2.

  5. Clique no card Microsoft.Web.WebView2. As informações detalhadas aparecem na área central da janela.

  6. Na lista suspensa Versão , selecione uma versão de pré-lançamento do SDK do WebView2 ou certifique-se de que o Pré-lançamento mais recente esteja selecionado. Certifique-se de usar a mesma versão usada pelo projeto WinRTAdapter; para aplicativos WinRT WebView2 destinados ao WinUI 2 (UWP), essa versão precisa ser a mesma do projeto WinRTAdapter . A versão deve ser 1.0.1243.0 ou superior.

  7. Clique no botão Instalar . A caixa de diálogo Visualizar alterações é aberta para adicionar o WebView2 ao projeto principal.

  8. Clique no botão OK .

    O Visual Studio deve ser semelhante à seção Etapa acima, exceto que agora, o Gerenciador de Pacotes NuGet está aberto para o projeto principal em vez do projeto WinRTAdapter .

  9. Selecione Arquivo>, Salvar Tudo (Ctrl+Shift+S).

O SDK de pré-lançamento do WebView2 agora está instalado para o projeto principal.

Etapa 6: Gerar código-fonte para APIs host selecionadas

Em seguida, configure a ferramenta wv2winrt (a ferramenta WebView2 WinRT JS Projection) para incorporar as classes WinRT que você deseja usar. Isso gera arquivos de origem que serão compilados. A geração de código para essas APIs permite que seu código JavaScript do lado da Web chame essas APIs.

Nas etapas de exemplo abaixo, especificaremos dois Windows namespaces, e a ferramenta wv2winrt gerará código-fonte apenas para APIs nesses namespaces:

Posteriormente, quando o aplicativo de exemplo estiver em execução, você chamará essas APIs do Console do DevTools, para demonstrar que essas APIs especificadas do lado do host podem ser chamadas a partir do código do lado da Web.

Especifique o namespace e a classe da seguinte maneira:

  1. No Gerenciador de Soluções, clique com o botão direito do mouse no projeto WinRTAdapter e selecione Propriedades. A caixa de diálogo Páginas de Propriedades do WinRTAdapter é aberta.

  2. À esquerda, expanda e selecione Propriedades> comunsWebView2.

  3. Defina Usar as APIs do WinRT WebView2 como Não. Isso ocorre para que o SDK do WebView2 não copie o componente WebView2 WinRT para a saída do projeto. Este projeto WinRTAdapter não está chamando nenhuma API WinRT WebView2, portanto, não precisa do componente WinRT.

  4. Defina Use a ferramenta wv2winrt como Sim.

  5. Defina Usar maiúsculas e minúsculas do JavaScript como Sim.

  6. Na linha Incluir filtros , clique na coluna à direita, clique no menu suspenso da célula e clique em Editar. A caixa de diálogo Incluir filtros é aberta.

  7. Na caixa de texto superior, cole as seguintes cadeias de caracteres em linhas separadas, sem espaços em branco à direita ou à esquerda:

    Windows.System.UserProfile
    Windows.Globalization.Language
    

    Caixa de diálogo incluir filtros

    Você precisa especificar o nome completo dos namespaces ou classes, conforme mostrado acima.

  8. Clique no botão OK para fechar a caixa de diálogo Incluir filtros .

  9. Verifique se a caixa de diálogo Páginas de Propriedades do WinRTAdapter se parece com o seguinte, para este passo a passo:

    A caixa de diálogo 'Páginas de Propriedades do WinRTAdapter', com 'Propriedades Comuns > WebView2' expandidas

  10. Clique no botão OK para fechar a caixa de diálogo Páginas de Propriedades .

  11. Selecione Arquivo>, Salvar Tudo (Ctrl+Shift+S).

Adicionando uma referência apontando para o projeto do adaptador

Em seguida, adicione uma referência no projeto principal, apontando para o projeto do adaptador.

No projeto principal, como MyUWPGetStartApp, adicione uma referência que aponte para o projeto WinRTAdapter , da seguinte maneira:

  1. No Gerenciador de Soluções, expanda o projeto principal, como MyUWPGetStartApp, clique com o botão direito do mouse em Referências e selecione Adicionar Referência. A caixa de diálogo Gerenciador de Referências é aberta.

  2. Na árvore à esquerda, selecione Projetos. Marque a caixa de seleção WinRTAdapter :

    A caixa de seleção WinRTAdapter na caixa de diálogo Gerenciador de Referências do projeto principal

  3. Clique no botão OK para fechar a caixa de diálogo Gerenciador de referências .

  4. Selecione Arquivo>, Salvar Tudo (Ctrl+Shift+S).

Gerar o código de API

Em seguida, gere o código da API:

  1. Clique com o botão direito do mouse no projeto WinRTAdapter e selecione Compilar.

    O código-fonte é gerado para namespaces ou classes que você especificou na caixa de diálogo Incluir filtros da ferramenta wv2winrt (a ferramenta de projeção WebView2 WinRT JS):

    • Windows.System.UserProfile namespace
    • Windows.Globalization.Language classe
  2. Após a conclusão da compilação, selecione Arquivo>Salvar Tudo (Ctrl+Shift+S).

Importante

Se você instalou uma versão de lançamento do SDK do WebView2 e seu build falhar com error MIDL2011: [msg]unresolved type declaration [context]: Microsoft.Web.WebView2.Core.ICoreWebView2DispatchAdapter [ RuntimeClass 'WinRTAdapter.DispatchAdapter' ], esse é um problema na versão de lançamento do SDK do WebView2 e você precisará alterar Use as APIs do WebView2 WinRT para Sim nas etapas acima.

Como alternativa, adicione o seguinte após o último </ItemGroup> no arquivo do projeto WinRTAdapter.vcxproj:

<ItemGroup Condition="'$(WebView2UseDispatchAdapter)' == 'true'">
 <Reference Include="$(WebView2SDKPath)lib\Microsoft.Web.WebView2.Core.winmd">
   <!-- wv2winrt needs Dispatch Adapter metadata to generate code -->
 </Reference>
</ItemGroup>

Substitua $(WebView2SDKPath) pelo diretório em que o SDK do WebView2 foi instalado, com um \ no final. Por exemplo: ..\<sample-directory>\packages\Microsoft.Web.WebView2.1.0.1264.42\.

Etapa 7: Atualizar a estrutura de destino (somente WinUI 3)

Se seu aplicativo for para WinUI 2 (UWP), ignore esta etapa.

Etapa 8: adicionar o objeto host no projeto principal

Em seguida, passe o objeto WinRT do lado nativo do aplicativo host para o lado Web do aplicativo host. Para fazer isso, adicione um InitializeWebView2Async método que chame AddHostObjectToScript, da seguinte maneira:

  1. Em Gerenciador de Soluções, expanda o projeto principal, como MyUWPGetStartApp, expanda MainPage.xaml e selecione MainPage.xaml.cs.

  2. Abaixo do MainPage construtor, adicione o seguinte InitializeWebView2Async método:

    private async void InitializeWebView2Async()
    {
       await WebView2.EnsureCoreWebView2Async();
       var dispatchAdapter = new WinRTAdapter.DispatchAdapter();
       WebView2.CoreWebView2.AddHostObjectToScript("Windows", dispatchAdapter.WrapNamedObject("Windows", dispatchAdapter));
    }
    

    Esse método chama AddHostObjectToScript.

    Na linha AddHostObjectToScript("Windows", ..., Windows está o namespace de nível superior. Se você tiver outros namespaces de nível superior, poderá adicionar chamadas adicionais para AddHostObjectToScript, como no exemplo a seguir:

    WebView2.CoreWebView2.AddHostObjectToScript("RuntimeComponent1", dispatchAdapter.WrapNamedObject("RuntimeComponent1", dispatchAdapter));
    

    A WrapNamedObject chamada cria um objeto wrapper para o RuntimeComponent1 namespace. A AddHostObjectToScript chamada adiciona esse objeto encapsulado ao script usando o nome RuntimeComponent1.

    Para obter diretrizes completas sobre como usar componentes WinRT personalizados, consulte Componentes WinRT personalizados (de terceiros), abaixo.

  3. MainPage No construtor, abaixothis.InitializeComponent();, adicione o seguinte código:

    InitializeWebView2Async();
    
  4. Clique com o botão direito do mouse no projeto principal, como MyUWPGetStartApp, e selecione Definir como projeto de inicialização. Negrito indica projeto de inicialização.

  5. Selecione Arquivo>, Salvar Tudo (Ctrl+Shift+S).

  6. Pressione F5 para executar o aplicativo de exemplo. O aplicativo WinUI 2 (UWP) habilitado para WebView2 é aberto:

    O aplicativo WebView2 WinUI 2 UWP

O código do lado da Web do aplicativo host (e o Console do DevTools) agora pode chamar métodos e propriedades dos namespaces ou classes especificados do objeto host.

Etapa 9: Chamar métodos e propriedades no objeto host do JavaScript do lado da Web

Acessar APIs projetadas por meio do Console do DevTools

Em seguida, use o Console do DevTools para demonstrar que o código do lado da Web pode chamar as APIs do lado do host que foram especificadas na ferramenta wv2winrt (a ferramenta de projeção WebView2 WinRT JS):

  1. Se o aplicativo não estiver em execução, no Visual Studio, pressione F5 para executar o aplicativo de exemplo.

  2. Clique na parte principal da janela do aplicativo de exemplo WebView2 para dar foco a ela e pressione Ctrl+Shift+I para abrir o Microsoft Edge DevTools. Ou clique com o botão direito do mouse na página e selecione Inspecionar.

    A janela do DevTools do Microsoft Edge é aberta.

  3. Se a janela do DevTools do Microsoft Edge não for exibida, pressione Alt+Tab para exibi-la.

  4. Na janela DevTools , selecione a guia Console .

  5. Clique no botão Limpar console (ícone Limpar console) ou clique com o botão direito do mouse no Console e selecione Limpar console. As mensagens podem aparecer periodicamente no Console.

  6. No Console do DevTools, cole o seguinte código de classe Windows.Globalization.Language e pressione Enter:

    const Windows = chrome.webview.hostObjects.sync.Windows;
    (new Windows.Globalization.Language("en-US")).displayName;
    

    O Console gera uma cadeia de caracteres de nome de idioma, como English (Estados Unidos), demonstrando que o código do lado do host (lado nativo) do aplicativo pode ser chamado a partir do código JavaScript do lado da Web:

    Usando o console do DevTools para testar a chamada de código do lado nativo a partir de código do lado da Web

  7. Tente omitir os parênteses. No Console do DevTools, insira a seguinte instrução:

    new Windows.Globalization.Language("en-US").displayName;
    

    O Console gera uma cadeia de caracteres de nome de idioma, como English (Estados Unidos).

    Da mesma forma, você pode acessar membros do namespace Windows.System.UserProfile .

  8. Feche a janela do DevTools.

  9. Feche o aplicativo.

Parabéns! Você concluiu a demonstração de exemplo de chamada de código WinRT a partir do código JavaScript.

Acessar APIs projetadas por meio de arquivos de código-fonte

Acima, usamos o console do DevTools para executar instruções JavaScript que acessam o objeto host projetado. Da mesma forma, você pode acessar o objeto host projetado de dentro dos arquivos de código-fonte. Para fazer isso, primeiro execute o código de configuração do script:

// early in setup code:
const Windows = chrome.webview.hostObjects.sync.Windows;

Em seguida, no corpo principal do código, você adiciona chamadas a objetos projetados, como a seguir:

(new Windows.Globalization.Language("en-US")).displayName;

Da mesma forma, você pode acessar Windows.System.UserProfile os membros da API.

Este é o fim das etapas do tutorial. As seções a seguir são informações gerais sobre aplicativos WinRT WebView2.

Componentes WinRT personalizados (de terceiros)

A ferramenta wv2winrt (a ferramenta de projeção WebView2 WinRT JS) dá suporte a componentes WinRT personalizados de terceiros, além de APIs WinRT do sistema operacional primário.

Componentes WinRT de terceiros com a ferramenta wv2winrt

Para usar componentes WinRT personalizados (de terceiros) com a ferramenta wv2winrt , além das etapas acima, execute também as seguintes etapas:

  1. Adicione um terceiro projeto (diferente do aplicativo principal e do projeto WinRTAdapter) à solução do Visual Studio que implementa a classe WinRT.

  2. Faça com que o projeto WinRTAdapter 'Adicione uma referência' ao seu novo terceiro projeto que contém sua classe WinRT.

  3. Atualize o filtro Incluir do projeto WinRTAdapter nas propriedades para incluir também sua nova classe.

  4. Adicione uma linha adicional para InitializeWebView2Async Para adicionar o namespace da sua classe WinRT:

    WebView2.CoreWebView2.AddHostObjectToScript("MyCustomNamespace", dispatchAdapter.WrapNamedObject("MyCustomNamespace", dispatchAdapter));

  5. Para facilitar a chamada de método da Web, opcionalmente, adicione seu proxy de sincronização de namespace como um objeto global no script. Por exemplo:

    window.MyCustomNamespace = chrome.webview.hostObjects.sync.MyCustomNamespace;

Para obter um exemplo disso, consulte o seguinte exemplo de WebView2:

Métodos assíncronos do WinRT

Seguindo as etapas do guia acima, você poderá usar proxies síncronos. Para chamadas de método assíncrono, você precisará usar chrome.webview.hostObjects.options.forceAsyncMethodMatches.

A forceAsyncMethodMatches propriedade é uma matriz de regexes, em que, se algum regex corresponder a um nome de método em um proxy de sincronização, o método será executado de forma assíncrona. Definir isso para [/Async$/] fará com que ele corresponda a qualquer método que termine com o sufixo Async. Em seguida, as chamadas de método correspondentes funcionam como um método em um proxy assíncrono e retornam uma promessa que você pode aguardar.

Exemplo:

const Windows = chrome.webview.hostObjects.sync.Windows;
chrome.webview.hostObjects.options.forceAsyncMethodMatches = [/Async$/];

let result = await Windows.System.Launcher.launchUriAsync(new Windows.Foundation.Uri('https://contoso.com/'));

Para obter mais informações, consulte a forceAsyncMethodMatches linha no método CoreWebView2.AddHostObjectToScript.

Assinando eventos do WinRT

Os eventos do WinRT também são expostos por meio dos proxies de script. Você pode adicionar e remover manipuladores de eventos de instância do WinRT e eventos estáticos do WinRT usando os addEventListener(string eventName, function handler) métodos and removeEventListener(string eventName, function handler) .

Esses métodos funcionam de maneira semelhante aos métodos DOM de mesmo nome. Chamada addEventListener com um nome de cadeia de caracteres do evento WinRT que você deseja assinar como o primeiro parâmetro e um retorno de chamada de função a ser chamado sempre que o evento for gerado. Chamar removeEventListener com os mesmos parâmetros cancela a assinatura desse evento. Por exemplo:

const Windows = chrome.webview.hostObjects.sync.Windows;
const coreApplication = Windows.ApplicationModel.Core.CoreApplication;
const coreApplicationView = coreApplication.getCurrentView();
const titleBar = coreApplicationView.titleBar;
titleBar.addEventListener('IsVisibleChanged', () => {
    console.log('titlebar visibility changed to: ' + titleBar.isVisible);
});

Para um evento WinRT que fornece argumentos de evento, eles são fornecidos como o primeiro parâmetro para a função do manipulador de eventos. Por exemplo, o Windows.Foundation.Collections.PropertySet.MapChanged evento tem IMapChangedEventArgs<string, object> o objeto event arg e esse objeto é fornecido como o parâmetro para o retorno de chamada.

const Windows = chrome.webview.hostObjects.sync.Windows;
const propertySet = new Windows.Foundation.Collections.PropertySet();
propertySet.addEventListener('MapChanged', eventArgs => {
    const key = eventArgs.key;
    const collectionChange = eventArgs.collectionChange;
    // ...
});

Além disso, o objeto event args terá as seguintes propriedades:

Nome da propriedade Descrição
target O objeto que gerou o evento
type O nome da cadeia de caracteres do evento
detail Uma matriz de todos os parâmetros fornecidos ao representante do WinRT

Fazer com que os proxies JavaScript AddHostObjectToScript atuem mais como outras APIs JavaScript

AddHostObjectToScript o padrão é o uso de proxies assíncronos e detalhados, mas você pode fazer com que os AddHostObjectToScript proxies JavaScript atuem mais como outras APIs JavaScript. Para ler mais sobre AddHostObjectToScript e seu comportamento padrão, consulte AddHostObjectToScript. Além disso, se você estiver migrando um aplicativo host da projeção do JavaScript WinRT em aplicativos UWP JavaScript ou do WebView baseado em EdgeHTML, talvez queira usar a abordagem a seguir para corresponder melhor ao comportamento anterior.

Para fazer com que os AddHostObjectToScript proxies JavaScript ajam mais como outras APIs JavaScript, defina as seguintes propriedades:

  • chrome.webview.hostObjects.option.defaultSyncProxy - Os proxies podem ser assíncronos ou síncronos. Normalmente, sabemos, ao chamar um método em um proxy síncrono, que o resultado também deve ser um proxy síncrono. Mas, em alguns casos, perdemos esse contexto, como quando fornecemos uma referência a uma função para o código nativo e, em seguida, o código nativo chama essa função posteriormente. Nesses casos, o proxy será assíncrono, a menos que essa propriedade esteja definida.

  • chrome.webview.hostObjects.options.forceAsyncMethodMatches - Esta é uma matriz de expressões regulares. Se você chamar um método em um proxy síncrono, a chamada do método será realmente executada de forma assíncrona se o nome do método corresponder a uma cadeia de caracteres ou expressão regular que esteja nessa matriz. Definir esse valor como [/Async$/] fará com que qualquer método que termine com Async seja uma chamada de método assíncrono. Se um método assíncrono não corresponder aqui e não for forçado a ser assíncrono, o método será invocado de forma síncrona, bloqueando a execução do JavaScript de chamada e, em seguida, retornando a resolução da promessa, em vez de retornar uma promessa.

  • chrome.webview.hostObjects.options.ignoreMemberNotFoundError - Se você tentar obter o valor de uma propriedade de um proxy e a propriedade não existir na classe nativa correspondente, você obterá uma exceção - a menos que você defina essa propriedade como true, caso em que o comportamento corresponderá ao comportamento de projeção do Chakra WinRT (e comportamento geral do JavaScript) e retornará undefined sem erros.

Chakra A projeção do WinRT coloca os namespaces do WinRT diretamente no objeto raiz. Em contraste:

  • AddHostObjectToScript coloca proxies raiz assíncronos em chrome.webview.hostObjects.
  • AddHostObjectToScript coloca a sincronização de proxies raiz em chrome.webview.hostObjects.sync.

Para acessar proxies raiz onde o código de projeção do Chakra WinRT esperaria, você pode atribuir os locais de namespace do WinRT do proxy raiz ao objeto raiz. Por exemplo:

window.Windows = chrome.webview.hostObjects.sync.Windows;

Para garantir que o JavaScript que configura tudo isso seja executado antes de qualquer outra coisa, você pode adicionar a instrução acima ao seu JavaScript ou pode dizer ao WebView2 para injetar a instrução acima para você antes de executar qualquer outro script, usando o CoreWebView2.AddScriptToExecuteOnDocumentCreatedAsync método.

O exemplo a seguir demonstra as técnicas acima:

webview.CoreWebView2.AddScriptToExecuteOnDocumentCreatedAsync(
            "(() => {" +
                    "if (chrome && chrome.webview) {" +
                        "console.log('Setting up WinRT projection options');" +
                        "chrome.webview.hostObjects.options.defaultSyncProxy = true;" +
                        "chrome.webview.hostObjects.options.forceAsyncMethodMatches = [/Async$/,/AsyncWithSpeller$/];" +
                        "chrome.webview.hostObjects.options.ignoreMemberNotFoundError = true;"  +
                        "window.Windows = chrome.webview.hostObjects.sync.Windows;" +
                    "}" +
                "})();");

Obter informações sobre propriedades do WebView2

As informações sobre as propriedades do WebView2 estão disponíveis em dois locais:

  • As Páginas de Propriedades do projeto WinRTAdapter.
  • wv2winrt.exe ajuda de linha de comando. Esta é a ferramenta wv2winrt (a ferramenta de projeção WebView2 WinRT JS).

Páginas de Propriedades do projeto WinRTAdapter

Nas Páginas de Propriedades do projeto WinRTAdapter, para obter ajuda sobre uma propriedade, clique em uma linha de propriedade. A ajuda é mostrada na parte inferior da caixa de diálogo:

Propriedades listadas nas Páginas de Propriedades do WinRTAdapter

Ajuda de linha de comando para propriedades wv2winrt.exe

A ajuda de linha de comando fornece wv2winrt.exe informações sobre os parâmetros da ferramenta wv2winrt (a ferramenta WebView2 WinRT JS Projection). Por exemplo:

Parâmetro Descrição
verbose Liste algum conteúdo para padronizar, incluindo quais arquivos foram criados e informações sobre as regras de inclusão e exclusão.
include A lista como acima excluirá namespaces e runtimeclasses por padrão, exceto aqueles listados. As declarações de inclusão podem ser namespaces que incluem tudo nesse namespace ou nomes de classe de runtimepara incluir apenas essa classe de runtime.
use-javascript-case Altera o código gerado para produzir nomes de métodos, nomes de propriedade e assim por diante, que usam o mesmo estilo de uso de maiúsculas e minúsculas que a projeção do WinRT do JavaScript de Chakra. O padrão é produzir nomes que correspondam ao winrt.
output-path Define o caminho no qual os arquivos gerados serão gravados.
output-namespace Define o namespace a ser usado para a classe WinRT gerada.
winmd-paths Uma lista delimitada por espaço de todos os arquivos winmd que devem ser examinados para geração de código.

Confira também

Tutorial e amostra:

Referência da API:

Artigo equivalente ao .NET: