Version: 2023.2
事件参考
更改事件

捕获事件

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

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

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

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

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

行为

鼠标捕获

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

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

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

指针捕获

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

事件列表

MouseCaptureEvent

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

target:接受捕获的元素。

MouseCaptureOutEvent

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

target:失去捕获的元素。

PointerCaptureEvent

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

target:接受捕获的元素。

PointerCaptureOutEvent

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

target:失去捕获的元素。

示例

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

要查看示例运行效果,请执行以下操作:

  1. Assets > Scripts > Editor 下,创建一个新的 C# 文件,名为 CaptureEventsTestWindow.cs
  2. 将该示例复制到 C# 脚本。
  3. 从编辑器工具栏中,选择 Window > UI Toolkit > Capture Events Test Window
  4. 单击对话窗口中的各个标签,并观察控制台的输出。
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");
        });
    }
}
事件参考
更改事件