Начало работы с WebView2 в приложениях WinUI 2 (UWP)

В этом руководстве вы:

• Настройте средства разработки для создания приложений UWP, использующих WebView2 для отображения веб-содержимого.
• Создайте начальное приложение WinUI 2 (UWP).
• Установите пакет Microsoft.UI.Xaml (WinUI 2) для проекта.
• Добавьте элемент управления WebView2, который отображает содержимое веб-страницы.
• Узнайте об основных понятиях WebView2.

Вы используете шаблон проекта Пустое приложение C# (универсальное приложение для Windows), а затем установите пакет Microsoft.UI.Xaml (WinUI 2) для этого проекта. При установке этого пакета в качестве зависимости устанавливается пакет Microsoft.Web.WebView2 (пакет SDK для WebView2).

Пакет Microsoft.UI.Xaml (WinUI 2) является частью библиотеки пользовательского интерфейса Windows. Этот пакет предоставляет функции пользовательского интерфейса Windows, в том числе:

• Элементы управления XAML UWP.
• Стили плотных элементов управления.
• Стили и материалы Fluent.

Платформы

Эта статья относится к Windows и Xbox.

WinUI 2 поддерживает только UWP. Эти элементы управления являются обратно совместимыми.

См. также:

• Примеры мультимедийных приложений для Xbox

Завершенный проект

Завершенная версия этого проекта (решения) начало работы находится в репозитории WebView2Samples. Вы можете использовать готовое решение (из репозитория или из приведенных ниже действий) в качестве базового плана для добавления дополнительного кода WebView2 и других функций.

Полная версия этого учебного проекта доступна в репозитории WebView2Samples :

• Имя примера: WinUI2_Sample
• Каталог репозитория: WinUI2_GettingStarted
• Файл решения: MyUWPGetStartApp.sln

Следуйте приведенным ниже основным разделам Шаг.

Сведения о WinUI и WebView2

В приложениях WinUI 2 (UWP) WebView2 предоставляется как элемент управления XAML. После внедрения элемента управления XAML в приложение в качестве именованного элемента управления вы можете ссылаться на этот элемент управления XAML в файлах C#.

В WinUI предоставляется только подмножество интерфейсов и функций WebView2:

• Объект WebView2 XAML предоставляет CoreWebView2 интерфейс вместе с наиболее важными функциями.

• Интерфейсы, например, скрыты, так как CoreWebView2Controller WinUI обеспечивает создание среды и окна в фоновом режиме.

См. также ограничение XAML ниже.

Шаг 1. Установка Visual Studio

В этой статье показаны шаги и снимки экрана для Visual Studio 2022 Community Edition. Требуется Microsoft Visual Studio 2019 версии 16.9 или более поздней. Visual Studio 2017 не поддерживается.

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

   Затем вернитесь на эту страницу и перейдите ниже.

2. Если Visual Studio не отображает номера строк в редакторе кода, может потребоваться включить номера строк. Для этого выберите Сервис>Параметры>Текстовый редактор>Все>языки Номера строк. Нажмите кнопку ОК.

Шаг 2. Установка рабочих нагрузок для классических приложений .NET, C++ и средств разработки UWP

1. Откройте Microsoft Visual Studio. Откроется окно параметра открытия:

   

2. В правом нижнем углу щелкните Продолжить без кода. Visual Studio откроется, пуст:

   

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

   

Если окно Изменение Visual Studio не открыто, в окне Visual Studio Installer нажмите кнопку Изменить.

1. На вкладке Рабочие нагрузки прокрутите до и щелкните следующие карточки, чтобы выбрать их: Убедитесь, что флажок установлен на каждой из следующих карточек:

   • Разработка классических приложений .NET
   • Разработка классических приложений на C++
   • разработка универсальная платформа Windows

2. Справа в разделе Сведения об установке разверните узел универсальная платформа Windows разработки, а затем выберите C++ (версия 143) универсальная платформа Windows средства:

   

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

3. Нажмите кнопку Изменить .

   Откроется окно Контроль учетных записей пользователей с вопросом "Вы хотите разрешить этому приложению вносить изменения в устройство? Visual Studio Installer. Проверенный издатель: Корпорация Майкрософт. Источник файла: жесткий диск на этом компьютере. Показать дополнительные сведения (кнопка)".

4. Нажмите кнопку Да .

5. Откроется диалоговое окно "Перед началом работы, закройте Visual Studio":

   

6. Нажмите кнопку Продолжить .

   Visual Studio скачивает, проверяет и устанавливает выбранные пакеты:

   

   На этом снимку экрана показано Visual Studio Professional 2022 г., хотя эта статья была обновлена с использованием Visual Studio Community 2022 г.

   Установка может занять несколько минут. Появится Visual Studio с пустым Обозреватель решений.

7. Нажмите клавиши ALT+TAB, чтобы переключиться в окно Visual Studio Installer, а затем закройте окно Visual Studio Installer.

Шаг 3. Создание приложения UWP

1. Если Visual Studio открыта, выберите Файл>Новый>проект. Откроется диалоговое окно Создание проекта.

   Или, если Visual Studio закрыта, откройте ее, а затем на начальном экране Visual Studio щелкните Создать проект карта:

   

2. В текстовом поле Поиск шаблонов в верхней части окна введите пустое приложение C# (универсальное приложение для Windows), а затем выберите карта пустое приложение C# (универсальное приложение для Windows):

   

3. Нажмите кнопку Далее .

   Откроется диалоговое окно Настройка нового проекта для пустого приложения (универсальное приложение для Windows):

   

4. В текстовом поле Имя проекта введите имя проекта, например MyUWPGetStartApp.

5. В текстовом поле Расположение введите путь, например C:\Users\myusername\Documents\MyWebView2Projects.

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

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

   

7. Примите значения по умолчанию и нажмите кнопку ОК .

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

   • Нажмите кнопку Да , чтобы включить режим разработчика для компьютера, а затем закройте окно Параметры .

   Visual Studio отображает только что созданное решение и проект:

   

Шаг 4. Сборка и запуск пустого проекта

Перед добавлением кода WebView2 убедитесь, что проект работает, и посмотрите, как выглядит пустое приложение следующим образом:

1. Выполните сборку и запуск пустого проекта. Для этого выберите Отладка>Начать отладку (F5). Откроется окно приложения, временно отображается сетка, а затем отображается содержимое приложения:

   

   Это базовое приложение WinUI 2 (UWP) без WebView2.

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

Затем вы настроите этот новый проект WinUI 2 (UWP) для размещения элемента управления WebView2 и использования API WebView2.

Шаг 5. Установка пакета SDK для WinUI 2 (Microsoft.UI.Xaml)

Затем установите пакет Microsoft.UI.Xaml для этого проекта. Microsoft.UI.Xaml — Это WinUI 2.

1. В Обозреватель решений щелкните правой кнопкой мыши проект (не узел решения над ним) и выберите Управление пакетами NuGet.

   В Visual Studio откроется панель Диспетчер пакетов NuGet .

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

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

4. В поле Поиск введите Microsoft.UI.Xaml, а затем выберите microsoft.UI.Xaml карта под полем поиска:

   

   Для версии 2.8.0 или более поздней в разделе Зависимости внизу перечислены microsoft.Web.Web.WebView2 .

   Для HoloLens 2 разработки пакет Microsoft.Web.WebView2 должен иметь версию 1.0.1722.45 или более поздней, которая может быть выше, чем по умолчанию. WebView2 на HoloLens 2 находится в предварительной версии и может быть изменен до выпуска общедоступной версии. WebView2 поддерживается только на HoloLens 2 устройствах с обновлением Windows 11. Дополнительные сведения см. в разделе Обновление HoloLens 2.

5. На средней панели в раскрывающемся списке Версия убедитесь, что выбрана последняя стабильная версия 2.8.0 или более поздняя.

6. Нажмите кнопку Установить .

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

   

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

8. Откроется диалоговое окно Принятие лицензии :

   

9. Нажмите кнопку Принимаю . В Visual Studio readme.txt отобразится файл с сообщением о том, что вы установили пакет WinUI:

   

   В средстве чтения перечислены некоторые строки кода, аналогичные тому, который мы добавим.

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

Теперь вы установили пакет Microsoft.UI.Xaml, который является WinUI 2, для проекта. Пакет SDK Для WinUI 2 (Microsoft.UI.Xaml) включает пакет SDK для WebView2, поэтому вам не нужно отдельно устанавливать пакет NuGet для пакета SDK Для WebView2.

Шаг 6. Создание экземпляра элемента управления WebView2 в коде XAML

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

1. В Обозреватель решений разверните проект, а затем дважды щелкните Файл MainPage.xaml.

   MainPage.xaml открывается в конструкторе с редактором кода под ним:

   

2. В редакторе кода в начальном <Page> теге <Pageэлемента добавьте следующий атрибут ниже остальных xmlns: атрибутов:

   xmlns:controls="using:Microsoft.UI.Xaml.Controls"
   

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

3. MainPage.xaml В файле в <Grid> элементе (который еще не содержит других элементов) добавьте элемент управления WebView2, добавив следующий элемент:

   <controls:WebView2 x:Name="WebView2" Source="https://bing.com"/>
   

4. Нажмите клавиши CTRL+S , чтобы сохранить файл.

   Над файлом MainPage.xaml в редакторе кода может отображаться предварительный просмотр содержимого элемента управления WebView2 или он может оставаться пустым (белым) до первой сборки приложения:

   

   Волнистая подчеркивание исчезает после сборки и запуска приложения на следующем шаге.

Шаг 7. Сборка и запуск проекта, содержащего элемент управления WebView2

1. Щелкните Отладка>Начать отладку (F5). (При сборке для HoloLens 2 см. раздел Использование Visual Studio для развертывания и отладки). Откроется окно приложения, в котором кратко отображается сетка WebView2 WebUI:

   

2. Через некоторое время в окне приложения появится веб-сайт Bing в элементе управления WebView2 для WebUI 2:

   

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

Поздравляем, вы создали свое первое приложение WebView2!

Теперь вы можете изменить содержимое элемента управления WebView2, чтобы добавить собственное содержимое.

Сведения о событиях навигации

Далее ознакомьтесь с событиями навигации, которые необходимы для приложений WebView2. Изначально приложение переходит по адресу https://bing.com.

• В новом окне или вкладке прочитайте события навигации для приложений WebView2, а затем вернитесь на эту страницу.

Особые рекомендации по WebView2 в WinUI 2 (UWP)

Элемент управления WinUI 2 (UWP) WebView2 находится в разработке.

Пользовательский интерфейс автозаполнения

Пользовательский интерфейс автозаполнения еще не реализован для WebView2 для приложений UWP.

См. также:

• Автозаполнение в обзоре функций и API WebView2.

Сохранить в формате PDF

Для печати в PDF требуется, чтобы у приложения был доступ к расположению, которое можно записывать в UWP, например к локальной папке. Полный список путей, доступных для UWP, см. в разделе Разрешения на доступ к файлам.

См. также:

• Печать в обзоре функций и API WebView2.

Печать по умолчанию

Печать по умолчанию отключена для WebView2 для приложений UWP. Однако можно записать и распечатать текущее окно просмотра, вызвав .CapturePreview

См. также:

• Запись изображений в обзоре функций и API WebView2.

Smartscreen

WebView2 отправляет URL-адреса, по которым осуществляется переход в приложении, в службу SmartScreen , чтобы обеспечить безопасность клиентов. Если вы хотите отключить эту навигацию, это можно сделать с помощью переменной среды:

• Environment.SetEnvironmentVariable("WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS", "--disable-features=msSmartScreenProtection");

Эта переменная среды должна быть задана перед CoreWebView2 созданием, которое происходит при первоначальном задании свойства WebView2.Source или вызове метода WebView2.EnsureCoreWebView2Async .

Скачивание файлов

Существует несколько известных ограничений для текущего поведения загрузки для WebView2 в UWP.

Сохранить как

Сохранение файлов с помощью функции "Сохранить как " работает и включено для WebView2 для приложений UWP. Файлы будут сохранены в папке, которую выберет пользователь.

Папка, в которую загружаются файлы

Если узел не изменяет ResultFilePath значение загруженного файла, скачанные файлы будут загружены во вложенную папку с именем пакета приложения в папке Downloads .

Если узел изменяет ResultFilePath значение скачаемого файла, файл будет скачан только в том случае, если приложение имеет доступ к нему по умолчанию. Если вы хотите использовать расположение файла, к которому приложение по умолчанию не имеет доступа, необходимо задать соответствующую возможность. См . статью Объявления возможностей приложений в документации по UWP.

Центр загрузок

Открытие файлов и папок из Центра загрузок отключено. Щелкнув значок файла или папки, соответствующий файл или папку не откроется.

См. также:

• Загрузки в обзоре функций и API WebView2.

Ограничение XAML

Поддержка XAML Island требует дополнительной работы и может рассматриваться для будущих выпусков.

Настройка DefaultBackgroundColor

В WinUI 2 DefaultBackgroundColor свойство не предоставляется напрямую. Вы можете задать цвет фона по умолчанию, задав переменную среды следующим образом:

Environment.SetEnvironmentVariable("WEBVIEW2_DEFAULT_BACKGROUND_COLOR", "FF000000");

См. также:

• .NET: Свойство WebView2.DefaultBackgroundColor
• Win32: свойство ICoreWebView2Controller2::D efaultBackgroundColor (get, put)

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

В WinUI 2 прозрачность достигается путем установки цвета в .00FFFFFF

Курсоры CSS

В WinUI 2 (UWP) курсоры CSS имеют следующие ограничения.

URL-адреса изображений

Курсор CSS не может быть URL-адресом изображения, например cursor: url(https://contoso.com/cursor.png), pointer;. См . статью CSS — курсор, загруженный из URL-адреса, не работает.

Предопределенные курсоры CSS

В WinUI 2 (UWP) некоторые предопределенные курсоры CSS не поддерживаются. Курсоры CSS можно использовать для изменения курсора на некоторые из предопределенных курсоров, например cursor: wait; или cursor: crosshair;, но не на другие, например cursor: progress или cursor: none.

См. также:

• Курсоры CSS— в разделе Значения описаны приведенные выше ключевое слово значения.

Средства разработчика Microsoft Edge

В WinUI 2 средства разработки Microsoft Edge нельзя запустить в приложении WebView2 WinUI 2 (UWP) с подписью магазина. Однако эту проблему можно обойти с помощью удаленной отладки. См. раздел Удаленная отладка приложений WebView2 WinUI 2 (UWP).

Ограничения API

Следующие классы недоступны в WinUI 2:

• CoreWebView2EnvironmentOptions
• CoreWebView2ControllerOptions

См. также

• Справочник по API WebView2
• Пример приложения WinUI 2 (UWP) — шаги для скачивания, обновления, сборки и запуска примера WinUI 2 WebView2.
• Управление папками данных пользователя
• Пример кода для WebView2 — руководство по репозиторию WebView2Samples .
• Рекомендации по разработке приложений WebView2

Github:

• Репозиторий WebView2Samples
• Пример приложения UWP WebView2 — пример WinUI 2 (UWP) WebView2.
• Проблемы — репозиторий microsoft-ui-xaml — для ввода запросов или ошибок, связанных с WinUI.
• В отличие от некоторых других учебников, в репозитории WebView2Samples нет полной версии этого начало работы руководства.
• Пакет NuGet Microsoft.UI.Xaml
• Примеры мультимедийных приложений для Xbox