Condividi tramite

WebView

  • Articolo

L'interfaccia utente dell'app multipiattaforma .NET (.NET MAUI) WebView visualizza pagine Web remote, file HTML locali e stringhe HTML in un'app. Il contenuto visualizzato in un WebView include il supporto per CSS (Cascading Style Sheets) e JavaScript. Per impostazione predefinita, i progetti .NET MAUI includono le autorizzazioni della piattaforma necessarie affinché WebView visualizzi una pagina web remota.

WebView definisce le proprietà seguenti:

  • Cookies, di tipo CookieContainer, fornisce la memorizzazione per una raccolta di cookie.
  • CanGoBack, di tipo bool, indica se l'utente può passare alle pagine precedenti. Si tratta di una proprietà di sola lettura.
  • CanGoForward, di tipo bool, indica se l'utente può spostarsi in avanti. Si tratta di una proprietà di sola lettura.
  • Source, di tipo WebViewSource, rappresenta la posizione visualizzata dal WebView.
  • UserAgent, di tipo string, rappresenta l'agente utente. Il valore predefinito è l'agente utente del browser della piattaforma sottostante o null se non può essere determinato.

Queste proprietà sono supportate da oggetti BindableProperty, il che significa che possono essere destinazioni di associazioni dati e stilizzati.

La proprietà Source può essere impostata su un oggetto UrlWebViewSource o su un oggetto HtmlWebViewSource, che entrambi derivano da WebViewSource. Un UrlWebViewSource viene usato per caricare una pagina Web specificata con un URL, mentre un oggetto HtmlWebViewSource viene usato per caricare un file HTML locale o html locale.

WebView definisce un evento Navigating che viene generato all'inizio della navigazione della pagina e un evento Navigated che viene generato al completamento della navigazione della pagina. L'oggetto WebNavigatingEventArgs che accompagna l'evento Navigating definisce una proprietà Cancel di tipo bool che può essere utilizzata per annullare la navigazione. L'oggetto WebNavigatedEventArgs che accompagna l'evento Navigated definisce una proprietà Result di tipo WebNavigationResult che indica il risultato della navigazione.

WebView definisce gli eventi seguenti:

  • Navigating, generato all'avvio dello spostamento tra le pagine. L'oggetto WebNavigatingEventArgs che accompagna questo evento definisce una proprietà Cancel di tipo bool che può essere utilizzata per annullare la navigazione.
  • Navigated, che viene generato al completamento della navigazione della pagina. L'oggetto WebNavigatedEventArgs che accompagna questo evento definisce una proprietà Result di tipo WebNavigationResult che indica il risultato della navigazione.
  • ProcessTerminated, generato quando un processo di WebView termina in modo imprevisto. L'oggetto WebViewProcessTerminatedEventArgs che accompagna questo evento definisce proprietà specifiche della piattaforma che indicano il motivo per cui il processo non è riuscito.

Importante

Un WebView deve specificare le sue proprietà HeightRequest e WidthRequest quando sono contenute in un HorizontalStackLayout, StackLayouto VerticalStackLayout. Se non si specificano queste proprietà, il WebView non verrà visualizzato.

Visualizzare una pagina Web

Per visualizzare una pagina Web remota, impostare la proprietà Source su un string che specifica l'URL:

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

Il codice C# equivalente è:

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

Gli URI devono essere completamente formati con il protocollo specificato.

Nota

Nonostante la proprietà Source sia di tipo WebViewSource, può essere impostata su un URI sotto forma di stringa. Poiché .NET MAUI include un convertitore di tipi e un operatore di conversione implicita, che converte l'URI basato su stringa in un oggetto UrlWebViewSource.

Configurare App Transport Security su iOS e Mac Catalyst

Dalla versione 9, iOS consentirà solo all'app di comunicare con server sicuri. Un'app deve acconsentire esplicitamente all'abilitazione della comunicazione con server non sicuri.

La configurazione Info.plist seguente illustra come abilitare un dominio specifico per aggirare i requisiti di 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>

È consigliabile abilitare solo domini specifici per ignorare ATS, consentendo di usare siti attendibili sfruttando al contempo la sicurezza aggiuntiva nei domini non attendibili.

La seguente configurazione Info.plist mostra come disabilitare ATS per un'applicazione:

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

Importante

Se l'app richiede una connessione a un sito Web non sicuro, devi sempre immettere il dominio come eccezione usando la chiave NSExceptionDomains anziché disattivare completamente ATS usando la chiave NSAllowsArbitraryLoads.

Visualizzare il codice HTML locale

Per visualizzare codice HTML inline, impostare la proprietà Source su un oggetto 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>

In XAML le stringhe HTML possono diventare illeggibili a causa dell'escape dei simboli < e >. Pertanto, per una maggiore leggibilità, l'HTML può essere inserito in una sezione 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>

Il codice C# equivalente è:

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

Visualizzare un file HTML locale

Per visualizzare un file HTML locale, aggiungere il file alla cartella Resources\Raw del progetto dell'app e impostarne l'azione di compilazione su MauiAsset. Il file può quindi essere caricato dal codice HTML inline definito in un oggetto HtmlWebViewSource impostato come valore della proprietà 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>

Il file HTML locale può caricare Fogli di Stile CSS, JavaScript e immagini se anch'essi sono stati aggiunti al progetto dell'app con l'azione di compilazione MauiAsset.

Per altre informazioni sugli asset non elaborati, vedere asset non elaborati.

Ricaricare il contenuto

WebView dispone di un metodo Reload che può essere chiamato per ricaricare l'origine:

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

Quando il metodo Reload viene richiamato l'evento ReloadRequested viene generato, a indicare che è stata effettuata una richiesta per ricaricare il contenuto corrente.

Eseguire la navigazione

WebView supporta la navigazione a livello di codice con i metodi GoBack e GoForward. Questi metodi consentono lo spostamento tramite lo stack di pagine WebView e devono essere chiamati solo dopo aver esaminato i valori delle proprietà CanGoBack e CanGoForward:

WebView webView = new WebView();
...

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

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

Quando la navigazione della pagina si verifica in un WebView, sia avviata a livello di codice che dall'utente, si verificano i seguenti eventi:

  • Navigating, che viene generato all'avvio della navigazione nella pagina. L'oggetto WebNavigatingEventArgs che accompagna l'evento Navigating definisce una proprietà Cancel di tipo bool che può essere utilizzata per annullare la navigazione.
  • Navigated, generato al termine dell'esplorazione della pagina. L'oggetto WebNavigatedEventArgs che accompagna l'evento Navigated definisce una proprietà Result di tipo WebNavigationResult che indica il risultato della navigazione.

Gestire le autorizzazioni in Android

Quando si passa a una pagina che richiede l'accesso all'hardware di registrazione del dispositivo, ad esempio la fotocamera o il microfono, l'autorizzazione deve essere concessa dal controllo WebView. Il controllo WebView utilizza il tipo Android.Webkit.WebChromeClient su Android per rispondere alle richieste di autorizzazione. Tuttavia, l'implementazione WebChromeClient fornita da .NET MAUI ignora le richieste di autorizzazione. È necessario creare un nuovo tipo che eredita da MauiWebChromeClient e approva le richieste di autorizzazione.

Importante

La personalizzazione del WebView per approvare le richieste di autorizzazione, usando questo approccio, richiede l'API Android 26 o versione successiva.

Le richieste di autorizzazione da una pagina Web al controllo WebView sono diverse dalle richieste di autorizzazione dall'app MAUI .NET all'utente. Le autorizzazioni dell'app .NET MAUI vengono richieste e approvate dall'utente per l'intera app. Il controllo WebView dipende dalla capacità delle app di accedere all'hardware. Per illustrare questo concetto, considerare una pagina Web che richiede l'accesso alla fotocamera del dispositivo. Anche se tale richiesta è approvata dal controllo WebView, l'app MAUI .NET non ha l'autorizzazione dell'utente per accedere alla fotocamera, quindi la pagina web non sarebbe in grado di accedervi.

I passaggi seguenti illustrano come intercettare le richieste di autorizzazione dal controllo WebView per usare la fotocamera. Se si sta tentando di usare il microfono, i passaggi sarebbero simili, ad eccezione del fatto che si userebbero autorizzazioni correlate al microfono anziché autorizzazioni correlate alla fotocamera.

  1. Aggiungere prima di tutto le autorizzazioni necessarie per l'app al manifesto Android. Aprire il file Platforms/Android/AndroidManifest.xml e aggiungere quanto segue nel nodo manifest:

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

  2. A un certo punto dell'app, ad esempio quando viene caricata la pagina contenente un controllo WebView, richiedere l'autorizzazione dell'utente per consentire all'app di accedere alla fotocamera.

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

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

  3. Aggiungi la seguente classe alla cartella Platforms/Android, modificando lo spazio dei nomi radice affinché corrisponda a quello del tuo progetto (non aggiungere .Platforms.Android allo spazio dei nomi):

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

    Nel frammento di codice precedente, la classe MyWebChromeClient eredita da MauiWebChromeCliented esegue l'override del metodo OnPermissionRequest per intercettare le richieste di autorizzazione della pagina Web. Ogni elemento di autorizzazione viene controllato per verificare se corrisponde alla costante stringa PermissionRequest.ResourceVideoCapture, che rappresenta la fotocamera. Se l'autorizzazione per la fotocamera è concessa, il codice verifica se l'app ha il permesso di usare la fotocamera. Se l'autorizzazione è concessa, la richiesta della pagina Web viene accettata.

  4. Usare il metodo SetWebChromeClient nel controllo WebView Android per impostare il client Chrome su MyWebChromeClient. I due elementi seguenti illustrano come impostare il client Chrome:

    • Dato un controllo MAUI .NET WebView denominato theWebViewControl, è possibile impostare il client Chrome direttamente nella visualizzazione della piattaforma, ovvero il controllo Android:

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

    • È anche possibile usare il mapping delle proprietà del gestore per forzare tutti i controlli WebView a usare il client Chrome. Per ulteriori informazioni, vedere Gestori.

      Il metodo CustomizeWebViewHandler del frammento di codice seguente deve essere chiamato all'avvio dell'app, ad esempio nel metodo 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
}

Imposta i cookie

I cookie possono essere impostati su un WebView in modo che vengano inviati con la richiesta Web all'URL specificato. Impostare i cookie aggiungendo Cookie oggetti a un CookieContainere quindi impostando il contenitore come valore della proprietà associabile WebView.Cookies. Il codice seguente illustra un esempio:

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

In questo esempio viene aggiunto un singolo Cookie all'oggetto CookieContainer, che viene quindi impostato come valore della proprietà WebView.Cookies. Quando il WebView invia una richiesta Web all'URL specificato, il cookie viene inviato con la richiesta.

Richiamare JavaScript

WebView include la possibilità di richiamare una funzione JavaScript da C# e restituire qualsiasi risultato al codice C# chiamante. Questa interoperabilità viene realizzata tramite il metodo EvaluateJavaScriptAsync, come illustrato nell'esempio seguente.

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

Il metodo WebView.EvaluateJavaScriptAsync valuta il JavaScript specificato come argomento, e restituisce qualsiasi risultato come string. In questo esempio viene richiamata la funzione JavaScript factorial, che restituisce il fattoriale di number di conseguenza. Questa funzione JavaScript viene definita nel file HTML locale caricato dal WebView ed è illustrato nell'esempio seguente:

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

Configurare il WebView nativo su iOS e Mac Catalyst

Il controllo WebView nativo è un MauiWKWebView in iOS e Mac Catalyst, che deriva da WKWebView. Uno degli overload del costruttore MauiWKWebView consente di specificare un oggetto WKWebViewConfiguration, fornendo informazioni su come configurare l'oggetto WKWebView. Le configurazioni tipiche includono l'impostazione dell'agente utente, la specifica dei cookie da rendere disponibili per il contenuto Web e l'inserimento di script personalizzati nel contenuto Web.

È possibile creare un oggetto WKWebViewConfiguration nell'app e quindi configurarne le proprietà in base alle esigenze. In alternativa, puoi chiamare il metodo statico MauiWKWebView.CreateConfiguration per recuperare l'oggetto WKWebViewConfiguration MAUI di .NET e quindi modificarlo. L'oggetto WKWebViewConfiguration può quindi essere specificato come argomento per l'overload del costruttore MauiWKWebView.

Poiché la configurazione del WebView nativo non può essere modificata su iOS e Mac Catalyst una volta creata la vista della piattaforma del gestore, è necessario creare un delegato di factory del gestore personalizzato per poterla modificare:

#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

Nota

È consigliabile configurare MauiWKWebView con un oggetto WKWebViewConfiguration prima che venga visualizzato un WebView nell'app. Le posizioni appropriate per eseguire questa operazione si trovano nel percorso di avvio dell'app, ad esempio in MauiProgram.cs o App.xaml.cs.

Impostare le preferenze di riproduzione multimediale in iOS e Mac Catalyst

La riproduzione multimediale inline del video HTML5, inclusa la riproduzione automatica e la funzione picture-in-picture, è abilitata per impostazione predefinita per il WebView in iOS e Mac Catalyst. Per modificare questo valore predefinito o impostare altre preferenze di riproduzione multimediale, devi creare un delegato factory del gestore personalizzato, perché le preferenze di riproduzione multimediale non possono essere modificate dopo la creazione della visualizzazione della piattaforma del gestore. Il codice seguente illustra un esempio di questa operazione:

#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

Per ulteriori informazioni sulla configurazione di un WebView su iOS, vedere Configura il WebView nativo su iOS e Mac Catalyst.

Ispezionare un WebView su Mac Catalyst

Per usare gli strumenti di sviluppo Safari per ispezionare il contenuto di un WebView su Mac Catalyst, aggiungere il codice seguente all'app:

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

Questo codice personalizza il mapper di proprietà per il WebViewHandler su Mac Catalyst, per rendere WebView contenuto ispezionabile dagli strumenti di sviluppo di Safari. Per altre informazioni sui gestori, vedere Gestori.

Per usare gli strumenti di sviluppo safari con un'app Mac Catalyst:

  1. Apri Safari sul tuo Mac.
  2. In Safari selezionare la casella di controllo Impostazioni >Safari > Avanzate > Mostra sviluppo nella barra dei menu.
  3. Esegui l'app .NET MAUI Mac Catalyst.
  4. In Safari selezionare il menu sviluppo sviluppo, dove il segnaposto è il nome del dispositivo, ad esempio . Quindi, seleziona la voce sotto il nome della tua app, la quale evidenzierà anche l'app in esecuzione. In questo modo verrà visualizzata la finestra di controllo Web .

Avviare il browser di sistema

È possibile aprire un URI nel Web browser di sistema con la classe Launcher, fornita da Microsoft.Maui.Essentials. Chiamare il metodo OpenAsync del launcher e passare un argomento string o Uri che rappresenti l'URI da aprire.

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

Per altre informazioni, vedere Launcher.