Бөлісу құралы:

Начало работы с WebView2 в приложениях WinUI 3 (Windows App SDK)

  • Мақала

В этой статье описано, как настроить средства разработки и создать начальное приложение WebView2 для WinUI 3 (Windows App SDK), а также ознакомиться с основными понятиями WebView2. Сначала используйте шаблон проекта Visual Studio Blank App, Packaged (WinUI 3 in Desktop), который использует WindowsAppSDK, включающий пакет SDK для WebView2. Затем добавьте элемент управления WebView2, адресную строку и кнопку Go , а также логику URL-адреса, чтобы разрешить переход только по URL-адресам HTTPS.

В этом руководстве вы выполните следующие действия.

  1. Настройка среды разработки.

  2. Используйте шаблон проекта Visual Studio Blank App, Packaged (WinUI 3 in Desktop) для создания пустого проекта WinUI 3, который определяет приложение, содержащее кнопку.

  3. Добавьте элемент управления WebView2 вместо кнопки и сначала перейдите на домашнюю страницу Майкрософт. WebView2 поддерживается, так как шаблон проекта использует пакет NuGet Microsoft.WindowsAppSDK , который включает пакет SDK для WebView2.

  4. Добавьте адресную строку в качестве элемента управления "Текстовое поле", а затем используйте введенную строку HTTPS для перехода на новую веб-страницу:

    Приложение после перехода по адресу Bing HTTPS

  5. Вставьте JavaScript в элемент управления WebView2, чтобы отобразить предупреждение (диалоговое окно), когда пользователь пытается перейти по URL-адресу, который имеет только http:// префикс вместо https://:

    Элемент управления WebView2 приложения отображает диалоговое окно оповещений для веб-сайтов, отличных от HTTPS

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

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

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

Шаг 1. Установка последней версии Visual Studio 2022

Убедитесь, что Visual Studio 2022 установлена и обновлена.

Чтобы установить последнюю версию Visual Studio 2022, выполните следующие действия:

  1. Перейдите в Visual Studio: интегрированная среда разработки и Код Редактор для разработчиков программного обеспечения и Teams, а затем в разделе Visual Studio 2022 нажмите кнопку Скачать, а затем выберите Community 2022 или другую версию.

  2. Во всплывающем окне Загрузки в правом верхнем углу Microsoft Edge VisualStudioSetup.exe отображается список. Щелкните Открыть файл.

    откроется Visual Studio Installer.

  3. Следуйте инструкциям и примите значения по умолчанию. На следующем шаге вы установите или обновите рабочую нагрузку и компонент рабочей нагрузки.

Шаг 2. Установка последней Windows App SDK

Убедитесь, что последняя Windows App SDK установлена в Visual Studio 2022. Windows App SDK включает шаблоны проектов Visual Studio и пакет SDK для WebView2. Эти шаблоны проектов включают шаблон проекта Blank App, Packaged (WinUI 3 in Desktop), который использует WindowsAppSDK, включая пакет SDK для WebView2.

Windows App SDK устанавливается в качестве компонента Windows App SDK шаблонов C# рабочей нагрузки Разработка классических приложений .NET для Visual Studio. До Visual Studio 2022 версии 17.1 Windows App SDK устанавливался как расширение Visual Studio, как описано в статье Установка средств для Windows App SDK.

Чтобы установить последнюю версию Visual Studio 2022 с последней Windows App SDK:

  1. В Windows нажмите клавишу Пуск и введите Visual Studio 2022.

    В списке указано приложение Visual Studio 2022.

  2. Нажмите кнопку Open (Открыть).

    Откроется диалоговое окно Visual Studio 2022 с разделами Open recent и Начало работы.

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

    Откроется Visual Studio.

  4. В меню Сервис выберите Получить средства и компоненты.

    Откроется окно Visual Studio Installer.

  5. Убедитесь, что выбрана вкладка Рабочие нагрузки .

  6. В разделе Desktop & Mobile выберите карта рабочей нагрузки разработка классических приложений .NET, чтобы появилась галочка:

    Флажок компонента

  7. В дереве Сведения об установке справа в разделе Разработка> классических приложений .NETНеобязательно установите флажок для компонента Windows App SDK C# Templates (Шаблоны C#) в нижней части дерева.

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

    Откроется диалоговое окно Контроль учетных записей пользователей .

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

    Вам будет предложено закрыть Visual Studio.

  10. Нажмите кнопку Продолжить (при условии, что у вас нет несохраненных работ).

    Visual Studio загружает и устанавливает последнюю версию компонента шаблонов C# Windows App SDK. В окне Visual Studio Installer появится сообщение о том, что все установки обновлены, и откроется Visual Studio 2022.

Шаг 3. Создание пустого проекта WinUI 3

Затем создайте проект, который является базовым приложением WebView2 для WinUI 3 (Windows App SDK). Это классическое приложение будет содержать одно окно main. Проект еще не будет содержать код WebView2.

Создание приложения WebView2 для WinUI 3 (Windows App SDK):

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

  2. Если Visual Studio 2022 не работает:

    1. В Windows нажмите клавишу Пуск и введите Visual Studio 2022.

      В списке указано приложение Visual Studio 2022.

    2. Нажмите кнопку Open (Открыть).

      Откроется диалоговое окно запуска Visual Studio 2022 с разделами Open recent и Начало работы.

    3. В разделе Начало работы щелкните создать проект карта. Откроется окно Создание проекта .

  3. В окне Создание проекта в поле Поиск шаблонов введите WinUI 3 на рабочем столе:

    Поиск по

    Перечислены шаблоны проектов, которые были установлены на предыдущем крупном шаге.

  4. Щелкните пустое приложение, Упаковано (WinUI 3 в классическом режиме) карта, чтобы выбрать его, а затем нажмите кнопку Далее.

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

  5. В текстовом поле Имя проекта введите имя проекта, например WinUI3GetStarted:

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

  6. В текстовом поле Расположение введите каталог, например C:\Users\myUsername\source\.

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

    Проект создается:

Новый проект WinUI 3 в Обозреватель решений

  1. Если появится диалоговое окно "Не удалось установить пакет Microsoft.WindowsAppSDK", нажмите кнопку ОК .

Шаг 4. Обновление или установка Windows App SDK

При создании проекта в Visual Studio проверка состояние пакетов NuGet решения. Убедитесь, что необходимые пакеты NuGet установлены шаблоном проекта, и убедитесь, что пакеты были обновлены, чтобы в проекте были установлены последние функции и исправления.

Чтобы обновить или установить последнюю версию пакета NuGet Windows App SDK для проекта, выполните следующие действия:

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

    В Visual Studio откроется вкладка NuGet: WinUI3GetStarted . Если пакет Microsoft.WindowsAppSDK был установлен во время создания проекта с помощью шаблона проекта, выбрана вкладка Установленные , и этот пакет отображается в списке:

    Ожидаемые пакеты, перечисленные на вкладке Установленные на вкладке NuGet

    Если пакет Microsoft.WindowsAppSDK не указан на вкладке Установленные :

  2. Откройте вкладку Обзор и в текстовом поле Поиск введите Microsoft.WindowsAppSDK.

  3. Выберите карта Microsoft.WindowsAppSDK:

    Установка пакета SDK

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

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

  5. Нажмите кнопку Применить и примите условия лицензии.

    Установлен пакет NuGet Microsoft.WindowsAppSDK .

  6. На вкладке NuGet — Решение щелкните вкладку Обновления, а затем при необходимости обновите все перечисленные там пакеты.

  7. Закройте вкладку NuGet — Решение .

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

Новый проект WinUI 3 остается открытым в Обозреватель решений в Visual Studio:

Новый проект WinUI 3 в Обозреватель решений

  • Файл App.xaml.cs определяет Application класс, представляющий экземпляр приложения.

  • Файл MainWindow.xaml.cs определяет MainWindow класс, представляющий окно main, отображаемое экземпляром приложения. Классы являются производными от типов в Microsoft.UI.Xaml пространстве имен WinUI.

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

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

  2. Выберите Отладка>Пуск (F5).

    Может открыться диалоговое окно Включение режима разработчика для Windows :

    Диалоговое окно: включение режима разработчика для Windows

  3. Если появится это диалоговое окно, щелкните Параметры для разработчиков, включите переключатель Режим разработчика , нажмите кнопку Да , а затем нажмите кнопку Закрыть диалогового окна Visual Studio. Дополнительные сведения о режиме разработчика см. в разделе Включение устройства для разработки в статье Создание классических приложений для Windows.

    Выполняется сборка проекта. Откроется пустое классическое приложение WinUI без добавления элемента управления WebView2:

    Новое пустое приложение WinUI 3

  4. Нажмите кнопку Click Me (Щелкнуть меня ).

    Метка кнопки изменится на Clicked.

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

Шаг 6. Добавление элемента управления WebView2

Проект основан на шаблоне проекта Пустое приложение, упакованое (WinUI 3 в классической версии), который использует пакет NuGet Microsoft.WindowsAppSDK , включающий пакет SDK для WebView2. Таким образом, мы можем добавить код WebView2. Вы измените MainWindow.xaml файлы и MainWindow.xaml.cs , чтобы добавить элемент управления WebView2 в пустой проект приложения WinUI 3, изначально загрузив домашнюю страницу Майкрософт. В XAML-файле элемент управления WebView будет помечен следующим образом:

<controls:WebView2 x:Name="MyWebView" Source="https://www.microsoft.com">

Чтобы добавить элемент управления WebView2, который изначально переходит на домашнюю страницу Майкрософт, выполните следующие действия:

  1. В Visual Studio в Обозреватель решений дважды щелкните .MainWindow.xaml

    Файл откроется в редакторе кода.

  2. Скопируйте и вставьте следующий атрибут в начальный <Window> тег в конце списка пространств имен XML:

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

    Этот код добавляет пространство имен XAML WebView2. Убедитесь, что код в MainWindow.xaml выглядит следующим образом:

    <?xml version="1.0" encoding="utf-8"?>
<Window
    x:Class="MyWebView2WinUI3.MainWindow"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:local="using:MyWebView2WinUI3"
    xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
    xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
    xmlns:controls="using:Microsoft.UI.Xaml.Controls"
    mc:Ignorable="d">

    <StackPanel Orientation="Horizontal" HorizontalAlignment="Center" VerticalAlignment="Center">
        <Button x:Name="myButton" Click="myButton_Click">Click Me</Button>
    </StackPanel>
</Window>

  3. <StackPanel> Удалите элемент (три строки).

  4. Над конечным тегом </Window> вставьте следующий <Grid> элемент:

    <Grid>
    <Grid.RowDefinitions>
        <RowDefinition Height="Auto"/>
        <RowDefinition Height="*"/>
    </Grid.RowDefinitions>
    <Grid.ColumnDefinitions>
        <ColumnDefinition Width="*"/>
        <ColumnDefinition Width="Auto"/>
    </Grid.ColumnDefinitions>

    <controls:WebView2 x:Name="MyWebView"  Grid.Row="1" Grid.ColumnSpan="2"
        Source="https://www.microsoft.com" HorizontalAlignment="Stretch" 
        VerticalAlignment="Stretch"/>
</Grid>

    Этот <Grid> элемент содержит <controls:WebView2> элемент с именем MyWebView, который имеет Source атрибут, который задает начальный URI, отображаемый в элементе управления WebView2 (https://www.microsoft.com). Когда приложение откроется, в элементе управления WebView2 будет отображаться домашняя страница Microsoft.com.

  5. В Обозреватель решений разверните MainWindow.xaml узел и дважды щелкните .MainWindow.xaml.cs

  6. В MainWindow.xaml.csудалите следующую строку кода C# в методе myButton_Click :

    myButton.Content = "Clicked";

    Пока метод пуст. Позже мы будем использовать его для кнопки "Перейти " в адресной строке.

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

  8. Нажмите клавишу F5.

    Проект будет создан, и откроется приложение:

    Элемент управления WebView2, отображающий веб-страницу microsoft.com

    Приложение — это ведущее приложение WebView2, включающее элемент управления WebView2. Элемент управления WebView2 изначально отображает веб-сайт https://www.microsoft.com. Пока нет текстового поля адресной строки или кнопки "Перейти ".

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

Шаг 7. Добавление элементов управления навигацией

Чтобы разрешить пользователям управлять веб-страницей, отображаемой в элементе управления WebView2, добавьте адресную строку в приложение следующим образом:

  1. Вставьте MainWindow.xamlследующий код в <Grid> элемент над элементом <controls:WebView2> :

       <TextBox Name="addressBar" Grid.Column="0"/>
   <Button x:Name="myButton" Grid.Column="1" Click="myButton_Click">Go</Button>

    Убедитесь, что результирующий <Grid> элемент в MainWindow.xaml файле соответствует следующему:

    <Grid>
    <Grid.RowDefinitions>
        <RowDefinition Height="Auto"/>
        <RowDefinition Height="*"/>
    </Grid.RowDefinitions>
    <Grid.ColumnDefinitions>
        <ColumnDefinition Width="*"/>
        <ColumnDefinition Width="Auto"/>
    </Grid.ColumnDefinitions>

    <TextBox Name="addressBar" Grid.Column="0"/>
    <Button x:Name="myButton" Grid.Column="1" Click="myButton_Click">Go</Button>

    <controls:WebView2 x:Name="MyWebView"  Grid.Row="1" Grid.ColumnSpan="2"
        Source="https://www.microsoft.com" HorizontalAlignment="Stretch" 
        VerticalAlignment="Stretch"/>
</Grid>

  2. Вставьте MainWindow.xaml.csследующий try/catch блок в текст myButton_Click метода:

    private void myButton_Click(object sender, RoutedEventArgs e)
{
    try
    {
        Uri targetUri = new Uri(addressBar.Text);
        MyWebView.Source = targetUri;
    }
    catch (FormatException ex)
    {
        // Incorrect address entered.
    }
}

    Этот код перемещает элемент управления WebView2 по URL-адресу, который пользователь вводит в адресной строке, когда пользователь нажимает кнопку Go , путем повторного MyWebView.Source задания значения свойства, эквивалентного атрибуту Source<controls:WebView2 x:Name="MyWebView"> элемента .

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

  4. Нажмите клавишу F5.

    Проект выполняет сборку, и откроется приложение, на котором изначально отображается домашняя страница Майкрософт. Теперь есть адресная строка и кнопка "Перейти ".

  5. Введите новый полный URL-адрес HTTPS в адресной строке, например https://www.bing.com, и нажмите кнопку Перейти :

    Приложение отображает веб-сайт Bing

    Элемент управления WebView2 в приложении отображает веб-сайт Bing. В адресной строке отображается URL-адрес, например https://www.bing.com.

  6. Введите неполный URL-адрес в адресной строке, например bing.com, и нажмите кнопку Перейти .

    Элемент управления WebView2 не пытается перейти по url-адресу. Возникает исключение, так как URL-адрес не начинается с http:// или https://. try В разделе addressBar.Text строка не начинается с http:// или https://, но строка, не являющаяся URI, передается конструкторуUri, что создает System.UriFormatException исключение. В Visual Studio на панели Вывод отображается сообщение "Исключение, выданное: "System.UriFormatException" в System.Private.Uri.dll". Приложение продолжает работать.

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

Шаг 8. Обработка событий навигации

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

  • NavigationStarting
  • SourceChanged
  • ContentLoading
  • HistoryChanged
  • NavigationCompleted

Эти события создаются элементом управления WebView2 во время навигации по веб-странице. Если происходит перенаправление HTTP, в строке имеется несколько NavigationStarting событий. Дополнительные сведения см. в разделе События навигации для приложений WebView2.

При возникновении ошибки возникают следующие события и может отображаться веб-страница ошибки:

  • SourceChanged
  • ContentLoading
  • HistoryChanged

В этом разделе вы добавите код для импорта библиотеки WebView2 Core, которая обрабатывает события навигации для перехода к URL-адресам различных типов.

Чтобы обработать события навигации, выполните приведенные далее действия.

  1. В MainWindow.xaml.csдобавьте следующую строку в верхней части над другими using операторами:

    using Microsoft.Web.WebView2.Core;

    Зарегистрируйте обработчик, который NavigationStarting отменяет все запросы, отличные от HTTPS:

  2. В MainWindow.xaml.csконструкторе добавьте следующую NavigationStarting строку:

    public MainWindow()
{
    this.InitializeComponent();
    MyWebView.NavigationStarting += EnsureHttps;
}

    Эта строка регистрирует EnsureHttps метод (добавленный ниже) в качестве прослушивателя NavigationStarting события.

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

    private void EnsureHttps(WebView2 sender, CoreWebView2NavigationStartingEventArgs args)
{
    String uri = args.Uri;
    if (!uri.StartsWith("https://"))
    {
        args.Cancel = true;
    }
    else
    {
        addressBar.Text = uri;
    }
}

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

  5. Нажмите клавишу F5.

    Проект будет создан, и откроется приложение.

  6. В приложении в адресной строке введите URL-адрес HTTP, например http://bing.com, и нажмите кнопку Перейти .

    Приложение не переходит на ту страницу, так как навигация заблокирована для сайтов HTTP. Мы еще не добавили диалоговое окно, чтобы сообщить пользователю, почему отображаемый сайт не изменился.

  7. Введите URL-адрес HTTPS, например https://bing.com, и нажмите кнопку Перейти .

    Приложение переходит на указанную страницу, так как навигация разрешена для сайтов HTTPS.

  8. В приложении в адресной строке введите строку без префикса, например bing.com, а затем нажмите кнопку Перейти .

    Приложение не переходит на страницу. Как UriFormatException и раньше, возникает исключение, которое отображается в области Вывод в Visual Studio.

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

Шаг 9. Вставка JavaScript для оповещения пользователя о адресе, отличном от HTTPS

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

  • Запустите внедренный Код JavaScript после создания глобального объекта.

  • Запустите внедренный JavaScript перед выполнением любого другого скрипта, включенного в HTML-документ.

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

Чтобы отобразить оповещение при попытке пользователя перейти на сайт, отличный от HTTPS, выполните следующие действия:

  1. В MainWindow.xaml.csметоде EnsureHttps добавьте следующую ExecuteScriptAsync строку:

    private void EnsureHttps(WebView2 sender, CoreWebView2NavigationStartingEventArgs args)
{
    String uri = args.Uri;
    if (!uri.StartsWith("https://"))
    {
        MyWebView.ExecuteScriptAsync($"alert('{uri} is not safe, try an https link')");
        args.Cancel = true;
    }
    else
    {
        addressBar.Text = uri;
    }
}

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

  3. Нажмите клавишу F5.

    Проект будет создан, и откроется приложение.

  4. В адресной строке приложения введите URL-адрес, отличный от HTTPS, например http://www.bing.com, и нажмите кнопку Перейти .

    Элемент управления WebView2 приложения отображает диалоговое окно оповещений для веб-сайтов, отличных от HTTPS, в котором говорится, что не-HTTPS uri небезопасно:

    Элемент управления WebView2 приложения отображает диалоговое окно оповещений для веб-сайтов, отличных от HTTPS

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

Поздравляем, вы создали приложение WebView2 WinUI 3 (Windows App SDK)!

WinAppSDK поддерживает пользовательские среды WebView2

WinAppSDK поддерживает пользовательские среды WebView2, начиная с WinAppSDK 1.5 (1.5.0-experimental2). Дополнительные сведения см. в статье WinUI3 WebView2 с пользовательским CoreWebView2Environment.

Чтобы создать экземпляр настраиваемой среды WebView2, можно инициализировать WebView2 с помощью одного из переопределений (перечисленных WebView2.EnsureCoreWebView2Async ниже) и передать пользовательское CoreWebView2Environment (и, при необходимости, настраиваемое CoreWebView2ControllerOptions):

public IAsyncAction EnsureCoreWebView2Async (CoreWebView2Environment environment)
public IAsyncAction EnsureCoreWebView2Async (CoreWebView2Environment environment, CoreWebView2ControllerOptions controllerOptions)

Также см. пример кода в разделе Отключение навигации SmartScreen ниже.

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

Особые рекомендации по WinUI 3 WebView2

Отключение навигации SmartScreen

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

CoreWebView2EnvironmentOptions environmentOptions = new CoreWebView2EnvironmentOptions();
environmentOptions.AdditionalBrowserArguments = "--disable-features=msSmartScreenProtection";

string browserFolder = null; // Use null to get default browser folder
string userDataFolder = null; // Use null to get default user data folder
CoreWebView2Environment environment = await CoreWebView2Environment.CreateWithOptionsAsync(
    browserFolder, userDataFolder, environmentOptions);

// ...

this.WebView2.EnsureCoreWebView2Async(environment);
Отключение SmartScreen с помощью переменной среды

Мы больше не рекомендуем использовать переменную среды. Вместо этого используйте приведенный выше подход на основе кода API.

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

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

Настройка DefaultBackgroundColor

В WebView2 для WinUI 3 DefaultBackgroundColor параметр существует в объекте WebView2 XAML. Например:

public MainWindow()
{
    this.InitializeComponent();
    MyWebView.DefaultBackgroundColor = Colors.LightBlue;
}

Прозрачность

WinUI 3 не поддерживает прозрачные фоны. См. раздел Поддержка прозрачного фона для WebView2? · Проблема No 2992.

Поддержка WinAppSDK для пользовательских сред WebView2

См . статью WinAppSDK, поддерживающую пользовательские среды WebView2 выше.

См. также

developer.microsoft.com:

  • Microsoft Edge WebView2 — начальное введение в функции WebView2 на developer.microsoft.com.

GitHub: