fix(tutorial): complete click targets from UI events

CHANGELOG.md

@@ -1,10 +1,15 @@
 # Changelog
 
-## 0.1.1
+## 0.1.4
 
-- 声明 `JsonUtility` 所需的 Unity JSON Serialize 模块，使包可在最小消费者项目中独立解析与编译。
+- `ClickTarget` 对 UI Button 和显式 `ShrinkTutorialAnchor` 改为点击事件驱动，不再依赖轮询鼠标按下、抬起的帧时序；非 UI 目标保留原有指针检测。
 
-## Unreleased
+## 0.1.3
+
+- 修复 `ClickTarget` 在目标按钮点击后立即打开、关闭或替换 UI 时误判未命中的问题；现在按下时确认原目标，松开时按按下时的目标区域完成步骤。
+- 支持在场景中显式绑定教程 Canvas、遮罩和提示框，并可关闭运行时 UI 生成。
+
+## 0.1.2
 
 - 修复 `ClickTarget` 对 UI 目标过早在按下阶段完成的问题，改为等待指针释放并确认 EventSystem 射线真实命中目标后再过步。
 - 修复隐藏中的 `Path` 目标仍被教程当作可用目标的问题；现在 inactive 目标会继续等待，不会把提示框提前挂到尚未显示的控件上。
@@ -12,6 +17,10 @@
 - 修复教程结束或 `maskShape=None` 步骤下遮罩仍继续绘制/拦截的问题；现在无高亮时蒙版会完全隐藏。
 - 修复 `ShrinkTutorialSample` 在前一次演示完成后下次 Play 不再显示教程的问题；样例现在会在启动时清掉自身教程进度再重新播放。
 
+## 0.1.1
+
+- 声明 `JsonUtility` 所需的 Unity JSON Serialize 模块，使包可在最小消费者项目中独立解析与编译。
+
 ## 0.1.0
 
 - 初始版本。

README.md

@@ -67,6 +67,11 @@ Assets/Modules/ShrinkTutorial/
 ShrinkTutorialManager.Instance.StartTutorial("tut.inventory.open");
 ```
 
+如果项目要求所有 UI 预先存在于场景，可在 `ShrinkTutorialManager` 上显式绑定
+`Canvas Override`、`Mask Override` 与 `Dialog Override`，并关闭
+`Allow Runtime Ui Fallback`。`ShrinkTutorialDialog` 的内容文本、箭头与跳过按钮也要
+在场景中序列化绑定；该模式不会在运行时创建教程 UI。
+
 也可以给入口物体挂 `ShrinkTutorialTrigger`，在 `OnEnable` 首次可见时自动触发。
 
 ### 4. 动态对象锚点

Runtime/Core/ShrinkTutorialManager.cs

@@ -15,6 +15,12 @@ namespace ShrinkTutorial
 
         [SerializeField] private ShrinkTutorialSettings settingsOverride;
 
+        [Header("Explicit scene UI")]
+        [SerializeField] private Canvas canvasOverride;
+        [SerializeField] private ShrinkTutorialMask maskOverride;
+        [SerializeField] private ShrinkTutorialDialog dialogOverride;
+        [SerializeField] private bool allowRuntimeUiFallback = true;
+
         private readonly List<string> _pendingTutorialIds = new();
         private readonly HashSet<string> _completedTutorials = new();
         private readonly HashSet<string> _skippedTutorials = new();
@@ -32,6 +38,13 @@ namespace ShrinkTutorial
         private bool _skipRequested;
         private bool _stepCompleted;
         private bool _stepCompletionQueued;
+        private bool _clickTargetArmed;
+        private Rect _clickTargetArmedRect;
+        private ShrinkTutorialMaskShape _clickTargetArmedShape;
+        private int _clickTargetArmedFrame;
+        private bool _clickTargetArmedWithTouch;
+        private Button _clickTargetButton;
+        private ShrinkTutorialAnchor _clickTargetAnchor;
         private float _stepAutoTimer;
         private string _receivedCustomEvent = string.Empty;
 
@@ -202,6 +215,8 @@ namespace ShrinkTutorial
                 _skipRequested = false;
                 _stepCompleted = false;
                 _stepCompletionQueued = false;
+                _clickTargetArmed = false;
+                UnbindClickTargetEvents();
                 _stepAutoTimer = tutorial.steps[stepIndex].autoDelay;
                 _receivedCustomEvent = string.Empty;
 
@@ -225,6 +240,8 @@ namespace ShrinkTutorial
                 if (targetTransform)
                     LogDebug($"Resolved target for step {stepIndex}: {GetTransformPath(targetTransform)}");
 
+                BindClickTargetEvents(step, targetTransform);
+
                 EmitSignal(step.enterSignal);
                 _dialog.SetSkipVisible(ResolveSettings().showSkipButton);
 
@@ -237,6 +254,7 @@ namespace ShrinkTutorial
                     yield return null;
                 }
 
+                UnbindClickTargetEvents();
                 EmitSignal(step.exitSignal);
                 _dialog.Hide();
 
@@ -298,16 +316,7 @@ namespace ShrinkTutorial
                     }
                     break;
                 case ShrinkTutorialCompleteCondition.ClickTarget:
-                    if (targetTransform &&
-                        ShrinkTutorialTargetUtility.TryBuildScreenRect(targetTransform, out var targetRect) &&
-                        WasPrimaryPointerReleased(targetRect, step.maskShape, out var screenPosition) &&
-                        WasPointerReleaseRoutedToTarget(targetTransform, screenPosition))
-                    {
-                        LogDebug(
-                            $"ClickTarget candidate accepted, tutorial={_currentTutorial?.tutorialId}, step={_currentStepIndex}, " +
-                            $"pointer={screenPosition}, target={GetTransformPath(targetTransform)}");
-                        QueueStepCompletion();
-                    }
+                    TickClickTargetCompletion(step, targetTransform);
                     break;
                 case ShrinkTutorialCompleteCondition.CustomEvent:
                 case ShrinkTutorialCompleteCondition.DragToTarget:
@@ -359,24 +368,131 @@ namespace ShrinkTutorial
             return pressed && !_dialog.ContainsScreenPoint(screenPosition);
         }
 
-        private bool WasPrimaryPointerReleased(Rect targetRect, ShrinkTutorialMaskShape maskShape, out Vector2 screenPosition)
+        private void TickClickTargetCompletion(ShrinkTutorialStep step, Transform targetTransform)
         {
-            if (!TryGetPointerUpPosition(out screenPosition))
-                return false;
+            if (_clickTargetButton || _clickTargetAnchor)
+                return;
 
-            if (_dialog.ContainsScreenPoint(screenPosition))
+            if (!_clickTargetArmed &&
+                targetTransform &&
+                ShrinkTutorialTargetUtility.TryBuildScreenRect(targetTransform, out var targetRect) &&
+                TryGetPointerDownPosition(out var pointerDownPosition))
             {
-                LogDebug($"Pointer release ignored because it hit dialog, pointer={screenPosition}");
-                return false;
+                if (_dialog.ContainsScreenPoint(pointerDownPosition))
+                {
+                    LogDebug($"Pointer down ignored because it hit dialog, pointer={pointerDownPosition}");
+                }
+                else if (!IsPointInsideTarget(targetRect, step.maskShape, pointerDownPosition))
+                {
+                    LogDebug($"Pointer down outside target, pointer={pointerDownPosition}, rect={targetRect}");
+                }
+                else if (WasPointerRoutedToTarget(targetTransform, pointerDownPosition))
+                {
+                    _clickTargetArmed = true;
+                    _clickTargetArmedRect = targetRect;
+                    _clickTargetArmedShape = step.maskShape;
+                    _clickTargetArmedFrame = Time.frameCount;
+                    _clickTargetArmedWithTouch = Input.touchCount > 0;
+                    LogDebug(
+                        $"ClickTarget armed, tutorial={_currentTutorial?.tutorialId}, step={_currentStepIndex}, " +
+                        $"pointer={pointerDownPosition}, target={GetTransformPath(targetTransform)}");
+                }
             }
 
-            var insideTarget = maskShape == ShrinkTutorialMaskShape.Circle
+            if (!_clickTargetArmed)
+                return;
+
+            if (!TryGetPointerUpPosition(out var pointerUpPosition))
+            {
+                if (_clickTargetArmedWithTouch ||
+                    Time.frameCount <= _clickTargetArmedFrame ||
+                    Input.GetMouseButton(0))
+                {
+                    return;
+                }
+
+                pointerUpPosition = Input.mousePosition;
+            }
+
+            var armedRect = _clickTargetArmedRect;
+            var armedShape = _clickTargetArmedShape;
+            _clickTargetArmed = false;
+
+            if (_dialog.ContainsScreenPoint(pointerUpPosition))
+            {
+                LogDebug($"Pointer release ignored because it hit dialog, pointer={pointerUpPosition}");
+                return;
+            }
+
+            if (!IsPointInsideTarget(armedRect, armedShape, pointerUpPosition))
+            {
+                LogDebug($"Pointer release outside armed target, pointer={pointerUpPosition}, rect={armedRect}");
+                return;
+            }
+
+            LogDebug(
+                $"ClickTarget candidate accepted, tutorial={_currentTutorial?.tutorialId}, step={_currentStepIndex}, " +
+                $"pointer={pointerUpPosition}, target={GetTransformPath(targetTransform)}");
+            QueueStepCompletion();
+        }
+
+        private void BindClickTargetEvents(ShrinkTutorialStep step, Transform targetTransform)
+        {
+            if (step.completeCondition != ShrinkTutorialCompleteCondition.ClickTarget || !targetTransform)
+                return;
+
+            _clickTargetButton = targetTransform.GetComponent<Button>() ??
+                                 targetTransform.GetComponentInParent<Button>() ??
+                                 targetTransform.GetComponentInChildren<Button>(true);
+            if (_clickTargetButton)
+            {
+                _clickTargetButton.onClick.AddListener(HandleClickTargetEvent);
+                LogDebug($"Bound ClickTarget button event: {GetTransformPath(_clickTargetButton.transform)}");
+                return;
+            }
+
+            _clickTargetAnchor = targetTransform.GetComponent<ShrinkTutorialAnchor>() ??
+                                 targetTransform.GetComponentInParent<ShrinkTutorialAnchor>() ??
+                                 targetTransform.GetComponentInChildren<ShrinkTutorialAnchor>(true);
+            if (_clickTargetAnchor)
+            {
+                _clickTargetAnchor.Clicked += HandleClickTargetPointerEvent;
+                LogDebug($"Bound ClickTarget anchor event: {GetTransformPath(_clickTargetAnchor.transform)}");
+            }
+        }
+
+        private void HandleClickTargetEvent()
+        {
+            LogDebug($"ClickTarget button event received, tutorial={_currentTutorial?.tutorialId}, step={_currentStepIndex}");
+            QueueStepCompletion();
+        }
+
+        private void HandleClickTargetPointerEvent(PointerEventData eventData)
+        {
+            if (eventData != null && eventData.button != PointerEventData.InputButton.Left)
+                return;
+
+            LogDebug($"ClickTarget pointer event received, tutorial={_currentTutorial?.tutorialId}, step={_currentStepIndex}");
+            QueueStepCompletion();
+        }
+
+        private void UnbindClickTargetEvents()
+        {
+            if (_clickTargetButton)
+                _clickTargetButton.onClick.RemoveListener(HandleClickTargetEvent);
+
+            if (_clickTargetAnchor)
+                _clickTargetAnchor.Clicked -= HandleClickTargetPointerEvent;
+
+            _clickTargetButton = null;
+            _clickTargetAnchor = null;
+        }
+
+        private static bool IsPointInsideTarget(Rect targetRect, ShrinkTutorialMaskShape maskShape, Vector2 screenPosition)
+        {
+            return maskShape == ShrinkTutorialMaskShape.Circle
                 ? IsPointInsideCircle(targetRect, screenPosition)
                 : targetRect.Contains(screenPosition);
-            if (!insideTarget)
-                LogDebug($"Pointer release outside target, pointer={screenPosition}, rect={targetRect}");
-
-            return insideTarget;
         }
 
         private static bool IsPointInsideCircle(Rect targetRect, Vector2 screenPosition)
@@ -430,7 +546,7 @@ namespace ShrinkTutorial
             return false;
         }
 
-        private bool WasPointerReleaseRoutedToTarget(Transform targetTransform, Vector2 screenPosition)
+        private bool WasPointerRoutedToTarget(Transform targetTransform, Vector2 screenPosition)
         {
             var eventSystem = EventSystem.current;
             if (!eventSystem)
@@ -521,6 +637,8 @@ namespace ShrinkTutorial
             _currentStepIndex = -1;
             _runner = null;
             _stepCompletionQueued = false;
+            _clickTargetArmed = false;
+            UnbindClickTargetEvents();
 
             TryStartQueuedTutorial();
         }
@@ -530,6 +648,24 @@ namespace ShrinkTutorial
             if (_canvas && _mask && _dialog)
                 return;
 
+            if (canvasOverride && maskOverride && dialogOverride)
+            {
+                _canvas = canvasOverride;
+                _mask = maskOverride;
+                _dialog = dialogOverride;
+                if (!_dialog.BindExisting())
+                    throw new InvalidOperationException("ShrinkTutorial explicit dialog bindings are incomplete.");
+
+                _dialog.Hide();
+                return;
+            }
+
+            if (!allowRuntimeUiFallback)
+            {
+                throw new InvalidOperationException(
+                    "ShrinkTutorialManager requires explicit Canvas, Mask and Dialog bindings when runtime UI fallback is disabled.");
+            }
+
             var settings = ResolveSettings();
             var canvasObject = new GameObject("ShrinkTutorialCanvas", typeof(RectTransform), typeof(Canvas), typeof(CanvasScaler),
                 typeof(GraphicRaycaster));

Runtime/Trigger/ShrinkTutorialAnchor.cs

@@ -1,12 +1,20 @@
+using System;
 using UnityEngine;
+using UnityEngine.EventSystems;
 
 namespace ShrinkTutorial
 {
-    public class ShrinkTutorialAnchor : MonoBehaviour
+    public class ShrinkTutorialAnchor : MonoBehaviour, IPointerClickHandler
     {
         [SerializeField] private string anchorId = string.Empty;
 
         public string AnchorId => anchorId;
+        public event Action<PointerEventData> Clicked;
+
+        public void OnPointerClick(PointerEventData eventData)
+        {
+            Clicked?.Invoke(eventData);
+        }
 
         public void SetAnchorId(string value)
         {

Runtime/UI/ShrinkTutorialDialog.cs

@@ -7,12 +7,30 @@ namespace ShrinkTutorial
 {
     public class ShrinkTutorialDialog : MonoBehaviour
     {
-        private RectTransform _rectTransform;
-        private RectTransform _arrowRectTransform;
-        private TextMeshProUGUI _contentText;
-        private GameObject _skipButtonObject;
+        [Header("Explicit scene bindings")]
+        [SerializeField] private RectTransform _rectTransform;
+        [SerializeField] private RectTransform _arrowRectTransform;
+        [SerializeField] private TextMeshProUGUI _contentText;
+        [SerializeField] private GameObject _skipButtonObject;
         private Action _skipAction;
 
+        /// <summary>
+        /// Uses UI objects that already exist in the scene. This path intentionally does not
+        /// create children or add listeners at runtime; scene-authored persistent callbacks
+        /// remain the source of truth.
+        /// </summary>
+        public bool BindExisting()
+        {
+            if (!_rectTransform)
+                _rectTransform = GetComponent<RectTransform>();
+
+            if (_rectTransform && _arrowRectTransform && _contentText)
+                return true;
+
+            Debug.LogError("[ShrinkTutorial] Explicit dialog bindings are incomplete.", this);
+            return false;
+        }
+
         public void Initialize(Transform parent, Action skipAction)
         {
             _skipAction = skipAction;

package.json

@@ -1,6 +1,6 @@
 {
   "name": "com.cneicy.shrink-tutorial",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "displayName": "ShrinkTutorial",
   "description": "面向 Unity 的互动式新手引导系统，提供数据驱动教程、遮罩挖洞、动态锚点、步骤条件与运行时调度。",
   "unity": "2022.3",