Avatar
展示用户头像、图片回退内容和头像组合的组件
头像（Avatar）用于展示用户、团队、组织或对象的视觉标识。组件基于 Radix Avatar 封装，内置图片加载失败时的回退内容，并通过 size 控制头像尺寸。
import { Avatar, AvatarFallback, AvatarImage, AvatarRoot } from '@skyroc/web-ui';架构说明
Avatar 由三个结构组件组成：
AvatarRoot：头像根容器，负责尺寸、圆角和裁切。AvatarImage：头像图片，负责渲染src和alt。AvatarFallback：图片加载失败或延迟显示时的回退内容。
Avatar 主组件会自动组合这三个结构组件，常规使用时只需要传入 src、alt 和 fallback。
何时使用
- 展示用户头像、团队标识、应用图标或对象缩略图。
- 图片可能加载失败，需要展示姓名缩写、图标或占位内容。
- 多个用户需要以头像组形式紧凑展示。
- 需要统一控制头像尺寸、圆形裁切和回退样式。
基础用法
传入 src 设置头像图片，传入 alt 提供可访问文本，传入 fallback 作为加载失败时的回退内容。
尺寸
通过 size 控制头像根容器大小，从 xs 到 2xl 共 6 个尺寸。
| 尺寸 | 容器尺寸 | 适用场景 |
|---|---|---|
xs | 24px | 表格、紧凑列表 |
sm | 32px | 菜单、次级信息 |
md | 40px | 常规场景（默认） |
lg | 48px | 用户卡片、详情区域 |
xl | 56px | 个人资料、重点展示 |
2xl | 64px | 大头像、个人主页头部 |
回退内容
当图片加载失败或不可用时，fallback 会显示在头像容器中。常见内容包括姓名缩写、符号或图标。
自定义回退
fallback 支持任意 React 节点，可放入图标、自定义图片或其他占位内容。通过 classNames.fallback 或 fallbackProps 可调整回退区域样式。
头像组
多个 Avatar 可以通过布局 class 组合成头像组。需要重叠展示时，可在外层使用负间距，并通过 className 或 classNames.root 添加描边。
自定义样式
通过 classNames 精细控制 root、image、fallback 三个 slot 的 class。
也可以通过 rootProps、fallbackProps 分别向根容器和回退内容传入额外属性；主组件自身继承图片属性，className 默认作用在 AvatarImage 上。
API
Avatar
通用属性参考：基于 Radix UI Avatar，主组件继承 AvatarImage 的图片属性，并额外支持回退内容和根容器配置。
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| src | 头像图片地址 | string | - |
| alt | 头像图片替代文本 | string | - |
| fallback | 图片加载失败或等待加载时显示的回退内容 | ReactNode | - |
| size | 头像尺寸，作用于根容器 | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | 'md' |
| delayMs | 延迟显示 fallback 的毫秒数 | number | - |
| className | 头像图片的 class | ClassValue | - |
| classNames | 各 slot 的自定义 class（root / image / fallback） | AvatarUi | - |
| fallbackProps | 传递给 AvatarFallback 的额外 props | AvatarFallbackProps | - |
| rootProps | 传递给 AvatarRoot 的额外 props | AvatarRootProps | - |
| onLoadingStatusChange | 图片加载状态变化时触发 | (status: "idle" | "loading" | "loaded" | "error") => void | - |
| ref | 指向底层 img 元素的 ref | Ref<HTMLImageElement> | - |
子组件
Avatar 也导出基础结构组件，适合需要手动组合 Root、Image、Fallback 的场景。
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| AvatarRoot | 头像根容器，支持 Radix Avatar Root props、size 和 className | AvatarRootProps | - |
| AvatarImage | 头像图片，支持 Radix Avatar Image props、size 和 className | AvatarImageProps | - |
| AvatarFallback | 回退内容，支持 Radix Avatar Fallback props、delayMs、size 和 className | AvatarFallbackProps | - |
类型
AvatarProps
主组件属性。继承 AvatarImageProps 和 AvatarFallbackProps 中的 delayMs，并额外提供 fallback、classNames、rootProps 和 fallbackProps。
| 字段 | 类型 | 说明 |
|---|---|---|
| alt | string | 头像图片替代文本。来自 img 元素属性。 |
| className | ClassValue | 图片元素的 class。来自 StyledComponentProps。 |
| classNames | AvatarUi | 各 slot 的自定义 class。 |
| delayMs | number | 延迟显示 fallback 的毫秒数。来自 AvatarFallbackProps。 |
| fallback | React.ReactNode | 图片不可用时展示的回退内容。 |
| fallbackProps | AvatarFallbackProps | 传递给 AvatarFallback 的额外属性。 |
| onLoadingStatusChange | (status: 'idle' | 'loading' | 'loaded' | 'error') => void | 图片加载状态变化回调。来自 Radix Avatar Image props。 |
| ref | Ref<HTMLImageElement> | 转发到底层图片元素的 ref。 |
| rootProps | AvatarRootProps | 传递给 AvatarRoot 的额外属性。 |
| size | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | 头像尺寸。来自 StyledComponentProps。 |
| src | string | 头像图片地址。来自 img 元素属性。 |
| ...React.ImgHTMLAttributes<HTMLImageElement> | React.ImgHTMLAttributes<HTMLImageElement> | 支持其余标准 img 属性。 |
AvatarUi
Avatar 各 slot 的自定义 class 配置。
| 字段 | 类型 | 说明 |
|---|---|---|
| root | ClassValue | 根容器的 class。 |
| image | ClassValue | 图片元素的 class。 |
| fallback | ClassValue | 回退内容的 class。 |
AvatarRootProps
根容器属性。继承 Radix Avatar Root props，并通过 StyledComponentProps 增加 className 和 size。
| 字段 | 类型 | 说明 |
|---|---|---|
| asChild | boolean | 将渲染委托给子元素。来自 Radix Primitive。 |
| children | React.ReactNode | 根容器子节点，通常是 AvatarImage 和 AvatarFallback。 |
| className | ClassValue | 根容器 class。 |
| id | string | DOM id。来自 span 元素属性。 |
| ref | Ref<HTMLSpanElement> | 转发到底层 span 元素的 ref。 |
| size | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | 头像尺寸，影响根容器大小。 |
AvatarImageProps
图片属性。继承 Radix Avatar Image props，并通过 StyledComponentProps 增加 className 和 size。
| 字段 | 类型 | 说明 |
|---|---|---|
| alt | string | 图片替代文本。 |
| asChild | boolean | 将渲染委托给子元素。来自 Radix Primitive。 |
| className | ClassValue | 图片 class。 |
| height | number | string | 图片高度。来自 img 元素属性。 |
| onLoadingStatusChange | (status: 'idle' | 'loading' | 'loaded' | 'error') => void | 图片加载状态变化回调。 |
| ref | Ref<HTMLImageElement> | 转发到底层 img 元素的 ref。 |
| size | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | 尺寸属性会被接收；当前图片样式主要依赖根容器尺寸。 |
| src | string | 图片地址。 |
| width | number | string | 图片宽度。来自 img 元素属性。 |
| ...React.ImgHTMLAttributes<HTMLImageElement> | React.ImgHTMLAttributes<HTMLImageElement> | 支持其余标准 img 属性与事件。 |
AvatarFallbackProps
回退内容属性。继承 Radix Avatar Fallback props，并通过 StyledComponentProps 增加 className 和 size。
| 字段 | 类型 | 说明 |
|---|---|---|
| asChild | boolean | 将渲染委托给子元素。来自 Radix Primitive。 |
| children | React.ReactNode | 回退内容。 |
| className | ClassValue | 回退内容 class。 |
| delayMs | number | 延迟显示 fallback 的毫秒数。 |
| id | string | DOM id。来自 span 元素属性。 |
| ref | Ref<HTMLSpanElement> | 转发到底层 span 元素的 ref。 |
| size | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | 尺寸属性会被接收；当前回退内容样式主要依赖根容器尺寸。 |
StyledComponentProps<T>
项目内用于包装 Radix props 的通用类型。
| 字段 | 类型 | 说明 |
|---|---|---|
| ...T | Omit<T, "className"> | 继承原始组件属性，但重新定义 className。 |
| className | ClassValue | 组件 class。 |
| size | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | 项目统一尺寸类型。 |
RadixAvatarRootProps
Radix Avatar Root 原始属性。
| 字段 | 类型 | 说明 |
|---|---|---|
| ...PrimitiveSpanProps | PrimitiveSpanProps | 继承 Radix Primitive span 属性。 |
RadixAvatarImageProps
Radix Avatar Image 原始属性。
| 字段 | 类型 | 说明 |
|---|---|---|
| ...PrimitiveImageProps | PrimitiveImageProps | 继承 Radix Primitive img 属性。 |
| onLoadingStatusChange | (status: 'idle' | 'loading' | 'loaded' | 'error') => void | 图片加载状态变化回调。 |
RadixAvatarFallbackProps
Radix Avatar Fallback 原始属性。
| 字段 | 类型 | 说明 |
|---|---|---|
| ...PrimitiveSpanProps | PrimitiveSpanProps | 继承 Radix Primitive span 属性。 |
| delayMs | number | 延迟显示 fallback 的毫秒数。 |
PrimitiveSpanProps
Radix Primitive span 属性。
| 字段 | 类型 | 说明 |
|---|---|---|
| ...React.ComponentPropsWithoutRef<typeof Primitive.span> | React.ComponentPropsWithoutRef<typeof Primitive.span> | 继承 Primitive.span 的无 ref 属性。 |
PrimitiveImageProps
Radix Primitive img 属性。
| 字段 | 类型 | 说明 |
|---|---|---|
| ...React.ComponentPropsWithoutRef<typeof Primitive.img> | React.ComponentPropsWithoutRef<typeof Primitive.img> | 继承 Primitive.img 的无 ref 属性。 |
PrimitivePropsWithRef<E>
Radix Primitive 通用属性类型。
| 字段 | 类型 | 说明 |
|---|---|---|
| ...React.ComponentPropsWithRef<E> | React.ComponentPropsWithRef<E> | 继承指定元素的原生属性和 ref。 |
| asChild | boolean | 将渲染委托给子元素。 |
AvatarSlots
Avatar 可配置 classNames 的 slot