WebView

L’interface .NET Multi-Platform App UI (.NET MAUI) WebView affiche des pages web distantes, des fichiers HTML locaux et des chaînes HTML dans une application. Le contenu a affiché une fonctionnalité WebView qui inclut une prise en charge pour les feuilles de style en cascade (CSS) et JavaScript. Par défaut, les projets .NET MAUI incluent les autorisations de plateforme requises pour qu’une fonctionnalité WebView affiche une page web distante.

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

• Cookies, de type CookieContainer, offre 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 accéder aux pages suivantes. Il s’agit d’une propriété en lecture seule.
• Source, de type WebViewSource, représente l’emplacement affiché par la fonctionnalité WebView.
• UserAgent, de type string, représente l’agent utilisateur. La valeur par défaut correspondant à l’agent utilisateur du navigateur de plateforme sous-jacent, ou null s’il n’est pas déterminé.

Les propriétés s’appuient sur des objets BindableProperty, ce qui signifie qu’elles peuvent être les cibles de liaisons de données et mises en forme avec un style.

La propriété Source peut être définie sur un objet UrlWebViewSource ou un objet HtmlWebViewSource qui dérivent tous deux de WebViewSource. Un UrlWebViewSource est utilisé 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 un HTML local.

WebView définit un événement Navigating déclenché lorsqu’une navigation de page démarre et un événement Navigated déclenché lorsqu’une navigation de page se termine. L’objet WebNavigatingEventArgs qui accompagne l’événement Navigating définit une propriété Cancel de type bool que vous pouvez utiliser pour annuler une navigation. L’objet WebNavigatedEventArgs qui accompagne l’événement Navigated définit une propriété Result de type WebNavigationResult qui indique le résultat d’une navigation.

Important

Une WebView doit spécifier ses propriétés HeightRequest et WidthRequest quand elles sont contenues dans une disposition HorizontalStackLayout, StackLayout ou VerticalStackLayout. Si vous ne spécifiez pas ces propriétés, la WebView n’effectue aucun affichage.

Afficher une page web

Pour afficher une page web distante, définissez la propriété Source sur une 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 seront complètement formés avec le protocole spécifié.

Remarque

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

Configurer App Transport Security sur iOS et Mac Catalyst

Depuis la version 9, iOS permet à votre application de communiquer uniquement avec des serveurs sécurisés. Une application doit accepter d’autoriser 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 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 conseillé 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 comme exception en utilisant la clé NSExceptionDomains au lieu de désactiver complètement ATS en utilisant la clé NSAllowsArbitraryLoads.

Afficher un HTML local

Pour afficher un HTML inclus, 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>

Dans XAML, les chaînes HTML peuvent devenir illisibles en raison de l’échappement des symboles < et >. Par conséquent, pour une meilleure lisibilité, le 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 Ressources/Brutes de votre projet d’application et définissez son action de build sur MauiAsset. Le fichier peut ensuite être chargé à partir du HTML inclus défini dans un objet HtmlWebViewSource qui est défini en tant que 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 s’ils ont également été ajoutés à votre projet d’application avec l’action de build MauiAsset.

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

Recharger du contenu

WebView dispose d’une méthode Reload que vous pouvez appeler 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 la navigation

WebView prend en charge la navigation programme avec les méthodes GoBack et GoForward. Ces méthodes permettent une navigation via la pile de page WebView et doivent uniquement être appelées après inspection des 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();
}

Quand une navigation de page se produit dans une WebView, initiée de manière programmatique ou par l’utilisateur, les événements suivants se produisent :

• Navigating qui est déclenché quand la navigation de page démarre. L’objet WebNavigatingEventArgs qui accompagne l’événement Navigating définit une propriété Cancel de type bool que vous pouvez utiliser pour annuler une navigation.
• Navigated qui est déclenché quand la navigation de page se termine. L’objet WebNavigatedEventArgs qui accompagne l’événement Navigated définit une propriété Result de type WebNavigationResult qui indique le résultat d’une navigation.

Gérer des autorisations sur Android

Lors de la navigation vers une page qui demande l’accès au matériel d’enregistrement de l’appareil, tel qu’une caméra ou un microphone, l’autorisation doit être octroyée par le contrôle WebView. Le contrôle WebView utilise le type 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 type qui hérite de MauiWebChromeClient et approuve les demandes d’autorisation.

Important

La personnalisation de WebView pour approuver des demandes d’autorisation en utilisant cette approche nécessite l’API Android 26 ou version ultérieure.

Les demandes d’autorisation d’une page web au contrôle WebView diffèrent 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’application complète. Le contrôle WebView est dépendant sur la capacité des applications à accéder au matériel. Pour illustrer ce concept, imaginons une page web demandant l’accès à la caméra d’un appareil. Même en cas d’approbation de la demande par le contrôle WebView, l’utilisateur n’a pas encore autorisé l’application .NET MAUI à accéder à la caméra et la page web ne peut pas accéder à la caméra.

Les étapes suivantes montrent comment intercepter des demandes d’autorisation à partir du contrôle WebView pour utiliser la caméra. Si vous essayez d’utiliser le micro, les étapes seront semblables, à ceci près que vous utiliserez des autorisations liées au micro au lieu des autorisations liées à la caméra.

1. Ajoutez d’abord les autorisations d’application nécessaires dans le manifeste Android. Ouvrez le fichier Plateformes/Android/AndroidManifest.xml et ajoutez le code suivant dans le nœud manifest :

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

2. À un moment donné dans votre application, comme lors du chargement d’une page contenant un contrôle WebView, demandez l’autorisation de l’utilisateur pour permettre à l’application d’accéder à 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 dans le dossier Plateformes/Android en changeant l’espace de noms racine afin qu’il corresponde à l’espace de noms de votre projet :

   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 précédent, la classe MyWebChromeClient hérite de MauiWebChromeClient et 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 la caméra. Si une autorisation de caméra est mise en correspondance, le code vérifie que l’application est autorisée à utiliser la caméra. En cas d’autorisation, la demande de la page web est accordée.

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

   • Compte tenu du contrôle WebView .NET MAUI nommé theWebViewControl, vous pouvez définir le client Chrome directement sur la vue de la plateforme qui constitue le contrôle Android :

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

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

     La méthode CustomizeWebViewHandler de l’extrait suivant doit être appelée au démarrage de l’application, tel que 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

Vous pouvez définir des cookies sur une fonctionnalité WebView afin de les envoyer avec la demande 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, un seul Cookie est ajouté à l’objet CookieContainer, qui est ensuite défini comme valeur de la propriété WebView.Cookies. Quand WebView envoie une requête web à l’URL spécifiée, le cookie est envoyé avec la demande.

Appeler JavaScript

WebView inclut la possibilité d’appeler une fonction JavaScript à partir de C# et de renvoyer les résultats au code C# appelant. Cette interopérabilité est accomplie 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 JavaScript spécifié en tant qu’argument et retourne les résultats sous la forme de string. Dans cet exemple, la fonction factorial JavaScript est appelée et retourne la factorielle de number comme résultat. Cette fonction JavaScript est définie dans le fichier HTML local chargé par WebView 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 la fonctionnalité WebView native sur iOS et Mac Catalyst

Le contrôle WebView natif est un MauiWKWebView sur iOS et Mac Catalyst qui dérive de WKWebView. L’une des surcharges du constructeur MauiWKWebView active un objet WKWebViewConfiguration à spécifier, ce qui fournit des informations sur la configuration de l’objet WKWebView. Les configurations classiques incluent la définition de l’agent utilisateur qui spécifie les cookies à mettre à la disposition de votre contenu web et injecte des scripts personnalisés dans votre contenu web.

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

Étant donné que la configuration de 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

Remarque

Vous devez configurer MauiWKWebView avec un objet WKWebViewConfiguration avant l’affichage de WebView dans votre application. Les emplacements convenant à cette opération se trouvent dans le chemin d’accès de démarrage de votre application, tel que 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 incluse de la vidéo HTML5, y compris la lecture automatique et l’image dans l’image, est activée par défaut pour la fonctionnalité 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 l’affichage de la plateforme du gestionnaire créé. Le code suivant montre un exemple pour effectuer cette opération :

#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 obtenir plus d’informations sur la configuration d’une fonctionnalité WebView sur iOS, consultez Configurer la fonctionnalité WebView native sur iOS et Mac Catalyst.

Examiner une fonctionnalité WebView sur Mac Catalyst

Pour utiliser des outils de développement Safari afin d’inspecter le contenu d’une fonctionnalité WebView sur Mac Catalyst, ajoutez le code suivant dans 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é pour le WebViewHandler sur Mac Catalyst pour que le contenu de WebView puisse être inspecté par les outils de développement de Safari. Pour obtenir plus d’informations sur les gestionnaires, consultez Gestionnaires.

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

1. Ouvrez Safari sur votre Mac.
2. Dans Safari, cochez la case Safari > Paramètres > 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 > {Device name} dans lequel l’espace réservé {Device name} est le nom de votre appareil tel que 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 Web Inspector.

Lancer le navigateur système

Il est possible d’ouvrir un URI dans le navigateur web système avec la classe Launcher qui est fournie par Microsoft.Maui.Essentials. Appelez la méthode OpenAsync du lanceur et transmet 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 Lanceur.