.NET 多平台應用程式 UI (.NET MAUI) WebView 會在應用程式中顯示遠端網頁、本機 HTML 檔案和 HTML 字串。 顯示於 WebView 的內容支援級聯樣式表(CSS)和 JavaScript。 根據預設,.NET MAUI 專案包含 WebView 顯示遠端網頁所需的平台許可權。

WebView 定義下列屬性:

Cookies ,類型為 CookieContainer ,提供用於儲存 Cookie 集合的存儲空間。 CanGoBack 類型為 bool ,指出使用者是否可以瀏覽至先前的頁面。 這是唯讀屬性。 CanGoForward 的類型是 bool ,表示使用者是否可以向前瀏覽。 這是唯讀屬性。
  • 類型為 Source WebViewSource ,代表 WebView 顯示的位置。
  • UserAgent 的類型為 string ,代表使用者代理程式。 預設值是底層平台瀏覽器的用戶代理,如果無法確定,則為 null

    這些屬性是由 BindableProperty 物件所支援,這表示這些屬性可以是數據系結的目標,並設定樣式。

    Source 屬性可以設定為 UrlWebViewSource 物件或 HtmlWebViewSource 物件,這兩者都衍生自 WebViewSource UrlWebViewSource 用於載入以 URL 指定的網頁,而 HtmlWebViewSource 物件則用於載入本機 HTML 檔案或本機 HTML。

    WebView 定義頁面導覽啟動時引發的 Navigating 事件,以及頁面導覽完成時引發的 Navigated 事件。 WebNavigatingEventArgs 物件隨附於 Navigating 事件,並定義了一個屬於 Cancel 類型的 bool 屬性,此屬性可用來取消導覽。 隨著 WebNavigatedEventArgs 事件的 Navigated 物件定義了一個類型為 Result WebNavigationResult 屬性,該屬性指示導覽結果。

    WebView 定義下列事件:

    Navigating 會在頁面導覽開始時觸發。 與此事件相關聯的 WebNavigatingEventArgs 物件定義了一個類型為 Cancel bool 屬性,此屬性可用來取消導覽。 Navigated ,在頁面導航完成時會被觸發。 此事件附帶的 WebNavigatedEventArgs 物件定義了 Result 屬性,此屬性為類型 WebNavigationResult ,表示導覽結果。 ProcessTerminated ,是當 WebView 進程意外結束時會引發的事件。 此事件隨附的 WebViewProcessTerminatedEventArgs 物件會定義平臺特定屬性,指出進程失敗的原因。

    當包含在 WebView HeightRequest WidthRequest 時, HorizontalStackLayout 必須指定其 StackLayout VerticalStackLayout 屬性。 如果您無法指定這些屬性,則 WebView 將不會轉譯。

    若要顯示遠端網頁,請將 Source 屬性設定為指定 URI 的 string

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

    對等的 C# 程式代碼為:

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

    URI 必須以指定的通訊協定完整形成。

    儘管 Source 屬性屬於 WebViewSource類型,但 屬性可以設定為字串型 URI。 這是因為 .NET MAUI 包含類型轉換器,以及隱含轉換運算元,可將字串型 URI 轉換成 UrlWebViewSource 物件。

    在 iOS 和 Mac Catalyst 上設定應用程式傳輸安全性

    由於版本 9,iOS 只會允許您的應用程式與安全伺服器通訊。 應用程式必須選擇啟用與不安全伺服器通訊。

    下列 Info.plist 組態顯示如何讓特定網域略過 Apple Transport Security (ATS) 需求:

    	<key>NSAppTransportSecurity</key>
    		<key>NSExceptionDomains</key>
    			<key>mydomain.com</key>
    				<key>NSIncludesSubdomains</key>
    				<true/>
    				<key>NSTemporaryExceptionAllowsInsecureHTTPLoads</key>
    				<true/>
    				<key>NSTemporaryExceptionMinimumTLSVersion</key>
    				<string>TLSv1.1</string>
    			</dict>
    		</dict>
    	</dict>
    

    最佳做法是僅允許特定網域繞過 ATS,這樣您可以使用可信任的網站,同時在不受信任的網域上利用額外的安全保護。

    下列 Info.plist 配置顯示如何停用應用程式中的 ATS:

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

    如果您的應用程式需要連線到不安全的網站,您應該一律使用 NSExceptionDomains 密鑰輸入網域作為例外狀況,而不是使用 NSAllowsArbitraryLoads 金鑰完全關閉 ATS。

    顯示本機 HTML

    若要顯示內嵌 HTML,請將 Source 屬性設定為 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>
    

    在 XAML 中,HTML 字串可能會因為逸出 <> 符號而變得無法讀取。 因此,為了提高可讀性,HTML 可以在 CDATA 區段中內嵌:

    <WebView>
        <WebView.Source>
            <HtmlWebViewSource>
                <HtmlWebViewSource.Html>
                    <![CDATA[
                    <H1>.NET MAUI</H1>
                    <P>Welcome to WebView.</P>
                    </BODY>
                    </HTML>
                </HtmlWebViewSource.Html>
            </HtmlWebViewSource>
        </WebView.Source>
    </WebView>
    

    對等的 C# 程式代碼為:

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

    顯示本機 HTML 檔案

    若要顯示本機 HTML 檔案,請將檔案新增至應用程式專案的 Resources\Raw 資料夾,並將其建置動作設定為 MauiAsset。 然後,您可以從 HtmlWebViewSource 物件中定義的內嵌 HTML 載入檔案,該物件設定為 Source 屬性的值:

    <WebView>
        <WebView.Source>
            <HtmlWebViewSource>
                <HtmlWebViewSource.Html>
                    <![CDATA[
                    </head>
                    <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>
    

    本機 HTML 檔案可以載入級聯樣式表(CSS)、JavaScript 和影像,但前提是這些資源已經使用 MauiAsset 建置動作加入到您的應用程式專案中。

    如需原始資產的詳細資訊,請參閱 原始資產

    WebView 具有一個方法 Reload,可以呼叫這個方法來重新載入其來源:

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

    叫用 Reload 方法時,會引發 ReloadRequested 事件,指出已提出重載目前內容的要求。

    WebView 支援使用 GoBackGoForward 方法進行程式化導覽。 這些方法能夠導覽 WebView 頁面堆疊,而且只有在檢查 CanGoBackCanGoForward 屬性的值之後,才應該使用:

    WebView webView = new WebView();
    // Go backwards, if allowed.
    if (webView.CanGoBack)
        webView.GoBack();
    // Go forwards, if allowed.
    if (webView.CanGoForward)
        webView.GoForward();
    

    WebView中的頁面導航發生時,無論是通過程式設計或由使用者啟動,都會發生以下事件:

    Navigating會在頁面導航開始時觸發。 WebNavigatingEventArgs 物件隨附於 Navigating 事件,並定義了一個屬於 Cancel 類型的 bool 屬性,此屬性可用來取消導覽。 Navigated,會在頁面導覽完成時觸發。 隨著 WebNavigatedEventArgs 事件的 Navigated 物件定義了一個類型為 ResultWebNavigationResult 屬性,該屬性指示導覽結果。

    在 Android 上啟用或停用 JavaScript

    在 Android 上,預設 WebView會啟用 JavaScript 執行。 您可以使用 Android 專屬的平台設定 API 在執行階段切換這項行為:

    using Microsoft.Maui.Controls.PlatformConfiguration;
    using Microsoft.Maui.Controls.PlatformConfiguration.AndroidSpecific;
    // Disable JavaScript
    webView.On<Android>().SetJavaScriptEnabled(false);
    // Re-enable JavaScript
    webView.On<Android>().SetJavaScriptEnabled(true);
    // Query current state
    bool isEnabled = webView.On<Android>().IsJavaScriptEnabled();
    

    停用 JavaScript 可能會破壞依賴 JavaScript 的網站的功能。 此外,在停用 JavaScript 時,呼叫 不會 EvaluateJavaScriptAsync 執行腳本。

    在 Android 上全屏播放視頻

    當影片託管在 AndroidWebView 上時,可以透過在allowfullscreen中加入iframe來全螢幕播放。

    myWebView.Source = new HtmlWebViewSource
      Html = @"<!DOCTYPE html>
          <meta name='viewport' content='width=device-width, initial-scale=1.0'>
          <style>
            body { margin: 0; padding: 0; }
            .video-container { position: relative; padding-bottom: 56.25%; height: 0; overflow: hidden; }
            .video-container iframe { position: absolute; top: 0; left: 0; width: 100%; height: 100%; }
          </style>
        </head>
          <div class='video-container'>
            <iframe src='https://www.youtube.com/embed/YE7VzlLtp-4'
                frameborder='0'
                allow='accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share'
                allowfullscreen>
            </iframe>
        </body>
        </html>"
    
    

    在 Android 上,當按下指定 WebView (在新視窗中開啟內容) 的超連結時,不會發生target="_blank"導覽。 這是因為要在新視窗中開啟超連結需要實作 OnCreateWindow,而 .NET MAUI 不具備此功能。 因此,對於此案例,您應該決定是否要自行實作 OnCreateWindow 、在系統瀏覽器中開啟 URL,或執行其他動作。

    或者,若要強制所有超連結在相同的 WebView中開啟,請修改應用程式中的 WebViewHandler,讓原生 WebView停用對多個視窗的支援。

    #if ANDROID
        Microsoft.Maui.Handlers.WebViewHandler.Mapper.AppendToMapping("SupportMultipleWindows", (handler, view) =>
            handler.PlatformView.Settings.SetSupportMultipleWindows(false);
    #endif
    

    這段程式碼透過在 Android 上呼叫具有WebViewHandler引數的方法SetSupportMultipleWindows來自訂false的屬性對應器,並且應在使用者能流覽至指定target="_blank"的超連結之前執行。 如需處理程式的詳細資訊,請參閱 處理程式

    管理 Android 的權限

    流覽至要求存取裝置錄製硬體的頁面時,例如相機或麥克風,WebView 控件必須授與許可權。 WebView 控制項會使用 Android 上的 Android.Webkit.WebChromeClient 類型來響應許可權要求。 不過,.NET MAUI 所提供的 WebChromeClient 實作會忽略許可權要求。 您必須建立繼承自 MauiWebChromeClient 的新類型,並核准權限請求。

    自定義 WebView 以使用此方法核准許可權要求,需要 Android API 26 或更新版本。

    從網頁到 WebView 控件的許可權要求,與 .NET MAUI 應用程式對用戶的許可權要求不同。 針對整個應用程式,使用者會要求並核准 .NET MAUI 應用程式許可權。 WebView 控件取決於應用程式存取硬體的能力。 為了說明這個概念,請考慮要求存取裝置相機的網頁。 即使該要求已通過 WebView 控制核准,但如果 .NET MAUI 應用程式尚未獲得使用者允許存取相機,網頁仍將無法存取相機。

    下列步驟示範如何攔截來自 WebView 控件的許可權要求,以使用相機。 如果您嘗試使用麥克風,步驟會很類似,不同之處在於您會使用麥克風相關許可權,而不是相機相關許可權。

  • 首先,將必要的應用程式許可權新增至 Android 指令清單。 開啟 Platform/Android/AndroidManifest.xml 檔案,並在 [manifest] 節點中新增下列內容:

    <uses-permission android:name="android.permission.CAMERA" />
    
  • 在您的應用程式中某個時間點,例如載入包含 WebView 控件的頁面時,要求使用者的許可權,以允許應用程式存取相機。

    private async Task RequestCameraPermission()
        PermissionStatus status = await Permissions.CheckStatusAsync<Permissions.Camera>();
        if (status != PermissionStatus.Granted)
            await Permissions.RequestAsync<Permissions.Camera>();
    
  • 將下列類別新增至 Platform/Android 資料夾,將根命名空間變更為符合專案的命名空間(請勿將 .Platforms.Android 附加至命名空間):

    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();
                        request.Grant(request.GetResources());
                    return;
            base.OnPermissionRequest(request);
    

    在上一個代碼段中,MyWebChromeClient 類別繼承自 MauiWebChromeClient,並覆寫 OnPermissionRequest 方法來攔截網頁許可權要求。 系統會檢查每個權限項目,以查看它是否符合代表相機的 PermissionRequest.ResourceVideoCapture 字串常數。 如果符合相機許可權,程式代碼會檢查應用程式是否有權使用相機。 如果具有權限,將滿足網頁的請求。

  • 使用 Android SetWebChromeClient 控制件上的 WebView 方法,將 chrome 客戶端設定為 MyWebChromeClient。 下列兩個專案示範如何設定 Chrome 用戶端:

  • 假設有名為 WebView的 .NET MAUI theWebViewControl 控制項,您可以直接在平台檢視中設定瀏覽器用戶端,這是指 Android 控制項:

    ((IWebViewHandler)theWebViewControl.Handler).PlatformView.SetWebChromeClient(new MyWebChromeClient((IWebViewHandler)theWebViewControl.Handler));
    
  • 您也可以使用處理程式屬性對應來強制所有 WebView 控件使用 Chrome 用戶端。 如需詳細資訊,請參閱 處理程式

    當應用程式啟動時,應該呼叫下列代碼段的 CustomizeWebViewHandler 方法,例如在 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
    

    設定 Cookie

    可以在 WebView 裝置上設定 Cookie,以便隨 Web 請求一同發送至指定的 URL。 將 Cookie 物件新增至 CookieContainer來設定 Cookie,然後將容器設定為可系結屬性 WebView.Cookies 的值。 下列程式代碼顯示範例:

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

    在此範例中,會將單一 Cookie 新增至 CookieContainer 對象,然後設定為 WebView.Cookies 屬性的值。 當 WebView 傳送 Web 要求至指定的 URL 時,Cookie 會隨要求一起傳送。

    叫用 JavaScript

    WebView 包含從 C# 叫用 JavaScript 函式的能力,並將任何結果傳回呼叫的 C# 程式代碼。 這個 Interop 是使用 EvaluateJavaScriptAsync 方法完成的,如下列範例所示:

    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}.";
                  WebView.EvaluateJavaScriptAsync 方法會評估指定為 自變數的 JavaScript,並以 string傳回任何結果。 在此範例中,會叫用 factorial JavaScript 函式,因此會傳回 number 的因數。 此 JavaScript 函式定義於 WebView 載入的本機 HTML 檔案中,如下列範例所示:

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

    在 iOS 和 Mac Catalyst 上設定原生 WebView

    原生 WebView 控件是 iOS 和 Mac Catalyst 上的 MauiWKWebView,衍生自 WKWebView。 其中一個 MauiWKWebView 建構函式多載可指定 WKWebViewConfiguration 物件,以提供如何設定 WKWebView 對象的相關信息。 一般設定包括設定使用者代理程式、指定要提供給 Web 內容的 Cookie,以及將自定義腳本插入您的 Web 內容中。

    您可以在應用程式中建立 WKWebViewConfiguration 物件,然後視需要設定其屬性。 或者,您可以呼叫靜態 MauiWKWebView.CreateConfiguration 方法來擷取 .NET MAUI 的 WKWebViewConfiguration 對象,然後加以修改。 然後,可以將 WKWebViewConfiguration 物件指定為 MauiWKWebView 建構函式多載的自變數。

    由於在建立處理站平台檢視之後,無法在iOS和Mac Catalyst上變更原生元件 WebView 的設定,因此您應該建立自訂處理站工廠委派來修改它:

    #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
    

    您應該在應用程式中顯示 MauiWKWebView 之前,使用 WKWebViewConfiguration 對象來設定 WebView。 適合執行此動作的位置位於您應用程式的啟動路徑中,例如在 MauiProgram.csApp.xaml.cs中。

    在 iOS 和 Mac Catalyst 上設定媒體播放喜好設定

    在 iOS 和 Mac Catalyst 上,WebView 預設會啟用 HTML5 視訊的內嵌媒體播放功能,這包括自動播放和畫中畫功能。 若要變更此預設值,或設定其他媒體播放喜好設定,您應該建立自定義處理程式處理站委派,因為一旦建立處理程式的平台檢視之後,就無法變更媒體播放喜好設定。 下列程式代碼示範執行此動作的範例:

    #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
    

    如需在 iOS 上設定 WebView 的詳細資訊,請參閱 在 iOS 和 Mac Catalyst 上設定原生 WebView

    檢查 Mac Catalyst 上的 WebView

    若要使用 Safari 開發人員工具來檢查 Mac Catalyst 上 WebView 的內容,請將下列程式代碼新增至您的應用程式:

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

    此程式代碼會自定義 Mac Catalyst 上 WebViewHandler 的屬性對應程式,讓 Safari 開發人員工具可檢查 WebView 內容。 如需處理程式的詳細資訊,請參閱 處理程式

    若要搭配 Mac Catalyst 應用程式使用 Safari 開發人員工具:

  • 在您的 Mac 上開啟 Safari。
  • 在 Safari 中,選取 [Safari > [設定] > [進階] > [在功能表欄] 複選框中顯示 [開發] 功能表。
  • 執行 .NET MAUI Mac Catalyst 應用程式。
  • 在 Safari 中,選取 [開發 > {裝置名稱}] 選單,其中的 {Device name} 佔位符代表您的裝置名稱,例如 Macbook Pro。 然後選取您應用程式名稱下的項目,並反白顯示您正在運行的應用程式。 這會導致 Web 偵測器 窗口出現。
  • 啟動系統瀏覽器

    在系統網頁瀏覽器中,可以使用 Launcher 類別開啟 URI,而該類別是由 Microsoft.Maui.Essentials提供。 呼叫啟動器 OpenAsync 方法,並傳入代表要開啟之 URI 的 stringUri 自變數:

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

    如需詳細資訊,請參閱 Launcher

    攔截網路請求

    對於裝載 Web 內容且需要攔截要求的混合式案例 (例如,修改標頭或提供本機回應) ,請參閱下列攔截指引:

    混合網路檢視
  • BlazorWebView
  •