当指针设备与 UI 进行交互操作时将触发指针事件。与鼠标事件类似,指针事件提供有关所用输入设备的附加信息,例如笔压力或倾斜角度。
在 UI 工具包中,指针事件总是先于鼠标事件。
指针事件没有持久的位置。当它们从触控设备上释放时也没有固定位置。
某些指针事件(如 PointerStationaryEvent
和 PointerCancelEvent
事件)具有由输入设备的操作系统 (OS) 触发的条件。
所有指针事件的基类是 PointerEventBase。
事件 | 描述 | 涓滴 | 冒泡 | 可取消 |
---|---|---|---|---|
PointerDownEvent | 当您按下指针时发送。 | 是 | 是 | 是 |
PointerUpEvent | 当您松开指针时发送。 | 是 | 是 | 是 |
PointerMoveEvent | 当指针状态变化时发送。 | 是 | 是 | 是 |
PointerEnterEvent | 当指针进入某一视觉元素或其后代之一时发送。 | 是 | 是 | |
PointerLeaveEvent | 当指针离开某一视觉元素及其所有后代时发送。 | 是 | 是 | |
PointerOverEvent | 当指针进入某一视觉元素时发送。 | 是 | 是 | 是 |
PointerOutEvent | 当指针离开某一视觉元素时发送。 | 是 | 是 | 是 |
PointerStationaryEvent | 当某个指针类型(如触笔或手指)经过操作系统设定的时间量之后未发生变化时发送。 | 是 | 是 | 是 |
PointerCancelEvent | 当操作系统取消指针操作时发送。 | 是 | 是 | 是 |
altitudeAngle
:altitudeAngle 包含触控笔相对于表面的角度,以弧度为单位。值为 0 表示触笔平行于表面。值为 pi/2 表示触笔垂直于表面。
azimuthAngle
:azimuthAngle 包含触笔相对于 x 轴的角度(以弧度为单位)。值为 0 表示触笔指向沿着设备 x 轴方向。
button
:button
属性返回一个整数,该整数标识被按下以触发事件的鼠标键。下表列出了整数和关联的鼠标键:
整数 | 按钮 |
---|---|
0 | 左键 |
1 | 右键 |
2 | 中键 |
clickCount
:clickCount 属性包含按键被按下的次数。
deltaPosition
:deltaPosition
包含上一个鼠标事件与当前鼠标事件之间指针位置的差异。
deltaTime
:deltaTime
属性包含自上次记录指针值更改以来经过的时间(以秒为单位)。
localPosition
:localPosition
属性返回相对于目标视觉元素的指针位置。
modifiers
: The modifiers property returns the modifier key currently held down. Some examples of modifiers are the Shift
, Ctrl
, or Alt
keys. For more information, see the Modifier keys section of the MDN documentation.
pointerId
:pointerId 属性返回一个整数,用于标识发送事件的指针。
pointerType
:pointerType 属性返回一个字符串,定义创建该事件的指针类型。
position
:position 属性返回屏幕或世界坐标系中的指针位置。
pressedButtons
:pressedButton 属性返回一个整数,用于标识当前按下的鼠标键组合。
该数字是单个鼠标键的整数值的总和(见下表)。例如,同时按住鼠标右键和鼠标中键将导致 pressedButton 的值为 6。
整数 | 按钮 |
---|---|
1 | 左键 |
2 | 右键 |
4 | 中键 |
pressure
:pressure 属性返回当前触控操作施加的压力。如果设备未报告压力,此属性的值将为 1.0f。
radius
:radius 属性返回触控操作的半径的估值。加上 radiusVariance 可获得最大触控半径,减去它可获得最小触控半径。
radiusVariance
:radiusVariance 属性值决定了触控半径的精度。半径加上此值可获得最大触控半径,减去它可获得最小触控半径。
tangentialPressure
:tangentialPressure 属性返回一个浮点值,表示施加到触控笔上附加压敏控件的压力。
twist
:twist 属性返回触控笔绕其轴的旋转,以弧度为单位。
以下列表提供了该事件系列中每个事件的名称、描述和目标。有关事件的更多信息,请参阅 UI 工具包 API。
当您在视觉元素内按下指针时发送 PointerDownEvent。
target
:接收指针捕获的视觉元素。否则是光标下最上层的可选元素。
当您在视觉元素内释放指针时触发 PointerUpEvent。
当 PointerUpEvent
事件触发时,它也会移除指针坐标。它还清除指针的缓存,因此没有指针位置的记录。
target
:接收指针捕获的视觉元素。否则是光标下最上层的可选元素。
当指针改变状态时发生 PointerMoveEvent。
target
:接收指针捕获的视觉元素。否则是光标下最上层的可选元素。
当指针进入视觉元素或其后代之一时发送 PointerEnterEvent。
target
:指针退出的视觉元素(或其后代之一)。
当指针离开某一视觉元素及其所有后代时发送 PointerLeaveEvent。例如,如果一个视觉元素包含一个子元素,则当指针不再位于父元素或子元素上方时,父元素将收到此事件。当指针仍在其子元素之一上方时,父元素不会收到 PointerLeaveEvent,即使它不再是指针下方的最顶层元素。实际上,它将收到 PointerOverEvent。
target
:指针退出的视觉元素(或其后代之一)。
当指针进入视觉元素时发送 PointerOverEvent。
target
:指针下的视觉元素。
当指针离开视觉元素时发送 PointerOutEvent。
target
:指针退出的视觉元素。
当某个指针类型(如触笔或手指)经过操作系统设定的时间量之后未发生变化时发送 PointerStationaryEvent。
target
:捕获指针的视觉元素,或指针下最顶部的可选元素。
当操作系统取消指针操作时发送 PointerCancelEvent。
target
:捕获指针的视觉元素,或指针下最顶部的可选元素。
以下代码示例创建一个编辑器窗口,其中含有一个包含黄色框的红色框。当指针离开视觉元素或其子元素时,它会将消息打印到控制台。它展示了 PointerOutEvent 和 PointerLeaveEvent 的行为。
要查看示例运行效果,请执行以下操作:
<ui:UXML xmlns:ui="UnityEngine.UIElements" xmlns:uie="UnityEditor.UIElements" xsi="http://www.w3.org/2001/XMLSchema-instance" engine="UnityEngine.UIElements" editor="UnityEditor.UIElements" noNamespaceSchemaLocation="../../UIElementsSchema/UIElements.xsd" editor-extension-mode="False">
<ui:VisualElement style="flex-grow: 1; justify-content: center; align-items: center;">
<ui:VisualElement name="Red_Box" style="background-color: rgb(183, 34, 46); width: 50%; height: 50%; align-items: center; justify-content: center;">
<ui:VisualElement name="Yellow_Box" style="width: 175%; height: 50%; background-color: rgb(197, 163, 0);" />
</ui:VisualElement>
</ui:VisualElement>
</ui:UXML>
using UnityEditor;
using UnityEngine;
using UnityEngine.UIElements;
using UnityEditor.UIElements;
public class PointerEventsTestWindow : EditorWindow
{
[MenuItem("Window/UI Toolkit/Pointer Events Test Window")]
public static void ShowExample()
{
PointerEventsTestWindow wnd = GetWindow<PointerEventsTestWindow>();
wnd.titleContent = new GUIContent("Pointer Events Test Window");
}
public void CreateGUI()
{
// 导入 UXML
VisualTreeAsset visualTree = AssetDatabase.LoadAssetAtPath<VisualTreeAsset>("Assets/Scripts/Editor/PointerEventsTestWindow.uxml");
visualTree.CloneTree(rootVisualElement);
// 获取红框并注册指针事件回调
VisualElement redBox = rootVisualElement.Q("Red_Box");
redBox.RegisterCallback<PointerOutEvent>(OnPointerOutEvent, TrickleDown.TrickleDown);
redBox.RegisterCallback<PointerLeaveEvent>(OnPointerLeaveEvent, TrickleDown.TrickleDown);
}
private void OnPointerLeaveEvent(PointerLeaveEvent evt)
{
Debug.Log($"Pointer LEAVE Event.Target: {(evt.target as VisualElement).name}");
}
private void OnPointerOutEvent(PointerOutEvent evt)
{
Debug.Log($"Pointer OUT Event.Target: {(evt.target as VisualElement).name}");
}
}