Partage via

WebView

  • Article

L’interface utilisateur de l’application multiplateforme .NET (.NET MAUI) WebView affiche des pages web distantes, des fichiers HTML locaux et des chaînes HTML dans une application. Le contenu affiché à WebView inclut la prise en charge des feuilles de style en cascade (CSS) et JavaScript. Par défaut, les projets .NET MAUI incluent les autorisations de plateforme requises pour un WebView pour afficher une page web distante.

WebView définit les propriétés suivantes :

  • Cookies, de type CookieContainer, fournit un stockage pour une collection de cookies.
  • CanGoBack, de type bool, indique si l’utilisateur peut accéder aux pages précédentes. Il s’agit d’une propriété en lecture seule.
  • CanGoForward, de type bool, indique si l’utilisateur peut naviguer vers l’avant. Il s’agit d’une propriété en lecture seule.
  • Source, de type WebViewSource, représente l’emplacement que le WebView affiche.
  • UserAgent, de type string, représente l’agent utilisateur. La valeur par défaut est l’agent utilisateur du navigateur de plateforme sous-jacent, ou null s’il ne peut pas être déterminé.

Ces propriétés sont sauvegardées par des objets BindableProperty, ce qui signifie qu’elles peuvent être des cibles de liaisons de données et mises en forme.

La propriété Source peut être définie sur un objet UrlWebViewSource ou un objet HtmlWebViewSource, qui dérive tous deux de WebViewSource. Une UrlWebViewSource est utilisée pour charger une page web spécifiée avec une URL, tandis qu’un objet HtmlWebViewSource est utilisé pour charger un fichier HTML local ou html local.

WebView définit un événement Navigating déclenché lors du démarrage de la navigation de page et un événement Navigated déclenché lorsque la navigation de page est terminée. L’objet WebNavigatingEventArgs qui accompagne l’événement Navigating définit une propriété Cancel de type bool qui peut être utilisée pour annuler la navigation. L’objet WebNavigatedEventArgs qui accompagne l’événement Navigated définit une propriété Result de type WebNavigationResult qui indique le résultat de navigation.

WebView définit les événements suivants :

  • Navigating, qui est déclenché lorsque la navigation de page démarre. L’objet WebNavigatingEventArgs qui accompagne cet événement définit une propriété Cancel de type bool qui peut être utilisée pour annuler la navigation.
  • Navigated, qui est déclenché lorsque la navigation de page est terminée. L’objet WebNavigatedEventArgs qui accompagne cet événement définit une propriété Result de type WebNavigationResult qui indique le résultat de navigation.
  • ProcessTerminated, qui est déclenché lorsqu’un processus WebView se termine de façon inattendue. L’objet WebViewProcessTerminatedEventArgs qui accompagne cet événement définit des propriétés spécifiques à la plateforme qui indiquent pourquoi le processus a échoué.

Important

Une WebView doit spécifier ses propriétés HeightRequest et WidthRequest lorsqu’elles sont contenues dans un HorizontalStackLayout, StackLayoutou VerticalStackLayout. Si vous ne spécifiez pas ces propriétés, la WebView ne s’affiche pas.

Afficher une page web

Pour afficher une page web distante, définissez la propriété Source sur un string qui spécifie l’URI :

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

Le code C# équivalent est :

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

Les URI doivent être entièrement formés avec le protocole spécifié.

Note

Malgré la propriété Source de type WebViewSource, la propriété peut être définie sur un URI basé sur une chaîne. Cela est dû au fait que .NET MAUI inclut un convertisseur de type et un opérateur de conversion implicite, qui convertit l’URI basé sur la chaîne en objet UrlWebViewSource.

Configurer App Transport Security sur iOS et Mac Catalyst

Depuis la version 9, iOS autorise uniquement votre application à communiquer avec des serveurs sécurisés. Une application doit choisir d’activer la communication avec des serveurs non sécurisés.

La configuration Info.plist suivante montre comment activer un domaine spécifique pour contourner les exigences d’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>

Il est recommandé d’autoriser uniquement des domaines spécifiques à contourner ATS, ce qui vous permet d’utiliser des sites approuvés tout en bénéficiant d’une sécurité supplémentaire sur des domaines non approuvés.

La configuration Info.plist suivante montre comment désactiver ATS pour une application :

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

Important

Si votre application nécessite une connexion à un site web non sécurisé, vous devez toujours entrer le domaine en tant qu’exception à l’aide de la clé NSExceptionDomains au lieu de désactiver complètement ATS à l’aide de la clé NSAllowsArbitraryLoads.

Afficher le code HTML local

Pour afficher le code HTML inline, définissez la propriété Source sur un objet 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>

En XAML, les chaînes HTML peuvent devenir illisibles en raison de l’échappement des symboles < et >. Par conséquent, pour une meilleure lisibilité, le code HTML peut être inclus dans une section 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>

Le code C# équivalent est :

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

Afficher un fichier HTML local

Pour afficher un fichier HTML local, ajoutez le fichier au dossier Resources\Raw de votre projet d’application et définissez son action de génération sur MauiAsset. Ensuite, le fichier peut être chargé à partir du code HTML inline défini dans un objet HtmlWebViewSource défini comme valeur de la propriété 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>

Le fichier HTML local peut charger des feuilles de style en cascade (CSS), JavaScript et des images, si elles ont également été ajoutées à votre projet d’application avec l’action de génération MauiAsset.

Pour plus d’informations sur les ressources brutes, consultez ressources brutes.

Recharger le contenu

WebView a une méthode Reload qui peut être appelée pour recharger sa source :

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

Lorsque la méthode Reload est appelée l’événement ReloadRequested est déclenché, indiquant qu’une demande a été effectuée pour recharger le contenu actuel.

Effectuer une navigation

WebView prend en charge la navigation par programmation avec les méthodes GoBack et GoForward. Ces méthodes permettent de parcourir la pile de pages WebView et doivent être appelées uniquement après avoir inspecté les valeurs des propriétés CanGoBack et CanGoForward :

WebView webView = new WebView();
...

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

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

Lorsque la navigation de page se produit dans un WebView, lancée par programme ou par l’utilisateur, les événements suivants se produisent :

  • Navigating, qui est déclenché lors du démarrage de la navigation de page. L’objet WebNavigatingEventArgs qui accompagne l’événement Navigating définit une propriété Cancel de type bool qui peut être utilisée pour annuler la navigation.
  • Navigated, qui est déclenché lorsque la navigation de page est terminée. L’objet WebNavigatedEventArgs qui accompagne l’événement Navigated définit une propriété Result de type WebNavigationResult qui indique le résultat de navigation.

Gérer les autorisations sur Android

Lorsque vous accédez à une page qui demande l’accès au matériel d’enregistrement de l’appareil, tel que la caméra ou le microphone, l’autorisation doit être accordée par le contrôle WebView. Le contrôle WebView utilise le type de Android.Webkit.WebChromeClient sur Android pour réagir aux demandes d’autorisation. Toutefois, l’implémentation WebChromeClient fournie par .NET MAUI ignore les demandes d’autorisation. Vous devez créer un nouveau type qui hérite de MauiWebChromeClient et approuve les demandes d’autorisation.

Important

La personnalisation du WebView pour approuver les demandes d’autorisation, en utilisant cette méthode, nécessite l’API Android 26 ou supérieure.

Les demandes d’autorisation d’une page web vers le contrôle WebView sont différentes des demandes d’autorisation de l’application .NET MAUI à l’utilisateur. Les autorisations d’application .NET MAUI sont demandées et approuvées par l’utilisateur, pour l’ensemble de l’application. Le contrôle WebView dépend de la capacité des applications à accéder au matériel. Pour illustrer ce concept, envisagez une page web qui demande l’accès à la caméra de l’appareil. Même si cette demande est approuvée par le contrôle WebView, mais l’application .NET MAUI n’a pas été approuvée par l’utilisateur pour accéder à la caméra, la page web ne serait pas en mesure d’accéder à la caméra.

Les étapes suivantes montrent comment intercepter les demandes d’autorisation du contrôle WebView pour utiliser l’appareil photo. Si vous essayez d’utiliser le microphone, les étapes sont similaires, sauf que vous utiliseriez des autorisations liées au microphone au lieu des autorisations associées à la caméra.

  1. Tout d’abord, ajoutez les autorisations d’application requises au manifeste Android. Ouvrez le fichier Platforms/Android/AndroidManifest.xml et ajoutez les éléments suivants dans le nœud manifest :

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

  2. À un moment donné dans votre application, par exemple lorsque la page contenant un contrôle WebView est chargée, demandez l’autorisation de l’utilisateur pour autoriser l’accès de l’application à la caméra.

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

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

  3. Ajoutez la classe suivante au dossier Platforms/Android, en modifiant l’espace de noms racine pour qu’il corresponde à l’espace de noms de votre projet (n’ajoutez pas de .Platforms.Android à l’espace de noms) :

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

    Dans l’extrait de code précédent, la classe MyWebChromeClient hérite de MauiWebChromeClientet remplace la méthode OnPermissionRequest pour intercepter les demandes d’autorisation de page web. Chaque élément d’autorisation est vérifié pour voir s’il correspond à la constante de chaîne PermissionRequest.ResourceVideoCapture, qui représente l’appareil photo. Si une autorisation d’appareil photo est mise en correspondance, le code vérifie si l’application est autorisée à utiliser l’appareil photo. S’il dispose d’une autorisation, la demande de la page web est accordée.

  4. Utilisez la méthode SetWebChromeClient sur le contrôle WebView d’Android pour définir le client Chrome sur MyWebChromeClient. Les deux éléments suivants montrent comment définir le client Chrome :

    • Étant donné un contrôle .NET MAUI WebView nommé theWebViewControl, vous pouvez définir le client Chrome directement sur la vue de plateforme, qui est le contrôle Android :

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

    • Vous pouvez également utiliser le mappage de propriétés de gestionnaire pour forcer tous les contrôles WebView à utiliser votre client Chrome. Pour plus d’informations, consultez Handlers.

      La méthode CustomizeWebViewHandler de l’extrait de code suivant doit être appelée au démarrage de l’application, par exemple dans la méthode 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
}

Définir des cookies

Les cookies peuvent être définis sur une WebView afin qu’ils soient envoyés avec la requête web à l’URL spécifiée. Définissez les cookies en ajoutant des objets Cookie à un CookieContainer, puis définissez le conteneur comme valeur de la propriété WebView.Cookies pouvant être liée. Le code suivant montre un exemple :

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

Dans cet exemple, une seule Cookie est ajoutée à l’objet CookieContainer, qui est ensuite défini comme valeur de la propriété WebView.Cookies. Lorsque le WebView envoie une requête web à l’URL spécifiée, le cookie est envoyé avec la requête.

Appeler JavaScript

WebView inclut la possibilité d’appeler une fonction JavaScript à partir de C# et de renvoyer le résultat au code C# qui l'a appelé. Cette interopérabilité s’effectue avec la méthode EvaluateJavaScriptAsync, qui est illustrée dans l’exemple suivant :

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

La méthode WebView.EvaluateJavaScriptAsync évalue le code JavaScript spécifié en tant qu’argument et retourne n’importe quel résultat sous la forme d’un string. Dans cet exemple, la fonction JavaScript factorial est appelée, qui retourne la factorielle de number en conséquence. Cette fonction JavaScript est définie dans le fichier HTML local que le WebView charge, et est illustrée dans l’exemple suivant :

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

Configurer le WebView natif sur iOS et Mac Catalyst

Le contrôle natif WebView est un(e) MauiWKWebView sur iOS et Mac Catalyst, qui dérive de WKWebView. L’une des surcharges de constructeur MauiWKWebView permet à un objet WKWebViewConfiguration d’être spécifié, qui fournit des informations sur la configuration de l’objet WKWebView. Les configurations classiques incluent la définition de l’agent utilisateur, la spécification de cookies pour rendre disponible votre contenu web et l’injection de scripts personnalisés dans votre contenu web.

Vous pouvez créer un objet WKWebViewConfiguration dans votre application, puis configurer ses propriétés en fonction des besoins. Vous pouvez également appeler la méthode de MauiWKWebView.CreateConfiguration statique pour récupérer l’objet WKWebViewConfiguration de .NET MAUI, puis le modifier. L’objet WKWebViewConfiguration peut ensuite être spécifié en tant qu’argument de la surcharge du constructeur MauiWKWebView.

Étant donné que la configuration du WebView natif ne peut pas être modifiée sur iOS et Mac Catalyst une fois la vue de plateforme du gestionnaire créée, vous devez créer un délégué de fabrique de gestionnaire personnalisé pour le modifier :

#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

Note

Vous devez configurer MauiWKWebView avec un objet WKWebViewConfiguration avant qu’un WebView ne s’affiche dans votre application. Les emplacements appropriés pour ce faire se trouvent dans le chemin de démarrage de votre application, par exemple dans MauiProgram.cs ou App.xaml.cs.

Définir les préférences de lecture multimédia sur iOS et Mac Catalyst

La lecture multimédia inline de la vidéo HTML5, y compris la lecture automatique et l’image dans l’image, est activée par défaut pour les WebView sur iOS et Mac Catalyst. Pour modifier cette valeur par défaut ou définir d’autres préférences de lecture multimédia, vous devez créer un délégué de fabrique de gestionnaire personnalisé, car les préférences de lecture multimédia ne peuvent pas être modifiées une fois la vue de plateforme du gestionnaire créée. Le code suivant montre un exemple de ce qui suit :

#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

Pour plus d’informations sur la configuration d’un WebView sur iOS, consultez Configurer le WebView natif sur iOS et Mac Catalyst.

Inspecter un WebView sur Mac Catalyst

Pour utiliser les outils de développement Safari pour inspecter le contenu d’un WebView sur Mac Catalyst, ajoutez le code suivant à votre application :

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

Ce code personnalise le mappeur de propriétés pour le WebViewHandler sur Mac Catalyst pour rendre le contenu WebView inspectable par les outils de développement Safari. Pour plus d’informations sur les gestionnaires, consultez gestionnaires.

Pour utiliser les outils de développement Safari avec une application Mac Catalyst :

  1. Ouvrez Safari sur votre Mac.
  2. Dans Safari, cochez la case Paramètres > Safari > Avancé > Afficher le menu Développement dans la barre de menus.
  3. Exécutez votre application .NET MAUI Mac Catalyst.
  4. Dans Safari, sélectionnez le menu Développer > {Nom de l’appareil}, où le nom de votre appareil est représenté par le texte provisoire {Device name}, par exemple Macbook Pro. Sélectionnez ensuite l’entrée sous le nom de votre application, qui met également en évidence votre application en cours d’exécution. Cela entraîne l’affichage de la fenêtre de l’inspecteur web .

Lancer le navigateur système

Il est possible d’ouvrir un URI dans le navigateur web système avec la classe Launcher, fournie par Microsoft.Maui.Essentials. Appelez la méthode OpenAsync du lanceur et transmettez un argument string ou Uri qui représente l’URI à ouvrir :

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

Pour plus d’informations, consultez Launcher.