WebView

Interfejs użytkownika aplikacji wieloplatformowej platformy .NET (.NET MAUI) WebView wyświetla zdalne strony internetowe, lokalne pliki HTML i ciągi HTML w aplikacji. Wyświetlona zawartość WebView zawiera obsługę kaskadowych arkuszy stylów (CSS) i JavaScript. Domyślnie projekty MAUI platformy .NET obejmują uprawnienia platformy wymagane do WebView wyświetlenia zdalnej strony internetowej.

WebView definiuje następujące właściwości:

• Cookies, typu CookieContainer, udostępnia magazyn dla kolekcji plików cookie.
• CanGoBack, typu bool, wskazuje, czy użytkownik może przejść do poprzednich stron. Jest to właściwość tylko do odczytu.
• CanGoForward, typu bool, wskazuje, czy użytkownik może przejść do przodu. Jest to właściwość tylko do odczytu.
• Source, typu WebViewSource, reprezentuje lokalizację wyświetlaną przez program WebView .
• UserAgent, typu string, reprezentuje agenta użytkownika. Wartość domyślna to agent użytkownika podstawowej przeglądarki platformy lub null jeśli nie można go określić.

Te właściwości są wspierane przez BindableProperty obiekty, co oznacza, że mogą być obiektami docelowymi powiązań danych i stylizowanymi.

Właściwość Source można ustawić na UrlWebViewSource obiekt lub HtmlWebViewSource obiekt, który pochodzi zarówno z WebViewSourceklasy . Element jest UrlWebViewSource używany do ładowania strony internetowej określonej przy użyciu adresu URL, podczas gdy HtmlWebViewSource obiekt jest używany do ładowania lokalnego pliku HTML lub lokalnego kodu HTML.

WebViewNavigating definiuje zdarzenie, które jest wywoływane podczas uruchamiania nawigacji po stronie, a Navigated zdarzenie zgłaszane po zakończeniu nawigacji strony. Obiekt WebNavigatingEventArgs , który towarzyszy Navigating zdarzeniu, definiuje Cancel właściwość typu bool , która może służyć do anulowania nawigacji. Obiekt WebNavigatedEventArgs , który towarzyszy Navigated zdarzeniu, definiuje Result właściwość typu WebNavigationResult , która wskazuje wynik nawigacji.

Ważne

Element WebView musi określać jego HeightRequest właściwości i WidthRequest w przypadku, gdy znajduje się w obiekcie HorizontalStackLayout, StackLayoutlub VerticalStackLayout. Jeśli nie określisz tych właściwości, WebView element nie będzie renderowany.

Wyświetlanie strony internetowej

Aby wyświetlić zdalną stronę internetową, ustaw Source właściwość na string , która określa identyfikator URI:

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

Równoważny kod języka C# to:

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

Identyfikatory URI muszą być w pełni sformułowane przy użyciu określonego protokołu.

Uwaga

Source Pomimo właściwości typu WebViewSourcewłaściwość może być ustawiona na identyfikator URI oparty na ciągach. Dzieje się tak, ponieważ program .NET MAUI zawiera konwerter typów i niejawny operator konwersji, który konwertuje identyfikator URI oparty na ciągu na UrlWebViewSource obiekt.

Konfigurowanie usługi App Transport Security w systemach iOS i Mac Catalyst

Ponieważ wersja 9, system iOS zezwoli aplikacji tylko na komunikację z bezpiecznymi serwerami. Aplikacja musi zdecydować się na włączanie komunikacji z niezabezpieczonymi serwerami.

Poniższa konfiguracja pliku Info.plist pokazuje, jak włączyć określoną domenę w celu obejścia wymagań usługi 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>

Najlepszym rozwiązaniem jest włączenie tylko określonych domen w celu obejścia usługi ATS, co umożliwia korzystanie z zaufanych witryn przy jednoczesnym korzystaniu z dodatkowych zabezpieczeń w niezaufanych domenach.

Poniższa konfiguracja pliku Info.plist pokazuje, jak wyłączyć usługę ATS dla aplikacji:

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

Ważne

Jeśli aplikacja wymaga połączenia z niezabezpieczoną witryną internetową, zawsze należy wprowadzić domenę jako wyjątek przy użyciu NSExceptionDomains klucza zamiast wyłączać usługę ATS całkowicie przy użyciu NSAllowsArbitraryLoads klucza.

Wyświetlanie lokalnego kodu HTML

Aby wyświetlić wbudowany kod HTML, ustaw Source właściwość na HtmlWebViewSource obiekt:

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

W języku XAML ciągi HTML mogą stać się nieczytelne z powodu ucieczki symboli < i > . W związku z tym w celu zwiększenia czytelności kod HTML może być podkreślony w CDATA sekcji:

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

Równoważny kod języka C# to:

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

Wyświetlanie lokalnego pliku HTML

Aby wyświetlić lokalny plik HTML, dodaj plik do folderu Resources\Raw projektu aplikacji i ustaw jego akcję kompilacji na MauiAsset. Następnie plik można załadować z wbudowanego kodu HTML zdefiniowanego HtmlWebViewSource w obiekcie ustawionym jako wartość Source właściwości:

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

Lokalny plik HTML może ładować kaskadowe arkusze stylów (CSS), JavaScript i obrazy, jeśli zostały one również dodane do projektu aplikacji za pomocą akcji kompilacji MauiAsset .

Aby uzyskać więcej informacji na temat nieprzetworzonych zasobów, zobacz Nieprzetworzone zasoby.

Załaduj ponownie zawartość

WebView ma metodę Reload , którą można wywołać w celu ponownego załadowania jego źródła:

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

Reload Po wywołaniu metody zdarzenie zostanie wyzwoloneReloadRequested, co oznacza, że żądanie zostało wykonane w celu ponownego załadowania bieżącej zawartości.

Wykonywanie nawigacji

WebView obsługuje nawigację programową za GoBack pomocą metod i GoForward . Te metody umożliwiają nawigację za pośrednictwem stosu WebView stron i powinny być wywoływane tylko po sprawdzeniu wartości CanGoBack właściwości i CanGoForward :

WebView webView = new WebView();
...

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

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

Gdy nawigacja między stronami WebViewodbywa się w programie inicjowanym programowo lub przez użytkownika, występują następujące zdarzenia:

• Navigating, który jest wywoływany po uruchomieniu nawigacji po stronie. Obiekt WebNavigatingEventArgs , który towarzyszy Navigating zdarzeniu, definiuje Cancel właściwość typu bool , która może służyć do anulowania nawigacji.
• Navigated, który jest wywoływany po zakończeniu nawigacji po stronie. Obiekt WebNavigatedEventArgs , który towarzyszy Navigated zdarzeniu, definiuje Result właściwość typu WebNavigationResult , która wskazuje wynik nawigacji.

Obsługa uprawnień w systemie Android

Podczas przechodzenia do strony, która żąda dostępu do sprzętu rejestrującego urządzenie, takiego jak aparat lub mikrofon, musi zostać przyznane uprawnienie przez kontrolkę WebView . Kontrolka WebView używa Android.Webkit.WebChromeClient typu w systemie Android do reagowania na żądania uprawnień. Jednak implementacja WebChromeClient dostarczana przez program .NET MAUI ignoruje żądania uprawnień. Należy utworzyć nowy typ, który dziedziczy z MauiWebChromeClient i zatwierdza żądania uprawnień.

Ważne

Dostosowanie żądania uprawnień do zatwierdzania przy użyciu tego podejścia wymaga interfejsu WebView API systemu Android w wersji 26 lub nowszej.

Żądania uprawnień ze strony internetowej do kontrolki WebView różnią się od żądań uprawnień z aplikacji .NET MAUI do użytkownika. Uprawnienia aplikacji .NET MAUI są wymagane i zatwierdzone przez użytkownika dla całej aplikacji. Kontrolka WebView jest zależna od możliwości uzyskiwania dostępu do sprzętu przez aplikacje. Aby zilustrować tę koncepcję, rozważ stronę internetową żądającą dostępu do aparatu urządzenia. Nawet jeśli to żądanie zostanie zatwierdzone przez kontrolkę WebView , ale aplikacja .NET MAUI nie miała zatwierdzenia przez użytkownika w celu uzyskania dostępu do aparatu, strona internetowa nie będzie mogła uzyskać dostępu do aparatu.

W poniższych krokach pokazano, jak przechwytywać żądania uprawnień z kontrolki WebView w celu korzystania z aparatu. Jeśli próbujesz użyć mikrofonu, kroki będą podobne, z tą różnicą, że należy użyć uprawnień związanych z mikrofonem zamiast uprawnień związanych z kamerą.

1. Najpierw dodaj wymagane uprawnienia aplikacji do manifestu systemu Android. Otwórz plik Platformy/Android/AndroidManifest.xml i dodaj następujący kod w węźlemanifest:

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

2. W pewnym momencie w aplikacji, na przykład po załadowaniu strony zawierającej WebView kontrolkę, poproś użytkownika o uprawnienie, aby zezwolić aplikacji na dostęp do aparatu.

   private async Task RequestCameraPermission()
   {
       PermissionStatus status = await Permissions.CheckStatusAsync<Permissions.Camera>();
   
       if (status != PermissionStatus.Granted)
           await Permissions.RequestAsync<Permissions.Camera>();
   }
   

3. Dodaj następującą klasę do folderu Platformy/Android , zmieniając przestrzeń nazw katalogu głównego w celu dopasowania do przestrzeni nazw projektu:

   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);
       }
   }
   

   W poprzednim fragmencie MyWebChromeClient kodu klasa dziedziczy z MauiWebChromeClientklasy i zastępuje metodę OnPermissionRequest przechwytywania żądań uprawnień strony internetowej. Każdy element uprawnień jest sprawdzany, aby sprawdzić, czy pasuje do stałej PermissionRequest.ResourceVideoCapture ciągu, która reprezentuje aparat. Jeśli uprawnienie aparatu jest zgodne, kod sprawdza, czy aplikacja ma uprawnienia do korzystania z aparatu. Jeśli ma uprawnienia, żądanie strony internetowej zostanie przyznane.

4. SetWebChromeClient Użyj metody w kontrolce systemu AndroidWebView, aby ustawić klienta chrome na MyWebChromeClient. W poniższych dwóch elementach pokazano, jak ustawić klienta chrome:

   • Na podstawie kontrolki MAUI WebView platformy .NET o nazwie theWebViewControlmożna ustawić klienta chrome bezpośrednio w widoku platformy, który jest kontrolką systemu Android:

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

   • Możesz również użyć mapowania właściwości programu obsługi, aby wymusić użycie wszystkich WebView kontrolek do korzystania z klienta chrome. Aby uzyskać więcej informacji, zobacz Programy obsługi.

     Poniższa metoda fragmentu kodu powinna być wywoływana CustomizeWebViewHandler po uruchomieniu aplikacji, na przykład w metodzie 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
     }
     

Ustawianie plików cookie

Pliki cookie można ustawić na obiekcie WebView , aby były wysyłane za pomocą żądania internetowego do określonego adresu URL. Ustaw pliki cookie, dodając Cookie obiekty do elementu , a następnie ustaw kontener jako wartość właściwości możliwej WebView.Cookies do CookieContainerpowiązania. Poniżej znajduje się kod przykładowy:

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() };

W tym przykładzie CookieContainer do obiektu jest dodawany pojedynczy elementCookie, który jest następnie ustawiany jako wartość WebView.Cookies właściwości. Po wysłaniu WebView żądania internetowego do określonego adresu URL plik cookie jest wysyłany wraz z żądaniem.

Wywoływanie kodu JavaScript

WebView program zawiera możliwość wywoływania funkcji JavaScript z języka C# i zwracania dowolnego wyniku do wywołującego kodu języka C#. Ta współpraca jest realizowana za pomocą EvaluateJavaScriptAsync metody , która jest pokazana w poniższym przykładzie:

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}.";

Metoda WebView.EvaluateJavaScriptAsync oblicza kod JavaScript określony jako argument i zwraca dowolny wynik jako string. W tym przykładzie wywoływana factorial jest funkcja JavaScript, która zwraca współczynniki number w wyniku. Ta funkcja JavaScript jest zdefiniowana w lokalnym pliku HTML ładowanych WebView i jest pokazana w poniższym przykładzie:

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

Konfigurowanie natywnego elementu WebView w systemach iOS i Mac Catalyst

WebView Natywna kontrolka jest kontrolką MauiWKWebView w systemach iOS i Mac Catalyst, która pochodzi z klasy WKWebView. MauiWKWebView Jedno z przeciążeń konstruktora umożliwia WKWebViewConfiguration określenie obiektu, który zawiera informacje o sposobie konfigurowania WKWebView obiektu. Typowe konfiguracje obejmują ustawienie agenta użytkownika, określenie plików cookie w celu udostępnienia zawartości internetowej i wstrzyknięcie skryptów niestandardowych do zawartości internetowej.

Możesz utworzyć WKWebViewConfiguration obiekt w aplikacji, a następnie skonfigurować jego właściwości zgodnie z potrzebami. Alternatywnie możesz wywołać metodę statyczną MauiWKWebView.CreateConfiguration , aby pobrać obiekt .NET MAUI WKWebViewConfiguration , a następnie zmodyfikować go. Obiekt WKWebViewConfiguration można następnie określić jako argument przeciążenia konstruktora MauiWKWebView .

Ponieważ nie można zmienić konfiguracji natywnej WebView w systemach iOS i Mac Catalyst po utworzeniu widoku platformy programu obsługi, należy utworzyć niestandardowy delegat fabryki obsługi, aby go zmodyfikować:

#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

Uwaga

Należy skonfigurować MauiWKWebView obiekt przed wyświetleniem WKWebViewConfiguration obiektu WebView w aplikacji. Odpowiednie lokalizacje do wykonania są w ścieżce uruchamiania aplikacji, na przykład w MauiProgram.cs lub App.xaml.cs.

Ustawianie preferencji odtwarzania multimediów w systemach iOS i Mac Catalyst

Wbudowane odtwarzanie multimediów wideo HTML5, w tym autoodtwarzanie i obraz na obrazie, jest domyślnie włączone w WebView systemach iOS i Mac Catalyst. Aby zmienić to ustawienie domyślne lub ustawić inne preferencje odtwarzania multimediów, należy utworzyć niestandardowy delegat fabryki obsługi, ponieważ nie można zmienić preferencji odtwarzania multimediów po utworzeniu widoku platformy programu obsługi. Poniższy kod przedstawia przykład wykonywania tego zadania:

#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

Aby uzyskać więcej informacji na temat konfigurowania elementu WebView w systemie iOS, zobacz Konfigurowanie natywnego elementu WebView w systemach iOS i Mac Catalyst.

Inspekcja elementu WebView na komputerze Mac Catalyst

Aby użyć narzędzi deweloperskich Safari do sprawdzania zawartości WebView elementu na komputerze Mac Catalyst, dodaj następujący kod do aplikacji:

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

Ten kod dostosowuje maper właściwości dla WebViewHandler narzędzia mac Catalyst, aby WebView zawartość można było sprawdzić za pomocą narzędzi deweloperskich Safari. Aby uzyskać więcej informacji na temat procedur obsługi, zobacz Programy obsługi.

Aby użyć narzędzi deweloperskich Safari z aplikacją Mac Catalyst:

1. Otwórz przeglądarkę Safari na komputerze Mac.
2. W przeglądarce Safari zaznacz pole wyboru Ustawienia > zaawansowane Pokaż menu Programowanie > na pasku > menu.
3. Uruchom aplikację .NET MAUI Mac Catalyst.
4. W przeglądarce Safari wybierz menu Develop {Device name} (Opracowywanie > {nazwa urządzenia} ), w którym {Device name} symbol zastępczy to Nazwa urządzenia, na przykład Macbook Pro. Następnie wybierz wpis pod nazwą aplikacji, który będzie również wyróżniać uruchomioną aplikację. Spowoduje to wyświetlenie okna Inspektor sieci Web.

Uruchamianie przeglądarki systemowej

Istnieje możliwość otwarcia identyfikatora URI w systemowej przeglądarce internetowej z klasą Launcher , która jest dostarczana przez Microsoft.Maui.Essentialsprogram . Wywołaj metodę modułu uruchamiania OpenAsync i przekaż string argument lub Uri reprezentujący identyfikator URI, aby otworzyć:

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

Aby uzyskać więcej informacji, zobacz Uruchamianie.