頁面區塊 Sections
星等評價橫列
一列附星等的評價卡，頂部總評分數字計數進場，各卡星星依序填滿並支援小數星等，搭配商品縮圖與已驗證購買徽章。
電商商品頁與落地頁常見的評價區塊。頂部匯總列顯示大字平均分、小數填滿的五星與「來自 1,240 則評價」，右側可選的星等分佈長條同時是篩選器；下方一列 3–4 張評價卡，每張卡帶唯讀星等（支援 4.5 這類小數）、粗體標題、引言、姓名縮寫頭像，以及右下的商品縮圖與「已驗證購買」徽章。區塊捲進視口時平均分由 0 計數到目標、星星一顆顆填滿並輕彈一下，窄螢幕的卡片列改為橫向捲動 snap。
把這個效果裝進你的專案
在專案資料夾執行指令，CLI 會加入原始碼與依賴套件，再依下方使用範例引用元件。
npx webberui@latest add star-rated-reviewsPlayground
即時調整 props、程式碼片段同步更新——直接試出你要的樣子再複製。
1200
80
編輯中的呼叫預設屬性
<StarRatedReviews/>
完整範例包含預覽的排版與資料。先安裝元件，再把範例檔貼入你的專案。
安裝
npx webberui@latest add https://webberui.com/r/star-rated-reviews.json或在 components.json 設定 registries 後，改用 @webberui/star-rated-reviews 安裝。
使用
import { StarRatedReviews } from "@/components/ui/star-rated-reviews";
<StarRatedReviews
eyebrow="顧客評價"
title="買過的人怎麼說"
distribution={[8, 12, 28, 112, 1080]}
testimonials={[
{
headline: "保溫一整天，下午還是燙的",
quote: "通勤帶著走完全不漏，杯蓋單手就能開。",
name: "林語晴",
role: "設計師",
rating: 5,
verified: true,
productName: "隨行保溫瓶",
},
{
headline: "尺寸剛好塞進抽屜",
quote: "疊三個整理文具和充電線很方便。",
name: "陳柏宇",
rating: 4.5,
verified: true,
productSrc: "/images/stacking-bin.jpg",
productName: "疊疊收納盒",
},
]}
/>Props
| Prop | 型別 | 預設值 | 說明 |
|---|---|---|---|
testimonials | StarRatedReviewsItem[] | — | 評價資料，建議 3–4 則 |
eyebrow | string | "顧客評價" | 標題上方的小標 |
title | string | "買過的人怎麼說" | 區塊標題；同時作為 section 的無障礙名稱 |
subtitle | string | — | 標題下方的說明文字 |
average | number | — | 平均分（0–5）；未提供時以 testimonials 的 rating 平均 |
totalCount | number | — | 評價總則數；未提供時取 distribution 加總，再不然取 testimonials 數量 |
distribution | number[] | — | 星等分佈，索引 0 為 1 星的則數、依序到 5 星；畫面由 5 星往下排列 |
showDistribution | boolean | true | 是否顯示星等分佈長條（需提供 distribution） |
showProduct | boolean | true | 是否顯示卡片右下的商品縮圖 |
filter | number | null | — | 受控的星等篩選（1–5，null 為全部）；未提供時由元件內部管理 |
defaultFilter | number | null | null | 非受控模式的初始篩選 |
onFilterChange | (star: number | null) => void | — | 點分佈長條或「顯示全部評價」時回呼 |
verifiedLabel | string | "已驗證購買" | 徽章文字 |
className | string | — | 附加到根 section 的 class |
StarRatedReviewsItem
| 欄位 | 型別 | 預設值 | 說明 |
|---|---|---|---|
quote | string | — | 評價內文 |
name | string | — | 評價者姓名；頭像顯示縮寫（中文取末兩字、拉丁取首字母） |
role | string | — | 職稱 |
company | string | — | 公司或單位 |
rating | number | — | 星等 0–5，可為 4.5 等小數；未提供時該卡不顯示星等 |
avatarHue | number | — | 頭像漸層色相；未提供時依索引以黃金角度分配 |
highlight | string | — | quote 中要以強調色標記的片段 |
metric | { value: string; label: string } | — | 引言下方的成效數字 |
headline | string | — | 卡片頂部的粗體一句話標題 |
productSrc | string | — | 商品縮圖網址；未提供時以漸層 + 抽象物件 SVG 佔位 |
productName | string | — | 商品名稱，作為縮圖的替代文字 |
verified | boolean | — | 顯示「已驗證購買」徽章 |
細節
- 小數星等：每顆星是底層 neutral 的星形，上層同一顆星以外框寬度百分比裁切，因此 4.5、4.3 都能精準呈現。
- 進場節奏：區塊進入視口（只播一次）時，平均分由 0 計數到目標，時長讀
--wb-star-rated-reviews-count（預設1200ms）；匯總五星與各卡星星依序填滿，間隔讀--wb-star-rated-reviews-stagger（預設80ms），每顆星填滿的瞬間以 spring 放大到 1.2 再回彈；分佈長條以 60ms 間隔由左展開，卡片以 100ms 間隔上移淡入。 - 顏色：星色走
--wb-star-rated-reviews-star（預設琥珀色#f59e0b），強調色走--wb-star-rated-reviews-accent（預設#0d9488，深色模式#2dd4bf），只用於徽章、標記與焦點框。 - 篩選：分佈長條是切換按鈕，點選後只顯示四捨五入後等於該星等的卡片，再點一次或按「顯示全部評價」即清除。
- 版面：窄螢幕的卡片列是可橫向捲動的 snap 區域，md 以上平均分欄。頭像與商品縮圖都由索引確定性產生，伺服器與瀏覽器輸出一致。
可及性
- 根元素為
<section aria-labelledby>，以標題作為區塊名稱；每則評價以figure／blockquote／figcaption呈現 - 每組星等為
role="img"，aria-label例如「4.5 顆星，滿分 5 顆」 - 平均分的計數過程對輔助科技隱藏，螢幕閱讀器只會讀到終值「平均 4.8 分，滿分 5 分」
- 分佈長條為
aria-pressed切換按鈕，aria-label含星等、則數與占比；篩選結果以role="status"播報 - 卡片列為可聚焦的
region，鍵盤使用者可用方向鍵橫向捲動；所有按鈕有focus-visible焦點框 - 使用者系統開啟「減少動態效果」時，平均分直接顯示終值、星星與長條直接填滿，不彈跳；卡片只以 150ms 淡入，不位移