鼠标事件

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

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

所有鼠标事件的基类是 MouseEventBase。

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

独特的属性

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

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

pressedButtons：pressedButton 属性返回一个整数，用于标识当前按下的鼠标键组合。

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

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

modifiers：modifiers 属性返回在键盘事件期间按下的修改键。修改键的一些示例是 Shift、Ctrl 或 Alt 键。

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

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

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

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

事件列表

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

MouseDownEvent

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

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

MouseUpEvent

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

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

MouseMoveEvent

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

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

WheelEvent

按下鼠标滚轮时发送 WheelEvent。

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

MouseEnterWindowEvent

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

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

MouseLeaveWindowEvent

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

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

MouseEnterEvent

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

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

MouseLeaveEvent

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

target：鼠标光标退出的视觉元素（或其后代之一）。

MouseOverEvent

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

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

MouseOutEvent

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

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

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

ContextualMenuPopulateEvent

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

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

ContextClickEvent（已弃用）

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

示例

编辑器窗口示例

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

此代码示例重点演示 MouseDownEvent 和 MouseEnterEvent 的事件触发，以及如何使用事件参数。

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

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}");
    }
}