Atlas Plate

圖鑑式滾動導讀：一側釘住滿幅圖版，另一側為編號說明；滾動至某條說明時鏡頭平移縮放至對應熱點並點亮編號引線。

載入預覽⋯

Playground

即時調整 props、程式碼片段同步更新——直接試出你要的樣子再複製。

放大倍率zoom

2.2

圖框長寬比aspectRatio

釘住間距offsetTop

<AtlasPlate />

安裝

npx shadcn@latest add https://webberui.com/r/atlas-plate.json

或在 components.json 設定 registries 後，改用 @webberui/atlas-plate 安裝。

安裝依賴後，從 registry JSON（/r/atlas-plate.json 的 files[0].content）複製 atlas-plate.tsx 原始碼到你的 components/ui/ 目錄：

npm install motion clsx tailwind-merge

使用

AtlasPlate 接收一幅 figure（<img>、SVG 或任意節點）作為滿幅圖版，並以一組 AtlasEntry 子元件作為編號說明。每條說明用 x / y（0–100 的百分比）宣告自己在圖版上的熱點；滾動到該說明時，鏡頭會平移縮放到那個熱點，對應的編號引線同時點亮。

import { AtlasPlate, AtlasEntry } from "@/components/ui/atlas-plate";

<AtlasPlate figure={<img src="/plate.jpg" alt="" className="h-full w-full object-cover" />}>
  <AtlasEntry x={50} y={14} dir="up" title="花冠">
    六枚放射狀花瓣構成的輪生結構。
  </AtlasEntry>
  <AtlasEntry x={26} y={42} dir="left" title="葉片" zoom={2.6}>
    單葉互生，葉脈自基部呈羽狀分岐。
  </AtlasEntry>
  <AtlasEntry x={50} y={90} dir="down" title="根系">
    主根向下延伸並分岐出鬚根。
  </AtlasEntry>
</AtlasPlate>

若圖版與說明放在頁面內的巢狀捲動容器（overflow-y-auto）中，請把該容器的 ref 傳給 container，鏡頭的焦點偵測與釘住定位才會以它為基準。

Props

AtlasPlate

Prop	型別	預設值	說明
`figure`	`React.ReactNode`	預設佔位圖	滿幅圖版視覺，隨鏡頭平移縮放
`children`	`React.ReactNode`	—	一組 `AtlasEntry`，順序即編號順序
`zoom`	`number`	`2.2`	聚焦熱點時的預設放大倍率
`aspectRatio`	`number`	`1`	圖框長寬比（寬 / 高）
`offsetTop`	`number`	`16`	圖版釘住時距容器頂端的距離（px）
`container`	`RefObject<HTMLElement \| null>`	視窗	巢狀捲動容器的 ref
`plateLabel`	`string`	`"圖鑑圖版"`	圖框的無障礙標籤
`listLabel`	`string`	`"圖鑑說明清單"`	說明清單的無障礙標籤
`className`	`string`	—	套用在最外層 grid 上
`figureClassName`	`string`	—	套用在圖框上
`listClassName`	`string`	—	套用在說明清單 `<ol>` 上

AtlasEntry

Prop	型別	預設值	說明
`x`	`number`	—	熱點水平位置（0–100，百分比）
`y`	`number`	—	熱點垂直位置（0–100，百分比）
`title`	`React.ReactNode`	—	說明標題，同時顯示於圖框焦點題名
`zoom`	`number`	繼承 `AtlasPlate`	覆寫此條聚焦時的放大倍率
`dir`	`"auto" \| "up" \| "down" \| "left" \| "right"`	`"auto"`	編號引線指向；`auto` 依象限朝外側頁緣
`id`	`string`	—	說明列的錨點 id
`children`	`React.ReactNode`	—	說明內文

細節

鏡頭運鏡以 CSS transform（translate + scale）折衷實現，將焦點熱點平移縮放至圖框中央，無需 WebGL。
圖版上的熱點標記會反向縮放（1 / scale），使圓點、引線與編號徽章不論鏡頭放大到幾倍都維持固定的螢幕尺寸。
焦點以 IntersectionObserver 取各說明列的可見比例，最高者即為當前焦點；圖框以 sticky 釘住，長清單在一旁捲動。

可及性

使用者系統開啟「減少動態效果」時，保留雙欄版面與焦點高亮，僅停用鏡頭的平移縮放與過渡動畫。
每條說明的編號是原生按鈕，可鍵盤聚焦、Enter 觸發，將該說明捲動至焦點位置；聚焦中的說明以 aria-current 標記。
圖版上的裝飾性標記對輔助科技隱藏（aria-hidden），編號與內容資訊由說明清單承載。

On this page