Поделиться через

Веб-просмотр

Пользовательский интерфейс приложений .NET (.NET MAUI) WebView отображает удаленные веб-страницы, локальные HTML-файлы и HTML-строки в приложении. Содержимое, отображаемое WebView, включает поддержку каскадных таблиц стилей (CSS) и JavaScript. По умолчанию проекты .NET MAUI включают разрешения платформы, необходимые для того, чтобы WebView мог отображать удаленную веб-страницу.

WebView определяет следующие свойства:

  • Cookiesтипа CookieContainerпредоставляет хранилище для коллекции файлов cookie.
  • CanGoBackтипа boolуказывает, может ли пользователь перейти на предыдущие страницы. Это свойство доступно только для чтения.
  • CanGoForwardтипа boolуказывает, может ли пользователь перейти вперед. Это доступное только для чтения свойство.
  • Sourceтипа WebViewSourceпредставляет расположение, отображаемое WebView.
  • UserAgent, типа string, представляет агента пользователя. Значение по умолчанию — это агент пользователя базового браузера платформы или null, если он не может быть определен.

Эти свойства поддерживаются объектами BindableProperty, что означает, что они могут использоваться в качестве объектов привязки данных и быть стилизованы.

Для свойства Source можно задать объект UrlWebViewSource или объект HtmlWebViewSource, производный от WebViewSource. UrlWebViewSource используется для загрузки веб-страницы, указанной с URL-адресом, а объект HtmlWebViewSource используется для загрузки локального HTML-файла или локального HTML.

WebView определяет событие Navigating, которое возникает при запуске навигации по страницам, и событие Navigated, которое возникает при завершении навигации по страницам. Объект WebNavigatingEventArgs, сопровождающий событие Navigating, определяет свойство Cancel типа bool, которое можно использовать для отмены навигации. Объект WebNavigatedEventArgs, сопровождающий событие Navigated, определяет свойство Result типа WebNavigationResult, указывающее результат навигации.

WebView определяет следующие события:

  • Navigating, возникающее при запуске навигации по страницам. Объект WebNavigatingEventArgs, сопровождающий это событие, определяет свойство Cancel типа bool, которое можно использовать для отмены навигации.
  • Navigated, который активируется при завершении навигации по страницам. Объект WebNavigatedEventArgs, который сопровождает это событие, определяет свойство Result типа WebNavigationResult, указывающее результат навигации.
  • ProcessTerminated, которое возникает, когда процесс WebView заканчивается неожиданно. Объект WebViewProcessTerminatedEventArgs, сопровождающий это событие, определяет свойства конкретной платформы, указывающие, почему процесс завершился сбоем.

Важный

WebView должен указывать свойства HeightRequest и WidthRequest, когда находится в HorizontalStackLayout, StackLayoutили VerticalStackLayout. Если не указать эти свойства, WebView не будет отображаться.

Отображение веб-страницы

Чтобы отобразить удаленную веб-страницу, задайте для свойства Source значение string, указывающее универсальный код ресурса (URI):

<WebView Source="https://learn.microsoft.com/dotnet/maui" />

Эквивалентный код C#:

WebView webvView = new WebView
{
    Source = "https://learn.microsoft.com/dotnet/maui"
};

URI должны быть полностью сформированы с указанным протоколом.

Заметка

Несмотря на то, что свойство Source является типа WebViewSource, его можно задать как строковый URI. Это связано с тем, что .NET MAUI включает преобразователь типов и неявный оператор преобразования, который преобразует URI на основе строк в объект UrlWebViewSource.

Настройте App Transport Security в iOS и Mac Catalyst

С версии 9 iOS позволит приложению взаимодействовать только с безопасными серверами. Приложению необходимо включить связь с небезопасными серверами.

В следующей конфигурации Info.plist показано, как разрешить обход требований к безопасности транспорта Apple (ATS) для определенного домена:

	<key>NSAppTransportSecurity</key>
	<dict>
		<key>NSExceptionDomains</key>
		<dict>
			<key>mydomain.com</key>
			<dict>
				<key>NSIncludesSubdomains</key>
				<true/>
				<key>NSTemporaryExceptionAllowsInsecureHTTPLoads</key>
				<true/>
				<key>NSTemporaryExceptionMinimumTLSVersion</key>
				<string>TLSv1.1</string>
			</dict>
		</dict>
	</dict>

Рекомендуется использовать только определенные домены для обхода ATS, что позволяет использовать надежные сайты, используя дополнительные возможности безопасности для недоверенных доменов.

В следующей конфигурации Info.plist показано, как отключить ATS для приложения:

	<key>NSAppTransportSecurity</key>
	<dict>
		<key>NSAllowsArbitraryLoads</key>
		<true/>
	</dict>

Важный

Если приложению требуется подключение к небезопасным веб-сайту, вы всегда должны ввести домен в качестве исключения с помощью ключа NSExceptionDomains вместо отключения ATS полностью с помощью ключа NSAllowsArbitraryLoads.

Отображение локального HTML-кода

Чтобы отобразить встроенный HTML-код, установите свойство Source в объект HtmlWebViewSource.

<WebView>
    <WebView.Source>
        <HtmlWebViewSource Html="&lt;HTML&gt;&lt;BODY&gt;&lt;H1&gt;.NET MAUI&lt;/H1&gt;&lt;P&gt;Welcome to WebView.&lt;/P&gt;&lt;/BODY&gt;&lt;HTML&gt;" />
    </WebView.Source>
</WebView>

В XAML строки HTML могут стать нечитаемыми из-за экранирования символов < и >. Таким образом, для повышения удобочитаемости HTML можно встроить в разделе CDATA.

<WebView>
    <WebView.Source>
        <HtmlWebViewSource>
            <HtmlWebViewSource.Html>
                <![CDATA[
                <HTML>
                <BODY>
                <H1>.NET MAUI</H1>
                <P>Welcome to WebView.</P>
                </BODY>
                </HTML>
                ]]>
            </HtmlWebViewSource.Html>
        </HtmlWebViewSource>
    </WebView.Source>
</WebView>

Эквивалентный код C#:

WebView webView = new WebView
{
    Source = new HtmlWebViewSource
    {
        Html = @"<HTML><BODY><H1>.NET MAUI</H1><P>Welcome to WebView.</P></BODY></HTML>"
    }
};

Отображение локального HTML-файла

Чтобы отобразить локальный HTML-файл, добавьте файл в папку Resources\Raw проекта приложения и задайте для его действия сборки значение MauiAsset. Затем файл можно загрузить из встроенного HTML- кода, определенного в объекте HtmlWebViewSource, заданном в качестве значения свойства Source:

<WebView>
    <WebView.Source>
        <HtmlWebViewSource>
            <HtmlWebViewSource.Html>
                <![CDATA[
                <html>
                <head>
                </head>
                <body>
                <h1>.NET MAUI</h1>
                <p>The CSS and image are loaded from local files!</p>
                <p><a href="localfile.html">next page</a></p>
                </body>
                </html>                    
                ]]>
            </HtmlWebViewSource.Html>
        </HtmlWebViewSource>
    </WebView.Source>
</WebView>

Локальный HTML-файл может загружать каскадные таблицы стилей (CSS), JavaScript и изображения, если они также были добавлены в проект приложения с помощью действия сборки MauiAsset.

Дополнительные сведения о необработанных ресурсах см. в Необработанные ресурсы.

Перезагрузить содержимое

WebView имеет метод Reload, который можно вызвать для перезагрузки источника:

WebView webView = new WebView();
...
webView.Reload();

При вызове метода Reload событие ReloadRequested указывает, что запрос был выполнен для перезагрузки текущего содержимого.

Выполнение навигации

WebView поддерживает программную навигацию с помощью методов GoBack и GoForward. Эти методы обеспечивают навигацию по стеку страниц WebView и должны вызываться только после проверки значений свойств CanGoBack и CanGoForward:

WebView webView = new WebView();
...

// Go backwards, if allowed.
if (webView.CanGoBack)
{
    webView.GoBack();
}

// Go forwards, if allowed.
if (webView.CanGoForward)
{
    webView.GoForward();
}

Когда навигация по страницам происходит в WebView, инициированной программно или пользователем, случаются следующие события:

  • Navigating, которое возникает при старте навигации по странице. Объект WebNavigatingEventArgs, сопровождающий событие Navigating, определяет свойство Cancel типа bool, которое можно использовать для отмены навигации.
  • Navigated, который возникает при завершении навигации по страницам. Объект WebNavigatedEventArgs, сопровождающий событие Navigated, определяет свойство Result типа WebNavigationResult, указывающее результат навигации.

Обработка разрешений в Android

При просмотре на страницу, которая запрашивает доступ к оборудованию записи устройства, например камере или микрофону, разрешение должно быть предоставлено элементом управления WebView. Элемент управления WebView использует тип Android.Webkit.WebChromeClient в Android для реагирования на запросы разрешений. Однако реализация WebChromeClient, предоставляемая .NET MAUI, игнорирует запросы разрешений. Необходимо создать новый тип, наследующий от MauiWebChromeClient и утверждающий запросы на разрешения.

Важный

Настройка WebView для утверждения запросов разрешений при использовании этого подхода требует Android API 26 или более поздней версии.

Запросы разрешений с веб-страницы на элемент управления WebView отличаются от запросов разрешений от приложения .NET MAUI пользователю. Разрешения приложения .NET MAUI запрашиваются и утверждаются пользователем для всего приложения. Элемент управления WebView зависит от способности приложения получить доступ к оборудованию. Чтобы проиллюстрировать эту концепцию, рассмотрим веб-страницу, которая запрашивает доступ к камере устройства. Даже если этот запрос утвержден элементом управления WebView, но приложение .NET MAUI не имеет утверждения пользователем для доступа к камере, веб-страница не сможет получить доступ к камере.

Ниже показано, как перехватывать запросы на разрешения от элемента управления WebView для использования камеры. Если вы пытаетесь использовать микрофон, шаги будут похожи, за исключением того, что вы будете использовать разрешения, связанные с микрофоном, вместо разрешений, связанных с камерой.

  1. Сначала добавьте необходимые разрешения приложения в манифест Android. Откройте файл Platform/Android/AndroidManifest.xml и добавьте следующее в узел manifest:

    <uses-permission android:name="android.permission.CAMERA" />

  2. В какой-то момент в приложении, например при загрузке страницы, содержащей элемент управления WebView, запросите разрешение от пользователя, чтобы разрешить приложению доступ к камере.

    private async Task RequestCameraPermission()
{
    PermissionStatus status = await Permissions.CheckStatusAsync<Permissions.Camera>();

    if (status != PermissionStatus.Granted)
        await Permissions.RequestAsync<Permissions.Camera>();
}

  3. Добавьте следующий класс в папку Platforms/Android, изменив корневое пространство имен так, чтобы оно соответствовало пространству имен вашего проекта (не добавляйте .Platforms.Android в пространство имен).

    using Android.Webkit;
using Microsoft.Maui.Handlers;
using Microsoft.Maui.Platform;

namespace MauiAppWebViewHandlers.Platforms.Android;

internal class MyWebChromeClient: MauiWebChromeClient
{
    public MyWebChromeClient(IWebViewHandler handler) : base(handler)
    {

    }

    public override void OnPermissionRequest(PermissionRequest request)
    {
        // Process each request
        foreach (var resource in request.GetResources())
        {
            // Check if the web page is requesting permission to the camera
            if (resource.Equals(PermissionRequest.ResourceVideoCapture, StringComparison.OrdinalIgnoreCase))
            {
                // Get the status of the .NET MAUI app's access to the camera
                PermissionStatus status = Permissions.CheckStatusAsync<Permissions.Camera>().Result;

                // Deny the web page's request if the app's access to the camera is not "Granted"
                if (status != PermissionStatus.Granted)
                    request.Deny();
                else
                    request.Grant(request.GetResources());

                return;
            }
        }

        base.OnPermissionRequest(request);
    }
}

    В предыдущем фрагменте класс MyWebChromeClient наследуется от MauiWebChromeClientи переопределяет метод OnPermissionRequest для перехвата запросов на разрешение веб-страницы. Каждый элемент разрешения проверяется, соответствует ли он константе строки PermissionRequest.ResourceVideoCapture, представляющей камеру. Если разрешение на использование камеры получено, код проверяет, имеет ли приложение доступ к камере. Если у страницы есть разрешение, запрос разрешён.

  4. Используйте метод SetWebChromeClient в элементе управления WebView Android, чтобы задать для клиента chrome значение MyWebChromeClient. В следующих двух элементах показано, как настроить клиент chrome:

    • Учитывая элемент управления .NET MAUI WebView с именем theWebViewControl, вы можете задать клиент chrome непосредственно в представлении платформы, который является элементом управления Android:

      ((IWebViewHandler)theWebViewControl.Handler).PlatformView.SetWebChromeClient(new MyWebChromeClient((IWebViewHandler)theWebViewControl.Handler));

    • Вы также можете использовать сопоставление свойств обработчика, чтобы заставить все элементы управления WebView использовать вашего клиента chrome. Дополнительную информацию см. в разделе Обработчики.

      Метод CustomizeWebViewHandler следующего фрагмента должен вызываться при запуске приложения, например в методе MauiProgram.CreateMauiApp.

      private static void CustomizeWebViewHandler()
{
#if ANDROID26_0_OR_GREATER
    Microsoft.Maui.Handlers.WebViewHandler.Mapper.ModifyMapping(
        nameof(Android.Webkit.WebView.WebChromeClient),
        (handler, view, args) => handler.PlatformView.SetWebChromeClient(new MyWebChromeClient(handler)));
#endif
}

Настройка файлов cookie

Куки-файлы можно настроить на WebView, чтобы они отправлялись с веб-запросом на указанный URL-адрес. Задайте файлы cookie, добавив объекты Cookie в CookieContainer, а затем задайте контейнер в качестве значения привязываемого свойства WebView.Cookies. В следующем коде показан пример:

using System.Net;

CookieContainer cookieContainer = new CookieContainer();
Uri uri = new Uri("https://learn.microsoft.com/dotnet/maui", UriKind.RelativeOrAbsolute);

Cookie cookie = new Cookie
{
    Name = "DotNetMAUICookie",
    Expires = DateTime.Now.AddDays(1),
    Value = "My cookie",
    Domain = uri.Host,
    Path = "/"
};
cookieContainer.Add(uri, cookie);
webView.Cookies = cookieContainer;
webView.Source = new UrlWebViewSource { Url = uri.ToString() };

В этом примере в объект CookieContainer добавляется один Cookie, который затем устанавливается в качестве значения свойства WebView.Cookies. Когда WebView отправляет веб-запрос на указанный URL-адрес, файл cookie отправляется с запросом.

Вызов JavaScript

WebView включает возможность вызова функции JavaScript из C# и возврата любого результата в вызывающий код C#. Это взаимодействие выполняется с помощью метода EvaluateJavaScriptAsync, который показан в следующем примере:

Entry numberEntry = new Entry { Text = "5" };
Label resultLabel = new Label();
WebView webView = new WebView();
...

int number = int.Parse(numberEntry.Text);
string result = await webView.EvaluateJavaScriptAsync($"factorial({number})");
resultLabel.Text = $"Factorial of {number} is {result}.";

Метод WebView.EvaluateJavaScriptAsync оценивает JavaScript, указанный в качестве аргумента, и возвращает любой результат в виде string. В этом примере вызывается функция JavaScript factorial, которая возвращает факториал number в результате. Эта функция JavaScript определена в локальном HTML-файле, который загружается WebView и показан в следующем примере:

<html>
<body>
<script type="text/javascript">
function factorial(num) {
        if (num === 0 || num === 1)
            return 1;
        for (var i = num - 1; i >= 1; i--) {
            num *= i;
        }
        return num;
}
</script>
</body>
</html>

Настройка встроенного WebView на iOS и Mac Catalyst

Собственный элемент управления WebView — это MauiWKWebView в iOS и Mac Catalyst, который является производным от WKWebView. Одна из перегрузок конструктора MauiWKWebView позволяет задать объект WKWebViewConfiguration, предоставляющий сведения о настройке объекта WKWebView. Типичные конфигурации включают настройку агента пользователя, указание файлов cookie для доступа к веб-содержимому и внедрение пользовательских скриптов в веб-содержимое.

Вы можете создать объект WKWebViewConfiguration в приложении, а затем настроить его свойства в соответствии с требованиями. Кроме того, можно вызвать статический метод MauiWKWebView.CreateConfiguration, чтобы получить WKWebViewConfiguration объект .NET MAUI, а затем изменить его. Затем объект WKWebViewConfiguration можно указать в качестве аргумента перегрузки конструктора MauiWKWebView.

Так как конфигурация собственного WebView не может быть изменена в iOS и Mac Catalyst после создания представления платформы обработчика, необходимо создать делегат фабрики пользовательских обработчиков, чтобы изменить его:

#if IOS || MACCATALYST
using WebKit;
using CoreGraphics;
using Microsoft.Maui.Platform;
using Microsoft.Maui.Handlers;
#endif
...

#if IOS || MACCATALYST
    Microsoft.Maui.Handlers.WebViewHandler.PlatformViewFactory = (handler) =>
    {
        WKWebViewConfiguration config = MauiWKWebView.CreateConfiguration();
        config.ApplicationNameForUserAgent = "MyProduct/1.0.0";
        return new MauiWKWebView(CGRect.Empty, (WebViewHandler)handler, config);
    };
#endif

Заметка

Перед отображением WebView в приложении необходимо настроить MauiWKWebView с объектом WKWebViewConfiguration. Подходящие расположения для этого находятся в пути запуска приложения, например в MauiProgram.cs или App.xaml.cs.

Настройка параметров воспроизведения мультимедиа в iOS и Mac Catalyst

Встроенное воспроизведение видео HTML5, включая автозапуск и картинку в картинке, включено по умолчанию для WebView в iOS и Mac Catalyst. Чтобы изменить этот параметр по умолчанию или задать другие параметры воспроизведения мультимедиа, необходимо создать делегат фабрики пользовательских обработчиков, так как параметры воспроизведения мультимедиа нельзя изменить после создания представления платформы обработчика. В следующем примере кода показано, как это сделать:

#if IOS || MACCATALYST
using WebKit;
using CoreGraphics;
using Microsoft.Maui.Platform;
using Microsoft.Maui.Handlers;
#endif
...

#if IOS || MACCATALYST
    Microsoft.Maui.Handlers.WebViewHandler.PlatformViewFactory = (handler) =>
    {
        WKWebViewConfiguration config = MauiWKWebView.CreateConfiguration();

        // True to play HTML5 videos inliine, false to use the native full-screen controller.
        config.AllowsInlineMediaPlayback = false;

        // True to play videos over AirPlay, otherwise false.
        config.AllowsAirPlayForMediaPlayback = false;

        // True to let HTML5 videos play Picture in Picture.
        config.AllowsPictureInPictureMediaPlayback = false;

        // Media types that require a user gesture to begin playing.
        config.MediaTypesRequiringUserActionForPlayback = WKAudiovisualMediaTypes.All;

        return new MauiWKWebView(CGRect.Empty, (WebViewHandler)handler, config);
    };
#endif

Дополнительные сведения о настройке WebView в iOS см. в статье Настройка встроенного WebView на iOS и Mac Catalyst.

Проверка WebView в Mac Catalyst

Чтобы использовать средства разработчика Safari для проверки содержимого WebView в Mac Catalyst, добавьте в приложение следующий код:

#if MACCATALYST
        Microsoft.Maui.Handlers.WebViewHandler.Mapper.AppendToMapping("Inspect", (handler, view) =>
        {
            if (OperatingSystem.IsMacCatalystVersionAtLeast(16, 6))
                handler.PlatformView.Inspectable = true;
        });
#endif

Этот код настраивает средство сопоставления свойств для WebViewHandler в Mac Catalyst, чтобы содержимое WebView было инспектируемым средствами разработки Safari. Дополнительные сведения об обработчиках см. в обработчиках.

Чтобы использовать средства разработчика Safari с приложением Mac Catalyst:

  1. Откройте Safari на компьютере Mac.
  2. В Safari установите флажок Safari > "Параметры" > "Дополнительно" > "Показать разработку" в строке меню.
  3. Запустите приложение .NET MAUI Mac Catalyst.
  4. В Safari выберите "Разработка > {Имя устройства} меню, где заполнитель {Device name} — это имя устройства, например Macbook Pro. Затем выберите запись в списке под названием вашего приложения, которая также выделит ваше запущенное приложение. Это приведет к отображению окна веб-инспектора.

Запуск системного браузера

Можно открыть унифицированный указатель ресурса (URI) в системном веб-браузере с помощью класса Launcher, который предоставляется Microsoft.Maui.Essentials. Вызовите метод OpenAsync загрузчика и передайте аргумент string или Uri, представляющий URI, который следует открыть:

await Launcher.OpenAsync("https://learn.microsoft.com/dotnet/maui");

Дополнительные сведения см. в лаунчере.