当您使用鼠标与 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。
target
:接收鼠标捕获的视觉元素。否则是光标下最上层的可选元素。
当光标位于视觉元素内时释放鼠标键时触发 MouseUpEvent。MouseUpEvent
是 MouseDownEvent
的互补事件。
target
:接收鼠标捕获的视觉元素。否则是光标下最上层的可选元素。
当光标热点在视觉元素内移动时发送 MouseMoveEvent。
target
:接收鼠标捕获的视觉元素。否则是光标下最上层的可选元素。
按下鼠标滚轮时发送 WheelEvent。
target
:接收鼠标捕获的视觉元素。否则是光标下最上层的可选元素。
当光标移动到编辑器窗口时触发 MouseEnterWindowEvent。当您进入 Game 视图窗口时,运行时面板不会收到此事件。
target
:接收鼠标捕获的视觉元素。否则是光标下最上层的可选元素。
当光标退出编辑器窗口的空间时触发 MouseLeaveWindowEvent。MouseLeaveWindowEvent
与 MouseEnterWindowEvent
相对应。
target
:接收鼠标捕获的视觉元素。否则它返回 null,因为光标不在元素上。
当光标移动到视觉元素或其后代之一时发送 MouseEnterEvent。
target
:鼠标光标下的视觉元素或其后代之一。
当光标移动到视觉元素之外时触发 MouseLeaveEvent。此事件与 MouseOutEvent
的不同之处在于,此事件将发送到鼠标退出的每个元素。此事件不会传播。
target
:鼠标光标退出的视觉元素(或其后代之一)。
当光标进入一个元素时发送 MouseOverEvent。此事件与 MouseEnterEvent
不同,因为此事件仅发送到鼠标进入的元素。
target
:位于鼠标光标下的视觉元素。
当指针设备将光标移动到视觉元素的边界之外时触发 MouseOutEvent。
MouseOutEvent
与 MouseLeaveEvent
的不同之处在于 MouseOutEvent
在离开视觉元素到任何其他元素时发送,而 MouseLeaveEvent
在从视觉元素转换到后代元素时不发送。
target
:鼠标光标退出的视觉元素。
当需要使用菜单项填充上下文菜单时由 ContextualMenuManager
发送的事件。
target
:要构建上下文菜单的视觉元素。
用户按下并松开第三个鼠标键时发送的事件。此事件仅用于向后兼容 IMGUI。
下面的代码示例创建一个带有三个按钮的编辑器窗口,当鼠标移到一个元素上或按下鼠标上的按键时,将消息打印到控制台。
此代码示例重点演示 MouseDownEvent
和 MouseEnterEvent
的事件触发,以及如何使用事件参数。
要查看示例运行效果,请执行以下操作:
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}");
}
}