Начало работы с WebView2 в приложениях WinForms

  • Статья

Это руководство поможет вам:

  • Настройте средства разработки.
  • Используйте шаблон проекта Visual Studio Windows Forms приложения (платформа .NET Framework) C#, чтобы создать проект WinForms.
  • Установите пакет SDK для Microsoft.Web.WebView2 для проекта WinForms.
  • Узнайте об основных понятиях WebView2.

Шаг 1. При необходимости клонирование или скачивание репозитория WebView2Samples

Выполните одно из следующих действий.

  • Создайте проект в Visual Studio, начиная с шаблона проекта, выполнив действия, описанные в разделах ниже. Это позволит получить последнюю структуру кода и проекта.

  • Клонируйте или скачайте WebView2Samples репозиторий, откройте готовый проект в Visual Studio и выполните действия, описанные в этой статье, чтобы понять создание проекта WinForms и добавленный код WebView2. См . статью Скачивание репозитория WebView2Samples в статье Настройка среды разработки для WebView2. Полная версия этого учебного проекта доступна в каталоге репозитория WebView2Samples WinForms_GettingStarted.

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

Пример в репозитории может быть не таким актуальным, как проект, создаваемый с помощью последних шаблонов проектов Visual Studio.

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

Требуется Microsoft Visual Studio. Microsoft Visual Studio Code не поддерживается в этом руководстве.

  1. Если Visual Studio еще не установлен, откройте страницу Microsoft Visual Studio в новом окне или вкладке и установите Visual Studio 2017 или более поздней версии, например Visual Studio 2022 Professional.

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

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

Начните с простого классического проекта, содержащего одно окно main.

  1. Откройте Visual Studio.

  2. Выберите Файл>Создать>Проект.

    Откроется окно Открыть последнюю версию Visual Studio:

    На открывающей панели Visual Studio отображается карта Создание проекта

  3. В правой части экрана щелкните карта Создать проект. Откроется окно Создание проекта в Visual Studio.

  4. В текстовое поле Поиск вставьте или начните вводить следующее:

    C# Windows Forms App (.NET Framework)

    Появятся результаты поиска, в котором перечислены типы проектов.

  5. Выберите карта приложение Windows Forms C# (платформа .NET Framework). Убедитесь, что имя совпадает со значком C#, а затем имя Windows Forms App (платформа .NET Framework). Затем нажмите кнопку Далее :

    На панели

  6. В текстовом поле Имя проекта введите имя проекта. В этой статье учебника используется имя WinForms_GettingStarted, например имя каталога репозитория для завершенного проекта.

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

  8. В раскрывающемся списке Платформа выберите платформа .NET Framework 4.7.2 или более поздней версии, например платформа .NET Framework 4.8:

    Заполнение окна

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

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

    Окно Visual Studio с базовым проектом WinForms и Designer Forms

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

  11. Выберите Отладка>Начать отладку (F5).

    Откроется пустое окно Form1 из нового проекта WinForms:

    Пустое окно Form1 из нового проекта WinForms

  12. Закройте окно Form1 .

Теперь у вас есть пустой проект WinForms, который выполняется. Затем настройте проект для добавления содержимого WebView2.

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

Для каждого проекта WebView2 вы используете диспетчер пакетов NuGet в Visual Studio, чтобы добавить пакет SDK WebView2 в проект. Вы устанавливаете пакет NuGet пакета NuGet пакета Sdk для Microsoft.Web.WebView2 для использования в текущем проекте.

Используйте NuGet, чтобы добавить пакет SDK WebView2 в проект следующим образом:

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

    Управление пакетами NuGet

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

  2. Откройте вкладку Обзор в левом верхнем углу.

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

  4. В строке поиска введите WebView2, а затем под строкой поиска щелкните Microsoft.Web.WebView2 , чтобы выбрать его:

    Диспетчер пакетов NuGet в Visual Studio, установка пакета NuGet пакета NuGet microsoft.Web.WebView2 SDK для текущего проекта

    Чтобы увеличить масштаб, щелкните правой кнопкой мыши >Открыть изображение на новой вкладке.

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

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

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

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

  8. Закройте окно диспетчера пакетов NuGet.

  9. Выберите Отладка>Начать отладку (F5), чтобы выполнить сборку и запуск проекта.

    В работающем проекте отображается то же пустое окно, что и раньше:

    Пустое окно Form1 из нового проекта WinForms

  10. Закройте окно Form1 .

Вы добавили пакет SDK Для WebView2 в проект, но еще не добавили в проект код WebView2.

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

Теперь, когда пакет SDK для WebView2 установлен для проекта WinForms, добавьте в приложение элемент управления WebView2 следующим образом:

Начальный проект уже имеет Form1.cs форму, но мы добавим еще одну, как Form2.cs, чтобы узнать, как это сделать.

  1. Выберите ProjectAdd Form (Windows Forms) (Форма добавления проекта > (Windows Forms)).

  2. В окне Добавление нового элемента слева выберите Элементы >Visual C#Windows Forms.

  3. Справа выберите Форма (Windows Forms) и нажмите кнопку Добавить:

    Окно

    Теперь проект имеет дополнительную форму с именем Form2.csфайла, показанным в Designer формы и в Обозреватель решений:

    Добавленная форма, Form2.cs, в Designer Формы и в Обозреватель решений

  4. Щелкните холст Form1 . Мы не будем использовать Form2.

  5. Выберите Просмотр>панели элементов.

    Ниже описано, где вы добавляете в приложение содержимое WebView2:

  6. На панели элементов щелкните Элемент управления WebView2 Windows Forms, чтобы развернуть параметры.

    В Visual Studio 2017 по умолчанию WebView2 не отображается на панели элементов. Чтобы включить отображение WebView2 на панели элементов, выберитеПараметры>инструментов>Общие> и задайте для параметра Автоматически заполнять панель элементов значение True.

  7. На панели элементов щелкните или перетащите элемент управления WebView2 на холст Designer форм добавленного элемента управления, например Form2.cs:

    Панель элементов, отображающая WebView2

  8. Перетащите стороны элемента управления WebView2, чтобы заполнить почти весь холст.

  9. Убедитесь, что в форме выбран новый элемент управления WebView2 . На панели Свойства в разделе Конструктор задайте для свойства (Имя) значение webView (строчные буквы "w", заглавная буква "V", без числового суффикса). Изначально элементу управления может быть присвоено другое имя, например webView21. При необходимости используйте кнопки Сортировка по категориям и по алфавиту , чтобы найти свойства:

    Свойства элемента управления WebView2

  10. На панели Свойства в разделе Прочее задайте для свойства Source значение https://www.microsoft.com. Свойство Source задает исходный URL-адрес, который будет отображаться в элементе управления WebView2.

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

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

    Элемент управления WebView2 отображает содержимое из https://www.microsoft.com, в элементе управления WebView2 в форме Windows Forms со ссылкой Перейти к main содержимому, если вы нажали ALT+TAB, чтобы переключиться в окно:

    Alt+TAB приводит к тому, что в примере приложения изначально отображается ссылка

  13. При необходимости щелкните ссылку Перейти к main содержимого.

    Элемент управления WebView2 отображает содержимое из https://www.microsoft.com, в элементе управления WebView2 в форме Windows Forms:

    Пример приложения отображает веб-сайт Майкрософт

  14. Закройте окно Form1 .

Если вы работаете на мониторе с высоким разрешением, может потребоваться настроить приложение Windows Forms для поддержки высокого разрешения.

Шаг 6. Добавление элементов управления и событий изменения размера окна процесса

Добавьте дополнительные элементы управления в форму Windows Forms из панели элементов, а затем обработайте события изменения размера окна, как показано ниже.

  1. Выберите Просмотреть>панель элементов или щелкните вкладку Панель элементов слева.

  2. На панели элементов щелкните Общие элементы управления.

    Добавьте элемент управления "Текстовое поле", как показано ниже.

  3. Перетащите элемент управления TextBox на холст Form1.cs form Designer.

  4. Убедитесь, что элемент управления TextBox имеет фокус.

  5. На панели Свойства в разделе Конструктор измените (Имя) ( возможно, с textBox1) на addressBar.

    Добавьте элемент управления "Кнопка", как показано ниже.

  6. Перетащите элемент управления Кнопка на холст Designer формы Form1.cs.

  7. Убедитесь, что элемент управления "Кнопка" имеет фокус.

  1. На панели Свойства в разделе Внешний вид полужирным шрифтом (около 15 свойств вниз) измените свойство Text (вероятно, с button1) на Go!

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

  2. Поместите текстовое поле в левой части формы, выровненное по вертикали с кнопкой, как показано ниже:

    Конструктор WinForms

  3. Измените размер текстового поля, как показано ниже.

    Текстовое поле и кнопка конструктора WinForms

  4. Щелкните Просмотреть>код , чтобы открыть Form1.cs.

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

  5. Удалите следующий код:

       public Form1()
{
   InitializeComponent();
}

  6. Вставьте этот код в то же расположение:

    public Form1()
{
   InitializeComponent();
   this.Resize += new System.EventHandler(this.Form_Resize);
}

private void Form_Resize(object sender, EventArgs e)
{
   webView.Size = this.ClientSize - new System.Drawing.Size(webView.Location);
   goButton.Left = this.ClientSize.Width - goButton.Width;
   addressBar.Width = goButton.Left - addressBar.Left;
}

    добавлен код Form_Resize

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

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

    Откроется окно Form1 , в котором отображается содержимое веб-страницы из https://www.microsoft.com:

    Окно WinForm Form1, в котором отображается содержимое веб-страницы из microsoft.com

    Если нажать клавиши ALT+TAB, чтобы переключиться в окно Form1, может потребоваться щелкнуть добавленную ссылку Перейти к main содержимого.

  9. Прокрутите окно вверх и вниз с помощью колесика мыши. Элементы управления вводом остаются на месте.

  10. Перетащите угол окна, чтобы изменить его размер. Текстовое поле изменяет ширину.

  11. Закройте окно Form1 .

Шаг 7. Навигация

Разрешить пользователям изменять URL-адрес, отображаемый элементом управления WebView2, считывая текст, введенный в текстовое поле, в качестве адресной строки.

  1. Выберите Просмотреть>код , Form1.cs чтобы открыть его в редакторе кода.

  2. В Form1.csдобавьте CoreWebView2 пространство имен, вставив следующий код в верхней части файла в виде строки 1:

    using Microsoft.Web.WebView2.Core;

  3. Выберите вкладку Form1.cs [Конструктор] , а затем дважды щелкните кнопку Go! . Метод goButton_Click добавляется в Form1.cs файл.

  4. Вставьте следующий код в файл, чтобы заменить пустой goButton_Click метод, чтобы текст метода был следующим:

    private void goButton_Click(object sender, EventArgs e)
{
   if (webView != null && webView.CoreWebView2 != null)
   {
      webView.CoreWebView2.Navigate(addressBar.Text);
   }
}

    goButton_Click Теперь функция перейдет к элементу управления WebView2 по URL-адресу, который вводится в текстовом поле адресной строки.

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

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

  7. В адресной строке введите URL-адрес, который начинается с https, например https://www.bing.com, и нажмите кнопку Go! :

    bing.com

    Элемент управления WebView2 отображает содержимое веб-страницы для URL-адреса.

  8. В адресной строке введите строку, которая не начинается с http, например www.bing.com, и нажмите кнопку Go! .

    Исключение аргумента из-за ввода url-адреса, отличного от URL-адреса

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

  9. Выберите Отладка>Остановить отладку или нажмите кнопку Продолжить. Окно Form1 закрывается.

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

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

  • NavigationStarting
  • SourceChanged
  • ContentLoading
  • HistoryChanged
  • NavigationCompleted

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

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

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

  • SourceChanged
  • ContentLoading
  • HistoryChanged

Примечание.

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

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

  1. В Form1.csобновите Form1() конструктор, чтобы он соответствовал следующему коду, а также добавьте функцию EnsureHttps(sender, args) под конструктором следующим образом:

    public Form1()
{
   InitializeComponent();
   this.Resize += new System.EventHandler(this.Form_Resize);

   webView.NavigationStarting += EnsureHttps;
}

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

    В конструкторе EnsureHttps регистрируется как обработчик события в элементе NavigationStarting управления WebView2.

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

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

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

    Загружается URL-адрес https; веб-содержимое изменится со значения по умолчанию Microsoft.com на Bing.com.

  5. В адресной строке введите URL-адрес, который начинается с http, например http://www.microsoft.com, и нажмите кнопку Go! .

    URL-адрес HTTP не загружается; веб-страница Bing.com по-прежнему отображается. В отличие от этого, вход http://www.microsoft.com в Microsoft Edge работает; он перенаправляет на сайт HTTPS для Microsoft.com.

  6. В адресной строке введите URL-адрес, который начинается с https, например https://www.microsoft.com, и нажмите кнопку Go! .

    Загружается URL-адрес https; Теперь появится веб-страница Microsoft.com, так как вы добавили "s" после "http".

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

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

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

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

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

  1. Измените функцию EnsureHttps , чтобы добавить следующую строку, содержащую ExecuteScriptAsync:

    void EnsureHttps(object sender, CoreWebView2NavigationStartingEventArgs args)
{
   String uri = args.Uri;
   if (!uri.StartsWith("https://"))
   {
      webView.CoreWebView2.ExecuteScriptAsync($"alert('{uri} is not safe, try an https link')");
      args.Cancel = true;
   }
}

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

    alert('{uri} is not safe, try an https link')

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

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

  4. Попробуйте перейти http://www.bing.com к (с http префиксом вместо https префикса).

    Приложение отображает оповещение:

    Оповещение HTTP, в которое указано, что попробуйте https.

Шаг 10. Обмен данными между хост-содержимым и веб-сайтом

Содержимое узла и веб-сайта можно использовать postMessage для взаимодействия друг с другом следующим образом:

  • Веб-содержимое в элементе управления WebView2 можно использовать для window.chrome.webview.postMessage отправки сообщения на узел. Узел обрабатывает сообщение с помощью любого зарегистрированного WebMessageReceived на узле.

  • Размещает публикацию сообщений в веб-содержимое в элементе управления WebView2 с помощью CoreWebView2.PostWebMessageAsString или CoreWebView2.PostWebMessageAsJSON. Эти сообщения перехватываются обработчиками, добавленными в window.chrome.webview.addEventListener.

Механизм связи передает сообщения из веб-содержимого на узел с помощью собственных возможностей.

В проекте, когда элемент управления WebView2 переходит по URL-адресу, он отображает URL-адрес в адресной строке и оповещает пользователя о URL-адресе, отображаемом в элементе управления WebView2.

  1. В Form1.csобновите Form1() конструктор и создайте InitializeAsync() под ним функцию, соответствующую следующему коду:

    public Form1()
{
   InitializeComponent();
   this.Resize += new System.EventHandler(this.Form_Resize);
   webView.NavigationStarting += EnsureHttps;
   InitializeAsync();
}

async void InitializeAsync()
{
   await webView.EnsureCoreWebView2Async(null);
}

    Функция InitializeAsync ожидает EnsureCoreWebView2Async, так как инициализация выполняется асинхронно CoreWebView2 .

    Затем зарегистрируйте обработчик событий для реагирования на WebMessageReceived. Этот обработчик событий будет зарегистрирован после CoreWebView2 инициализации.

  2. В Form1.csобновите InitializeAsyncи добавьте UpdateAddressBar под ним следующим образом:

    async void InitializeAsync()
{
   await webView.EnsureCoreWebView2Async(null);
   webView.CoreWebView2.WebMessageReceived += UpdateAddressBar;
}

void UpdateAddressBar(object sender, CoreWebView2WebMessageReceivedEventArgs args)
{
   String uri = args.TryGetWebMessageAsString();
   addressBar.Text = uri;
   webView.CoreWebView2.PostWebMessageAsString(uri);
}

    Затем, чтобы WebView2 отправлял веб-сообщение и реагировал на него, после CoreWebView2 инициализации узел внедряет скрипт в веб-содержимое, чтобы:

    • Отправьте URL-адрес на узел с помощью postMessage.

    • Зарегистрируйте обработчик событий для отображения сообщения, отправленного с узла, в поле оповещения перед отображением содержимого веб-страницы.

  3. В Form1.csобновите InitializeAsync , чтобы соответствовать следующему коду:

    async void InitializeAsync()
{
   await webView.EnsureCoreWebView2Async(null);
   webView.CoreWebView2.WebMessageReceived += UpdateAddressBar;

   await webView.CoreWebView2.AddScriptToExecuteOnDocumentCreatedAsync("window.chrome.webview.postMessage(window.document.URL);");
   await webView.CoreWebView2.AddScriptToExecuteOnDocumentCreatedAsync("window.chrome.webview.addEventListener(\'message\', event => alert(event.data));");
}

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

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

  6. Введите URL-адрес, например https://www.bing.com:

    Обновленный URL-адрес адресной строки изначально отображается в поле оповещения

    Первоначально появится оповещение, отображающее результирующий URL-адрес, отправленный с хост-сайта.

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

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

    Приложение отображает URL-адрес в адресной строке.

    • При запуске приложения URL-адрес по умолчанию — https://www.microsoft.com, а результирующий отображаемый адрес отображает языковой стандарт, например https://www.microsoft.com/en-us/.

    • Если ввести https://www.bing.comзначение , результирующий адрес будет вариантом, например https://www4.bing.com/?form=DCDN.

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

Распространение приложения WebView2

Если вы хотите распространить приложение, полученное из этого руководства, вам потребуется распространить среду выполнения WebView2 вместе с приложением. Затем среда выполнения WebView2 будет автоматически установлена на компьютерах пользователей. Дополнительные сведения см. в разделе Распространение приложения и среды выполнения WebView2.

См. также