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, ounull
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.
WebView définit les événements suivants :
Navigating
, qui est déclenché lorsqu’une navigation de page démarre. L’objetWebNavigatingEventArgs
qui accompagne l’événement définit une propriétéCancel
de typebool
que vous pouvez utiliser pour annuler une navigation.Navigated
, qui est déclenché lorsqu’une navigation de page se termine. L’objetWebNavigatedEventArgs
qui accompagne l’événement définit une propriétéResult
de typeWebNavigationResult
qui indique le résultat d’une navigation.ProcessTerminated
, qui est déclenché lorsqu’un processus WebView se termine de façon inattendue. L’objetWebViewProcessTerminatedEventArgs
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 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="<HTML><BODY><H1>.NET MAUI</H1><P>Welcome to WebView.</P></BODY><HTML>" />
</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’objetWebNavigatingEventArgs
qui accompagne l’événementNavigating
définit une propriétéCancel
de typebool
que vous pouvez utiliser pour annuler une navigation.Navigated
qui est déclenché quand la navigation de page se termine. L’objetWebNavigatedEventArgs
qui accompagne l’événementNavigated
définit une propriétéResult
de typeWebNavigationResult
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.
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" />
À 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>(); }
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 deMauiWebChromeClient
et remplace la méthodeOnPermissionRequest
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înePermissionRequest.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.Utilisez la méthode SetWebChromeClient sur le contrôle
WebView
de l’Android pour définir le client Chrome surMyWebChromeClient
. 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éthodeMauiProgram.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 :
- Ouvrez Safari sur votre Mac.
- Dans Safari, cochez la case Safari > Paramètres > Avancé > Afficher le menu Développement dans la barre de menus.
- Exécutez votre application .NET MAUI Mac Catalyst.
- 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 queMacbook 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.
Commentaires
https://aka.ms/ContentUserFeedback.
Bientôt disponible : Tout au long de 2024, nous allons supprimer progressivement GitHub Issues comme mécanisme de commentaires pour le contenu et le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultezEnvoyer et afficher des commentaires pour