Share via

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

  • Статья

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

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

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

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

Завершенная версия этого учебного проекта (начиная с 2020 г.) доступна в репозитории WebView2Samples :

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

Настоящее руководство обновляется и создает только один, а не второй проект (Пакет), как в 2020 году.

Шаг 1. Установка Visual Studio и Windows App SDK

Даже если у вас установлена Среда Visual Studio, прочитайте следующую страницу и, возможно, обновите программное обеспечение и установите шаблоны проектов.

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

Вернитесь с этой страницы и выполните указанные ниже действия.

В этом примере не требуется отдельно устанавливать пакет SDK для WebView2. Ниже вы выберете шаблон проекта Пустое приложение, Упакованое (WinUI в настольном компьютере), в котором используется WindowsAppSDK, включающий пакет SDK для WebView2.

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

  1. Установите среду выполнения WebView2 на устройствах с Windows 10 версии 1803 (сборка 17134) или более поздней, установив из любого расположения:
  • Чтобы напрямую скачать только среду выполнения, используйте раздел Скачать среду выполнения WebView2 на странице Microsoft Edge WebView2 по адресу developer.microsoft.com.
  • Чтобы скачать и установить канал предварительной версии Microsoft Edge (бета-версия, разработка или Canary), перейдите в раздел Стать участником программы предварительной оценки Microsoft Edge. Каналы предварительной версии также называются каналами предварительной оценки. Каналы предварительной версии включают среду выполнения WebView2.

Затем выполните указанные ниже действия.

Шаг 3. Create пустого проекта WinUI 3

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

  1. Если Visual Studio не запущена, запустите Visual Studio (не Visual Studio Code). В окне запуска Visual Studio щелкните Create новый проект карта. Откроется окно Create нового проекта.

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

    Включение режима разработчика: Когда Visual Studio откроется в какой-то момент во время выполнения действий, описанных в этой статье, может появиться запрос на включение режима разработчика для компьютера. Дополнительные сведения при необходимости см. в разделе Включение устройства для разработки в разделе Создание классических приложений для Windows.

  2. В диалоговом окне Create новый проект в поле Поиск для шаблонов введите WinUI 3 на рабочем столе:

    Поиск по

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

    Если шаблоны WinUI отсутствуют в списке, необходимо установить шаблоны проектов, как упоминалось выше, из раздела Установка средств для Windows App SDK. Дополнительные советы по отображению шаблона:

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

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

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

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

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

  5. В текстовом поле Расположение введите или перейдите к расположению, например C:\Users\username\Documents\WebView2.

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

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

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

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

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

  7. В раскрывающемся списке Конфигурации решений (в середине верхней части окна) выберите Отладка.

  8. В раскрывающемся списке Платформы решений выберите платформу, например x64.

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

  10. Нажмите клавишу F5, чтобы выполнить сборку и запуск проекта. Откроется пустое классическое приложение WinUI без добавления элемента управления WebView2:

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

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

Обновление номеров целевых версий

Для шага сборки выше: Если вы обновляете предыдущий проект, может потребоваться обновить номера версий для целевой версии и минимальной версии. Для этого в разделе Решение щелкните проект правой кнопкой мыши и выберите Изменить файл проекта. Откроется .csproj файл. Убедитесь, что значения обновлены следующим образом, а затем сохраните все изменения и выполните сборку проекта.

    <TargetFramework>net6.0-windows10.0.19041.0</TargetFramework>
    <TargetPlatformMinVersion>10.0.17763.0</TargetPlatformMinVersion>

Приведенные выше значения представляют:

  • Целевая версия: Windows 10, версия 2004 (сборка 19041) или более поздняя.
  • Минимальная версия: Windows 10, версия 1809 (сборка 17763).

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

Этот проект учебника основан на шаблоне проекта Пустое приложение, Упакованое (WinUI в рабочем столе). Этот шаблон проекта использует WindowsAppSDK, который включает пакет SDK для WebView2.

Измените MainWindow.xaml файлы и MainWindow.xaml.cs , чтобы добавить элемент управления WebView2 в пустой проект приложения WinUI 3, как показано ниже.

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

  2. Добавьте пространство имен XAML WebView2, вставив следующий атрибут в начальный <Window> тег:

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

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

    <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"
    mc:Ignorable="d">

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

  3. Чтобы добавить элемент управления WebView2, замените весь <StackPanel> элемент следующим <Grid> кодом. Свойство Source в нижней части экрана задает исходный URI, отображаемый в элементе управления WebView2 (https://www.microsoft.com):

    <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>

  4. В Обозреватель решений разверните MainWindow.xaml и откройте .MainWindow.xaml.cs

  5. В MainWindow.xaml.csзакомментируйте следующую строку, как показано ниже:

        // myButton.Content = "Clicked";

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

  7. Нажмите клавишу F5, чтобы выполнить сборку и запуск проекта.

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

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

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

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:

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

Чтобы разрешить пользователям управлять веб-страницей, отображаемой в элементе управления 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следующий код в myButton_Click, перезаписав существующий myButton_Click метод (который почти пуст). Этот код перемещает элемент управления WebView2 на URL-адрес, указанный в адресной строке.

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

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

  4. Нажмите клавишу F5, чтобы выполнить сборку и запуск проекта.

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

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

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

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

    Возникает ArgumentException исключение, которое появляется после закрытия приложения, так как URL-адрес не начинается с http:// или https://.

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

Шаг 6. События навигации

В этом разделе вы добавите код для импорта библиотеки WebView2 Core.

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

    using Microsoft.Web.WebView2.Core;

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

    • NavigationStarting
    • SourceChanged
    • ContentLoading
    • HistoryChanged
    • NavigationCompleted

    Если происходит перенаправление HTTP, в строке имеется несколько NavigationStarting событий.

    Дополнительные сведения см. в разделе События навигации для приложений WebView2.

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

    • SourceChanged
    • ContentLoading
    • HistoryChanged

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

  2. В MainWindow.xaml.csконструкторе добавьте следующую NavigationStarting строку, чтобы зарегистрировать EnsureHttps метод :

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

  3. В MainWindow.xaml.csпод конструктором добавьте следующий 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. Закройте приложение.

Шаг 7. Создание скриптов

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

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

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

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

  1. В методе 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 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: