Compartir a través de

Llamada al código winRT del lado nativo desde el código del lado web

  • Artículo

El código JavaScript del lado web puede acceder a métodos y propiedades de WinRT de lado nativo, con la ayuda de la herramienta wv2winrt (la herramienta proyección de WinRT JS de WebView2). La herramienta wv2winrt genera los archivos de código necesarios para el código JavaScript y habilita el uso de métodos y propiedades de cualquier API de WinRT, entre los que se incluyen:

  • Las API de WinRT de la aplicación host WebView2.
  • API de Windows WinRT.
  • API de WinRT de terceros.

Para obtener más información sobre por qué desea que el código JavaScript del lado web acceda a los métodos y propiedades de la aplicación host de WinRT, consulte la introducción de Llamada a código nativo desde código del lado web.

Por qué WinRT y .NET usan diferentes enfoques

Este artículo es para las API de WinRT WebView2, no para las API webview2 de .NET. El código de C# de este artículo compilará, pero no se ejecutará, para las API de WebView2 de .NET. Llamar con AddHostObjectToScript el código de C# de este artículo para las API webView2 de .NET generaría un mensaje de error.

La herramienta wv2winrt (la herramienta de proyección de WinRT JS de WebView2) es necesaria al proyectar objetos WinRT, ya que WinRT no admite IDispatch ni ningún otro mecanismo para inspeccionar e interactuar dinámicamente con objetos WinRT, que las plataformas Win32 y .NET de WebView2 admiten. Para el uso de .NET de AddHostObjectToScript, consulte Llamada a código de lado nativo desde código del lado web en lugar de este artículo.

Diferencias de configuración para WinUI 3 frente a WinUI 2

Si la aplicación WebView2 de WinRT tiene como destino WinUI 3 (SDK de Aplicaciones para Windows) en lugar de WinUI 2 (UWP), esta es una introducción a los pasos específicos de WinUI 3 que se proporcionan más adelante:

  • En una aplicación no empaquetada, debe realizar pasos adicionales que se encuentran en el artículo "Mejora de aplicaciones de escritorio no empaquetadas mediante componentes de Windows Runtime".

  • Agregue WinRTAdapter a CsWinRTIncludes.

  • En el caso de las aplicaciones winUI 3 (SDK de Aplicaciones para Windows), el proyecto de aplicación principal tiene una referencia a WinAppSDK que incluye directamente su propia copia de los archivos del SDK de WebView2, por lo que no puede incluir una referencia al SDK de WebView2 en el proyecto de aplicación principal sin generar mensajes de error.

  • La versión del adaptador del proyecto no tiene que coincidir.

  • Después de instalar las opciones "predeterminadas" para Visual Studio 2022 Community Edition, en Instalador de Visual Studio, haga clic en la tarjeta .NET y, a continuación, a la derecha, active la casilla SDK de Aplicaciones para Windows Plantillas de C#.

  • Si la plantilla de proyecto correcta sigue sin aparecer: en el Instalador de Visual Studio, haga clic en la tarjeta de UWP para seleccionarla, active la casilla herramientas de C++ v143 de la derecha y, a continuación, haga clic en el botón Modificar.

Estrategia y objetivo final de este ejemplo

Estrategia

Este artículo le guiará por los siguientes pasos principales:

  1. Cree un proyecto de WinRTAdapter para la herramienta wv2winrt (la herramienta Proyección de WinRT JS de WebView2).

  2. En este ejemplo, especifique las siguientes API del lado host para la proyección:

  3. Ejecute la herramienta wv2winrt para generar código fuente de C++/WinRT para los espacios de nombres o clases seleccionados.

  4. Llame a AddHostObjectToScript en el proyecto principal de WinUI.

  5. Llame a métodos y propiedades en el objeto host desde el código JavaScript del lado web (o desde la consola de DevTools).

Objetivo final

En primer lugar, elegiremos algunas API de WinRT a las que nos interesa llamar desde código JavaScript. En este ejemplo, usaremos la clase WinRT Language , que se encuentra en el Windows.Globalization espacio de nombres, para las aplicaciones para UWP de Windows. La clase Windows.Globalization.Language permite obtener información de idioma del sistema operativo nativo del cliente.

En la aplicación host WebView2, el código JavaScript del lado web puede acceder a los métodos y propiedades del Language objeto que se encuentra en el código nativo.

Acceso a las API proyectadas a través de la consola de DevTools

Al final de este tutorial de ejemplo, usará la consola de Microsoft Edge DevTools para probar la lectura de la propiedad del displayName host de la Language clase :

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

A continuación English (United States), la consola de DevTools generará , u otro nombre para mostrar de idioma, lo que demuestra que ha llamado a código nativo desde código JavaScript del lado web:

Uso de la consola de DevTools para probar la llamada a código nativo desde código del lado web

De forma similar, puede acceder a los miembros del espacio de nombres Windows.System.UserProfile .

Acceso a las API proyectadas a través de archivos de código fuente

De forma similar, en los archivos de código fuente en lugar de en la consola de DevTools, puede acceder al objeto host proyectado. En primer lugar, ejecute el código de instalación para el script:

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

A continuación, en el cuerpo principal del código, se agregan llamadas a objetos proyectados, como los siguientes:

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

De forma similar, puede acceder a los miembros del espacio de nombres Windows.System.UserProfile .

Comencemos

Paso 1: Crear u obtener un proyecto WebView2 básico

Instalar Visual Studio

  • Si Visual Studio 2015 o posterior aún no está instalado, en una ventana o pestaña independiente, vea Instalar Visual Studio en Configurar el entorno de desarrollo para WebView2. Siga los pasos de esa sección y vuelva a esta página y continúe con los pasos siguientes. En el presente artículo se muestran capturas de pantalla de Visual Studio Community Edición 2022.

Instalación de un canal de versión preliminar de Microsoft Edge

  • Si aún no está instalado un canal de versión preliminar de Microsoft Edge (Beta, Desarrollo o Canary), en una ventana o pestaña independiente, consulte Instalación de un canal de vista previa de Microsoft Edge en Configuración del entorno de desarrollo para WebView2. Siga los pasos de esa sección y vuelva a esta página y continúe con los pasos siguientes.

Creación o apertura de un proyecto WebView2 básico

  1. Realice cualquiera de los siguientes enfoques para obtener un proyecto de inicio de línea base que contenga un par de líneas de código WebView2 que inserte el control WebView2:

  2. En la unidad local, abra el .sln archivo que obtuvo anteriormente, como la solución de repositorio Samples:

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

    La solución de ejemplo se abre en Visual Studio:

    Adición de un nuevo proyecto para la herramienta wv2winrt

  3. En Visual Studio, seleccione Depurar>Iniciar depuración. Esto compila el proyecto y, a continuación, ejecuta la versión de línea base del proyecto. Se abre la aplicación de línea base, como la ventana MyUWPGetStartApp :

    Ventana de ejemplo para UWP de WebView2 WinUI 2

    Se muestra una aplicación WinUI 2 (UWP) que tiene un control WebView agregado, establecido para navegar inicialmente a Bing.com. Esta es la aplicación que resulta de realizar los pasos descritos en Introducción a WebView2 en aplicaciones WinUI 2 (UWP).

  4. Cierre la ventana de la aplicación.

Paso 2: Agregar un proyecto de WinRTAdapter para la herramienta wv2winrt

A continuación, cree un proyecto de WinRTAdapter para la herramienta wv2winrt (la herramienta Proyección de WinRT JS de WebView2). Este proyecto compila una biblioteca a la salida del código que se genera mediante la ejecución de la herramienta. Este código generado permite que las API de WinRT se expongan en el control WebView2.

Agregue un proyecto para la herramienta wv2winrt , como se indica a continuación:

  1. En Visual Studio, abra el proyecto WinUI del paso anterior.

  2. En Explorador de soluciones, haga clic con el botón derecho en la solución (no en el proyecto) y, a continuación, seleccione Agregar>nuevo proyecto. Se abre el cuadro de diálogo Agregar un nuevo proyecto .

  3. En el cuadro de texto Buscar, escriba Windows Runtime Componente (C++/WinRT).

    Enfoque alternativo: Si no agregas un proyecto con la plantilla de proyecto para Windows Runtime Component (C++/WinRT) como se describe en los pasos numerados siguientes, tendrás que instalar en su lugar la carga de trabajo de desarrollo de Plataforma universal de Windows siguiendo los pasos descritos en Introducción a C++/WinRT en aplicaciones > para UWP.

  4. Seleccione la tarjeta componente de Windows Runtime (C++/WinRT) y, a continuación, haga clic en el botón Siguiente:

    Selección de la tarjeta componente de Windows Runtime (C++/WinRT) en el cuadro de diálogo

    Nota: Asegúrese de que la plantilla incluye "C++/WinRT" en su nombre. Si esta plantilla no aparece, instale la carga de trabajo de desarrollo de Plataforma universal de Windows desde el Instalador de Visual Studio. Si usa Visual Studio 2019 y sigue sin encontrar la plantilla, instale las plantillas y el visualizador de C++/WinRT para la extensión VS2019 desde Extensiones > de Visual Studio > Administrar extensiones.

    Se abre la ventana Configurar el nuevo proyecto .

Configuración y creación del proyecto

  1. En el cuadro de texto Nombre del proyecto , asigne al proyecto el nombre Project, específicamente WinRTAdapter. Nota: Por ahora, debe usar este nombre de proyecto específico.

    En la ventana

    La ruta de acceso de la captura de pantalla anterior refleja el enfoque de clonación del repositorio de ejemplos.

  2. Haga clic en el botón Crear.

    Se abre el cuadro de diálogo Nuevo proyecto de Windows :

    Cuadro de diálogo

  3. Haga clic en el botón Aceptar .

    El proyecto WinRTAdapter se crea y se agrega en Explorador de soluciones junto al proyecto principal:

    El proyecto winRTAdapter recién creado

  4. SeleccioneGuardar todo en archivo> (Ctrl+Mayús+S).

La herramienta wv2winrt (la herramienta de proyección WebView2 WinRT JS) se ejecutará en este proyecto de WinRTAdapter . En un paso siguiente, generará código para las clases seleccionadas en este proyecto.

Paso 3: Instalar la biblioteca de implementación de Windows para el proyecto WinRTAdapter

En el proyecto WinRTAdapter, instale la Biblioteca de implementación de Windows (WIL), como se indica a continuación:

  1. En Explorador de soluciones, haga clic con el botón derecho en el proyecto WinRTAdapter y, a continuación, seleccione Administrar paquetes NuGet. Se abre la ventana Administrador de paquetes NuGet en Visual Studio.

  2. En la ventana Administrador de paquetes NuGet , haga clic en la pestaña Examinar .

  3. En la ventana Administrador de paquetes NuGet , en el cuadro Buscar , escriba Biblioteca de implementación de Windows y, a continuación, seleccione la tarjeta Biblioteca de implementación de Windows :

    Administrador de paquetes NuGet, seleccionando el paquete

  4. Haga clic en el botón Instalar . Se abre el cuadro de diálogo Vista previa de cambios :

    Cuadro de diálogo Vista previa de cambios de WIL para el proyecto winRTAdapter

  5. Haga clic en el botón Aceptar .

  6. SeleccioneGuardar todo en archivo> (Ctrl+Mayús+S).

WIL ya está instalado para el proyecto WinRTAdapter . Biblioteca de implementación de Windows (WIL) es una biblioteca de C++ solo de encabezado para facilitar el uso de la codificación COM para Windows. Proporciona interfaces de C++ legibles y seguras para tipos para los patrones de codificación COM de Windows.

Paso 4: Instalación del SDK de versión preliminar de WebView2 para el proyecto winRTAdapter

En el proyecto WinRTAdapter, instale también una versión preliminar del SDK de WebView2, como se indica a continuación:

  1. En Explorador de soluciones, haga clic con el botón derecho en el proyecto WinRTAdapter y, a continuación, seleccione Administrar paquetes NuGet. Se abre la ventana Administrador de paquetes NuGet.

  2. En la ventana Administrador de paquetes NuGet , haga clic en la pestaña Examinar .

  3. Active la casilla Incluir versión preliminar .

  4. En el cuadro Buscar , escriba WebView2.

  5. Haga clic en la tarjeta Microsoft.Web.WebView2 . La información detallada aparece en el área central de la ventana.

  6. En la lista desplegable Versión , seleccione una versión preliminar del SDK de WebView2 o asegúrese de que está seleccionada la versión preliminar más reciente . La versión debe ser 1.0.1243.0 o posterior. Tenga en cuenta el número de versión que seleccione.

    Administrador de paquetes NuGet, seleccionando el paquete del SDK de WebView2, para el proyecto WinRTAdapter

  7. Haga clic en el botón Instalar . Se abre el cuadro de diálogo Vista previa de cambios :

    Cuadro de diálogo Vista previa de cambios para agregar el SDK de WebView2 al proyecto de WinRTAdapter

  8. Haga clic en el botón Aceptar .

  9. SeleccioneGuardar todo en archivo> (Ctrl+Mayús+S).

El SDK de versión preliminar de WebView2 ahora está instalado para el proyecto winRTAdapter .

Paso 5: Instalar el SDK de versión preliminar de WebView2 (solo WinUI 2)

En el proyecto principal, como MyUWPGetStartApp, instale la misma versión preliminar del SDK de WebView2 que instaló para el proyecto WinRTAdapter , como se indica a continuación:

  1. En Explorador de soluciones, haga clic con el botón derecho en el proyecto principal, como MyUWPGetStartApp y, a continuación, seleccione Administrar paquetes NuGet. Se abre la ventana Administrador de paquetes NuGet.

  2. Active la casilla Incluir versión preliminar .

  3. Seleccione la pestaña Examinar .

  4. En el cuadro Buscar , escriba WebView2.

  5. Haga clic en la tarjeta Microsoft.Web.WebView2 . La información detallada aparece en el área central de la ventana.

  6. En la lista desplegable Versión , seleccione una versión preliminar del SDK de WebView2 o asegúrese de que está seleccionada la versión preliminar más reciente . Asegúrese de usar la misma versión que el proyecto WinRTAdapter; para las aplicaciones WebView2 de WinRT que tienen como destino WinUI 2 (UWP), debe ser la misma versión que para el proyecto WinRTAdapter . La versión debe ser 1.0.1243.0 o posterior.

  7. Haga clic en el botón Instalar . Se abre el cuadro de diálogo Vista previa de cambios para agregar WebView2 al proyecto principal.

  8. Haga clic en el botón Aceptar .

    Visual Studio debe ser similar a la sección Paso anterior, excepto que ahora, el Administrador de paquetes NuGet está abierto para el proyecto principal en lugar del proyecto WinRTAdapter .

  9. SeleccioneGuardar todo en archivo> (Ctrl+Mayús+S).

El SDK de versión preliminar de WebView2 ahora está instalado para el proyecto principal.

Paso 6: Generación de código fuente para las API de host seleccionadas

A continuación, configure la herramienta wv2winrt (la herramienta proyección JS de WinRT webView2) para incorporar las clases de WinRT que desea usar. Esto genera archivos de origen que, a continuación, se compilarán. La generación de código para estas API permite que el código JavaScript del lado web llame a estas API.

En los pasos de ejemplo siguientes, especificaremos dos Windows espacios de nombres y la herramienta wv2winrt generará código fuente solo para las API en esos espacios de nombres:

Más adelante, cuando se ejecute la aplicación de ejemplo, llamará a estas API desde la consola de DevTools para demostrar que se pueden llamar a estas API del lado host especificadas desde el código del lado web.

Especifique el espacio de nombres y la clase de la siguiente manera:

  1. En Explorador de soluciones, haga clic con el botón derecho en el proyecto WinRTAdapter y, a continuación, seleccione Propiedades. Se abre el cuadro de diálogo Páginas de propiedades de WinRTAdapter .

  2. A la izquierda, expanda y seleccione Propiedades comunes>WebView2.

  3. Establezca Use WebView2 WinRT API (Usar API de WinRT de WebView2 ) en No. Esto es para que el SDK de WebView2 no copie el componente WebView2 WinRT en la salida del proyecto. Este proyecto de WinRTAdapter no llama a ninguna API de WinRT de WebView2, por lo que no necesita el componente WinRT.

  4. Establezca Usar la herramienta wv2winrt en Sí.

  5. Establezca Usar caso de JavaScript en Sí.

  6. En la fila Incluir filtros , haga clic en la columna de la derecha, haga clic en el menú desplegable de esa celda y, a continuación, haga clic en Editar. Se abre el cuadro de diálogo Incluir filtros .

  7. En el cuadro de texto superior, pegue las siguientes cadenas en líneas independientes, sin espacios en blanco iniciales o finales:

    Windows.System.UserProfile
Windows.Globalization.Language

    Cuadro de diálogo Incluir filtros

    Debe especificar el nombre completo de los espacios de nombres o clases, como se muestra anteriormente.

  8. Haga clic en el botón Aceptar para cerrar el cuadro de diálogo Incluir filtros .

  9. Asegúrese de que el cuadro de diálogo Páginas de propiedades de WinRTAdapter sea similar al siguiente, para este tutorial:

    Cuadro de diálogo

  10. Haga clic en el botón Aceptar para cerrar el cuadro de diálogo Páginas de propiedades .

  11. SeleccioneGuardar todo en archivo> (Ctrl+Mayús+S).

Agregar una referencia que apunte al proyecto del adaptador

A continuación, agregue una referencia en el proyecto principal, apuntando al proyecto de adaptador.

En el proyecto principal, como MyUWPGetStartApp, agregue una referencia que apunte al proyecto WinRTAdapter , como se indica a continuación:

  1. En Explorador de soluciones, expanda el proyecto principal, como MyUWPGetStartApp, haga clic con el botón derecho en Referencias y seleccione Agregar referencia. Se abre el cuadro de diálogo Administrador de referencias .

  2. En el árbol de la izquierda, seleccione Proyectos. Active la casilla WinRTAdapter :

    Casilla WinRTAdapter en el cuadro de diálogo Administrador de referencias del proyecto principal

  3. Haga clic en el botón Aceptar para cerrar el cuadro de diálogo Administrador de referencias .

  4. SeleccioneGuardar todo en archivo> (Ctrl+Mayús+S).

Generación del código de API

A continuación, genere el código de API:

  1. Haga clic con el botón derecho en el proyecto WinRTAdapter y, a continuación, seleccione Compilar.

    El código fuente se genera para espacios de nombres o clases que especificó en el cuadro de diálogo Incluir filtros de la herramienta wv2winrt (la herramienta Proyección de WinRT JS de WebView2):

    • Espacio de nombres Windows.System.UserProfile
    • Clase Windows.Globalization.Language

  2. Una vez completada la compilación, seleccioneGuardar todo el archivo> (Ctrl+Mayús+S).

Importante

Si instaló una versión de lanzamiento del SDK de WebView2 y se produce un error en la compilación, error MIDL2011: [msg]unresolved type declaration [context]: Microsoft.Web.WebView2.Core.ICoreWebView2DispatchAdapter [ RuntimeClass 'WinRTAdapter.DispatchAdapter' ]se trata de un problema en la versión de lanzamiento del SDK de WebView2 y tendrá que cambiar Usar las API de WinRT de WebView2 a Sí en los pasos anteriores.

Como alternativa, agregue lo siguiente después de la última </ItemGroup> vez en el archivo WinRTAdapter.vcxprojde proyecto :

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

Reemplace por $(WebView2SDKPath) el directorio donde se instaló el SDK de WebView2, por un \ al final. Por ejemplo: ..\<sample-directory>\packages\Microsoft.Web.WebView2.1.0.1264.42\.

Paso 7: Actualizar la plataforma de destino (solo WinUI 3)

Si la aplicación es para WinUI 2 (UWP), omita este paso.

Paso 8: Agregar el objeto host en el proyecto principal

A continuación, pase el objeto WinRT del lado nativo de la aplicación host al lado web de la aplicación host. Para ello, agregue un InitializeWebView2Async método que llame a AddHostObjectToScript, como se indica a continuación:

  1. En Explorador de soluciones, expanda el proyecto principal, como MyUWPGetStartApp, expanda MainPage.xaml y, a continuación, seleccione MainPage.xaml.cs.

  2. Debajo del MainPage constructor, agregue el siguiente 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 llama a AddHostObjectToScript.

    En la línea AddHostObjectToScript("Windows", ..., Windows es el espacio de nombres de nivel superior. Si tiene otros espacios de nombres de nivel superior, puede agregar llamadas adicionales a AddHostObjectToScript, como en el ejemplo siguiente:

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

    La WrapNamedObject llamada crea un objeto contenedor para el espacio de RuntimeComponent1 nombres. La AddHostObjectToScript llamada agrega ese objeto encapsulado al script con el nombre RuntimeComponent1.

    Para obtener instrucciones completas sobre cómo usar componentes de WinRT personalizados, consulte Componentes personalizados (de terceros) de WinRT, a continuación.

  3. En el MainPage constructor siguiente this.InitializeComponent();, agregue el código siguiente:

    InitializeWebView2Async();

  4. Haga clic con el botón derecho en el proyecto principal, como MyUWPGetStartApp y, a continuación, seleccione Establecer como proyecto de inicio. Negrita indica el proyecto de inicio.

  5. SeleccioneGuardar todo en archivo> (Ctrl+Mayús+S).

  6. Presione F5 para ejecutar la aplicación de ejemplo. Se abre la aplicación WinUI 2 (UWP) habilitada para WebView2:

    La aplicación WebView2 WinUI 2 para UWP

El código del lado web de la aplicación host (y la consola de DevTools) ahora puede llamar a métodos y propiedades de los espacios de nombres o clases especificados del objeto host.

Paso 9: Llamar a métodos y propiedades en el objeto host desde JavaScript del lado web

Acceso a las API proyectadas a través de la consola de DevTools

A continuación, use la consola de DevTools para demostrar que el código del lado web puede llamar a las API del lado host que se especificaron en la herramienta wv2winrt (la herramienta Proyección de WinRT JS de WebView2):

  1. Si la aplicación no se está ejecutando, en Visual Studio, presione F5 para ejecutar la aplicación de ejemplo.

  2. Haga clic en la parte principal de la ventana de la aplicación de ejemplo WebView2 para darle el foco y, a continuación, presione Ctrl+Mayús+I para abrir Microsoft Edge DevTools. O bien, haga clic con el botón derecho en la página y, a continuación, seleccione Inspeccionar.

    Se abre la ventana Microsoft Edge DevTools.

  3. Si no se muestra la ventana Microsoft Edge DevTools, presione Alt+Tab para mostrarla.

  4. En la ventana DevTools , seleccione la pestaña Consola .

  5. Haga clic en el botón Borrar consola (icono Borrar consola) o haga clic con el botón derecho en la consola y, a continuación, seleccione Borrar consola. Los mensajes pueden aparecer periódicamente en la consola.

  6. En la consola de DevTools, pegue el siguiente código de clase Windows.Globalization.Language y presione Entrar:

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

    La consola genera una cadena de nombre de idioma, como English (United States), que muestra que se puede llamar al código del lado host (lado nativo) de la aplicación desde código JavaScript del lado web:

    Uso de la consola de DevTools para probar la llamada a código nativo desde código del lado web

  7. Intente omitir los paréntesis. En la consola de DevTools, escriba la siguiente instrucción:

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

    La consola genera una cadena de nombre de idioma, como English (United States).

    De forma similar, puede acceder a los miembros del espacio de nombres Windows.System.UserProfile .

  8. Cierre la ventana DevTools.

  9. Cierre la aplicación.

¡Enhorabuena! Ha terminado la demostración de ejemplo de llamada al código WinRT desde código JavaScript.

Acceso a las API proyectadas a través de archivos de código fuente

Anteriormente, usamos la consola de DevTools para ejecutar instrucciones JavaScript que acceden al objeto host proyectado. Del mismo modo, puede acceder al objeto host proyectado desde los archivos de código fuente. Para ello, primero ejecute el código de instalación para el script:

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

A continuación, en el cuerpo principal del código, se agregan llamadas a objetos proyectados, como los siguientes:

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

Puede acceder de forma similar a Windows.System.UserProfile los miembros de la API.

Este es el final de los pasos del tutorial. Las secciones siguientes son información general sobre las aplicaciones WinRT de WebView2.

Componentes de WinRT personalizados (de terceros)

La herramienta wv2winrt (la herramienta de proyección WebView2 WinRT JS) admite componentes de WinRT de terceros personalizados, además de las API de WinRT del sistema operativo de primer nivel.

Componentes de WinRT de terceros con la herramienta wv2winrt

Para usar componentes de WinRT personalizados (de terceros) con la herramienta wv2winrt , además de los pasos anteriores, siga estos pasos:

  1. Agregue un tercer proyecto (distinto de la aplicación principal y el proyecto de WinRTAdapter) a la solución de Visual Studio que implementa la clase WinRT.

  2. Haga que el proyecto de WinRTAdapter "Agregar una referencia" al nuevo tercer proyecto que contiene la clase WinRT.

  3. Actualice el filtro Include del proyecto WinRTAdapter en las propiedades para incluir también la nueva clase.

  4. Agregue una línea adicional a InitializeWebView2Async para agregar el espacio de nombres de la clase winrt:

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

  5. Para facilitar la llamada a métodos desde la web, agregue opcionalmente el proxy de sincronización de espacio de nombres como un objeto global en el script. Por ejemplo:

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

Para obtener un ejemplo de esto, vea el siguiente ejemplo de WebView2:

Métodos asincrónicos de WinRT

Siguiendo los pasos descritos en la guía anterior, debería poder usar servidores proxy sincrónicos. Para las llamadas a métodos asincrónicos, deberá usar chrome.webview.hostObjects.options.forceAsyncMethodMatches.

La forceAsyncMethodMatches propiedad es una matriz de expresiones regulares, donde si alguna expresión regular coincide con un nombre de método en un proxy de sincronización, el método se ejecutará de forma asincrónica en su lugar. Si se establece en , [/Async$/] coincidirá con cualquier método que termine con el sufijo Async. A continuación, las llamadas al método coincidente funcionan igual que un método en un proxy asincrónico y devuelve una promesa que puede esperar.

Ejemplo:

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 obtener más información, vea la forceAsyncMethodMatches fila del método CoreWebView2.AddHostObjectToScript.

Suscripción a eventos de WinRT

Los eventos de WinRT también se exponen a través de los servidores proxy de script. Puede agregar y quitar controladores de eventos de instancias de WinRT y eventos estáticos de WinRT mediante los addEventListener(string eventName, function handler) métodos y removeEventListener(string eventName, function handler) .

Estos métodos funcionan de forma similar a los métodos DOM del mismo nombre. Llame a addEventListener con un nombre de cadena del evento WinRT que desea suscribir como primer parámetro y una devolución de llamada de función a la que se llamará cada vez que se produzca el evento. Al llamar a removeEventListener con los mismos parámetros, se cancela la suscripción a ese evento. Por ejemplo:

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 un evento WinRT que proporciona argumentos de eventos, se proporcionan como el primer parámetro para la función del controlador de eventos. Por ejemplo, el Windows.Foundation.Collections.PropertySet.MapChanged evento tiene IMapChangedEventArgs<string, object> el objeto arg de evento y ese objeto se proporciona como parámetro para la devolución de llamada.

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;
    // ...
});

El objeto de argumentos de evento tendrá además las siguientes propiedades:

Nombre de la propiedad Description
target Objeto que generó el evento
type Nombre de cadena del evento
detail Matriz de todos los parámetros proporcionados al delegado de WinRT

Hacer que los servidores proxy de JavaScript AddHostObjectToScript actúen más como otras API de JavaScript

AddHostObjectToScript el valor predeterminado es usar servidores proxy asincrónicos y detallados, pero puede hacer que los AddHostObjectToScript servidores proxy de JavaScript actúen más como otras API de JavaScript. Para obtener más información sobre AddHostObjectToScript y su comportamiento predeterminado, vea AddHostObjectToScript. Además, si va a migrar una aplicación host desde la proyección de WinRT de JavaScript en aplicaciones para UWP de JavaScript, o desde el WebView basado en EdgeHTML, es posible que desee usar el siguiente enfoque para que coincida mejor con ese comportamiento anterior.

Para que los AddHostObjectToScript servidores proxy de JavaScript actúen más como otras API de JavaScript, establezca las siguientes propiedades:

  • chrome.webview.hostObjects.option.defaultSyncProxy - Los servidores proxy pueden ser asincrónicos o sincrónicos. Normalmente sabemos, al llamar a un método en un proxy sincrónico, que el resultado también debe ser un proxy sincrónico. Pero en algunos casos, perdemos ese contexto, por ejemplo, al proporcionar una referencia a una función a código nativo y, a continuación, código nativo más adelante llamando a esa función. En estos casos, el proxy será asincrónico, a menos que se establezca esta propiedad.

  • chrome.webview.hostObjects.options.forceAsyncMethodMatches - Se trata de una matriz de expresiones regulares. Si llama a un método en un proxy sincrónico, la llamada al método se realizará de forma asincrónica si el nombre del método coincide con una cadena o expresión regular que se encuentra en esta matriz. Si se establece este valor en [/Async$/], cualquier método que termine con Async será una llamada al método asincrónico. Si un método asincrónico no coincide aquí y no se ve obligado a ser asincrónico, el método se invocará sincrónicamente, lo que bloqueará la ejecución de la llamada a JavaScript y, a continuación, devolverá la resolución de la promesa, en lugar de devolver una promesa.

  • chrome.webview.hostObjects.options.ignoreMemberNotFoundError - Si intenta obtener el valor de una propiedad de un proxy y la propiedad no existe en la clase nativa correspondiente, obtendrá una excepción, a menos que establezca esta propiedad trueen , en cuyo caso el comportamiento coincidirá con el comportamiento de proyección de WinRT de Chakra (y el comportamiento general de JavaScript) y devolverá undefined sin ningún error.

La proyección de Chakra WinRT coloca los espacios de nombres de WinRT directamente en el objeto raíz. Por el contrario:

  • AddHostObjectToScript coloca servidores proxy raíz asincrónicos en chrome.webview.hostObjects.
  • AddHostObjectToScript coloca servidores proxy raíz de sincronización en chrome.webview.hostObjects.sync.

Para acceder a los servidores proxy raíz donde el código de proyección de Chakra WinRT esperaría, puede asignar las ubicaciones del espacio de nombres winRT del proxy raíz al objeto raíz. Por ejemplo:

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

Para asegurarse de que el JavaScript que establece todo esto se ejecuta antes que cualquier otra cosa, puede agregar la instrucción anterior a Su JavaScript, o bien puede indicar a WebView2 que inserte la instrucción anterior antes de ejecutar cualquier otro script mediante el CoreWebView2.AddScriptToExecuteOnDocumentCreatedAsync método .

En el ejemplo siguiente se muestran las técnicas anteriores:

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;" +
                    "}" +
                "})();");

Obtener información sobre las propiedades de WebView2

La información sobre las propiedades de WebView2 está disponible en dos lugares:

  • Páginas de propiedades del proyecto WinRTAdapter.
  • wv2winrt.exe ayuda de línea de comandos. Esta es la herramienta wv2winrt (la herramienta de proyección de WebView2 WinRT JS).

Páginas de propiedades del proyecto WinRTAdapter

En las páginas de propiedades del proyecto WinRTAdapter, para obtener ayuda sobre una propiedad, haga clic en una fila de propiedades. La ayuda se muestra en la parte inferior del cuadro de diálogo:

Propiedades que aparecen en las páginas de propiedades de WinRTAdapter

Ayuda de línea de comandos para propiedades de wv2winrt.exe

La ayuda de línea de comandos para wv2winrt.exe proporciona información sobre los parámetros de la herramienta wv2winrt (la herramienta proyección de WinRT JS de WebView2). Por ejemplo:

Parámetro Description
verbose Enumere el contenido de forma estándar, incluidos los archivos que se han creado y la información sobre las reglas de inclusión y exclusión.
include La lista como se mencionó anteriormente excluirá espacios de nombres y runtimeclasses de forma predeterminada, excepto los enumerados. Las declaraciones de inclusión pueden ser espacios de nombres que incluyen todo en ese espacio de nombres o nombres de clase runtime para incluir solo esa clase runtimeclass.
use-javascript-case Cambia el código generado para generar nombres de métodos, nombres de propiedad, etc., que usan el mismo estilo de mayúsculas y minúsculas que la proyección de WinRT de JavaScript de Chakra. El valor predeterminado es generar nombres que coincidan con winrt.
output-path Establece la ruta de acceso en la que se escribirán los archivos generados.
output-namespace Establece el espacio de nombres que se va a usar para la clase WinRT generada.
winmd-paths Una lista delimitada por espacios de todos los archivos winmd que se deben examinar para la generación de código.

Vea también

Tutorial y ejemplo:

Referencia de API:

Artículo equivalente de .NET: