WebView

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

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

• CookiesCookieContainerТип , предоставляет хранилище для коллекции файлов cookie.
• CanGoBackboolТип , указывает, может ли пользователь перейти на предыдущие страницы. Это свойство доступно только для чтения.
• CanGoForwardboolтип , указывает, может ли пользователь перейти вперед. Это свойство доступно только для чтения.
• SourceWebViewSourceТип , представляет расположение, которое отображаетсяWebView.
• UserAgentstringТип , представляет агент пользователя. Значение по умолчанию — это агент пользователя базового браузера платформы или null если он не может быть определен.

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

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

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

Внимание

Необходимо 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 объект.

Настройка безопасности транспорта приложений в iOS и Mac Catalyst

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

В следующей конфигурации Info.plist показано, как включить определенный домен для обхода требований Apple Transport Security (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-кода

Чтобы отобразить встроенный HtmlWebViewSource HTML, задайте Source для свойства объект:

<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- кода, определенного Source в HtmlWebViewSource объекте, заданном в качестве значения свойства:

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

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

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

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

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 настройки запросов на утверждение разрешений, использующих этот подход, требуется API Android 26 или более поздней версии.

Запросы разрешений с веб-страницы WebView на элемент управления отличаются от запросов разрешений от приложения MAUI .NET для пользователя. Разрешения приложения .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. Добавьте следующий класс в папку Platform/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 Используйте метод в элементе управления AndroidWebView, чтобы задать для клиента chrome значениеMyWebChromeClient. В следующих двух элементах показано, как настроить клиент chrome:

   • Учитывая элемент theWebViewControlуправления MAUI WebView .NET, вы можете задать клиент 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

Файлы 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() };

В этом примере один Cookie добавляется в CookieContainer объект, который затем задается в качестве значения 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. В этом примере factorial вызывается функция JavaScript, которая возвращает факториал 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 метод для получения объекта .NET MAUI WKWebViewConfiguration , а затем изменить его. Затем 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

Примечание.

Перед отображением в приложении необходимо настроить MauiWKWebView объект WebView 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");

Дополнительные сведения см. в разделе "Средство запуска".