当您使用鼠标与 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
.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
注册回调以及如何使用事件参数。
要查看示例的效果,请执行以下操作:
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}");
}
}
Did you find this page useful? Please give it a rating:
Thanks for rating this page!
What kind of problem would you like to report?
Thanks for letting us know! This page has been marked for review based on your feedback.
If you have time, you can provide more information to help us fix the problem faster.
Provide more information
You've told us this page needs code samples. If you'd like to help us further, you could provide a code sample, or tell us about what kind of code sample you'd like to see:
You've told us there are code samples on this page which don't work. If you know how to fix it, or have something better we could use instead, please let us know:
You've told us there is information missing from this page. Please tell us more about what's missing:
You've told us there is incorrect information on this page. If you know what we should change to make it correct, please tell us:
You've told us this page has unclear or confusing information. Please tell us more about what you found unclear or confusing, or let us know how we could make it clearer:
You've told us there is a spelling or grammar error on this page. Please tell us what's wrong:
You've told us this page has a problem. Please tell us more about what's wrong:
Thank you for helping to make the Unity documentation better!
Your feedback has been submitted as a ticket for our documentation team to review.
We are not able to reply to every ticket submitted.