Share via

Вызов собственного кода WinRT из веб-кода

  • Статья

Веб-код JavaScript может получить доступ к собственным методам и свойствам WinRT с помощью средства wv2winrt (средство проекции JS Для WebView2). Средство wv2winrt создает необходимые файлы кода для кода JavaScript и позволяет использовать методы и свойства любых API WinRT, включая:

  • Интерфейсы API WinRT ведущего приложения WebView2.
  • Интерфейсы API WinRT для Windows.
  • Сторонние API WinRT.

Дополнительные сведения о том, почему вы хотите, чтобы веб-код JavaScript получил доступ к методам и свойствам ведущего приложения WinRT, см. в статье Вызов собственного кода из веб-кода.

Почему WinRT и .NET используют разные подходы

Эта статья посвящена API-интерфейсам WinRT WebView2, а не API .NET WebView2. Код C#, приведенный в этой статье, будет создавать, но не выполняться для API .NET WebView2. Вызов AddHostObjectToScript кода C# этой статьи для API .NET WebView2 приведет к возникновению сообщения об ошибке.

Средство wv2winrt (средство проекции WinRT JS WebView2) требуется для проецирования объектов WinRT, так как WinRT не поддерживает IDispatch или какой-либо другой механизм для динамической проверки и взаимодействия с объектами WinRT, которые поддерживают платформы Win32 и .NET WebView2. Сведения об использовании .NET см. в статье Вызов собственного AddHostObjectToScriptкода из веб-кода вместо этой статьи.

Различия в настройке WinUI 3 и WinUI 2

Если приложение WinRT WebView2 предназначено для WinUI 3 (Windows App SDK), а не для WinUI 2 (UWP), ниже приведен обзор действий, относящихся к WinUI 3.

  • В непакуемом приложении необходимо выполнить дополнительные действия, описанные в статье Улучшение непакуемых классических приложений с помощью компонентов среда выполнения Windows.

  • Добавьте WinRTAdapter в CsWinRTIncludes.

  • Для приложений WinUI 3 (Windows App SDK) проект приложения main содержит ссылку на WinAppSDK, которая напрямую включает собственную копию файлов пакета SDK Для WebView2, поэтому вы не можете включить ссылку на пакет SDK WebView2 в проект приложения main без создания сообщений об ошибках.

  • Версия адаптера проекта не обязательно совпадает.

  • После установки параметров по умолчанию для выпуска Visual Studio 2022 Community в Visual Studio Installer щелкните карта .NET, а затем справа установите флажок Windows App SDK Шаблоны C#.

  • Если правильный шаблон проекта по-прежнему не отображается: в Visual Studio Installer щелкните карта UWP, чтобы выбрать его, установите флажок средства C++ версии 143 справа и нажмите кнопку Изменить.

Стратегия и конечная цель этого примера

Стратегия

В этой статье описаны следующие действия main.

  1. Создайте проект WinRTAdapter для средства wv2winrt (средство проекции WinRT JS WebView2).

  2. В этом примере укажите следующие API-интерфейсы на стороне узла для проекции:

  3. Запустите средство wv2winrt , чтобы создать исходный код C++/WinRT для выбранных пространств имен или классов.

  4. Вызовите AddHostObjectToScript в проекте WinUI main.

  5. Вызовите методы и свойства в объекте узла из веб-кода JavaScript (или из консоли DevTools).

Конечная цель

Во-первых, мы подберем некоторые API WinRT, которые нам нужны для вызова из кода JavaScript. В этом примере мы будем использовать класс WinRT Language , который находится в Windows.Globalization пространстве имен, для приложений Windows UWP. Класс Windows.Globalization.Language позволяет получать сведения о языке из собственной ОС клиента.

В хост-приложении WebView2 веб-код JavaScript может получить доступ к методам и свойствам Language объекта, который находится в машинном коде.

Доступ к проецируемым API через консоль DevTools

В конце этого примера пошагового руководства вы будете использовать консоль Microsoft Edge DevTools для тестирования чтения свойства Language узла displayName класса :

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

Затем консоль DevTools выведет English (United States)или другое отображаемое имя языка, демонстрируя, что вы вызвали собственный код из веб-кода JavaScript:

Использование консоли DevTools для тестирования вызова собственного кода из веб-кода

Аналогичным образом можно получить доступ к членам пространства имен Windows.System.UserProfile .

Доступ к проецируемым API через файлы исходного кода

Аналогичным образом, в файлах исходного кода, а не в консоли DevTools, вы можете получить доступ к проецируемым объекту узла. Сначала запустите код установки для скрипта:

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

Затем в main текст кода добавьте вызовы к проецируемым объектам, как показано ниже:

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

Аналогичным образом можно получить доступ к членам пространства имен Windows.System.UserProfile .

Итак, приступим!

Шаг 1. Создание или получение базового проекта WebView2

Установка Visual Studio

  • Если Visual Studio 2015 или более поздней версии еще не установлен, в отдельном окне или на вкладке см. статью Установка Visual Studioстатьи Настройка среды разработки для WebView2. Выполните действия, описанные в этом разделе, а затем вернитесь на эту страницу и выполните указанные ниже действия. В этой статье показаны снимки экрана для выпуска Visual Studio Community 2022.

Установка канала предварительной версии Microsoft Edge

  • Если канал предварительной версии Microsoft Edge (бета-версия, разработка или Canary) еще не установлен, в отдельном окне или на вкладке см . статью Установка канала предварительной версии Microsoft Edge в статье Настройка среды разработки для WebView2. Выполните действия, описанные в этом разделе, а затем вернитесь на эту страницу и выполните указанные ниже действия.

Создание или открытие базового проекта WebView2

  1. Выполните любой из следующих подходов, чтобы получить базовый начальный проект, содержащий несколько строк кода WebView2, который внедряет элемент управления WebView2:

    • Используйте предоставленный пример базового решения: Если это еще не сделано, клонируйте или скачайте репозиторий WebView2Samples на локальный диск. В отдельном окне или на вкладке см . раздел Скачивание репозитория WebView2Samplesстатьи Настройка среды разработки для WebView2. Выполните действия, описанные в этом разделе, а затем вернитесь на эту страницу и продолжите работу ниже. При этом подходе используется локальная копия https://github.com/MicrosoftEdge/WebView2Samples/tree/main/GettingStartedGuides/WinUI2_GettingStarted/MyUWPGetStartApp.sln.

    • Используйте шаблон проекта в Visual Studio, чтобы создать базовое приложение UWP и добавить элемент управления WebView2: Выполните действия, описанные в статье Начало работы с WebView2 в приложениях WinUI 2 (UWP), чтобы создать базовый начальный проект, содержащий несколько строк кода WebView2, который внедряет элемент управления WebView2.

    • Используйте существующую базу кода: Если у вас уже есть собственная база кода приложения, вы можете открыть этот проект в Visual Studio.

  2. На локальном .sln диске откройте файл, полученный выше, например решение репозитория примеров:

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

    Пример решения откроется в Visual Studio:

    Добавление нового проекта для средства wv2winrt

  3. В Visual Studio выберите Отладка>Начать отладку. При этом выполняется сборка проекта, а затем запускается базовая версия проекта. Откроется базовое приложение, например окно MyUWPGetStartApp :

    Окно примеров UWP Для WebView2 WinUI 2

    Отображается приложение WinUI 2 (UWP), в которое добавлен элемент управления WebView, для которого изначально задан переход к Bing.com. Это приложение, которое является результатом выполнения действий, описанных в статье Начало работы с WebView2 в приложениях WinUI 2 (UWP).

  4. Закройте окно приложения.

Шаг 2. Добавление проекта WinRTAdapter для средства wv2winrt

Затем создайте проект WinRTAdapter для средства wv2winrt (средство проекции JS WebView2 WinRT). Этот проект создает библиотеку из кода, созданного при запуске средства. Этот созданный код позволяет предоставлять API WinRT в элементе управления WebView2.

Добавьте проект для средства wv2winrt следующим образом:

  1. В Visual Studio откройте проект WinUI на предыдущем шаге.

  2. В Обозреватель решений щелкните правой кнопкой мыши решение (не проект), а затем выберите Добавить>новый проект. Откроется диалоговое окно Добавление нового проекта.

  3. В текстовом поле Поиск введите среда выполнения Windows Component (C++/WinRT).

    Альтернативный подход: Если вы не добавляете проект с помощью шаблона проекта для компонента среда выполнения Windows (C++/WinRT), как описано в приведенных ниже нумеруемых шагах, вам потребуется установить рабочую нагрузку разработки универсальная платформа Windows, выполнив действия, описанные в статье Общие сведения о приложениях > UWP в C++/WinRT.

  4. Выберите карта компонент среда выполнения Windows (C++/WinRT), а затем нажмите кнопку Далее:

    Выбор компонента среда выполнения Windows (C++/WinRT) карта в диалоговом окне

    Примечание: Убедитесь, что шаблон содержит "C++/WinRT" в имени. Если этот шаблон отсутствует в списке, установите рабочую нагрузку разработки универсальная платформа Windows из Visual Studio Installer. Если вы используете Visual Studio 2019 и по-прежнему не можете найти шаблон, установите расширение C++/WinRT и визуализатор для VS2019 из Visual Studio > Extensions > Manage Extensions.

    Откроется окно Настройка нового проекта .

Настройка и создание проекта

  1. В текстовом поле Имя проекта назовите Проект, в частности WinRTAdapter. Примечание: Сейчас необходимо использовать это конкретное имя проекта.

    В окне

    Путь на приведенном выше снимке экрана отражает подход клонирования репозитория примеров.

  2. Нажмите кнопку Создать.

    Откроется диалоговое окно Новый проект Windows :

    Диалоговое окно

  3. Нажмите кнопку ОК .

    Проект WinRTAdapter создается и добавляется в Обозреватель решений рядом с проектом main:

    Только что созданный проект WinRTAdapter

  4. Выберите Файл>Сохранить все (CTRL+SHIFT+S).

Средство wv2winrt (средство проекции WinRT JS WebView2) будет запущено в этом проекте WinRTAdapter . На следующем шаге вы создадите код для выбранных классов в этом проекте.

Шаг 3. Установка библиотеки реализации Windows для проекта WinRTAdapter

В проекте WinRTAdapter установите библиотеку реализации Windows (WIL) следующим образом:

  1. В Обозреватель решений щелкните правой кнопкой мыши проект WinRTAdapter и выберите Управление пакетами NuGet. Откроется окно Диспетчер пакетов NuGet в Visual Studio.

  2. В окне диспетчера пакетов NuGet откройте вкладку Обзор .

  3. В окне Диспетчер пакетов NuGet в поле Поиск введите Библиотека реализации Windows, а затем выберите библиотеку реализации Windows карта:

    Диспетчер пакетов NuGet, выбор пакета

  4. Нажмите кнопку Установить . Откроется диалоговое окно Предварительный просмотр изменений :

    Диалоговое окно Предварительный просмотр изменений для WIL для проекта WinRTAdapter

  5. Нажмите кнопку ОК .

  6. Выберите Файл>Сохранить все (CTRL+SHIFT+S).

Теперь для проекта WinRTAdapter установлен пакет WIL. Библиотека реализации Windows (WIL) — это библиотека C++, доступная только для заголовков, что упрощает использование COM-кода для Windows. Он предоставляет удобочитаемые и типобезопасные интерфейсы C++ для шаблонов кодирования COM в Windows.

Шаг 4. Установка предварительного пакета SDK для WebView2 для проекта WinRTAdapter

В проекте WinRTAdapter также установите предварительную версию пакета SDK WebView2 следующим образом:

  1. В Обозреватель решений щелкните правой кнопкой мыши проект WinRTAdapter и выберите Управление пакетами NuGet. Откроется окно Диспетчер пакетов NuGet.

  2. В окне диспетчера пакетов NuGet откройте вкладку Обзор .

  3. Установите флажок Включить предварительную версию .

  4. В поле Поиск введите WebView2.

  5. Щелкните карта Microsoft.Web.WebView2. Подробные сведения отображаются в средней области окна.

  6. В раскрывающемся списке Версия выберите предварительную версию пакета SDK для WebView2 или убедитесь, что выбрана последняя предварительная версия . Версия должна быть 1.0.1243.0 или выше. Обратите внимание, какой номер версии вы выбрали.

    Диспетчер пакетов NuGet, выбрав пакет SDK Для WebView2 для проекта WinRTAdapter

  7. Нажмите кнопку Установить . Откроется диалоговое окно Предварительный просмотр изменений :

    Диалоговое окно Предварительный просмотр изменений для добавления пакета SDK WebView2 в проект WinRTAdapter

  8. Нажмите кнопку ОК .

  9. Выберите Файл>Сохранить все (CTRL+SHIFT+S).

Пакет SDK для предварительной версии WebView2 теперь установлен для проекта WinRTAdapter .

Шаг 5. Установка предварительного пакета SDK для WebView2 (только WinUI 2)

В проекте main, например MyUWPGetStartApp, установите ту же предварительную версию пакета SDK Для WebView2, что и для проекта WinRTAdapter, как показано ниже.

  1. В Обозреватель решений щелкните правой кнопкой мыши проект main, например MyUWPGetStartApp, а затем выберите Управление пакетами NuGet. Откроется окно Диспетчер пакетов NuGet.

  2. Установите флажок Включить предварительную версию .

  3. Перейдите на вкладку Обзор .

  4. В поле Поиск введите WebView2.

  5. Щелкните карта Microsoft.Web.WebView2. Подробные сведения отображаются в средней области окна.

  6. В раскрывающемся списке Версия выберите предварительную версию пакета SDK для WebView2 или убедитесь, что выбрана последняя предварительная версия . Используйте ту же версию, что и в проекте WinRTAdapter; Для приложений WinRT WebView2, предназначенных для WinUI 2 (UWP), эта версия должна быть той же, что и для проекта WinRTAdapter . Версия должна быть 1.0.1243.0 или выше.

  7. Нажмите кнопку Установить . Откроется диалоговое окно Предварительный просмотр изменений, чтобы добавить WebView2 в проект main.

  8. Нажмите кнопку ОК .

    Visual Studio должна выглядеть примерно так, как в приведенном выше разделе Шаг, за исключением того, что теперь диспетчер пакетов NuGet открыт для проекта main вместо проекта WinRTAdapter.

  9. Выберите Файл>Сохранить все (CTRL+SHIFT+S).

Пакет SDK для предварительной версии WebView2 теперь установлен для проекта main.

Шаг 6. Создание исходного кода для выбранных API узла

Затем настройте средство wv2winrt (средство проекции WinRT JS WebView2), чтобы включить классы WinRT, которые вы хотите использовать. При этом создаются исходные файлы, которые затем будут скомпилированы. Создание кода для этих API позволяет веб-коду JavaScript вызывать эти API.

В приведенном ниже примере мы укажем два Windows пространства имен, а средство wv2winrt создаст исходный код только для API в этих пространствах имен:

Позже, когда пример приложения будет запущен, вы вызовете эти API из консоли DevTools, чтобы продемонстрировать, что указанные API на стороне узла можно вызывать из веб-кода.

Укажите пространство имен и класс следующим образом:

  1. В Обозреватель решений щелкните правой кнопкой мыши проект WinRTAdapter и выберите пункт Свойства. Откроется диалоговое окно Страницы свойств WinRTAdapter .

  2. В левой части экрана разверните узел и выберите Общие свойства>WebView2.

  3. Задайте для параметра Use WebView2 WinRT APIзначение Нет. Это значит, что пакет SDK для WebView2 не копирует компонент WinRT WebView2 в выходные данные проекта. Этот проект WinRTAdapter не вызывает api WinRT WebView2, поэтому компонент WinRT ему не нужен.

  4. Установите для параметра Использовать средство wv2winrt значение Да.

  5. Задайте для параметра Use JavaScript case (Использовать вариант JavaScript ) значение Да.

  6. В строке Включить фильтры щелкните столбец справа, щелкните раскрывающееся меню в этой ячейке и нажмите кнопку Изменить. Откроется диалоговое окно Включить фильтры .

  7. В верхнем текстовом поле вставьте следующие строки в отдельные строки без пробелов в начале или в конечной части:

    Windows.System.UserProfile
Windows.Globalization.Language

    Диалоговое окно

    Необходимо указать полное имя пространств имен или классов, как показано выше.

  8. Нажмите кнопку ОК , чтобы закрыть диалоговое окно Включить фильтры .

  9. Убедитесь, что диалоговое окно Страницы свойств WinRTAdapter выглядит следующим образом:

    Диалоговое окно

  10. Нажмите кнопку ОК , чтобы закрыть диалоговое окно Страницы свойств .

  11. Выберите Файл>Сохранить все (CTRL+SHIFT+S).

Добавление ссылки, указывающей на проект адаптера

Затем добавьте ссылку в проект main, указывающую на проект адаптера.

В проекте main, например MyUWPGetStartApp, добавьте ссылку, указывающую на проект WinRTAdapter, следующим образом:

  1. В Обозреватель решений разверните проект main, например MyUWPGetStartApp, щелкните правой кнопкой мыши ссылки и выберите Добавить ссылку. Откроется диалоговое окно Диспетчер ссылок .

  2. В дереве слева выберите Проекты. Установите флажок WinRTAdapter :

    Флажок WinRTAdapter в диалоговом окне диспетчера ссылок для проекта main

  3. Нажмите кнопку ОК , чтобы закрыть диалоговое окно Диспетчер ссылок .

  4. Выберите Файл>Сохранить все (CTRL+SHIFT+S).

Создание кода API

Затем создайте код API:

  1. Щелкните правой кнопкой мыши проект WinRTAdapter и выберите Сборка.

    Исходный код создается для пространств имен или классов, указанных в диалоговом окне Включить фильтры средства wv2winrt (средство проекции WinRT JS WebView2):

    • Пространство имен Windows.System.UserProfile
    • Класс Windows.Globalization.Language

  2. После завершения сборки выберите Файл>Сохранить все (CTRL+SHIFT+S).

Важно!

Если вы установили выпускную версию пакета SDK для WebView2 и сборка завершается сбоем с error MIDL2011: [msg]unresolved type declaration [context]: Microsoft.Web.WebView2.Core.ICoreWebView2DispatchAdapter [ RuntimeClass 'WinRTAdapter.DispatchAdapter' ], это проблема в выпускной версии пакета SDK для WebView2, и вам потребуется изменить значение Использовать API WinRT WebView2 на Да на описанных выше шагах.

Кроме того, добавьте следующее после последнего </ItemGroup> в файл WinRTAdapter.vcxprojпроекта :

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

Замените $(WebView2SDKPath) каталогом, в котором был установлен пакет SDK для WebView2, указав в \ конце. Пример: ..\<sample-directory>\packages\Microsoft.Web.WebView2.1.0.1264.42\.

Шаг 7. Обновление целевой платформы (только WinUI 3)

Если ваше приложение предназначено для WinUI 2 (UWP), пропустите этот шаг.

Шаг 8. Добавление объекта host в проект main

Затем передайте объект WinRT с собственной стороны ведущего приложения в веб-часть ведущего приложения. Для этого добавьте метод , вызывающий InitializeWebView2AsyncAddHostObjectToScript, как показано ниже.

  1. В Обозреватель решений разверните проект main, например MyUWPGetStartApp, разверните узел MainPage.xaml, а затем выберите MainPage.xaml.cs.

  2. Под конструктором MainPage добавьте следующий InitializeWebView2Async метод:

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

    Этот метод вызывает AddHostObjectToScript.

    В строке AddHostObjectToScript("Windows", ...Windows — это пространство имен верхнего уровня. Если у вас есть другие пространства имен верхнего уровня, можно добавить дополнительные вызовы к AddHostObjectToScript, как показано в следующем примере:

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

    Вызов WrapNamedObject создает объект-оболочку RuntimeComponent1 для пространства имен. Вызов AddHostObjectToScript добавляет этот объект в оболочку в скрипт с именем RuntimeComponent1.

    Полное руководство по использованию пользовательских компонентов WinRT см. в разделе Пользовательские (сторонние) компоненты WinRT ниже.

  3. В конструкторе MainPage ниже this.InitializeComponent();добавьте следующий код:

    InitializeWebView2Async();

  4. Щелкните правой кнопкой мыши проект main, например MyUWPGetStartApp, а затем выберите Задать в качестве запускаемого проекта. Полужирным шрифтом обозначает запуск проекта.

  5. Выберите Файл>Сохранить все (CTRL+SHIFT+S).

  6. Нажмите клавишу F5 , чтобы запустить пример приложения. Откроется приложение WinUI 2 с поддержкой WebView2 (UWP):

    Приложение UWP Для WebView2 WinUI 2

Веб-код ведущего приложения (и консоль DevTools) теперь может вызывать методы и свойства указанных пространств имен или классов ведущего объекта.

Шаг 9. Вызов методов и свойств объекта узла из JavaScript на стороне веб-сайта

Доступ к проецируемым API через консоль DevTools

Затем используйте консоль DevTools, чтобы продемонстрировать, что веб-код может вызывать ИНТЕРФЕЙСы API на стороне узла, указанные в средстве wv2winrt (средство проекции WinRT JS WebView2):

  1. Если приложение не запущено, в Visual Studio нажмите клавишу F5 , чтобы запустить пример приложения.

  2. Щелкните main части окна примера приложения WebView2, чтобы сосредоточиться на нем, а затем нажмите клавиши CTRL+SHIFT+I, чтобы открыть Средства разработки Microsoft Edge. Или щелкните страницу правой кнопкой мыши и выберите Проверить.

    Откроется окно Средства разработки Microsoft Edge.

  3. Если окно Средства разработки Microsoft Edge не отображается, нажмите клавиши ALT+TAB , чтобы отобразить его.

  4. В окне DevTools выберите вкладку Консоль .

  5. Нажмите кнопку Очистить консоль (очистить консоль) или щелкните правой кнопкой мыши консоль и выберите Команду Очистить консоль. Сообщения могут периодически появляться в консоли.

  6. В консоли DevTools вставьте следующий код класса Windows.Globalization.Language и нажмите клавишу ВВОД:

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

    Консоль выводит строку имени языка, например English (United States), демонстрирующую, что код на стороне узла (на стороне машинного кода) приложения можно вызвать из веб-кода JavaScript:

    Использование консоли DevTools для тестирования вызова собственного кода из веб-кода

  7. Попробуйте опустить скобки. В консоли DevTools введите следующую инструкцию:

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

    Консоль выводит строку имени языка, например English (United States).

    Аналогичным образом можно получить доступ к членам пространства имен Windows.System.UserProfile .

  8. Закройте окно Средства разработки.

  9. Закройте приложение.

Поздравляем! Вы завершили демонстрацию вызова кода WinRT из кода JavaScript.

Доступ к проецируемым API через файлы исходного кода

Выше мы использовали консоль DevTools для выполнения инструкций JavaScript, которые обращаются к проецируемму объекту узла. Аналогичным образом вы можете получить доступ к проецируемым объекту узла из файлов исходного кода. Для этого сначала запустите код установки для скрипта:

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

Затем в main текст кода добавьте вызовы к проецируемым объектам, как показано ниже:

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

Вы также можете получить доступ к Windows.System.UserProfile членам API.

Ниже приведены инструкции, описанные в руководстве. В следующих разделах приведены общие сведения о приложениях WinRT Для WebView2.

Пользовательские (сторонние) компоненты WinRT

Средство wv2winrt (средство проекции WinRT JS WebView2) поддерживает пользовательские сторонние компоненты WinRT, а также интерфейсы API WinRT для сторонних разработчиков.

Сторонние компоненты WinRT с инструментом wv2winrt

Чтобы использовать пользовательские (сторонние) компоненты WinRT со средством wv2winrt , в дополнение к описанным выше действиям также выполните следующие действия.

  1. Добавьте третий проект (отличный от приложения main и проекта WinRTAdapter) в решение Visual Studio, которое реализует класс WinRT.

  2. Создайте проект WinRTAdapter "Добавить ссылку" в новый третий проект, содержащий класс WinRT.

  3. Обновите фильтр Включить проекта WinRTAdapter в свойствах, чтобы также включить новый класс.

  4. Добавьте дополнительную строку в , InitializeWebView2Async чтобы добавить пространство имен класса winrt:

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

  5. Чтобы упростить вызов метода из Интернета, при необходимости добавьте прокси-сервер синхронизации пространства имен в качестве глобального объекта в скрипте. Например:

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

Пример этого см. в следующем примере WebView2:

Асинхронные методы WinRT

Следуя инструкциям, описанным в приведенном выше руководстве, вы сможете использовать синхронные прокси-серверы. Для вызовов асинхронных методов необходимо использовать chrome.webview.hostObjects.options.forceAsyncMethodMatches.

Свойство forceAsyncMethodMatches представляет собой массив регулярных выражений, где, если какой-либо из регулярных выражений соответствует имени метода на прокси-сервере синхронизации, метод будет выполняться асинхронно. Если задано значение , [/Async$/] он будет соответствовать любому методу, заканчивающийся суффиксом Async. Затем соответствующие вызовы методов работают так же, как метод на асинхронном прокси-сервере и возвращают обещание, которое можно ожидать.

Пример:

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/'));

Дополнительные сведения см. в строке в методе CoreWebView2.AddHostObjectToScript.forceAsyncMethodMatches

Подписка на события WinRT

События WinRT также предоставляются через прокси-серверы скриптов. Можно добавлять и удалять обработчики событий экземпляра WinRT и статических событий WinRT с помощью addEventListener(string eventName, function handler) методов и removeEventListener(string eventName, function handler) .

Эти методы работают аналогично методам DOM с тем же именем. Вызовите addEventListener со строковым именем события WinRT, на которое вы хотите подписаться в качестве первого параметра, и с обратным вызовом функции, вызываемой при возникновении события. Вызов removeEventListener с теми же параметрами отменяет подписку на это событие. Например:

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

Для события WinRT, предоставляющего аргументы событий, они предоставляются в качестве первого параметра функции обработчика событий. Например, Windows.Foundation.Collections.PropertySet.MapChanged событие имеет IMapChangedEventArgs<string, object> объект event arg, и этот объект предоставляется в качестве параметра для обратного вызова.

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

Объект event args также будет иметь следующие свойства:

Имя свойства Описание
target Объект, вызвав которому событие
type Строковое имя события
detail Массив всех параметров, предоставленных делегату WinRT

Сделайте, чтобы прокси-серверы JavaScript AddHostObjectToScript действуют больше, чем другие API JavaScript

AddHostObjectToScript по умолчанию используется асинхронные и подробные прокси-серверы, но вы можете сделать AddHostObjectToScript прокси-серверы JavaScript более похожими на другие API JavaScript. Дополнительные сведения о AddHostObjectToScript поведении по умолчанию см. в разделе AddHostObjectToScript. Кроме того, если вы переносите ведущее приложение из проекции JavaScript WinRT в приложениях JavaScript UWP или webView на основе EdgeHTML, может потребоваться использовать следующий подход, чтобы лучше соответствовать предыдущему поведению.

AddHostObjectToScript Чтобы прокси-серверы JavaScript более похожи на другие API JavaScript, задайте следующие свойства:

  • chrome.webview.hostObjects.option.defaultSyncProxy — Прокси-серверы могут быть асинхронными или синхронными. Как правило, при вызове метода на синхронном прокси-сервере мы знаем, что результатом также должен быть синхронный прокси-сервер. Но в некоторых случаях мы теряем этот контекст, например при предоставлении ссылки на функцию в машинный код, а затем машинный код вызовет ее. В таких случаях прокси-сервер будет асинхронным, если это свойство не задано.

  • chrome.webview.hostObjects.options.forceAsyncMethodMatches — это массив регулярных выражений. При вызове метода на синхронном прокси-сервере вызов метода фактически будет выполняться асинхронно, если имя метода соответствует строке или регулярному выражению, наличествию в этом массиве. При установке этого значения [/Async$/] любой метод, заканчивающийся Async на , будет асинхронным вызовом метода. Если асинхронный метод здесь не совпадает и не должен быть асинхронным, метод будет вызываться синхронно, блокируя выполнение вызывающего JavaScript и возвращая разрешение обещания, а не возвращая обещание.

  • chrome.webview.hostObjects.options.ignoreMemberNotFoundError — Если вы попытаетесь получить значение свойства прокси-сервера, а свойство не существует в соответствующем машинном классе, вы получите исключение , если только для этого свойства trueне задано значение , в этом случае поведение будет соответствовать поведению проекции Chakra WinRT (и общему поведению JavaScript) и возврату undefined без ошибок.

Проекция Chakra WinRT помещает пространства имен WinRT непосредственно на корневой объект. Напротив:

  • AddHostObjectToScript помещает асинхронные корневые прокси-серверы в chrome.webview.hostObjects.
  • AddHostObjectToScript размещает корневые прокси-серверы синхронизации в chrome.webview.hostObjects.sync.

Чтобы получить доступ к корневым прокси-серверам, где ожидается код проекции Chakra WinRT, можно назначить корневому объекту расположение пространства имен WinRT корневого прокси-сервера. Например:

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

Чтобы убедиться, что Код JavaScript, который задает все это, выполняется перед выполнением любого другого сценария, можно либо добавить указанную выше инструкцию в JavaScript, либо указать WebView2, чтобы она была внедрена выше перед выполнением любого другого CoreWebView2.AddScriptToExecuteOnDocumentCreatedAsync скрипта с помощью метода .

В следующем примере демонстрируются описанные выше методы.

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

Получение сведений о свойствах WebView2

Сведения о свойствах WebView2 доступны в двух местах:

  • Страницы свойств проекта WinRTAdapter.
  • wv2winrt.exe Справка из командной строки. Это средство wv2winrt (средство проекции WinRT JS WebView2).

Страницы свойств проекта WinRTAdapter

На страницах свойств проекта WinRTAdapter для получения справки о свойстве щелкните строку свойства. В нижней части диалогового окна отображается справка:

Свойства, перечисленные на страницах свойств WinRTAdapter

Справка по свойствам wv2winrt.exe из командной строки

Справка по командной строке для wv2winrt.exe содержит сведения о параметрах средства wv2winrt (средство проекции JS WebView2 WinRT). Например:

Параметр Описание
verbose Вывод содержимого в стандартный список, включая созданные файлы и сведения о правилах включения и исключения.
include Список, как указано выше, по умолчанию исключает пространства имен и классы среды выполнения, кроме перечисленных. Объявления включения могут быть пространствами имен, которые включают все в этом пространстве имен, или именами классов среды выполнения, включающими только этот класс среды выполнения.
use-javascript-case Изменяет созданный код для создания имен методов, имен свойств и т. д., которые используют тот же стиль регистра, что и проекция WinRT для JavaScript чакра. По умолчанию создается имя, соответствующее winrt.
output-path Задает путь, по которому будут записываться созданные файлы.
output-namespace Задает пространство имен, используемое для созданного класса WinRT.
winmd-paths Разделенный пробелами список всех winmd-файлов, которые следует изучить для создания кода.

См. также

Руководство и пример:

Справочник по API:

Статья, эквивалентная .NET: