頁面區塊 Sections
人像疊字引言
全幅人像畫面上疊放引言文字的 React 評價區塊，切換時影像交叉淡接並緩慢推近，文字逐行由遮罩中升起，可自動播放、拖曳切換。
把客戶評價做成一張全幅人像海報：大圓角畫面鋪滿人像（沒有照片時以暖色雙色漸層與抽象半身剪影佔位），底部的暗色漸層上疊著白色引言與署名。切換時舊圖淡出、新圖淡入並在整個播放間隔裡從 1.08 緩慢推近到 1；引言以行為單位從遮罩中逐行升起，舊文字向上淡出。頂端每則一段細進度條，右下角有上一則／下一則、頁數與暫停鈕，也可以左右拖曳畫面切換。
把這個效果裝進你的專案
在專案資料夾執行指令，CLI 會加入原始碼與依賴套件，再依下方使用範例引用元件。
npx webberui@latest add portrait-overlay-quotePlayground
即時調整 props、程式碼片段同步更新——直接試出你要的樣子再複製。
7000
700
編輯中的呼叫預設屬性
<PortraitOverlayQuote/>
完整範例包含預覽的排版與資料。先安裝元件，再把範例檔貼入你的專案。
安裝
npx webberui@latest add https://webberui.com/r/portrait-overlay-quote.json或在 components.json 設定 registries 後，改用 @webberui/portrait-overlay-quote 安裝。
使用
import { PortraitOverlayQuote } from "@/components/ui/portrait-overlay-quote";
<PortraitOverlayQuote
eyebrow="客戶怎麼說"
title="他們把網站換上新介面之後"
testimonials={[
{
quote: "改版後的訂位頁，\n讓週末候位少了一半。",
name: "林語晴",
role: "營運主理人",
company: "青嶼咖啡",
highlight: "少了一半",
},
{
quote: "司機打開派車畫面就知道下一站。新人第一天就能獨立跑線。",
name: "陳柏宇",
role: "調度主管",
company: "北辰物流",
photoSrc: "/images/team/chen.jpg",
},
]}
interval={7000}
onIndexChange={(i) => console.log(`切到第 ${i + 1} 則`)}
/>Props
| Prop | 型別 | 預設值 | 說明 |
|---|---|---|---|
testimonials | PortraitOverlayQuoteItem[] | — | 評價清單 |
eyebrow | string | — | 標題上方的小標 |
title | string | — | 區塊標題；有提供時作為 section 的 aria-labelledby |
subtitle | string | — | 標題下方的說明文字 |
autoplay | boolean | true | 是否自動播放；使用者開啟「減少動態效果」時一律關閉 |
interval | number | 7000 | 自動播放間隔（ms）；未提供時讀 --wb-portrait-overlay-quote-interval |
duration | number | 700 | 文字逐行升起的時長（ms）；未提供時讀 --wb-portrait-overlay-quote-duration |
aspect | "16/9" | "4/3" | "1/1" | "16/9" | md 以上的畫面比例；md 以下固定 4/5 |
index | number | — | 受控的目前索引；未提供時由元件內部管理 |
defaultIndex | number | 0 | 非受控模式的初始索引 |
onIndexChange | (index: number) => void | — | 索引變動時回呼 |
className | string | — | 透傳到根 section |
PortraitOverlayQuoteItem
| 欄位 | 型別 | 預設值 | 說明 |
|---|---|---|---|
quote | string | — | 引言內文；可用 \n 手動斷行，未斷行時自動依句末標點切行 |
name | string | — | 姓名，同時用來產生縮寫頭像（中文取末兩字、拉丁取首字母） |
role | string | — | 職稱 |
company | string | — | 公司 |
rating | number | — | 評分（0–5），顯示為星等 |
avatarHue | number | — | 佔位人像與頭像的色相；未提供時依索引以黃金角度（137.508°）推算 |
highlight | string | — | quote 中要以強調色底線標記的片段 |
metric | { value: string; label: string } | — | 搭配引言的關鍵數字 |
photoSrc | string | — | 人像照片網址；未提供時以漸層 + 抽象剪影佔位 |
細節
- 節奏變數：
--wb-portrait-overlay-quote-interval（預設7000ms）與--wb-portrait-overlay-quote-duration（預設700ms）。傳入interval／duration時會寫進這兩個變數，元件掛載後再從 computed style 讀回，所以在外層覆寫變數也會生效。 - 強調色只走
--wb-portrait-overlay-quote-accent（淺色預設#0d9488、深色預設#2dd4bf），用在小標、引言重點底線與進度段。 - 一個 rAF 迴圈同時推進 Ken Burns 縮放與進度段：暫停時計時不前進，進度停在當下，繼續後從原處接著跑；滑鼠移入、鍵盤焦點在區塊內、按下暫停鈕、分頁切到背景、捲出畫面時都會暫停。
- 影像交叉淡接固定 800ms，比文字慢，讓畫面先換、字再升起；每行以 90ms 錯開。
- 拖曳或左右滑動位移超過 60px 才會切換；從按鈕上開始的拖曳不算。
可及性
- 根元素是
section，有標題時以aria-labelledby指向標題；輪播區為role="region"並帶aria-roledescription="輪播" - 每則評價是
role="group"、aria-roledescription="評價"，aria-label例如「第 2 則，共 5 則」；引言以figure、blockquote、figcaption呈現 - 自動播放進行中
aria-live="off"，避免定時打斷螢幕閱讀器；暫停或手動切換時改為polite - 上一則／下一則與暫停鈕都是
type="button"並有aria-label，暫停鈕帶aria-pressed；焦點在區塊內時可用左右方向鍵切換 - 自動播放預設開啟時一定有可見的暫停鈕（WCAG 2.2.2），滑鼠移入或焦點進入也會暫停
- 使用者系統開啟「減少動態效果」時：自動播放關閉、不做 Ken Burns 推近與文字位移，影像與文字改為 150ms 淡入，仍可用按鈕切換