ClickerExtensions

概述（Overview）

ClickerExtensions 是一个专注于 Unity 中交互事件（点击、指针事件） 的静态扩展方法集合，位于 PFGameFramework.Library 命名空间。

主要功能包括：

• 2D UI（使用 EventTrigger）与 3D 物体交互事件的绑定
• 同步添加事件监听（Action / UnityAction）
• 异步等待点击事件（UniTask + CancellationToken 支持）
• 自动点击模拟（用于自动化测试、教学跳过、演示模式）
• 基于射线检测的 3D 物体点击判断
• 鼠标拖拽、滚轮缩放等常用交互辅助方法

适用于交互教学、实验步骤引导、自动化测试、物体拖拽等场景。 注意：部分方法依赖 EventTrigger + PhysicsRaycaster（3D）或 Canvas 下的 UI 事件系统。

---

方法一览（API Index）

方法名	目标类型	异步	返回类型	主要功能	典型用途
OnEventTriggerAddListener	GameObject / Component	否	void	添加 EventTrigger 监听（支持 Action / UniTask）	快速绑定指针事件
OnClickAsync3D	GameObject	是	UniTask	异步等待 3D 物体被点击（EventTrigger 版）	步骤等待 3D 交互
OnClickAsync3D1	GameObject	是	UniTask	异步等待 3D 物体被点击（射线检测轮询版）	更可靠的 3D 点击等待（无 EventTrigger）
OnClickAsync2D	Component (UI)	是	UniTask	异步等待 2D UI 被点击	等待按钮/图片点击
OnAutoClickAsync2D	Component (UI)	是	UniTask	支持自动模拟点击的 2D 等待	教学/演示自动跳过
OnAutoClickAsync3D	GameObject	是	UniTask	支持自动模拟点击的 3D 等待	教学/演示自动跳过 3D 对象
AddListener (EventTrigger)	EventTrigger	否	void	简洁添加 EventTrigger 事件	链式调用
AddListener (Button)	Button	否	void	简洁添加 Button onClick 监听	快速绑定按钮
OnPointerClick/Enter/ExitAddListener	Button	否	void	为 Button 添加特定指针事件	增强按钮交互（悬停、离开等）
Clicked3dObjectAsync	—	是	UniTask	异步等待任意 3D 物体被点击并返回对象	自由点击选择物体
DragObjectViaMouse	GameObject	否	void	3D 物体跟随鼠标拖拽	简单拖拽交互
Drag2dObjectViaMouse	GameObject	否	void	2D 物体跟随鼠标位置（屏幕空间）	UI 拖拽或指示器
PushPullObjectViaMouseScroll	GameObject	否	void	鼠标滚轮推拉物体距离	物体放大/缩小观察

---

方法详情

异步点击等待（推荐使用）

OnClickAsync3D（推荐 EventTrigger 版）

/// <summary>
/// 异步等待 3D 物体被点击（PointerClick），支持自动模拟点击
/// 需要相机上有 PhysicsRaycaster 组件
/// </summary>
public static async UniTask OnClickAsync3D(this GameObject obj, CancellationToken ctk)

特点：

• 自动添加 BoxCollider 和 EventTrigger
• 支持 AutoClickManager.EnableAutoClick 自动跳过
• 事件监听在完成后自动移除

OnClickAsync3D1（射线检测版）

/// <summary>
/// 异步等待 3D 物体被点击（纯射线检测轮询，不依赖 EventTrigger）
/// 更可靠，但每帧有少量开销
/// </summary>
public static async UniTask OnClickAsync3D1(this GameObject obj, CancellationToken ctk)

适用场景：EventTrigger 方案失效或不想添加组件时。

OnClickAsync2D

/// <summary>
/// 异步等待 2D UI 组件被点击（PointerClick）
/// 支持自动模拟点击
/// </summary>
public static async UniTask OnClickAsync2D<T>(this T component, CancellationToken ctk)
    where T : Component

典型用法：

await myButton.OnClickAsync2D(cts.Token);
Debug.Log("按钮被点击！");

---

自动点击支持

OnAutoClickAsync2D / OnAutoClickAsync3D

/// <summary>
/// 支持自动模拟点击的 2D/3D 等待
/// 通过 GlobalManager.AutoComplete 控制
/// </summary>
public static async UniTask OnAutoClickAsync2D<T>(this T button, CancellationToken token, float delay = 1)

用途：教学模式、演示录制、跳过手动操作。

---

事件绑定（同步）

OnEventTriggerAddListener（多重载）

// 绑定异步方法
public static void OnEventTriggerAddListener(this GameObject obj, Func<UniTask> function, EventTriggerType eventType = EventTriggerType.PointerClick)

// 绑定同步方法
public static void OnEventTriggerAddListener(this GameObject obj, Action fn, EventTriggerType eventType = EventTriggerType.PointerClick)

// 泛型组件版本
public static void OnEventTriggerAddListener<T>(this T component, Action<PointerEventData> onClickAction, EventTriggerType eventType = EventTriggerType.PointerClick)
    where T : Component

---

指针事件快捷绑定（Button 专用）

public static void OnPointerClickAddListener(this Button button, Action action)
public static void OnPointerEnterAddListener(this Button button, Action action)
public static void OnPointerExitAddListener(this Button button, Action action)

支持异步 lambda：

button.OnPointerEnterAddListener(async () => {
    await UniTask.Delay(300);
    Debug.Log("悬停后延迟显示");
});

---

3D 物体点击检测（不等待特定对象）

/// <summary>
/// 异步等待任意 3D 物体被点击（有 MeshRenderer），返回被点击的对象
/// </summary>
public static async UniTask<GameObject> Clicked3dObjectAsync(Camera camera)

同步版本：

public static GameObject Clicked3dObject(Camera camera)

---

拖拽与交互辅助

// 3D 物体跟随鼠标拖拽（保持与相机距离）
public static void DragObjectViaMouse(GameObject obj)
public static void DragObjectViaMouse(GameObject obj, float distance)

// 2D 物体直接跟随鼠标屏幕坐标
public static void Drag2dObjectViaMouse(this GameObject obj)

// 鼠标滚轮推拉物体
public static void PushPullObjectViaMouseScroll(GameObject obj)

推荐：在 OnDrag 或 Update 中调用实现拖拽功能。

---