Partilhar via


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

O código JavaScript do lado da Web pode aceder a métodos e propriedades WinRT do lado nativo, com a ajuda da ferramenta wv2winrt (a ferramenta WebView2 WinRT JS Projection). A ferramenta wv2winrt gera os ficheiros de código necessários para o código JavaScript e permite a utilização de métodos e propriedades de quaisquer APIs WinRT, incluindo:

  • As APIs WinRT da sua aplicação anfitriã WebView2.
  • APIs WinRT do Windows.
  • APIs WinRT de terceiros.

Para obter mais informações sobre o motivo pelo qual pretende que o código JavaScript do lado da Web aceda aos métodos e propriedades da sua aplicação anfitriã WinRT, veja a introdução de Chamar código nativo do código do lado da Web.

Por que motivo o WinRT e o .NET utilizam diferentes abordagens

Este artigo destina-se às APIs WinRT WebView2 e não às APIs .NET WebView2. O código C# neste artigo irá criar, mas não executar, para APIs .NET WebView2. Chamar AddHostObjectToScript através do código C# deste artigo para APIs .NET WebView2 produziria uma mensagem de erro.

A ferramenta wv2winrt (a ferramenta WebView2 WinRT JS Projection) é necessária para projetar objetos WinRT, porque o WinRT não suporta IDispatch nem qualquer outro mecanismo para inspecionar e interagir dinamicamente com objetos WinRT, que as plataformas Win32 e .NET do WebView2 suportam. Para a utilização do .NET do 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 vs. WinUI 2

Se a sua aplicação WinRT WebView2 tiver como destino o WinUI 3 (Windows App SDK) em vez do WinUI 2 (UWP), eis uma descrição geral dos passos específicos do WinUI 3 que são fornecidos mais abaixo:

  • Numa aplicação não empacotada, tem de efetuar passos adicionais que estão no artigo "Melhorar Aplicações de Ambiente de Trabalho não empacotadas com Windows Runtime Componentes".

  • Adicionar WinRTAdapter a CsWinRTIncludes.

  • Para aplicações WinUI 3 (Windows App SDK), o projeto de aplicação principal tem uma referência ao WinAppSDK que inclui diretamente a sua própria cópia dos ficheiros do SDK WebView2, pelo que não pode incluir uma referência ao SDK WebView2 no projeto da aplicação principal sem produzir mensagens de erro.

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

  • Depois de instalar as opções "predefinidas" para a Edição da Comunidade do Visual Studio 2022, em Visual Studio Installer, clique no card .NET e, à direita, selecione a caixa de verificação Windows App Modelos C# do SDK.

  • Se o modelo de projeto correto continuar a não aparecer: no Visual Studio Installer, clique na card UWP para o selecionar, selecione a caixa de verificação v143 C++ ferramentas à direita e, em seguida, clique no botão Modificar.

Estratégia e objetivo final deste exemplo

Estratégia

Este artigo explica-lhe os seguintes passos principais:

  1. Crie um projeto WinRTAdapter para a ferramenta wv2winrt (a ferramenta WebView2 WinRT JS Projection).

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

  3. Execute a ferramenta wv2winrt para gerar código fonte C++/WinRT para as classes ou espaços de nomes selecionados.

  4. Chame AddHostObjectToScript, no seu projeto WinUI principal.

  5. Chame métodos e propriedades no objeto anfitrião a partir do código JavaScript do lado da Web (ou da Consola de DevTools).

Objetivo final

Primeiro, vamos escolher algumas APIs WinRT que estamos interessados em chamar a partir do código JavaScript. Neste exemplo, vamos utilizar a classe WinRT Language , que está no espaço de nomes, para aplicações UWP do Windows.Globalization Windows. A Classe Windows.Globalization.Language permite obter informações de idioma do SO nativo do cliente.

Na aplicação anfitriã WebView2, o código JavaScript do lado da Web pode, em seguida, aceder a métodos e propriedades no Language objeto que está no código do lado nativo.

Aceder a APIs projetadas através da Consola de DevTools

No final deste exemplo, irá utilizar a Consola do Microsoft Edge DevTools para testar a leitura da propriedade do displayName anfitrião da Language classe:

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

A Consola de DevTools irá então produzir English (United States), ou outro nome a apresentar do idioma, demonstrando que chamou código do lado nativo do código JavaScript do lado da Web:

Utilizar a Consola de DevTools para testar a chamada de código nativo do código do lado da Web

Pode aceder de forma semelhante aos membros do Espaço de Nomes Windows.System.UserProfile .

Aceder a APIs projetadas através de ficheiros de código fonte

Da mesma forma, nos ficheiros de código fonte e não na Consola de DevTools, pode aceder ao objeto anfitrião 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, adicione chamadas a objetos projetados, como o seguinte:

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

Pode aceder de forma semelhante aos membros do Espaço de Nomes Windows.System.UserProfile .

Vamos começar!

Passo 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, numa janela ou separador separador, consulte Instalar o Visual Studio em Configurar o ambiente Dev para WebView2. Siga os passos nessa secção e, em seguida, regresse a esta página e continue os passos abaixo. O artigo atual mostra capturas de ecrã do Visual Studio Community Edition 2022.

Instalar um canal de pré-visualização do Microsoft Edge

  • Se um canal de pré-visualização do Microsoft Edge (Beta, Dev ou Canary) ainda não estiver instalado, numa janela ou separador separador separado, consulte Instalar um canal de pré-visualização do Microsoft Edge em Configurar o ambiente Dev para WebView2. Siga os passos nessa secção e, em seguida, regresse a esta página e continue os passos abaixo.

Criar ou abrir um projeto WebView2 básico

  1. Efetue qualquer uma das seguintes abordagens para obter um projeto inicial de linha de base que contenha algumas linhas de código WebView2 que incorporam o controlo WebView2:

  2. Na unidade local, abra o .sln ficheiro que obteve 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. Esta ação cria o projeto e, em seguida, executa a versão de linha de base do projeto. A aplicação de linha de base é aberta, como a janela MyUWPGetStartApp :

    A janela de Exemplo do WinUI 2 UWP do WebView2

    Apresentada é uma aplicação WinUI 2 (UWP) que tem um controlo WebView adicionado, definida para navegar inicialmente para Bing.com. Esta é a aplicação que resulta da realização dos passos em Introdução ao WebView2 em aplicações WinUI 2 (UWP).

  4. Feche a janela da aplicação.

Passo 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 a partir do código gerado ao executar a ferramenta. Este código gerado permite que as APIs WinRT sejam expostas no controlo WebView2.

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

  1. No Visual Studio, abra o projeto WinUI, a partir do passo anterior.

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

  3. Na caixa de texto Procurar, introduza Windows Runtime Componente (C++/WinRT).

    Abordagem alternativa: Se não adicionar um projeto com o modelo de projeto para o Componente Windows Runtime (C++/WinRT), conforme descrito nos passos numerados abaixo, terá de instalar a carga de trabalho de desenvolvimento Plataforma Universal do Windows, seguindo os passos em Aplicações > UWP Introdução ao C++/WinRT.

  4. Selecione o Componente Windows Runtime (C++/WinRT) card e, em seguida, clique no botão Seguinte:

    Selecionar o Componente Windows Runtime (C++/WinRT) card na caixa de diálogo

    Nota: Certifique-se de que o modelo inclui "C++/WinRT" no respetivo nome. Se este modelo não estiver listado, instale a carga de trabalho de desenvolvimento Plataforma Universal do Windows a partir do Visual Studio Installer. Se estiver a utilizar o Visual Studio 2019 e ainda não conseguir encontrar o modelo, instale os modelos C++/WinRT e o visualizador da extensão VS2019 a partir das Extensões > Gerir Extensões do Visual Studio>.

    É aberta a janela Configurar o novo projeto .

Configurar e criar o projeto

  1. Na caixa de texto Nome do projeto , atribua o nome Project, especificamente WinRTAdapter. Nota: Por agora, tem de utilizar este nome de projeto específico.

    Na janela

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

  2. Clique no botão Criar .

    É aberta a caixa de diálogo Novo Projeto do Windows :

    A caixa de diálogo

  3. Clique no botão OK .

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

    O projeto WinRTAdapter recentemente criado

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

A ferramenta wv2winrt (a ferramenta WebView2 WinRT JS Projection) será executada neste projeto WinRTAdapter . Num passo abaixo, irá gerar código para classes selecionadas neste projeto.

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

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

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

  2. Na janela Gestor de Pacotes NuGet , clique no separador Procurar .

  3. Na janela Gestor de Pacotes NuGet, na caixa Procurar, introduza Biblioteca de Implementação do Windows e, em seguida, selecione a Biblioteca de Implementação do Windows card:

    Gestor de Pacotes NuGet, selecionando o pacote

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

    A caixa de diálogo Pré-visualizar Alterações para WIL para o projeto WinRTAdapter

  5. Clique no botão OK .

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

WIL está agora instalado para o projeto WinRTAdapter . A Biblioteca de Implementação do Windows (WIL) é uma biblioteca C++ apenas com cabeçalho para facilitar a utilização da codificação COM para o Windows. Fornece interfaces C++ legíveis e seguras para padrões de codificação COM do Windows.

Passo 4: Instalar o SDK de pré-lançamento webView2 para o projeto WinRTAdapter

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

  1. No Gerenciador de Soluções, clique com o botão direito do rato no projeto WinRTAdapter e, em seguida, selecione Gerir Pacotes NuGet. É aberta a janela Gestor de Pacotes NuGet.

  2. Na janela Gestor de Pacotes NuGet , clique no separador Procurar .

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

  4. Na caixa Procurar , introduza WebView2.

  5. Clique no card Microsoft.Web.WebView2. São apresentadas informações detalhadas na área central da janela.

  6. Na lista pendente Versão , selecione uma versão de pré-lançamento do SDK WebView2 ou certifique-se de que a opção Pré-lançamento mais recente está selecionada. A versão tem de ser 1.0.1243.0 ou superior. Tenha em atenção o número da versão que selecionar.

    Gestor de Pacotes NuGet, ao selecionar o pacote SDK WebView2, para o projeto WinRTAdapter

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

    A caixa de diálogo Pré-visualizar Alterações para adicionar o SDK WebView2 ao projeto WinRTAdapter

  8. Clique no botão OK .

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

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

Passo 5: Instalar o SDK de pré-lançamento webView2 (apenas WinUI 2)

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

  1. No Gerenciador de Soluções, clique com o botão direito do rato no projeto principal, como MyUWPGetStartApp e, em seguida, selecione Gerir Pacotes NuGet. É aberta a janela Gestor de Pacotes NuGet.

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

  3. Selecione o separador Procurar.

  4. Na caixa Procurar , introduza WebView2.

  5. Clique no card Microsoft.Web.WebView2. São apresentadas informações detalhadas na área central da janela.

  6. Na lista pendente Versão , selecione uma versão de pré-lançamento do SDK WebView2 ou certifique-se de que a opção Pré-lançamento mais recente está selecionada. Certifique-se de que utiliza a mesma versão utilizada pelo projeto WinRTAdapter; para aplicações WinRT WebView2 que visam o WinUI 2 (UWP), esta tem de ser a mesma versão do projeto WinRTAdapter . A versão tem de ser 1.0.1243.0 ou superior.

  7. Clique no botão Instalar . É aberta a caixa de diálogo Pré-visualizar Alterações para adicionar o WebView2 ao projeto principal.

  8. Clique no botão OK .

    O Visual Studio deve ter um aspeto semelhante à secção Passo acima, exceto que agora, o Gestor de Pacotes NuGet está aberto para o projeto principal em vez do projeto WinRTAdapter .

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

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

Passo 6: Gerar código fonte para APIs de anfitrião selecionadas

Em seguida, configure a ferramenta wv2winrt (a ferramenta WebView2 WinRT JS Projection) para incorporar as classes WinRT que pretende utilizar. Isto gera ficheiros de origem que serão depois compilados. A geração de código para estas APIs permite que o código JavaScript do lado da Web chame estas APIs.

Nos passos de exemplo abaixo, vamos especificar dois Windows espaços de nomes e a ferramenta wv2winrt irá gerar código fonte apenas para APIs nesses espaços de nomes:

Mais tarde, quando a aplicação de exemplo estiver em execução, irá chamar estas APIs a partir da Consola de DevTools para demonstrar que estas APIs do lado do anfitrião especificadas podem ser chamadas a partir do código do lado da Web.

Especifique o espaço de nomes e a classe da seguinte forma:

  1. No Gerenciador de Soluções, clique com o botão direito do rato no projeto WinRTAdapter e, em seguida, selecione Propriedades. É aberta a caixa de diálogo Páginas de Propriedades do WinRTAdapter .

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

  3. Defina Utilizar APIs WinRT WebView2 como Não. Isto é para que o SDK WebView2 não copie o componente WinRT webView2 para a saída do projeto. Este projeto WinRTAdapter não está a chamar nenhuma APIs WinRT webView2, pelo que não precisa do componente WinRT.

  4. Defina Utilizar a ferramenta wv2winrt como Sim.

  5. Defina Utilizar caso JavaScript como Sim.

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

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

    Windows.System.UserProfile
    Windows.Globalization.Language
    

    Caixa de diálogo Incluir filtros

    Tem de especificar o nome completo dos espaços de nomes ou classes, conforme mostrado acima.

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

  9. Certifique-se de que a caixa de diálogo Páginas de Propriedades do WinRTAdapter tem o seguinte aspeto, para estas instruções:

    A caixa de diálogo

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

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

Adicionar uma referência que aponta 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 forma:

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

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

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

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

  4. SelecioneGuardar Todos os Ficheiros> (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 rato no projeto WinRTAdapter e, em seguida, selecione Compilar.

    O código fonte é gerado para espaços de nomes ou classes que especificou na caixa de diálogo Incluir filtros da ferramenta wv2winrt (a ferramenta WebView2 WinRT JS Projection):

    • Windows.System.UserProfile namespace
    • Windows.Globalization.Language classe
  2. Após a conclusão da compilação, selecioneGuardar Todos os Ficheiros> (Ctrl+Shift+S).

Importante

Se instalou uma versão de versão do SDK WebView2 e a compilação falhar com error MIDL2011: [msg]unresolved type declaration [context]: Microsoft.Web.WebView2.Core.ICoreWebView2DispatchAdapter [ RuntimeClass 'WinRTAdapter.DispatchAdapter' ]o , este é um problema na versão de lançamento do SDK WebView2 e terá de alterar Utilizar as APIs WinRT do WebView2 para Sim nos passos acima.

Em alternativa, adicione o seguinte após o último </ItemGroup> no ficheiro WinRTAdapter.vcxprojde 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 onde o SDK WebView2 foi instalado, por um \ no final. Por exemplo: ..\<sample-directory>\packages\Microsoft.Web.WebView2.1.0.1264.42\.

Passo 7: Atualizar o Target Framework (apenas WinUI 3)

Se a sua aplicação for para WinUI 2 (UWP), ignore este passo.

Passo 8: adicionar o objeto anfitrião no projeto principal

Em seguida, transmita o objeto WinRT do lado nativo da aplicação anfitriã para o lado Web da aplicação anfitriã. Para tal, adicione um InitializeWebView2Async método que chame AddHostObjectToScript, da seguinte forma:

  1. No Gerenciador de Soluções, expanda o projeto principal, como MyUWPGetStartApp, expanda MainPage.xaml e, em seguida, 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));
    }
    

    Este método chama AddHostObjectToScript.

    Na linha AddHostObjectToScript("Windows", ..., Windows é o espaço de nomes de nível superior. Se tiver outros espaços de nomes de nível superior, pode adicionar chamadas adicionais a AddHostObjectToScript, como no exemplo seguinte:

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

    A WrapNamedObject chamada cria um objeto wrapper para o RuntimeComponent1 espaço de nomes. A AddHostObjectToScript chamada adiciona esse objeto moldado ao script com o nome RuntimeComponent1.

    Para obter orientações completas sobre como utilizar componentes WinRT personalizados, veja 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 rato no projeto principal, como MyUWPGetStartApp e, em seguida, selecione Definir como projeto de arranque. Negrito indica o projeto de arranque.

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

  6. Prima F5 para executar a aplicação de exemplo. É aberta a aplicação WinUI 2 (UWP) ativada para WebView2:

    A aplicação WebView2 WinUI 2 UWP

O código do lado da Web da aplicação anfitriã (e a Consola de DevTools) podem agora chamar métodos e propriedades dos espaços de nomes ou classes especificados do objeto anfitrião.

Passo 9: Chamar métodos e propriedades no objeto anfitrião do JavaScript do lado da Web

Aceder a APIs projetadas através da Consola de DevTools

Em seguida, utilize a Consola de DevTools para demonstrar que o código do lado da Web pode chamar as APIs do lado do anfitrião que foram especificadas na ferramenta wv2winrt (a ferramenta WebView2 WinRT JS Projection):

  1. Se a aplicação não estiver em execução, no Visual Studio, prima F5 para executar a aplicação de exemplo.

  2. Clique na parte principal da janela da aplicação de exemplo WebView2 para o concentrar e, em seguida, prima Ctrl+Shift+I para abrir as DevTools do Microsoft Edge. Em alternativa, clique com o botão direito do rato na página e, em seguida, selecione Inspecionar.

    É aberta a janela DevTools do Microsoft Edge.

  3. Se a janela DevTools do Microsoft Edge não for apresentada, prima Alt+Tecla de Tabulação para a apresentar.

  4. Na janela DevTools , selecione o separador Consola .

  5. Clique no botão Limpar consola (Limpar consola) ou clique com o botão direito do rato na Consola e, em seguida, selecione Limpar consola. As mensagens podem aparecer periodicamente na Consola.

  6. Na Consola de DevTools, cole o seguinte código de Classe Windows.Globalization.Language e, em seguida, prima Enter:

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

    A Consola produz uma cadeia de nomes de idioma, como English (United States), que demonstra que o código do lado do anfitrião (nativo) da sua aplicação pode ser chamado a partir do código JavaScript do lado da Web:

    Utilizar a Consola de DevTools para testar a chamada de código nativo do código do lado da Web

  7. Tente omitir os parênteses. Na Consola de DevTools, introduza a seguinte instrução:

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

    A Consola produz uma cadeia de nome de idioma, como English (United States).

    Pode aceder de forma semelhante aos membros do Espaço de Nomes Windows.System.UserProfile .

  8. Feche a janela DevTools.

  9. Feche a aplicação.

Parabéns! Concluiu a demonstração de exemplo de chamar código WinRT a partir do código JavaScript.

Aceder a APIs projetadas através de ficheiros de código fonte

Acima, utilizámos a consola DevTools para executar instruções JavaScript que acedem ao objeto anfitrião projetado. Da mesma forma, pode aceder ao objeto anfitrião projetado a partir de ficheiros de código fonte. Para tal, primeiro executa 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, adicione chamadas a objetos projetados, como o seguinte:

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

Pode aceder Windows.System.UserProfile de forma semelhante aos membros da API.

Este é o fim dos passos do tutorial. As secções seguintes são informações gerais sobre as aplicações WinRT WebView2.

Componentes WinRT personalizados (de terceiros)

A ferramenta wv2winrt (a ferramenta WebView2 WinRT JS Projection) suporta componentes WinRT de terceiros personalizados, além das APIs WinRT do SO originais.

Componentes WinRT de terceiros com a ferramenta wv2winrt

Para utilizar componentes WinRT personalizados (de terceiros) com a ferramenta wv2winrt , além dos passos acima, efetue também os seguintes passos:

  1. Adicione um terceiro projeto (além da sua aplicação principal e do projeto WinRTAdapter) à sua solução do Visual Studio que implementa a sua classe WinRT.

  2. Peça ao projeto WinRTAdapter "Adicionar uma referência" ao seu novo terceiro projeto que contém a sua classe WinRT.

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

  4. Adicione uma linha adicional para InitializeWebView2Async adicionar o espaço de nomes da sua classe winrt:

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

  5. Para chamar facilmente o método a partir da Web, adicione opcionalmente o proxy de sincronização do espaço de nomes como um objeto global no script. Por exemplo:

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

Para obter um exemplo disto, veja o seguinte exemplo webView2:

Métodos WinRT assíncronos

Ao seguir os passos no guia acima, deverá conseguir utilizar proxies síncronos. Para chamadas de método assíncrono, terá de utilizar chrome.webview.hostObjects.options.forceAsyncMethodMatches.

A forceAsyncMethodMatches propriedade é uma matriz de regexes, em que, se algum regex corresponder ao nome de um método num proxy de sincronização, o método será executado de forma assíncrona. Definir isto como [/Async$/] irá fazer com que corresponda a qualquer método que termine com o sufixo Async. Em seguida, as chamadas de método correspondentes funcionam como um método num proxy assíncrono e devolvem uma promessa que 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, veja a forceAsyncMethodMatches linha no Método CoreWebView2.AddHostObjectToScript.

Subscrever eventos WinRT

Os eventos WinRT também são expostos através dos proxies de script. Pode adicionar e remover processadores de eventos de eventos WinRT de instâncias e eventos WinRT estáticos com os addEventListener(string eventName, function handler) métodos e removeEventListener(string eventName, function handler) .

Estes métodos funcionam de forma semelhante aos métodos DOM com o mesmo nome. Chame addEventListener com um nome de cadeia do evento WinRT que pretende subscrever como o primeiro parâmetro e uma chamada de retorno de função a ser chamada sempre que o evento for gerado. Chamar removeEventListener com os mesmos parâmetros anula a subscrição 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 eventos, estes são fornecidos como o primeiro parâmetro para a função de processador de eventos. Por exemplo, o Windows.Foundation.Collections.PropertySet.MapChanged evento tem IMapChangedEventArgs<string, object> o objeto arg de evento e esse objeto é fornecido como o parâmetro para a chamada de retorno.

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 do evento terá ainda as seguintes propriedades:

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

Faça com que os proxies JavaScript AddHostObjectToScript ajam mais como outras APIs JavaScript

AddHostObjectToScript a predefinição é utilizar proxies assíncronos e verbosos, mas pode fazer com que os AddHostObjectToScript proxies JavaScript ajam mais como outras APIs JavaScript. Para ler mais sobre AddHostObjectToScript o respetivo comportamento predefinido, veja AddHostObjectToScript. Além disso, se estiver a migrar uma aplicação anfitriã a partir da projeção WinRT de JavaScript em aplicações JavaScript UWP ou a partir do WebView baseado em EdgeHTML, poderá querer utilizar a seguinte abordagem para corresponder melhor a esse comportamento anterior.

Para 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 num proxy síncrono, que o resultado também deve ser um proxy síncrono. No entanto, em alguns casos, perdemos esse contexto, como quando fornecemos uma referência a uma função para código nativo e, em seguida, o código nativo chama mais tarde essa função. Nestes casos, o proxy será assíncrono, a menos que esta propriedade esteja definida.

  • chrome.webview.hostObjects.options.forceAsyncMethodMatches - Esta é uma matriz de expressões regulares. Se chamar um método num proxy síncrono, a chamada de método será realizada de forma assíncrona se o nome do método corresponder a uma cadeia ou expressão regular que esteja nesta matriz. Definir este valor como [/Async$/] fará com que qualquer método que termine com Async seja uma chamada de método assíncrona. 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, devolvendo a resolução da promessa, em vez de devolver uma promessa.

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

A projeção WinRT do Chakra coloca os espaços de nomes WinRT diretamente no objeto raiz. Por outro lado:

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

Para aceder a proxies de raiz em que o código de projeção WinRT de Chakra seria esperado, pode atribuir as localizações do espaço de nomes WinRT do proxy de raiz ao objeto raiz. Por exemplo:

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

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

O exemplo seguinte 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 as propriedades do WebView2

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

  • Páginas de Propriedades do projeto WinRTAdapter.
  • wv2winrt.exe ajuda da linha de comandos. Esta é a ferramenta wv2winrt (a ferramenta WebView2 WinRT JS Projection).

Páginas de Propriedades do projeto WinRTAdapter

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

Propriedades listadas nas Páginas de Propriedades do WinRTAdapter

Ajuda da linha de comandos para propriedades wv2winrt.exe

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

Parâmetro Descrição
verbose Liste alguns conteúdos para padrão, incluindo os ficheiros que foram criados e informações sobre as regras de inclusão e exclusão.
include A lista acima excluirá espaços de nomes e runtimeclasses por predefinição, exceto os listados. As declarações de inclusão podem ser espaços de nomes que incluem tudo nesse espaço de nomes ou nomes runtimeclass para incluir apenas essa runtimeclass.
use-javascript-case Altera o código gerado para produzir nomes de métodos, nomes de propriedades e assim sucessivamente, que utilizam o mesmo estilo de caixa que a projeção WinRT de JavaScript Chakra. A predefinição é produzir nomes que correspondam ao winrt.
output-path Define o caminho no qual os ficheiros gerados serão escritos.
output-namespace Define o espaço de nomes a utilizar para a classe WinRT gerada.
winmd-paths Uma lista delimitada por espaço de todos os ficheiros winmd que devem ser examinados para a geração de código.

Confira também

Tutorial e exemplo:

Referência da API:

Artigo equivalente a .NET: