Contact Sheet Gallery

攝影印樣版式的網格畫廊，齒孔膠片邊框、格號俱全，hover 以油性筆圈選，選中格放大為工作樣張並附手寫批註。

載入預覽⋯

Playground

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

每列格數columns

底片邊緣印字filmLabel

油性筆記號顏色markColor

進場每格間隔（秒）stagger

0.05

<ContactSheetGallery />

安裝

npx shadcn@latest add https://webberui.com/r/contact-sheet-gallery.json

或在 components.json 設定 registries 後，改用 @webberui/contact-sheet-gallery 安裝。

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

npm install motion clsx tailwind-merge lucide-react

使用

import {
  ContactSheetGallery,
  ContactSheetFrame,
} from "@/components/ui/contact-sheet-gallery";

<ContactSheetGallery columns={4} filmLabel="WEBBER 400TX">
  <ContactSheetFrame id="a" annotation="選這張 ✓">
    <img src="/photos/a.jpg" alt="街景" />
  </ContactSheetFrame>
  <ContactSheetFrame id="b">
    <img src="/photos/b.jpg" alt="人像" />
  </ContactSheetFrame>
</ContactSheetGallery>;

格內可放 <img>、漸層 div 或任意節點；<img> 會自動 object-cover 填滿格框。點擊格框即放大為工作樣張，點背景、按關閉鈕或 Esc 皆可收合。

受控選片

以 selectedId / onSelectChange 接管選中狀態，即可從外部同步或程式化開合工作樣張：

const [selected, setSelected] = React.useState<string | null>(null);

<ContactSheetGallery selectedId={selected} onSelectChange={setSelected}>
  {/* ...ContactSheetFrame */}
</ContactSheetGallery>;

Props

ContactSheetGallery

Prop	型別	預設值	說明
`children`	`ReactNode`	—	放入 `ContactSheetFrame` 子元件
`columns`	`number`	`4`	每列格數
`selectedId`	`string \| null`	—	受控的選中格 id（`null` 為未選）
`defaultSelectedId`	`string \| null`	`null`	非受控模式的初始選中格
`onSelectChange`	`(id: string \| null) => void`	—	選中格變更時觸發（含關閉時的 `null`）
`filmLabel`	`string`	`"WEBBER 400"`	印在下緣的底片邊緣印字
`markColor`	`string`	`"#e2482f"`	油性筆記號顏色
`stagger`	`number`	`0.05`	格框進場的每格間隔（秒）

ContactSheetFrame

Prop	型別	預設值	說明
`id`	`string`	—	唯一識別 key
`frameNumber`	`string \| number`	自動	格號，未指定時依位置編號，可傳 `"24A"`
`annotation`	`ReactNode`	—	放大時顯示的手寫式批註
`label`	`string`	`第 N 格`	輔助科技用的格框說明
`children`	`ReactNode`	—	格內影像內容

細節

膠片版式：齒孔邊條以 SVG pattern 平鋪，寬度自適應、與格數無關；下緣印上片種標記與方向箭頭。
油性筆圈選：hover 或鍵盤 focus 時，以 SVG pathLength 一筆描出蠟筆橢圓，記號採 non-scaling-stroke，貼合任意比例格框而線寬恆定。
工作樣張：點選以共享 layoutId 將格框放大為工作樣張，影像自原格「抽出」、原位留下空片格；批註以手寫體淡入並描出底線。
顏色一律走中性色階，唯一強調色為 markColor，可依專案調整。

可及性

每個格框是原生 <button>，支援 Enter / Space 選片，並帶 aria-pressed 與 aria-label（預設「第 N 格」）。
工作樣張為 role="dialog" + aria-modal，開啟時自動聚焦關閉鈕，關閉後把焦點還給原格框；Esc、點背景、關閉鈕皆可收合。
使用者系統開啟「減少動態效果」時，停用進場、圈選描繪與放大位移，直接切換靜態版面。

Contact Sheet Gallery

On this page