混合现实 WebView 插件的 API 参考（预览版）

项目
04/19/2024

适用于 Unity 的 Microsoft 混合现实 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 中的开始接收预览体验成员版本。

WebView2 和 WebView 插件仅在运行 Windows 11 更新的 HoloLens 2 设备上受支持。有关详细信息，请参阅更新 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 对象。只读

IWebView.Width 属性

WebView 纹理和 WebView 控件的宽度。请注意，Unity 场景中 IWebView 实例的呈现维度由 GameObject 控制。

IWebView.Height 属性

WebView 纹理和 WebView 控件的高度。请注意，Unity 场景中 IWebView 实例的呈现维度由 GameObject 控制。

IWebView.Page 属性

WebView 控件当前加载或导航到的 URI。只读

IWebView.OnceCreated 属性

当 WebView 控件已完全实例化并可供使用时执行任务。只读

示例

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 代码之间的互操作通信的接口。

若要详细了解 WebView2 中的互操作，请参阅本机端和 Web 端代码的互操作。

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

通过