From 291d72565fcf9cdc0eb501bdfe2d57495a107de9 Mon Sep 17 00:00:00 2001 From: wizardchen Date: Wed, 3 Jun 2026 13:27:22 +0800 Subject: [PATCH] feat(NewUserGuide): enhance guide component with improved backdrop and hole calculation - Added a new visual element for the guide's highlight area, improving user interaction. - Refactored hole calculation logic to ensure consistent spacing around highlighted elements. - Introduced a new computed property for dynamic styling of the highlight area. - Updated styles for backdrop elements to enhance visual clarity and interaction. - Improved accessibility by ensuring the guide's interactive elements are properly defined. --- frontend/src/components/NewUserGuide.vue | 109 ++++++++++++++++++++--- 1 file changed, 98 insertions(+), 11 deletions(-) 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);