头像组 · AvatarGroup

头像组用于内容展示场景。下面的官方示例展示原生用法与状态，属性名保持上游 API。

安装与前置条件

npm install @astryxdesign/core@0.7.1 @astryxdesign/theme-neutral@0.7.1 @stylexjs/stylex@0.19.0

需要 React 19+，按顺序导入基础 CSS 和主题，并设置 Theme Provider。参见开始使用。

示例与使用方式

头像组 · 综合展示 / 分组 / 溢出处理 1：首先体验这个示例，再查看代码理解组件的组合方式。
头像组 · 综合展示 / 分组 2：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
头像组 · 分组 3：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
头像组 · 分组 4：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
头像组 · 自定义 / 分组 / 溢出处理 5：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
头像组 · 默认状态 / 分组 / 溢出处理 6：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。

API 与上游详细参考

优先使用 0.7.1 官方中文说明；上游尚未提供中文的条目保留英文。属性名、类型及默认值保持原生 API，不把示例状态名称当成组件属性。

Avatar Group

AvatarGroup 以重叠排列方式显示多个头像，并可选择显示溢出指示器。使用组合式 API：直接传入 Avatar 子元素，每个头像可携带自己的属性。

属性	类型	默认值	说明
children *	ReactNode		Avatar children, optionally followed by one AvatarGroupOverflow. Consumers handle slicing to the desired visible count.
size	AvatarSize	'md'	Size applied to all avatars via context. This wins over each child Avatar's own size prop, including when it is left at the default, so set the size here rather than on the children.
shape	'circle' \| 'rounded' \| 'square'	'circle'	Shape applied to all avatars via context, overriding each avatar's own shape prop. Also applied to AvatarGroupOverflow's "+N" indicator.
ref	React.Ref<HTMLDivElement>		Ref forwarded to the root element.
xstyle	StyleXStyles		StyleX styles for layout customization.
data-testid	string		Test selector for automated testing frameworks.

使用建议

自行切分列表，只传入需要显示的头像，通常 3-5 个为佳。组件只渲染传入的子元素，不会自动切分。
使用 AvatarGroupOverflow 自定义溢出内容，如弹出触发器或"添加成员"按钮。
直接在每个 Avatar 子元素上传递状态点、点击处理器或工具提示。
可以用 HoverCard 或 Tooltip 包裹 Avatar 子元素以在悬停时显示更多信息，头像仍会重叠。请在被包裹的 Avatar 上设置 tooltip={false}，避免与内置的名称提示冲突。
避免：不要嵌套 AvatarGroup，使用单个组包含所有头像。
避免：不要在子头像上设置 size。分组的 size 会覆盖每个子 Avatar 自身的 size，即使分组使用默认值也是如此。

主题 API

{
  "targets": [
    {
      "className": "astryx-avatar-group",
      "visualProps": [
        "size",
        "shape"
      ]
    },
    {
      "className": "astryx-avatar-group-overflow",
      "visualProps": [
        "size",
        "shape"
      ]
    }
  ]
}

AvatarGroupOverflow

组件结构

Avatar children: Avatar elements that form the overlapping row. Each can have its own props.
Overflow indicator: A "+N" circle at the end showing hidden count, or a custom AvatarGroupOverflow slot.

Avatar Group Overflow

AvatarGroupOverflow 显示在 AvatarGroup 末尾，用来汇总未单独展示的成员。适用于只展示少量头像但仍需要显示隐藏数量的场景。

属性	类型	说明
count *	number	隐藏头像数量，用于默认 `+N` 标签和无障碍标签。
children	ReactNode	可选的自定义计数字符串。省略时使用默认 `+N` 标签。
onClick	() => void	点击溢出指示器时触发。提供后指示器会渲染为可聚焦按钮。
ref	React.Ref<HTMLElement>	转发到溢出指示器元素的引用。
xstyle	StyleXStyles	用于布局自定义的 StyleX 样式。

使用建议

向 count 传入真实隐藏数量，确保无障碍标签与可见指示器一致。
使用 +12 或 99+ 等短文本；指示器在计数较短时为圆形，计数较宽时会拉伸为胶囊形，确保数字始终完整显示。
当溢出项会打开成员列表、弹出层或详情视图时提供 onClick。
避免：不要让自定义文本与 count 不一致；count 仍用于无障碍标签。
避免：不要在指示器内使用长标签；更长的参与者详情应放在头像组旁边。

Default overflow count

<AvatarGroup size="lg">
  {users.slice(0, 3).map(user => (
    <Avatar key={user.id} src={user.src} name={user.name} />
  ))}
  <AvatarGroupOverflow count={users.length - 3} />
</AvatarGroup>

Custom count text

<AvatarGroup size="lg">
  {users.slice(0, 3).map(user => (
    <Avatar key={user.id} src={user.src} name={user.name} />
  ))}
  <AvatarGroupOverflow count={12}>12+</AvatarGroupOverflow>
</AvatarGroup>

组件结构

Count label: The compact +N or custom count text displayed inside the circular indicator.
Button behavior: When onClick is provided, the indicator becomes an interactive button with focus and hover states.