共用方式為

WebView

  • 發行項

.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當 包含在、 StackLayout或 VerticalStackLayout中HorizontalStackLayout時，必須指定其 HeightRequest 和 WidthRequest 屬性。 如果您無法指定這些屬性， WebView 將不會轉譯 。

顯示網頁

若要顯示遠端網頁，請將 Source 屬性設定為 string ，以指定 URI：

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

最佳做法是只讓特定網域略過 ATS，讓您能夠使用信任的網站，同時受益於不受信任的網域的其他安全性。

下列 Info.plist 組態示範如何停用應用程式的 ATS：

	<key>NSAppTransportSecurity</key>
	<dict>
		<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[
                <HTML>
                <BODY>
                <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。 然後，您可以從內嵌 HTML 載入檔案，該內嵌 HTML 定義於設定為 屬性的值Source的物件中HtmlWebViewSource：

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

如果本機 HTML 檔案也已使用 MauiAsset 建置動作新增至您的應用程式專案，則本機 HTML 檔案可以載入級聯樣式表 （CSS）、JavaScript 和影像。

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

重載內容

WebViewReload具有可以呼叫以重載其來源的方法：

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

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

執行導覽

WebView 支援使用 GoBack 和 GoForward 方法以程序設計方式流覽。 這些方法可讓您瀏覽WebView頁面堆疊，而且只有在檢查 和 CanGoForward 屬性的值CanGoBack之後，才應該呼叫：

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 的物件會 Result 定義型 WebNavigationResult 別的屬性，指出導覽結果。

處理 Android 的許可權

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

重要

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

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

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

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

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

  2. 在您的應用程式中某個時間點，例如載入包含 WebView 控制項的頁面時，要求使用者的許可權，以允許應用程式存取相機。

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

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

  3. 將下列類別新增至 [平臺/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();
                else
                    request.Grant(request.GetResources());

                return;
            }
        }

        base.OnPermissionRequest(request);
    }
}

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

  4. SetWebChromeClient使用 Android WebView 控制項上的 方法，將 Chrome 用戶端設定為 MyWebChromeClient。 下列兩個專案示範如何設定 Chrome 用戶端：

    • 假設有名為 theWebViewControl的 .NET MAUI WebView 控制件，您可以直接在平台檢視上設定 Chrome 用戶端，這是 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 要求將 Cookie 傳送至指定的 URL。 將物件新增至 CookieContainer來設定 Cookie 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 檔案中，如下列範例所示：

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

在 iOS 和 Mac Catalyst 上設定原生 WebView

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

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

由於在建立處理程式的平台檢視之後，原生設定 WebView 無法在iOS和Mac Catalyst上變更，因此您應該建立自定義處理程式處理站委派來修改它：

#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在應用程式中顯示 之前WebView，WKWebViewConfiguration使用 對象進行設定。 適合執行此動作的位置位於您應用程式的啟動路徑中，例如 MauiProgram.cs 或 App.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 ，讓 WebView 內容可供 Safari 開發人員工具檢查。 如需處理程式的詳細資訊，請參閱 處理程式。

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

  1. 在您的 Mac 上開啟 Safari。
  2. 在 Safari 中，選取 [Safari > 設定 > 進階 > 顯示開發] 功能表的選單列 複選框。
  3. 執行 .NET MAUI Mac Catalyst 應用程式。
  4. 在 Safari 中，選取 [開發 {裝置名稱}] 選單，其中{Device name}佔位符是您的裝置名稱，例如 Macbook Pro> 。 然後選取應用程式名稱底下的專案，這也會反白顯示您執行中的應用程式。 這會導致 Web 偵測器 窗口出現。

啟動系統瀏覽器

有可能在系統網頁瀏覽器中使用 Launcher 類別開啟 URI，而 類別是由 提供 Microsoft.Maui.Essentials。 呼叫啟動器 OpenAsync 的方法，並傳入 string 或 Uri 自變數，代表要開啟的URI：

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

如需詳細資訊，請參閱 啟動器。