Skyroc UIDocs
数据展示
SKYROC UI · COMPONENT

Avatar

展示用户头像、图片回退内容和头像组合的组件

@skyroc/web-uiTypeScriptRadix foundation

头像（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 作为加载失败时的回退内容。

预览
代码
Loading...

尺寸

通过 size 控制头像根容器大小，从 xs 到 2xl 共 6 个尺寸。

尺寸容器尺寸适用场景
xs24px表格、紧凑列表
sm32px菜单、次级信息
md40px常规场景（默认）
lg48px用户卡片、详情区域
xl56px个人资料、重点展示
2xl64px大头像、个人主页头部
预览
代码
Loading...

回退内容

当图片加载失败或不可用时，fallback 会显示在头像容器中。常见内容包括姓名缩写、符号或图标。

预览
代码
Loading...

自定义回退

fallback 支持任意 React 节点，可放入图标、自定义图片或其他占位内容。通过 classNames.fallback 或 fallbackProps 可调整回退区域样式。

预览
代码
Loading...

头像组

多个 Avatar 可以通过布局 class 组合成头像组。需要重叠展示时，可在外层使用负间距，并通过 className 或 classNames.root 添加描边。

预览
代码
Loading...

自定义样式

通过 classNames 精细控制 root、image、fallback 三个 slot 的 class。

也可以通过 rootProps、fallbackProps 分别向根容器和回退内容传入额外属性；主组件自身继承图片属性，className 默认作用在 AvatarImage 上。

API

Avatar

通用属性参考：基于 Radix UI Avatar，主组件继承 AvatarImage 的图片属性，并额外支持回退内容和根容器配置。

Props属性、类型与默认值
11 properties
属性说明类型默认值
src头像图片地址string-
alt头像图片替代文本string-
fallback图片加载失败或等待加载时显示的回退内容ReactNode-
size头像尺寸，作用于根容器'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl''md'
delayMs延迟显示 fallback 的毫秒数number-
className头像图片的 classClassValue-
classNames各 slot 的自定义 class（root / image / fallback）AvatarUi-
fallbackProps传递给 AvatarFallback 的额外 propsAvatarFallbackProps-
rootProps传递给 AvatarRoot 的额外 propsAvatarRootProps-
onLoadingStatusChange图片加载状态变化时触发(status: "idle" | "loading" | "loaded" | "error") => void-
ref指向底层 img 元素的 refRef<HTMLImageElement>-

子组件

Avatar 也导出基础结构组件，适合需要手动组合 Root、Image、Fallback 的场景。

Props属性、类型与默认值
3 properties
属性说明类型默认值
AvatarRoot头像根容器，支持 Radix Avatar Root props、size 和 classNameAvatarRootProps-
AvatarImage头像图片，支持 Radix Avatar Image props、size 和 classNameAvatarImageProps-
AvatarFallback回退内容，支持 Radix Avatar Fallback props、delayMs、size 和 classNameAvatarFallbackProps-

类型

AvatarProps

主组件属性。继承 AvatarImageProps 和 AvatarFallbackProps 中的 delayMs，并额外提供 fallback、classNames、rootProps 和 fallbackProps。

字段类型说明
altstring头像图片替代文本。来自 img 元素属性。
classNameClassValue图片元素的 class。来自 StyledComponentProps。
classNamesAvatarUi各 slot 的自定义 class。
delayMsnumber延迟显示 fallback 的毫秒数。来自 AvatarFallbackProps。
fallbackReact.ReactNode图片不可用时展示的回退内容。
fallbackPropsAvatarFallbackProps传递给 AvatarFallback 的额外属性。
onLoadingStatusChange(status: 'idle' | 'loading' | 'loaded' | 'error') => void图片加载状态变化回调。来自 Radix Avatar Image props。
refRef<HTMLImageElement>转发到底层图片元素的 ref。
rootPropsAvatarRootProps传递给 AvatarRoot 的额外属性。
size'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl'头像尺寸。来自 StyledComponentProps。
srcstring头像图片地址。来自 img 元素属性。
...React.ImgHTMLAttributes<HTMLImageElement>React.ImgHTMLAttributes<HTMLImageElement>支持其余标准 img 属性。

AvatarUi

Avatar 各 slot 的自定义 class 配置。

字段类型说明
rootClassValue根容器的 class。
imageClassValue图片元素的 class。
fallbackClassValue回退内容的 class。

AvatarRootProps

根容器属性。继承 Radix Avatar Root props，并通过 StyledComponentProps 增加 className 和 size。

字段类型说明
asChildboolean将渲染委托给子元素。来自 Radix Primitive。
childrenReact.ReactNode根容器子节点，通常是 AvatarImage 和 AvatarFallback。
classNameClassValue根容器 class。
idstringDOM id。来自 span 元素属性。
refRef<HTMLSpanElement>转发到底层 span 元素的 ref。
size'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl'头像尺寸，影响根容器大小。

AvatarImageProps

图片属性。继承 Radix Avatar Image props，并通过 StyledComponentProps 增加 className 和 size。

字段类型说明
altstring图片替代文本。
asChildboolean将渲染委托给子元素。来自 Radix Primitive。
classNameClassValue图片 class。
heightnumber | string图片高度。来自 img 元素属性。
onLoadingStatusChange(status: 'idle' | 'loading' | 'loaded' | 'error') => void图片加载状态变化回调。
refRef<HTMLImageElement>转发到底层 img 元素的 ref。
size'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl'尺寸属性会被接收；当前图片样式主要依赖根容器尺寸。
srcstring图片地址。
widthnumber | string图片宽度。来自 img 元素属性。
...React.ImgHTMLAttributes<HTMLImageElement>React.ImgHTMLAttributes<HTMLImageElement>支持其余标准 img 属性与事件。

AvatarFallbackProps

回退内容属性。继承 Radix Avatar Fallback props，并通过 StyledComponentProps 增加 className 和 size。

字段类型说明
asChildboolean将渲染委托给子元素。来自 Radix Primitive。
childrenReact.ReactNode回退内容。
classNameClassValue回退内容 class。
delayMsnumber延迟显示 fallback 的毫秒数。
idstringDOM id。来自 span 元素属性。
refRef<HTMLSpanElement>转发到底层 span 元素的 ref。
size'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl'尺寸属性会被接收；当前回退内容样式主要依赖根容器尺寸。

StyledComponentProps<T>

项目内用于包装 Radix props 的通用类型。

字段类型说明
...TOmit<T, "className">继承原始组件属性，但重新定义 className。
classNameClassValue组件 class。
size'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl'项目统一尺寸类型。

RadixAvatarRootProps

Radix Avatar Root 原始属性。

字段类型说明
...PrimitiveSpanPropsPrimitiveSpanProps继承 Radix Primitive span 属性。

RadixAvatarImageProps

Radix Avatar Image 原始属性。

字段类型说明
...PrimitiveImagePropsPrimitiveImageProps继承 Radix Primitive img 属性。
onLoadingStatusChange(status: 'idle' | 'loading' | 'loaded' | 'error') => void图片加载状态变化回调。

RadixAvatarFallbackProps

Radix Avatar Fallback 原始属性。

字段类型说明
...PrimitiveSpanPropsPrimitiveSpanProps继承 Radix Primitive span 属性。
delayMsnumber延迟显示 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。
asChildboolean将渲染委托给子元素。

AvatarSlots

Avatar 可配置 classNames 的 slot

'fallback' | 'image' | 'root'

ClassValue

CSS 类名类型

string | null | undefined | Record<string, boolean> | ClassValue[]

Tag

用于标记状态、分类或短文本信息的标签组件

List

用于展示标题、描述、前后插槽和补充内容的列表组件

On this page

架构说明何时使用基础用法尺寸回退内容自定义回退头像组自定义样式APIAvatar子组件类型