Ordo UI
组件Data Display

AvatarStack

@mox-hub/ui 组件 · Data Display · canonical

avatar-stack@mox-hub/uiData Displaycanonicalsrc/components/avatar-stack.tsx

变体轴

size
smmdlg
变体演示avatar-stack
还有 1 位成员

Props API

Prop类型默认值说明
items*AvatarStackItem[]——
max*number4—
size*"sm" | "lg" | "md""md"—
onOverflowClick*() => void——
labels*Partial<AvatarStackLabels>——
className*string——

源码

packages/ui/src/components/avatar-stack.tsx
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 /translator props,其次用I18nProvider目录;内置 zh-CN 默认值,en-US 为参考翻译。见Theming · i18n 与 RTL。
  • 对比度:高对比度 token、2px 控件边框与 3px 焦点环由主题层统一提供,见Foundations · Contrast。

用法说明

头像堆叠组:max 截断 + 溢出按钮、presence 状态点带文字替代;容器 role=group。