Depth Mask Hero
鎖屏景深主視覺：去背主體局部遮擋大字標題，捲動時主體、標題與背景以不同速率分離產生真實深度。
載入預覽⋯
Playground
即時調整 props、程式碼片段同步更新——直接試出你要的樣子再複製。
1
20
<DepthMaskHero />
安裝
npx shadcn@latest add https://webberui.com/r/depth-mask-hero.json或在 components.json 設定 registries 後，改用 @webberui/depth-mask-hero 安裝。
安裝依賴後，從 registry JSON（/r/depth-mask-hero.json 的 files[0].content）複製 depth-mask-hero.tsx 原始碼到你的 components/ui/ 目錄：
npm install motion clsx tailwind-merge使用
import { DepthMaskHero } from "@/components/ui/depth-mask-hero";
<DepthMaskHero
title="OUTSIDE"
kicker="夏季特輯"
date="7月13日 週一"
time="9:41"
subject="/people/hiker.png"
subjectAlt="登山者"
>
<section className="px-6 py-16">內文從這裡開始…</section>
</DepthMaskHero>未提供 subject 時會渲染內建的中性色人像剪影，因此無外部素材也能直接展示遮罩構圖。主視覺以 position: sticky 吸頂，捲動穿越後才把 children 內文遞補上來；若放在巢狀 overflow 容器內捲動，記得把該容器的 ref 傳入 container。
Props
| Prop | 型別 | 預設值 | 說明 |
|---|---|---|---|
title | React.ReactNode | — | 主標題，大字級、被主體局部遮擋 |
titleAs | "h1" | "h2" | "h3" | "h1" | 主標題的語意標籤，避免與頁面標題衝突 |
kicker | React.ReactNode | — | 眉題（小標），顯示於主標題上方 |
subject | string | — | 去背主體圖 URL（建議透明 PNG） |
subjectAlt | string | — | 主體替代文字；未提供時視為裝飾 |
background | string | — | 背景圖 URL；未提供時以中性色漸層填底 |
time | React.ReactNode | — | 鎖屏時間文字，例如 "9:41" |
date | React.ReactNode | — | 鎖屏日期文字，顯示於時間上方 |
height | string | "100svh" | 主視覺面板高度（任意 CSS 長度） |
scrollDistance | string | "80vh" | 深度分離所需的額外捲動距離 |
stickyTop | number | 0 | 面板吸頂位置（px） |
depth | number | 1 | 各層深度分離的位移倍率，越大分層越明顯 |
pointerParallax | boolean | true | 是否啟用滑鼠視差 |
parallaxStrength | number | 20 | 滑鼠視差的最大位移量（px） |
springConfig | SpringOptions | { stiffness: 140, damping: 20, mass: 0.4 } | 視差回彈的 spring 參數 |
container | React.RefObject<HTMLElement | null> | — | 巢狀捲動容器的 ref；預設以視窗為捲動容器 |
children | React.ReactNode | — | 捲動穿越主視覺後顯露的內文 |
heroClassName | string | — | 套用在主視覺面板上的 class |
titleClassName | string | — | 套用在主標題上的 class |
細節
- 三層深度分離：背景（
z-0）位移最小且與游標反向，標題（z-10）居中，去背主體（z-20）位移最大且與游標同向；捲動時三層以不同速率移動，速率差即是深度。 - 深度遮罩：主體為去背圖（透明 PNG）時，透明區自然露出後方標題、不透明區把標題遮住，形成鎖屏般的「文字繞到主體之後」效果，無需額外的 mask 資源。
- 鎖屏細節：
time與date以鎖屏樣式置頂顯示，並隨捲動先行淡出。 - 容器查詢排版：面板以
container-type: size建立容器脈絡，標題與細節皆採cqw單位，能在任意面板尺寸下等比縮放。 - 計時器／監聽清理：滑鼠視差以
motion的MotionValue與useSpring驅動，捲動進度以useScroll綁定；事件僅在pointermove/pointerleave上註冊，卸載時由 React 自動移除。
可及性
- 使用者系統開啟「減少動態效果」時，停用捲動視差與滑鼠視差，主視覺以靜態層疊呈現，版面結構不變。
- 主標題以真實的標題標籤（
titleAs）輸出，預設h1；置於已有主標的頁面時可下修為h2/h3。 - 主體圖提供
subjectAlt時作為有意義影像朗讀，未提供時以aria-hidden視為純裝飾。 - 背景、暈影、鎖屏時間等純視覺層皆標記
aria-hidden，不干擾輔助科技的閱讀順序。