混合實境 WebView 外掛程式的 API 參考（預覽）

發行項
12/18/2024

重要

WebView2 會繼續提供。不過，HoloLens 上的 WebView2 支援已停止（沒有錯誤修正、內容更新或技術支援），因此我們無法保證應用程式將持續運作一段時間。

適用於 Unity 的 Microsoft Mixed Reality WebView 外掛程式可讓您將 WebView2 功能整合到 HoloLens 2 應用程式中。此適用於 Unity 的 WebView 外掛程式藉由包裝 WebView2 控制件、自動處理轉譯，以及自動將輸入導向至 WebView2 控件，簡化將 WebView2 功能整合到 HoloLens 2 應用程式中。

此外掛程式也會管理 Unity 與 WebView2 之間的互操作性，透過訊息和事件啟用 JavaScript 與 Unity 之間的通訊。

此外掛程式會公開可透過 CoreWebView2 取得的功能子集。

HoloLens 2 上的 WebView2 和適用於 Unity 的 WebView 外掛程式都處於預覽狀態，在正式推出之前可能會變更。 Microsoft HoloLens 的 Insider Preview 中提供 WebView2 預覽版。若要存取此預覽版，您必須在 Windows 測試人員計劃中註冊;請參閱開始在 Insider Preview 中接收測試人員組建，以取得 HoloLens Microsoft。

執行 Windows 11 更新的 HoloLens 2 裝置僅支援 WebView2 和 WebView 外掛程式。如需詳細資訊，請參閱更新 HoloLens 2。

如需開始使用適用於 Unity 的 WebView 外掛程式的詳細資訊，請參閱開始使用 HoloLens 2 Unity 應用程式中的 WebView2。

IWebView 介面

Unity WebView 外掛程式的主要介面。

public interface IWebView
{
    event WebView_OnNavigated Navigated;

    event WebView_OnCloseRequested WindowCloseRequested;

    GameObject GameObject { get; }

    Texture2D Texture { get; }

    int Width { get; set; }

    int Height { get; set; }

    Uri Page { get; }
    
    Task OnceCreated { get; }

    void Resize(int width, int height);

    void Load(Uri url);

    void Dispose();
}

IWebView 委派

public delegate void WebView_OnNavigated(string path);

public delegate void WebView_OnCanGoForwardUpdated(bool value);

IWebView 事件

IWebView.Navigated 事件

當 CoreWebView2.SourceChanged 事件由 WebView 引發時觸發的事件。

範例

webView.Navigated += OnNavigated;

private void OnNavigated(string uri)
{
    UrlField.text = uri;
}

IWebView.WindowCloseRequested 事件

當 WebView 引發 CoreWebView2.WindowCloseRequested 事件時觸發的事件。

範例

webView.WindowCloseRequested += OnWindowCloseRequested;

private void OnWindowCloseRequested()
{
    Destroy(GameObject);
}

IWebView 屬性

IWebView.GameObject 屬性

最上層 Unity GameObject 實體，代表場景中的 WebView 外掛程式。 Readonly。

IWebView.Texture 屬性

WebView 內容轉譯的目標 2D Unity Texture2D 物件。 Readonly

IWebView.Width 屬性

WebView 紋理和 WebView 控件的寬度。 Unity 場景中實例的 IWebView 轉譯維度是由所 GameObject控制。

IWebView.Height 屬性

WebView 紋理和 WebView 控件的高度。 Unity 場景中實例的 IWebView 轉譯維度是由所 GameObject控制。

IWebView.Page 屬性

WebView 控件目前載入或巡覽至的 URI。 Readonly

IWebView.OnceCreated 屬性

工作會在 WebView 控件已完全具現化且可供使用時執行。 Readonly

範例

webView.OnceCreated.ContinueWith((task) => {

    // Finish setting up plugin.
    webview.Navigated += OnNavigated;
    webview.WindowCloseRequested += OnWindowCloseRequested;

    Load(initialURL);

}, TaskScheduler.FromCurrentSynchronizationContext());

IWebView 方法

IWebView.Resize 方法

變更 WebView2 控制件和 Texture的大小。如需詳細資訊，請參閱基礎 CoreWebView2Controller.Bounds 屬性。

Unity 場景中實例的 IWebView 轉譯維度是由所 GameObject控制。

範例

Resize(600, 400);

IWebView.Load 方法

導覽至指定的 URI。如需詳細資訊，請參閱基礎 CoreWebView2.Navigate 方法。

範例

Load(new Uri("https://www.microsoft.com"));

IWebView.Dispose 方法

清除與實例相關的 IWebView 記憶體、句柄和回呼等資源。

當您使用特定 IWebView 實例完成時，請叫用這個方法，以確保內部記憶體已正確釋放。呼叫之後 Dispose ， IWebView 實例應該視為無效。

範例

void OnDestroy()
{
    webView.Dispose();
}

IWithMouseEvents 介面

支援適用於 Unity 的 WebView 外掛程式的滑鼠和指標輸入。

public interface IWithMouseEvents
{
    void MouseEvent(WebViewMouseEventData mouseEvent);
}

IWithMouseEvents 方法

IWithMouseEvents.MouseEvent 方法

將 WebViewMouseEventData 事件傳播至 WebView 控件。根據內部邏輯，事件會導致呼叫 CoreWebView2Controller.SendMouseInput 方法或 CoreWebView2Controller.SendPointerInput 方法。

範例

public void OnPointerDown(PointerEventData eventData)
{
    IWithMouseEvents mouseEventsWebView = webView as IWithMouseEvents;

    // Call hypothetical function which converts the event's x, y into the WebView2's coordinate space.
    var hitCoord = ConvertToWebViewSpace(eventData.position.x, eventData.position.y);

    WebViewMouseEventData mouseEvent = new WebViewMouseEventData
    {
        X = hitCoord.x,
        Y = hitCoord.y,
        Type = PointerEvent.PointerDown,
        Button = PointerButton.Left,
        TertiaryAxisDeviceType = WebViewMouseEventData.TertiaryAxisDevice.PointingDevice
    };

    mouseEventsWebView.MouseEvent(mouseEvent);
}

IWithPostMessage 介面

Unity 程式代碼與託管 WebView 程式代碼之間 Interop 通訊的介面。

若要深入瞭解 WebView2 中的 Interop，請參閱原生端和 Web 端程式代碼的 Interop。

public interface IWithPostMessage : IWebView
{
    event WebView_OnPostMessage MessageReceived;

    void PostMessage(string message, bool isJSON = false);
}

IWithPostMessage 委派

public delegate void WebView_OnPostMessage(string message);

IWithPostMessage 事件

IWithPostMessage.MessageReceived 方法

從 WebView 控件收到新的 JavaScript 訊息時觸發。如需詳細資訊，請參閱基礎 CoreWebView2.WebMessageReceived 事件。

範例

(webView as IWithPostMessage).MessageReceived += OnMessageReceived;

void OnMessageReceived(string message)
{
    Debug.Log(message);
}

IWithPostMessage 方法

IWithPostMessage.PostMessage 方法

將 JavaScript 訊息傳送至 WebView 控件中的託管內容。視參數而定 isJSON ，這會導致呼叫 CoreWebView2.PostWebMessageAsString 方法或 CoreWebView2.PostWebMessageAsJson 方法。

var msg = new MyMessage("updateText", "Updated from Unity!");

(webView as IWithPostMessage).PostMessage(JsonUtility.ToJson(msg), true);

IWithBrowserHistory 介面

處理與瀏覽器歷程記錄相關的功能，例如流覽至上一頁。

public interface IWithBrowserHistory : IWebView
{
    event WebView_OnCanGoForwardUpdated CanGoForwardUpdated;

    event WebView_OnCanGoBackUpdated CanGoBackUpdated;

    void GoBack();

    void GoForward();
}

IWithBrowserHistory 委派

public delegate void WebView_OnCanGoBackUpdated(bool value);

public delegate void WebView_OnCloseRequested();

IWithBrowserHistory 事件

IWithBrowserHistory.CanGoForwardUpdated 事件

巡覽發生時觸發。如果 CoreWebView2.CanGoForward 屬性為 true，則事件委派會提供true值。

範例

(webView as IWithBrowserHistory).CanGoBackUpdated += OnCanGoBack;

void OnCanGoBack(bool value)
{
    BackButton.enabled = value;
}

IWithBrowserHistory.CanGoBackUpdated 事件

巡覽發生時觸發。如果 CoreWebView2.CanGoBack 屬性為 true，則事件委派會提供true值。

範例

(webView as IWithBrowserHistory).CanGoForwardUpdated += OnCanGoForward;

void OnCanGoForward(bool value)
{
    ForwardButton.enabled = value;
}

IWithBrowserHistory 方法

IWithBrowserHistory.GoBack 方法

巡覽至上一頁。如需詳細資訊，請參閱基礎 CoreWebView2.GoBack 方法。

範例

(webView as IWithBrowserHistory).GoBack();

IWithBrowserHistory.GoForward 方法

流覽至下一頁。如需詳細資訊，請參閱基礎 CoreWebView2.GoForward 方法。

範例

(webView as IWithBrowserHistory).GoForward();

共用方式為

混合實境 WebView 外掛程式的 API 參考 （預覽）