diff --git a/frontend/src/components/NewUserGuide.vue b/frontend/src/components/NewUserGuide.vue
index 888f4a60..8f230f2c 100644
--- a/frontend/src/components/NewUserGuide.vue
+++ b/frontend/src/components/NewUserGuide.vue
@@ -7,7 +7,10 @@
-
+
+
+
@@ -60,7 +63,9 @@ const CARD_WIDTH = 340
const GAP = 16
const EDGE = 16
const PAD = 8
-const holeRadius = 10
+/** 与侧栏 menu_item(4px)+ 内边距协调,略大于目标圆角即可 */
+const holeRadius = 8
+const BACKDROP_COLOR = 'rgba(15, 18, 22, 0.58)'
type Placement = 'right' | 'left' | 'bottom' | 'top'
@@ -128,8 +133,64 @@ const index = ref(0)
const vw = ref(window.innerWidth)
const vh = ref(window.innerHeight)
const targetRect = ref(null)
+const targetEl = ref(null)
const cardSize = ref({ width: CARD_WIDTH, height: 220 })
+type HoleRect = { x: number; y: number; width: number; height: number }
+
+/** 目标与相邻节点之间的可用间距(不含 margin 折叠到 border 外的部分) */
+const measureNeighborGap = (el: HTMLElement, r: DOMRect) => {
+ let above = PAD
+ const prev = el.previousElementSibling
+ if (prev) {
+ above = Math.max(0, r.top - prev.getBoundingClientRect().bottom)
+ }
+
+ let below = PAD
+ const next = el.nextElementSibling
+ if (next) {
+ below = Math.max(0, next.getBoundingClientRect().top - r.bottom)
+ } else {
+ const mb = parseFloat(getComputedStyle(el).marginBottom) || 0
+ below = Math.max(0, PAD - mb)
+ }
+
+ return { above, below }
+}
+
+/**
+ * 高亮框四边留白一致:受相邻项间距限制时同步缩小;
+ * 贴边 clamp 时同步收窄宽高,避免侧栏靠左时「左贴边、右留白」。
+ */
+const computeHighlightHole = (el: HTMLElement, r: DOMRect): HoleRect => {
+ const { above, below } = measureNeighborGap(el, r)
+ const inset = Math.min(PAD, above, below)
+
+ let x = r.left - inset
+ let y = r.top - inset
+ let width = r.width + inset * 2
+ let height = r.height + inset * 2
+
+ if (x < 0) {
+ width += x
+ x = 0
+ }
+ if (y < 0) {
+ height += y
+ y = 0
+ }
+ const rightOverflow = x + width - vw.value
+ if (rightOverflow > 0) {
+ width -= rightOverflow
+ }
+ const bottomOverflow = y + height - vh.value
+ if (bottomOverflow > 0) {
+ height -= bottomOverflow
+ }
+
+ return { x, y, width, height }
+}
+
const rootRef = ref(null)
const cardRef = ref(null)
@@ -141,14 +202,10 @@ const stepTitle = computed(() => t(`newUserGuide.steps.${step.value.key}.title`)
const stepDesc = computed(() => t(`newUserGuide.steps.${step.value.key}.desc`))
const hole = computed(() => {
+ const el = targetEl.value
const r = targetRect.value
- if (!r) return null
- return {
- x: Math.max(0, r.left - PAD),
- y: Math.max(0, r.top - PAD),
- width: r.width + PAD * 2,
- height: r.height + PAD * 2,
- }
+ if (!el || !r) return null
+ return computeHighlightHole(el, r)
})
const backdropPieces = computed(() => {
@@ -168,7 +225,7 @@ const backdropPieces = computed(() => {
]
})
-const ringStyle = computed(() => {
+const holeFrameStyle = computed(() => {
if (!hole.value) return {}
return {
left: `${hole.value.x}px`,
@@ -179,6 +236,13 @@ const ringStyle = computed(() => {
}
})
+const spotStyle = computed(() => ({
+ ...holeFrameStyle.value,
+ boxShadow: `0 0 0 9999px ${BACKDROP_COLOR}`,
+}))
+
+const ringStyle = holeFrameStyle
+
const overlaps = (
a: { left: number; top: number; right: number; bottom: number },
b: { left: number; top: number; right: number; bottom: number },
@@ -256,6 +320,7 @@ const locate = async (retry = 0) => {
const cur = step.value
if (!cur.target) {
+ targetEl.value = null
targetRect.value = null
await measureCard()
return
@@ -273,12 +338,14 @@ const locate = async (retry = 0) => {
goTo(index.value + 1)
return
}
+ targetEl.value = null
targetRect.value = null
await measureCard()
return
}
el.scrollIntoView({ block: 'nearest', inline: 'nearest', behavior: 'smooth' })
+ targetEl.value = el
targetRect.value = el.getBoundingClientRect()
await measureCard()
}
@@ -326,6 +393,7 @@ const close = () => {
}
closeGuideSettings()
active.value = false
+ targetEl.value = null
targetRect.value = null
}
@@ -375,7 +443,7 @@ onBeforeUnmount(() => {
pointer-events: none;
}
-// 四块挡板拦截点击;中间的空洞没有任何元素,因此点击会穿透到下层真实控件。
+// 四块透明挡板拦截点击;中间空洞无元素,点击穿透到下层控件。
.guide__backdrop {
position: fixed;
pointer-events: auto;
@@ -389,10 +457,29 @@ onBeforeUnmount(() => {
&--full {
inset: 0;
}
+
+ &--hit {
+ background: transparent;
+ }
+}
+
+// 仅负责圆角遮罩绘制;不拦截指针(box-shadow 本身也不参与命中)。
+.guide__spot {
+ position: fixed;
+ box-sizing: border-box;
+ pointer-events: none;
+ background: transparent;
+ transition:
+ top 0.28s cubic-bezier(0.4, 0, 0.2, 1),
+ left 0.28s cubic-bezier(0.4, 0, 0.2, 1),
+ width 0.28s cubic-bezier(0.4, 0, 0.2, 1),
+ height 0.28s cubic-bezier(0.4, 0, 0.2, 1),
+ border-radius 0.28s cubic-bezier(0.4, 0, 0.2, 1);
}
.guide__ring {
position: fixed;
+ box-sizing: border-box;
pointer-events: none;
border: 2px solid var(--td-brand-color);
box-shadow: 0 0 0 4px rgba(7, 192, 95, 0.18);