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

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

В этой статье описано, как настроить средства разработки и создать начальное приложение 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. Установка последней версии пакета SDK для Windows App

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

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

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

  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# в нижней части дерева.

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

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

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

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

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

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

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

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

Чтобы создать приложение WebView2 для WinUI 3 (пакет SDK для Windows App):

  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. Обновление или установка пакета SDK для Windows App

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

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

  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 класс, представляющий главное окно, отображаемое экземпляром приложения. Классы являются производными от типов в 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 (пакет SDK для Windows App)!

См. также

developer.microsoft.com:

GitHub:

  • Last updated on