Version: 2023.1
键盘事件
Navigation events

鼠标事件

当您使用鼠标与 UI 交互时会发生鼠标事件。触控、笔或其他指针设备会生成其他事件,而不是鼠标事件。 在鼠标事件 API 和本文档中,术语“鼠标”仅指物理鼠标或模拟物理鼠标的虚拟鼠标。

鼠标事件总是以相应的 PointerEvent 开始。

所有鼠标事件的基类是 MouseEventBase

事件 描述 涓滴 冒泡 可取消
MouseDownEvent 当用户按下鼠标键时发送。
MouseUpEvent 当用户释放鼠标键时发送。
MouseMoveEvent 当用户移动鼠标时发送。
WheelEvent 当用户激活鼠标滚轮时发送。
MouseEnterWindowEvent 当鼠标进入某个窗口时发送。
MouseLeaveWindowEvent 当鼠标离开某个窗口时发送。
MouseEnterEvent 当鼠标进入某一元素或其后代之一时发送。
MouseLeaveEvent 当鼠标离开某一元素或其后代之一时发送。
MouseOverEvent 当鼠标进入某一元素时发送。
MouseOutEvent 当鼠标离开某一元素时发送。
ContextClickEvent(已弃用) 用户按下并松开第三个鼠标键时发送。此事件用于向后兼容 IMGUI。

独特的属性

buttonbutton 属性返回一个整数,该整数标识被按下以触发事件的鼠标键。下表列出了整数和关联的鼠标键:

整数 按钮
0 左键
1 右键
2 中键

pressedButtonspressedButton 属性返回一个整数,用于标识当前按下的鼠标键组合。

该数字是单个鼠标键的整数值的总和(见下表)。例如,同时按住鼠标右键和鼠标中键将导致 pressedButton 的值为 6。

整数 按钮
1 左键
2 右键
4 中键

modifiersmodifiers 属性返回在键盘事件期间按下的修改键。修改键的一些示例是 ShiftCtrlAlt 键。

有关更多信息,请参阅 MDN 文档的“修改键”部分

mousePositionmousePosition 属性返回面板内的鼠标位置,也称为屏幕坐标系。有关面板坐标的更多信息,请参阅视觉树页面

localMousePositionlocalMousePosition 属性返回相对于目标视觉元素的坐标。

mouseDelta:上一个鼠标事件与当前鼠标事件之间指针位置的差异。

事件列表

以下列表提供了该事件系列中每个事件的名称、描述和目标。有关事件的更多信息,请参阅 UI 工具包 API

MouseDownEvent

当光标位于视觉元素内时按下鼠标键时发送 MouseDownEvent

target:接收鼠标捕获的视觉元素。否则是光标下最上层的可选元素。

MouseUpEvent

当光标位于视觉元素内时释放鼠标键时触发 MouseUpEventMouseUpEventMouseDownEvent 的互补事件。

target:接收鼠标捕获的视觉元素。否则是光标下最上层的可选元素。

MouseMoveEvent

当光标热点在视觉元素内移动时发送 MouseMoveEvent

target:接收鼠标捕获的视觉元素。否则是光标下最上层的可选元素。

WheelEvent

按下鼠标滚轮时发送 WheelEvent

target:接收鼠标捕获的视觉元素。否则是光标下最上层的可选元素。

MouseEnterWindowEvent

当光标移动到编辑器窗口时触发 MouseEnterWindowEvent。当您进入 Game 视图窗口时,运行时面板不会收到此事件。

target:接收鼠标捕获的视觉元素。否则是光标下最上层的可选元素。

MouseLeaveWindowEvent

当光标退出编辑器窗口的空间时触发 MouseLeaveWindowEventMouseLeaveWindowEventMouseEnterWindowEvent 相对应。

target:接收鼠标捕获的视觉元素。否则它返回 null,因为光标不在元素上。

MouseEnterEvent

当光标移动到视觉元素或其后代之一时发送 MouseEnterEvent

target:鼠标光标下的视觉元素或其后代之一。

MouseLeaveEvent

当光标移动到视觉元素之外时触发 MouseLeaveEvent。此事件与 MouseOutEvent 的不同之处在于,此事件将发送到鼠标退出的每个元素。此事件不会传播。

target:鼠标光标退出的视觉元素(或其后代之一)。

MouseOverEvent

当光标进入一个元素时发送 MouseOverEvent。此事件与 MouseEnterEvent 不同,因为此事件仅发送到鼠标进入的元素。

target:位于鼠标光标下的视觉元素。

MouseOutEvent

当指针设备将光标移动到视觉元素的边界之外时触发 MouseOutEvent

MouseOutEventMouseLeaveEvent 的不同之处在于 MouseOutEvent 在离开视觉元素到任何其他元素时发送,而 MouseLeaveEvent 在从视觉元素转换到后代元素时不发送。

target:鼠标光标退出的视觉元素。

ContextualMenuPopulateEvent

当需要使用菜单项填充上下文菜单时由 ContextualMenuManager 发送的事件。

target:要构建上下文菜单的视觉元素。

ContextClickEvent(已弃用)

用户按下并松开第三个鼠标键时发送的事件。此事件仅用于向后兼容 IMGUI。

示例

编辑器窗口示例

下面的代码示例创建一个带有三个按钮的编辑器窗口,当鼠标移到一个元素上或按下鼠标上的按键时,将消息打印到控制台。

此代码示例重点演示 MouseDownEventMouseEnterEvent 的事件触发,以及如何使用事件参数。

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

  1. Create a new C# script called MouseEventTestWindow.cs.
  2. 将该示例复制到 C# 脚本。
  3. Window > UI Toolkit > Mouse Event Test Window 下打开下面的示例。
using UnityEditor;
using UnityEngine;
using UnityEngine.UIElements;

// Open this in the Editor via the menu Window > UI ToolKit > Mouse Event Test Window
public class MouseEventTestWindow : EditorWindow
{
    [MenuItem("Window/UI Toolkit/Mouse Event Test Window")]
    public static void ShowExample()
    {
        MouseEventTestWindow wnd = GetWindow<MouseEventTestWindow>();
        wnd.titleContent = new GUIContent("Mouse Event Test Window");
    }
    public void CreateGUI()
    {
        // Add a few buttons
        for (int i = 0; i < 3; i++)
        {
            Button newElement = new Button { name = $"Button {i}", text = $"Button {i}" };
            newElement.style.flexGrow = 1;
            rootVisualElement.Add(newElement);
        }
        // Register mouse event callbacks
        rootVisualElement.RegisterCallback<MouseDownEvent>(OnMouseDown, TrickleDown.TrickleDown);
        rootVisualElement.RegisterCallback<MouseEnterEvent>(OnMouseEnter, TrickleDown.TrickleDown);
    }

    private void OnMouseDown(MouseDownEvent evt)
    {
        bool leftMouseButtonPressed = 0 != (evt.pressedButtons & (1 << (int)MouseButton.LeftMouse));
        bool rightMouseButtonPressed = 0 != (evt.pressedButtons & (1 << (int)MouseButton.RightMouse));
        bool middleMouseButtonPressed = 0 != (evt.pressedButtons & (1 << (int)MouseButton.MiddleMouse));
        Debug.Log($"Mouse Down event. Triggered by {(MouseButton)evt.button}.");
        Debug.Log($"Pressed buttons: Left button: {leftMouseButtonPressed} Right button: {rightMouseButtonPressed} Middle button: {middleMouseButtonPressed}");
    }

    private void OnMouseEnter(MouseEnterEvent evt)
    {
        VisualElement targetElement = (VisualElement)evt.target;
        Debug.Log($"Mouse is now over element '{targetElement.name}'");
    }
}

运行时示例

以下代码示例在按下任何鼠标键时将消息打印到控制台,显示哪个按键触发了事件,以及当前按下了哪些按键。

此代码示例重点演示了向 MouseDownEvent 注册回调以及如何使用事件参数。 要查看示例的效果,请执行以下操作:

  1. 创建一个具有有效 UIDocument 的游戏对象。
  2. Assets > Scripts 下,创建一个 C# 脚本,名为 MouseEventTestRuntime。
  3. 将该示例复制到 C# 脚本。
  4. 将 MouseEventTestRuntime 脚本附加到带有 UIDocument 的游戏对象。
  5. 进入运行模式。
  6. 将鼠标移到 Game 视图上,按下或按住鼠标上的按键。

using UnityEngine;
using UnityEngine.UIElements;

public class MouseEventTestRuntime : MonoBehaviour
{
    void Start()
    {
        var root = GetComponent<UIDocument>().rootVisualElement;
        var newLabel = new Label("Move the mouse or press buttons to see the log output");
        newLabel.style.flexGrow = 1;
        root.Add(newLabel);
        root.RegisterCallback<MouseDownEvent>(OnMouseDown, TrickleDown.TrickleDown);
    }

    private void OnMouseDown(MouseDownEvent evt)
    {
        bool leftMouseButtonPressed = 0 != (evt.pressedButtons & (1 << (int)MouseButton.LeftMouse));
        bool rightMouseButtonPressed = 0 != (evt.pressedButtons & (1 << (int)MouseButton.RightMouse));
        bool middleMouseButtonPressed = 0 != (evt.pressedButtons & (1 << (int)MouseButton.MiddleMouse));

        VisualElement targetElement = (VisualElement)evt.target;
        Debug.Log($"Mouse Down event.Triggered by {(MouseButton)evt.button} over element '{targetElement.name}'");
        Debug.Log($"Pressed buttons: Left button: {leftMouseButtonPressed} Right button: {rightMouseButtonPressed} Middle button: {middleMouseButtonPressed}");
    }
}

键盘事件
Navigation events