Partilhar via

Chamar código WinRT do lado nativo do código web

  • Artigo

O 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 De projeção JS do WebView2 WinRT). A ferramenta wv2winrt gera arquivos de código necessários para o código JavaScript e permite o uso de métodos e propriedades de qualquer APIs WinRT, incluindo:

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

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

Por que WinRT e .NET usam abordagens diferentes

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

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

Diferenças de configuração para WinUI 3 vs. WinUI 2

Se o aplicativo WinRT WebView2 tiver como destino o WinUI 3 (SDK do Aplicativo Windows) em vez do WinUI 2 (UWP), aqui está uma visão geral das etapas específicas do WinUI 3 que são fornecidas mais abaixo:

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

  • Adicionar WinRTAdapter a CsWinRTIncludes.

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

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

  • Depois de instalar opções "padrão" para a edição community do Visual Studio 2022, em Instalador do Visual Studio, clique no cartão .NET e, à direita, selecione a caixa de seleção SDK do Aplicativo Windows Modelos C#.

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

Estratégia e meta final deste exemplo

Estratégia

Este artigo orienta você pelas seguintes etapas main:

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

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

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

  4. Chame AddHostObjectToScript, em seu projeto WinUI main.

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

Meta final

Primeiro, escolheremos algumas APIs WinRT que estamos interessados em chamar do código JavaScript. Para este exemplo, usaremos a classe WinRT Language , que está no namespace, para aplicativos UWP do Windows.Globalization 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 de DevTools

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

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

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

Usar o Console de DevTools para testar a chamada de código nativo do 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 e não no Console de DevTools, você pode acessar o objeto host projetado. Primeiro, você executa o código de configuração para o script:

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

Em seguida, no main corpo do código, você adiciona chamadas a objetos projetados, como o seguinte:

(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 básico do WebView2

Instalar o Visual Studio

  • Se o Visual Studio 2015 ou posterior ainda não estiver instalado, em uma janela ou guia separada, consulte Instalar o Visual Studio em Configurar seu ambiente de desenvolvimento para WebView2. Siga as etapas nessa seção e, em seguida, retorne a esta página e continue as etapas abaixo. O artigo atual mostra capturas de tela para Visual Studio Community Edição 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 nessa 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 abordagens a seguir para obter um projeto inicial de linha de base que contém algumas linhas de código WebView2 que inserem o controle WebView2:

  2. Em sua unidade local, abra o .sln arquivo obtido acima, como a solução de repositório 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:

    Adicionar um novo projeto para a ferramenta wv2winrt

  3. No Visual Studio, selecione Depurar>Iniciar Depuração. Isso cria 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 Exemplo de UWP do WebView2 WinUI 2

    Mostrado é um aplicativo WinUI 2 (UWP) que tem um controle WebView adicionado, definido para navegar inicialmente para Bing.com. Este é o aplicativo que resulta de fazer as 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 De projeção JS do WinRT do WebView2). Este projeto cria uma biblioteca fora do código que é gerada executando a ferramenta. Esse código gerado permite que APIs WinRT sejam expostas no controle WebView2.

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

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

  2. Em 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 Windows Runtime Componente (C++/WinRT).

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

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

    Selecionando o cartão C++/WinRT (Componente Windows Runtime) na caixa de diálogo 'Adicionar um novo projeto'

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

    A janela Configurar seu novo projeto é aberta.

Configurar e criar o projeto

  1. Na caixa de texto Nome do projeto , nomeie o Projeto, especificamente, WinRTAdapter. Nota: Por enquanto, você deve usar esse nome de projeto específico.

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

    O caminho na captura de tela acima reflete a abordagem de clonar o 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 'Novo Projeto do Windows'

  3. Clique no botão OK .

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

    O projeto WinRTAdapter recém-criado

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

A ferramenta wv2winrt (a ferramenta de Projeção JS do WinRT do WebView2) será executada neste projeto WinRTAdapter . Em uma etapa abaixo, você gerará código para 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 maneira:

  1. Em 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 do NuGet é aberta no Visual Studio.

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

  3. Na janela Gerenciador de Pacotes do NuGet, na caixa Pesquisa, insira Biblioteca de Implementação do Windows e selecione a Biblioteca de Implementação do Windows cartão:

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

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

    A caixa de diálogo Alterações de Visualização para WIL para o projeto WinRTAdapter

  5. Clique no botão OK .

  6. SelecioneSalvar todos osarquivos> (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 com segurança de tipo para padrões de codificação com 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 maneira:

  1. Em 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 do NuGet é aberta.

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

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

  4. Na caixa Pesquisa , insira WebView2.

  5. Clique no cartão Microsoft.Web.WebView2. Informações detalhadas são exibidas na área intermediária da janela.

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

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

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

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

  8. Clique no botão OK .

  9. SelecioneSalvar todos osarquivos> (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 main, 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. Em Gerenciador de Soluções, clique com o botão direito do mouse no projeto main, como MyUWPGetStartApp e selecione Gerenciar Pacotes NuGet. A janela do Gerenciador de Pacotes do NuGet é aberta.

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

  3. Selecione a guia Procurar .

  4. Na caixa Pesquisa , insira WebView2.

  5. Clique no cartão Microsoft.Web.WebView2. Informações detalhadas são exibidas na área intermediária da janela.

  6. Na lista suspensa Versão , selecione uma versão de pré-lançamento do SDK do WebView2 ou verifique se o pré-lançamento mais recente está selecionado. Use a mesma versão usada pelo projeto WinRTAdapter; para aplicativos WinRT WebView2 que visam o WinUI 2 (UWP), essa precisa ser a mesma versão 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 Alterações de Visualização é aberta para adicionar o WebView2 ao projeto main.

  8. Clique no botão OK .

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

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

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

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

Em seguida, configure a ferramenta wv2winrt (a ferramenta De projeção do WinRT JS do WebView2) para incorporar as classes WinRT que você deseja usar. Isso gera arquivos de origem que serão compilados. Gerar código para essas APIs permite que o 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 de DevTools para demonstrar que essas APIs especificadas do lado do host podem ser chamadas do código do lado da Web.

Especifique o namespace e a classe da seguinte maneira:

  1. Em 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 da Propriedade WinRTAdapter é aberta.

  2. À esquerda, expanda e selecione Propriedades Comuns>WebView2.

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

  4. Defina Usar a ferramenta wv2winrt como Sim.

  5. Defina Usar caso JavaScript como Sim.

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

  7. Na caixa de texto mais alta, cole as seguintes cadeias de caracteres em linhas separadas, sem espaço em branco à direita ou à direita:

    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 da Propriedade WinRTAdapter se parece com a seguinte, para este passo a passo:

    A caixa de diálogo 'Páginas da Propriedade WinRTAdapter', com 'Propriedades Comuns > WebView2' expandida

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

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

Adicionar uma referência apontando para o projeto do adaptador

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

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

  1. Em Gerenciador de Soluções, expanda o projeto main, 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ência é aberta.

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

    A caixa de seleção WinRTAdapter na caixa de diálogo Gerenciador de Referência para o projeto main

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

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

Gerar o código da 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 especificadas na caixa de diálogo Incluir filtros da ferramenta wv2winrt (a ferramenta de Projeção JS do WinRT do WebView2):

    • Windows.System.UserProfile namespace
    • Windows.Globalization.Language classe

  2. Depois que a construção for concluída, selecioneSalvar todos osarquivos> (Ctrl+Shift+S).

Importante

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

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

<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, por um \ no final. Por exemplo: ..\<sample-directory>\packages\Microsoft.Web.WebView2.1.0.1264.42\.

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

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

Etapa 8: Adicionar o objeto host no projeto main

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 chama AddHostObjectToScript, da seguinte maneira:

  1. Em Gerenciador de Soluções, expanda o projeto main, 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 a AddHostObjectToScript, como o 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, confira Componentes WinRT personalizados (de terceiros), abaixo.

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

    InitializeWebView2Async();

  4. Clique com o botão direito do mouse no projeto main, como MyUWPGetStartApp e selecione Definir como projeto de inicialização. Bold indica o projeto de inicialização.

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

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

    O aplicativo UWP do WebView2 WinUI 2

O código web do aplicativo host (e o Console de 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 de DevTools

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

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

  2. Clique na main parte da janela do aplicativo de exemplo WebView2 para dar-lhe foco 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 Microsoft Edge DevTools é aberta.

  3. Se a janela Microsoft Edge DevTools 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 de DevTools, cole o seguinte código da 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 (United States), demonstrando que o código do lado do host (nativo) do aplicativo pode ser chamado do código JavaScript do lado da Web:

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

  7. Tente omitir os parênteses. No Console de 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 (United States).

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

  8. Feche a janela DevTools.

  9. Feche o aplicativo.

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

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

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

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

Em seguida, no main corpo do código, você adiciona chamadas a objetos projetados, como o seguinte:

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

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

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

Componentes WinRT personalizados (de terceiros)

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

Componentes WinRT de terceiros com a ferramenta wv2winrt

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

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

  2. Tenha o projeto WinRTAdapter 'Adicionar 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 adicionar o namespace da classe winrt:

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

  5. Para uma chamada de método fácil 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, confira o seguinte exemplo do WebView2:

Métodos WinRT assíncronos

Seguindo as etapas no guia acima, você deve ser capaz de 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 qualquer 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 como fará com que ele corresponda a [/Async$/] 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 retorna 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.

Inscrever-se em eventos WinRT

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

Esses métodos funcionam de forma semelhante aos métodos DOM de mesmo nome. Chame 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 assinaturas 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 args de evento, eles são fornecidos como o primeiro parâmetro para a função de manipulador de eventos. Por exemplo, o Windows.Foundation.Collections.PropertySet.MapChanged evento tem IMapChangedEventArgs<string, object> objeto arg de evento 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;
    // ...
});

O objeto args de evento também terá as seguintes propriedades:

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

Fazer com que proxies JavaScript AddHostObjectToScript ajam mais como outras APIs JavaScript

AddHostObjectToScript é padrão usar proxies assíncronos e verbosos, mas você pode fazer com que os AddHostObjectToScript proxies JavaScript ajam 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 WinRT do JavaScript em aplicativos UWP JavaScript ou do WebView baseado em EdgeHTML, talvez queira usar a abordagem a seguir para corresponder melhor a esse 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 - 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 ao fornecer uma referência a uma função ao código nativo e, em seguida, código nativo mais tarde chamando essa função. Nesses casos, o proxy será assíncrono, a menos que essa propriedade seja definida.

  • chrome.webview.hostObjects.options.forceAsyncMethodMatches - Essa é uma matriz de expressões regulares. Se você chamar um método em um proxy síncrono, a chamada de 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 nesta 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 da chamada JavaScript e 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, nesse caso, o comportamento corresponderá ao comportamento de projeção Chakra WinRT (e ao comportamento geral do JavaScript) e retornará undefined sem erro.

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

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

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

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

Para garantir que o JavaScript que define tudo isso seja executado antes de qualquer outra coisa, você pode adicionar a instrução acima ao JavaScript ou 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 lugares:

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

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 propriedade WinRTAdapter

Ajuda de linha de comando para propriedades de wv2winrt.exe

Ajuda de linha de comando para wv2winrt.exe fornecer informações sobre os parâmetros da ferramenta wv2winrt (a ferramenta De projeção JS do WinRT do WebView2). Por exemplo:

Parâmetro Descrição
verbose Liste algum conteúdo para padrão, 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 runtimeclass para incluir apenas essa classe de runtime.
use-javascript-case Altera o código gerado para produzir nomes de métodos, nomes de propriedades e assim por diante, que usam o mesmo estilo de invólucro que a projeção WinRT do JavaScript 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 exemplo:

Referência de API:

Artigo equivalente do .NET: