Preloader Collection
三款預載覆蓋層動畫——文字揭示、階梯滑動、像素溶解，載入完成時以各自的簽名式退場揭示內容。
載入預覽⋯
Playground
即時調整 props、程式碼片段同步更新——直接試出你要的樣子再複製。
68
8
<PreloaderCollection />
安裝
npx shadcn@latest add https://webberui.com/r/preloader-collection.json或在 components.json 設定 registries 後，改用 @webberui/preloader-collection 安裝。
安裝依賴後，從 registry JSON（/r/preloader-collection.json 的 files[0].content）複製 preloader-collection.tsx 原始碼到你的 components/ui/ 目錄：
npm install motion clsx tailwind-merge使用
import { PreloaderCollection } from "@/components/ui/preloader-collection";
// 非受控：掛載即顯示，minDuration 過後自動退場
<PreloaderCollection variant="staircase" label="WEBBER" />
// 受控：自行決定何時關閉（例如資料載入完成）
const [loading, setLoading] = React.useState(true);
<PreloaderCollection
variant="pixel"
loading={loading}
label="Loading"
onComplete={() => console.log("已揭示")}
/>Props
| Prop | 型別 | 預設值 | 說明 |
|---|---|---|---|
variant | "text" | "staircase" | "pixel" | "text" | 動畫款式：文字揭示／階梯滑動／像素溶解 |
loading | boolean | — | 受控是否顯示；由 true→false 觸發退場。未提供時為非受控 |
minDuration | number | 1400 | 非受控模式下，自動退場前的最短顯示時間（毫秒） |
position | "fixed" | "absolute" | "fixed" | 覆蓋定位：全螢幕或貼齊最近的定位祖先 |
label | string | "Loading" | 中央標籤文字（text 款作為主體，其他款作為說明） |
progress | number | — | 進度百分比（0–100）；提供時顯示數字，不影響退場時機 |
columns | number | 6／14 | staircase 的欄數（預設 6）／pixel 每列格數（預設 14） |
onComplete | () => void | — | 退場動畫全部完成、DOM 卸載後回呼 |
細節
- 受控／非受控雙模式：未傳
loading時為非受控——元件掛載即覆蓋畫面，minDuration過後自動退場，適合單純的進場遮罩。傳入loading則交由外部控制，通常綁定資料或路由的載入狀態，true→false時播放退場、揭示底下內容，並在動畫全部結束後呼叫onComplete。 - 三款簽名式退場：
text讓整片面板向上滑出，標籤逐字波浪明滅；staircase把覆蓋層切成數欄，退場時依索引錯位上滑成階梯；pixel依覆蓋層尺寸鋪成接近正方的像素格，退場時沿對角掃描逐格縮沒，形成像素溶解。三者的中央載入動態（跳動點、equalizer、閃爍像素矩陣）與各自的退場語彙一致。 - 像素格自適應：
pixel款以ResizeObserver量測覆蓋層寬高，用columns推算列數，讓每一格接近正方；量測在 paint 前於 layout effect 完成，不會有格數跳動。相鄰磚以同色outline補滿子像素髮絲縫，覆蓋期間不透光。 - 定位範圍：
position="fixed"覆蓋整個視口，適合頁面級預載；position="absolute"只覆蓋最近的relative／absolute祖先，適合區塊級載入（如卡片或面板內），示範即採用此模式。 - 進度顯示：傳入
progress時各款顯示百分比數字並更新aria-valuenow；progress僅供顯示與朗讀，是否退場仍由loading（或minDuration）決定，兩者可獨立控制。
可及性
- 覆蓋層在有
progress時為role="progressbar"（帶aria-valuemin/max/now），否則為role="status" aria-live="polite"，並帶aria-busy與aria-label；所有磚塊與裝飾動態皆aria-hidden，螢幕閱讀器只會聽到一次標籤與進度。 - 使用者系統開啟「減少動態效果」時，改為僅顯示標籤與進度的靜態覆蓋層，退場只做單純淡出，不播放磚塊動畫。
- 覆蓋層帶
select-none與cursor-wait，並以實心磚塊阻擋底層互動，避免使用者在載入期間誤觸尚未就緒的內容。