From d3a510eee68fc264590b2ea40c3bd019329ecf96 Mon Sep 17 00:00:00 2001
From: Ap_Tx <3045929398@qq.com>
Date: Sat, 17 Oct 2026 15:37:42 +0800
Subject: [PATCH] =?UTF-8?q?fix:=20=E5=BC=95=E5=AF=BC=E6=AD=A5=E9=AA=A4?=
 =?UTF-8?q?=E5=88=87=E6=8D=A2=E6=97=B6=E8=87=AA=E5=8A=A8=E6=BB=9A=E5=8A=A8?=
 =?UTF-8?q?=E5=88=B0=E7=9B=AE=E6=A0=87=E5=85=83=E7=B4=A0?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

新手引导进行到"更新设置"这一步时，目标按钮位于设置页左侧导航列表的
滚动区域内，可能在视口之外。此前引导只读取目标位置、不会滚动过去，
气泡指向屏幕外，玩家看不到"更新"按钮，容易反复点击版本号。

新增 ensureTargetVisible()：步骤切换后若目标不在视口内，就平滑滚动
到视口中央，滚动后刷新目标位置让气泡跟随。
---
 .../ui/onboarding/useOnboardingTour.ts        | 22 +++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/apps/app-frontend/src/components/ui/onboarding/useOnboardingTour.ts b/apps/app-frontend/src/components/ui/onboarding/useOnboardingTour.ts
index f86f69f..b76d06f 100644
--- a/apps/app-frontend/src/components/ui/onboarding/useOnboardingTour.ts
+++ b/apps/app-frontend/src/components/ui/onboarding/useOnboardingTour.ts
@@ -197,6 +197,27 @@ export function useOnboardingTour(
 		requestAnimationFrame(updateRect)
 	}
 
+	// Bring the current step target into view when the tour jumps to a step
+	// whose target lives inside a scrollable container (e.g. the settings
+	// sidebar). Without this the bubble can point at an off-screen element.
+	function ensureTargetVisible() {
+		const target = targetElement.value
+		if (!target) return
+		const rect = target.getBoundingClientRect()
+		const outOfView =
+			rect.top < 0 ||
+			rect.left < 0 ||
+			rect.bottom > window.innerHeight ||
+			rect.right > window.innerWidth
+		if (!outOfView) return
+		target.scrollIntoView({ block: 'center', inline: 'nearest', behavior: 'smooth' })
+		requestAnimationFrame(() => {
+			if (targetElement.value === target) {
+				targetRect.value = target.getBoundingClientRect()
+			}
+		})
+	}
+
 	function goTo(destination: StepDestination) {
 		if (destination === 'complete') {
 			events.complete()
@@ -343,6 +364,7 @@ export function useOnboardingTour(
 		await nextTick()
 		updateBubbleSize()
 		updateTarget()
+		ensureTargetVisible()
 	})
 
 	watch(mode, () => {