狀態頭像

成員列表、留言串、帳號選單都用得到的頭像。圖片在 mounted 後預載，載入前先顯示由 alt 產生的首字母——中文名取最後兩字、英文取前兩個單字的首字母，底色依名字的確定性 hash 從六個中性暖灰色調中挑選，同一個人每次都同色。圖片載入完成時兩層交叉淡接，載入失敗則保留首字母。右下角可加線上狀態點，線上時外圈緩慢呼吸；開啟 ring 後 hover 或外層連結聚焦時，描邊會從頭像邊緣擴張出來。

Playground

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

import * as React from "react";

export default function Example() {
  return (
    <div className="flex min-h-[320px] w-full items-center justify-center p-6">

<Avatar/>

    </div>
  );
}

安裝

npx webberui@latest add https://webberui.com/r/avatar.json

使用

import { Avatar } from "@/components/ui/avatar";

<Avatar src="/team/yuqing.jpg" alt="林雨晴" status="online" ring />

{/* 沒有圖片：顯示「雨晴」 */}
<Avatar alt="林雨晴" size="lg" shape="rounded" />

{/* 外層是連結時，聚焦也會顯示描邊 */}
<a href="/members/yuqing" className="rounded-full focus-visible:outline-none">
  <Avatar src="/team/yuqing.jpg" alt="林雨晴" ring delayMs={300} />
</a>

Props

另外具名匯出 getInitials(alt)，方便在其他地方（例如下拉選單的文字頭像）沿用同一套首字母規則。

細節

• 首字母規則：含中日韓漢字的名字取最後兩個漢字（「林雨晴」→「雨晴」，單字名取一字），因為中文習慣以名稱呼；其他名字取前兩個單字的首字母並大寫（「Maya Lin」→「ML」）。
• 預載只在 mounted 後以 new Image() 進行，SSR 首次渲染一律輸出首字母層，與 client 第一次渲染一致，不會產生 hydration 警告。
• 圖片層與首字母層絕對定位疊在同一個框裡，交叉淡接時版面不會跳動。
• 狀態點尺寸為頭像的 25%，外圈 2px 與背景同色；離開狀態用 CSS mask 畫成月牙，缺口是真正透明的；離線為空心圓。只有線上狀態有呼吸脈動（外圈放大至 1.8 倍並淡出，2 秒一輪）。
• 時間節奏外露為 --wb-avatar-duration（預設 200ms）與 --wb-ease-out，可在全域樣式覆寫。

可及性

• 圖片使用 alt；圖片未載入時首字母層為 role="img" 並以 aria-label 帶出完整名字
• 有 status 時附上 sr-only 文字（例如「（線上）」），螢幕閱讀器會讀出「林雨晴（線上）」；狀態點與脈動本身 aria-hidden
• 描邊同時回應 hover 與外層連結／按鈕的 focus-visible，鍵盤使用者也看得到聚焦位置
• 使用者系統開啟「減少動態效果」時，交叉淡接改為直接切換、線上狀態點不脈動