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

项目
12/18/2024

重要

WebView2 将继续可用。但是，HoloLens 上的 WebView2 支持已停止（无 bug 修复、内容更新或技术支持），因此我们不能保证应用程序将继续在任何长时间内工作。

适用于 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();

通过