捕获事件

捕获事件通知您鼠标捕获状态的变化。UI 工具包有两种类型的捕获事件：

鼠标捕获事件
指针捕获事件

当一个元素捕获鼠标或指针时，它是唯一从指针设备接收事件的元素，直到设备释放或丢失捕获。

例如，如果您在文本框中单击，则该文本框会捕获鼠标。鼠标仍然可以在屏幕上移动，但不会触发文本框外的事件。只要文本框捕获了您的鼠标，它就不会触发其他事件。当用户在文本框外按下鼠标上的按钮时，该框会释放其鼠标捕获。

事件	描述	涓滴	冒泡
MouseCaptureEvent	当某一元素接受鼠标捕获时发送。	✔	✔
MouseCaptureOutEvent	当某一元素释放鼠标捕获或以其他方式失去鼠标捕获时发送。	✔	✔
PointerCaptureEvent	当某一元素捕获指针时发送。	✔	✔
PointerCaptureOutEvent	当某一元素释放指针时发送。	✔	✔

行为

鼠标捕获

鼠标捕获事件是指物理鼠标或模拟物理鼠标的虚拟鼠标上的事件。捕获鼠标也会导致鼠标指针的 PointerCaptureEvent。

当一个元素释放鼠标捕获时，相应的 MouseCaptureOutEvent 触发，目标是请求释放捕获的元素。

永远不可能有两个元素同时捕获鼠标。如果另一个视觉元素触发了一个 MouseCaptureEvent，发送原始 MouseCaptureEvent 的元素将丢失捕获。这也会在原始元素上触发一个 MouseCaptureOutEvent。

指针捕获

在 UI 工具包中，指针事件先于鼠标事件。如果指针类型是鼠标，捕获它也会触发相应的鼠标捕获事件。捕获指针也将捕获鼠标。

事件列表

MouseCaptureEvent

当元素接受鼠标捕获时，发送 MouseCaptureEvent 事件。

target：接受捕获的元素。

MouseCaptureOutEvent

当元素释放或失去鼠标捕获时，发送 MouseCaptureOutEvent 事件。

target：失去捕获的元素。

PointerCaptureEvent

当指针接受鼠标捕获时，发送 PointerCaptureEvent 事件。

target：接受捕获的元素。

PointerCaptureOutEvent

当元素释放或失去指针捕获时，发送 PointerCaptureOutEvent 事件。

target：失去捕获的元素。

示例

以下示例演示了捕获事件以及捕获和释放指针的行为。

要查看示例运行效果，请执行以下操作：

在 Assets > Scripts > Editor 下，创建一个新的 C# 文件，名为 CaptureEventsTestWindow.cs
将该示例复制到 C# 脚本。
从编辑器工具栏中，选择 Window > UI Toolkit > Capture Events Test Window。
单击对话窗口中的各个标签，并观察控制台的输出。

using UnityEditor;
using UnityEngine;
using UnityEngine.UIElements;

public class CaptureEventsTestWindow : EditorWindow
{
    [MenuItem("Window/UI Toolkit/Capture Events Test Window")]
    public static void ShowExample()
    {
        var wnd = GetWindow<CaptureEventsTestWindow>();
        wnd.titleContent = new GUIContent("Capture Events Test Window");
    }

    private bool m_IsCapturing = false;

    public void CreateGUI()
    {
        // 添加一些可点击的标签，在点击时将消息打印到控制台
        for (int i = 0; i < 4; i++)
        {
            Label clickableLabel = new Label($"Label {i} - Click Me!");
            clickableLabel.RegisterCallback<MouseDownEvent>((evt) => { Debug.Log($"Clicked on label '{(evt.target as Label).text}'"); });
            rootVisualElement.Add(clickableLabel);
        }

        // 现在添加一个捕获指针的标签
        Label capturingLabel = new Label("Click here to capture mouse");
        capturingLabel.RegisterCallback<MouseDownEvent>((evt) =>
        {
            if (!m_IsCapturing)
            {
                capturingLabel.text = "Click here to release mouse";
                MouseCaptureController.CaptureMouse(capturingLabel);
                m_IsCapturing = true;
            }
            else
            {
                capturingLabel.text = "Click here to capture mouse";
                MouseCaptureController.ReleaseMouse(capturingLabel);
                m_IsCapturing = false;
            }
        });
        rootVisualElement.Add(capturingLabel);

        // 注册回调以在鼠标被捕获或释放时打印消息
        rootVisualElement.RegisterCallback<MouseCaptureEvent>((evt) =>
        {
            Debug.Log("Mouse captured");
        });
        rootVisualElement.RegisterCallback<MouseCaptureOutEvent>((evt) =>
        {
            Debug.Log("Mouse captured released");
        });
    }
}

事件参考

更改事件

手册