Version: 2023.1
面板事件
工具提示事件

指针事件

当指针设备与 UI 进行交互操作时将触发指针事件。与鼠标事件类似,指针事件提供有关所用输入设备的附加信息,例如笔压力或倾斜角度。

在 UI 工具包中,指针事件总是先于鼠标事件。

指针事件没有持久的位置。当它们从触控设备上释放时也没有固定位置。

某些指针事件(如 PointerStationaryEventPointerCancelEvent 事件)具有由输入设备的操作系统 (OS) 触发的条件。

所有指针事件的基类是 PointerEventBase

事件 描述 涓滴 冒泡 可取消
PointerDownEvent 当您按下指针时发送。
PointerUpEvent 当您松开指针时发送。
PointerMoveEvent 当指针状态变化时发送。
PointerEnterEvent 当指针进入某一视觉元素或其后代之一时发送。
PointerLeaveEvent 当指针离开某一视觉元素及其所有后代时发送。
PointerOverEvent 当指针进入某一视觉元素时发送。
PointerOutEvent 当指针离开某一视觉元素时发送。
PointerStationaryEvent 当某个指针类型(如触笔或手指)经过操作系统设定的时间量之后未发生变化时发送。
PointerCancelEvent 当操作系统取消指针操作时发送。

独特的属性

altitudeAngle:altitudeAngle 包含触控笔相对于表面的角度,以弧度为单位。值为 0 表示触笔平行于表面。值为 pi/2 表示触笔垂直于表面。

azimuthAngle:azimuthAngle 包含触笔相对于 x 轴的角度(以弧度为单位)。值为 0 表示触笔指向沿着设备 x 轴方向。

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

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

clickCount:clickCount 属性包含按键被按下的次数。

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

deltaTimedeltaTime 属性包含自上次记录指针值更改以来经过的时间(以秒为单位)。

localPositionlocalPosition 属性返回相对于目标视觉元素的指针位置。

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

当您在视觉元素内按下指针时发送 PointerDownEvent

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

PointerUpEvent

当您在视觉元素内释放指针时触发 PointerUpEvent

PointerUpEvent 事件触发时,它也会移除指针坐标。它还清除指针的缓存,因此没有指针位置的记录。

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

PointerMoveEvent

当指针改变状态时发生 PointerMoveEvent

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

PointerEnterEvent

当指针进入视觉元素或其后代之一时发送 PointerEnterEvent

target:指针退出的视觉元素(或其后代之一)。

PointerLeaveEvent

当指针离开某一视觉元素及其所有后代时发送 PointerLeaveEvent。例如,如果一个视觉元素包含一个子元素,则当指针不再位于父元素或子元素上方时,父元素将收到此事件。当指针仍在其子元素之一上方时,父元素不会收到 PointerLeaveEvent,即使它不再是指针下方的最顶层元素。实际上,它将收到 PointerOverEvent

target:指针退出的视觉元素(或其后代之一)。

PointerOverEvent

当指针进入视觉元素时发送 PointerOverEvent

target:指针下的视觉元素。

PointerOutEvent

当指针离开视觉元素时发送 PointerOutEvent

target:指针退出的视觉元素。

PointerStationaryEvent

当某个指针类型(如触笔或手指)经过操作系统设定的时间量之后未发生变化时发送 PointerStationaryEvent

target:捕获指针的视觉元素,或指针下最顶部的可选元素。

PointerCancelEvent

当操作系统取消指针操作时发送 PointerCancelEvent

target:捕获指针的视觉元素,或指针下最顶部的可选元素。

示例

以下代码示例创建一个编辑器窗口,其中含有一个包含黄色框的红色框。当指针离开视觉元素或其子元素时,它会将消息打印到控制台。它展示了 PointerOutEventPointerLeaveEvent 的行为。

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

  1. Assets > Scripts > Editor 下,创建一个新的 UXML 文件,名为 PointerEventsTestWindow.uxml
  2. 将下面的 UXML 代码复制到其中
  3. Assets > Scripts > Editor 下,创建一个新的 C# 文件,名为 PointerEventsTestWindow.cs
  4. 将代码示例复制到 C# 脚本。
  5. 从编辑器工具栏中,选择 Window > UI Toolkit > Pointer Events Test Window

UXML 代码

<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>

C# 代码


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

其他资源

面板事件
工具提示事件