(Preview) Mixed Reality WebView 外掛程式的 API 參考

發行項
05/16/2023

適用于 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 外掛程式都處於預覽狀態，而且在正式運作之前可能會變更。 WebView2 預覽版適用于 Microsoft HoloLens 的 Insider Preview 中提供。若要存取此預覽版，您必須在 Windows 測試人員計畫中註冊;如需Microsoft HoloLens，請參閱在Insider Preview中開始接收測試人員組建。

只有在執行 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 事件

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

範例

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

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

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

共用方式為