组件Data Display
AvatarStack
@mox-hub/ui 组件 · Data Display · canonical
avatar-stack@mox-hub/uiData Displaycanonicalsrc/components/avatar-stack.tsx变体轴
sizesmmdlg
变体演示avatar-stack
还有 1 位成员
Props API
| Prop | 类型 | 默认值 | 说明 |
|---|---|---|---|
| items* | AvatarStackItem[] | — | — |
| max* | number | 4 | — |
| size* | "sm" | "lg" | "md" | "md" | — |
| onOverflowClick* | () => void | — | — |
| labels* | Partial<AvatarStackLabels> | — | — |
| className* | string | — | — |
源码
import { cn } from "../lib/utils"
import {
Avatar,
AvatarFallback,
AvatarGroup as AvatarGroupRoot,
AvatarGroupCount,
AvatarImage,
} from "./avatar"
import { NavStatusDot } from "./nav-status-dot"
import { RawButton } from "./raw/raw-button"
import type { Tone } from "./tone"
/**
* AvatarStack —— 成员堆叠 + 在线状态(原子层;治理方案 B12)。
*
* 纯展示件:数据由 `items` 全量传入,超过 `max` 只渲染堆叠内的前 N 人,
* 其余折叠为 `+N`。`onOverflowClick` 是唯一交互口,不传时 `+N` 退化为静态计数
* (不渲染一个点了没反应的死按钮)。
*
* 可访问性(§8.5#4:不得只靠颜色传达状态):
* - 容器 `role="group"` + `aria-label`;
* - 每个人的可访问名含姓名与状态(`aria-label` / `title` 同文),状态点本身
* `aria-hidden`——它是视觉增强,不是唯一信号;
* - `+N` 按钮的无障碍名由 `labels.overflow(count)` 给出,视觉文本 `+N` 不再重复播报。
*
* presence 只收语义状态词,tone 映射在组件内固定(online → success、busy → danger、
* away → warning、offline → default),颜色走 `nav-status-dot` / `tone.ts` 唯一链路。
*/
export type AvatarPresence = "online" | "busy" | "away" | "offline"
export interface AvatarStackItem {
id: string
name: string
src?: string
/** 无头像图时的兜底文本;缺省由 name 推导(中英文均取前两个字符/首字母) */
fallback?: string
presence?: AvatarPresence
}
export interface AvatarStackLabels {
/** 组容器无障碍名(默认「成员」) */
group: string
/** 单人气泡无障碍名(默认「姓名,状态」;无 presence 时只播姓名) */
item: (name: string, presence?: string) => string
/** 溢出计数的可访问名(默认「还有 N 位成员」) */
overflow: (count: number) => string
online: string
busy: string
away: string
offline: string
}
export interface AvatarStackProps {
items: AvatarStackItem[]
/** 堆叠内最多展示的人数,默认 4 */
max?: number
size?: "sm" | "md" | "lg"
/** 传了才把 `+N` 渲染为按钮;不传则静态展示计数 */
onOverflowClick?: () => void
labels?: Partial<AvatarStackLabels>
className?: string
}
const DEFAULT_LABELS: AvatarStackLabels = {
group: "成员",
item: (name, presence) => (presence ? `${name},${presence}` : name),
overflow: (count) => `还有 ${count} 位成员`,
online: "在线",
busy: "忙碌",
away: "离开",
offline: "离线",
}
/** presence → tone:状态词到视觉词表的唯一映射,颜色由 NavStatusDot 落地 */
const PRESENCE_TONE: Record<AvatarPresence, Tone> = {
online: "success",
busy: "danger",
away: "warning",
offline: "default",
}
/** ui/avatar 的尺寸档(default 对应本件的 md) */
const SIZE_MAP = {
sm: "sm",
md: "default",
lg: "lg",
} as const
/** 无头像图时的首字母:单段取前两字,多段取首尾词首字 */
function getInitials(name: string): string {
const parts = name.trim().split(/\s+/).filter(Boolean)
if (parts.length === 0) return "?"
if (parts.length === 1) {
return Array.from(parts[0]).slice(0, 2).join("").toUpperCase()
}
return (
Array.from(parts[0])[0] + Array.from(parts[parts.length - 1])[0]
).toUpperCase()
}
function AvatarStack({
items,
max = 4,
size = "md",
onOverflowClick,
labels,
className,
}: AvatarStackProps) {
const L: AvatarStackLabels = { ...DEFAULT_LABELS, ...labels }
const limit = Math.max(0, Math.trunc(max))
const visibleItems = items.slice(0, limit)
const hiddenCount = items.length - visibleItems.length
const overflowLabel = L.overflow(hiddenCount)
return (
<AvatarGroupRoot
role="group"
aria-label={L.group}
className={cn("items-center", className)}
>
{visibleItems.map((item) => {
const presenceLabel = item.presence ? L[item.presence] : undefined
const accessibleName = L.item(item.name, presenceLabel)
return (
<Avatar
key={item.id}
size={SIZE_MAP[size]}
role="img"
aria-label={accessibleName}
title={accessibleName}
data-avatar-id={item.id}
>
{item.src ? <AvatarImage src={item.src} alt="" /> : null}
<AvatarFallback aria-hidden="true">
{item.fallback ?? getInitials(item.name)}
</AvatarFallback>
{item.presence ? (
// 状态点只做视觉增强;姓名与状态已并入头像的 aria-label / title。
<span
aria-hidden="true"
className="pointer-events-none absolute end-0 bottom-0 flex items-center justify-center rounded-full bg-background p-0.5"
>
<NavStatusDot
tone={PRESENCE_TONE[item.presence]}
label={presenceLabel as string}
/>
</span>
) : null}
</Avatar>
)
})}
{hiddenCount > 0 ? (
<AvatarGroupCount>
{onOverflowClick ? (
<RawButton
type="button"
aria-label={overflowLabel}
title={overflowLabel}
onClick={onOverflowClick}
className="absolute inset-0 inline-flex cursor-pointer items-center justify-center rounded-full outline-none focus-visible:ring-2 focus-visible:ring-ring/50"
>
<span aria-hidden="true">+{hiddenCount}</span>
</RawButton>
) : (
<>
<span aria-hidden="true">+{hiddenCount}</span>
<span className="sr-only">{overflowLabel}</span>
</>
)}
</AvatarGroupCount>
) : null}
</AvatarGroupRoot>
)
}
export { AvatarStack }
可访问性与 RTL
- 键盘:交互件保留
:focus-visible焦点环;浮层支持 Escape 关闭与焦点归还,菜单 / 页签按 Base UI 约定支持方向键。 筛选菜单、拖拽排序、执行树与模型 listbox 等关键键盘流由 Playwright 断言覆盖,见规范示例 · 交互与可访问性。 - RTL:间距、对齐与方向性图标使用逻辑属性 (
ms-*/text-start/rtl:-scale-x-100);通过ThemeProvider或I18nProvider的direction="rtl"驱动,`lint:rtl` 会拦截新增物理类。 - 文案:优先用组件
labels/translate/translatorprops,其次用I18nProvider目录;内置 zh-CN 默认值,en-US 为参考翻译。见Theming · i18n 与 RTL。 - 对比度:高对比度 token、2px 控件边框与 3px 焦点环由主题层统一提供,见Foundations · Contrast。
用法说明
头像堆叠组:max 截断 + 溢出按钮、presence 状态点带文字替代;容器 role=group。