Avatar 头像

代表用户的图片元素，带有回退显示。加载中、没有图片源或图片加载失败时显示姓名缩写。

基础用法

SAvatar({ src: $r('app.media.startIcon'), fallback: 'SP' })
SAvatar({ src: 'https://example.invalid/me.png', fallback: 'CN' })  // load error → initials
SAvatar({ fallback: 'JD', sizing: 40 })
SAvatar({ fallback: 'AB', sizing: 56 })

网页近似预览，真机效果以 HarmonyOS 渲染为准。

尺寸

sizing：vp 数值，或 'xs' | 'sm' | 'default' | 'md' | 'lg' | 'xl'。

SAvatar({ fallback: 'XS', sizing: 'xs' })
SAvatar({ fallback: 'SM', sizing: 'sm' })
SAvatar({ fallback: 'DF' })
SAvatar({ fallback: 'MD', sizing: 'md' })
SAvatar({ fallback: 'LG', sizing: 'lg' })
SAvatar({ fallback: 'XL', sizing: 'xl' })

网页近似预览，真机效果以 HarmonyOS 渲染为准。

形状与状态

shape：circle | rounded | square；status：online | away | busy | offline。

SAvatar({ src: $r('app.media.startIcon'), fallback: 'SP', sizing: 'lg' })
SAvatar({ src: $r('app.media.startIcon'), fallback: 'SP', sizing: 'lg', shape: 'rounded' })
SAvatar({ src: $r('app.media.startIcon'), fallback: 'SP', sizing: 'lg', shape: 'square' })
SAvatar({ fallback: 'ON', sizing: 'lg', status: 'online' })
SAvatar({ fallback: 'AW', sizing: 'lg', status: 'away' })
SAvatar({ fallback: 'BS', sizing: 'lg', status: 'busy', shape: 'rounded' })
SAvatar({ fallback: 'OF', sizing: 'lg', status: 'offline' })

网页近似预览，真机效果以 HarmonyOS 渲染为准。

组

SAvatarGroup 让头像带背景色描边重叠排列，并追加 "+N"。

SAvatarGroup({ fallbacks: ['CN', 'LR', 'ER', 'MK'] })
SAvatarGroup({ fallbacks: ['CN', 'LR', 'ER', 'MK', 'JD', 'AB'], max: 3, sizing: 'md' })
SAvatarGroup({ fallbacks: ['SP', 'CN'], sources: [$r('app.media.startIcon')], extra: 12,
  sizing: 'lg', shape: 'rounded' })

网页近似预览，真机效果以 HarmonyOS 渲染为准。

API

从组件库源码中的 @Param / @Event / @BuilderParam 声明自动提取。

SAvatar

shadcn-vue 的 Avatar（+ AvatarImage / AvatarFallback）：relative flex size-8 shrink-0 overflow-hidden rounded-full。图片加载期间、缺少 src 时以及加载失败时，会显示回退内容（bg-muted 上的姓名缩写）。

变体：sizing（vp，或 xs | sm | default | md | lg | xl）、shape（circle | rounded | square）、status（右下角的状态点：online | away | busy | offline），以及 ring（2vp 的背景色圆环，用于重叠展示）。

属性	类型	默认值	说明
src	ResourceStr | undefined	undefined
fallback	string	''	没有图片时显示的姓名缩写。
sizing	number | AvatarSize AvatarSize = 'xs' | 'sm' | 'default' | 'md' | 'lg' | 'xl'	32	直径，单位 vp（size-8 即 32），或使用命名尺寸。
shape	AvatarShape AvatarShape = 'circle' | 'rounded' | 'square'	'circle'
status	AvatarStatus | undefined AvatarStatus = 'online' | 'away' | 'busy' | 'offline'	undefined	位于右下角的状态点。
ring	boolean	false	背景色的 2vp 圆环（ring-2 ring-background）。
label	string | undefined	undefined	无障碍名称；默认为 fallback。

SAvatarGroup

重叠的头像组（shadcn 的 flex -space-x-2 *:ring-2 *:ring-background 模式），带有「+N」气泡。采用数据驱动，因为插槽中的子组件无法再次调整样式：传入姓名缩写以及（可选的）图片。

属性	类型	默认值	说明
fallbacks	string[]	[]	每个头像的姓名缩写（每项对应一个头像）。
sources	ResourceStr[]	[]	每个头像的图片，按索引对应（可选，长度可以更短）。
max	number	0	在「+N」气泡之前显示的头像数量；0 表示全部显示。
extra	number	0	列表之外的额外数量（例如服务器返回的总数），将计入「+N」气泡。
sizing	number | AvatarSize AvatarSize = 'xs' | 'sm' | 'default' | 'md' | 'lg' | 'xl'	32
shape	AvatarShape AvatarShape = 'circle' | 'rounded' | 'square'	'circle'
overlap	number | undefined	undefined	头像的重叠距离，单位 vp；默认为直径的四分之一（32vp 时即 -space-x-2）。
label	string | undefined	undefined	头像组的无障碍名称。