Avatar

展示用户或团队头像，支持图片、文字和渐变占位，让列表、评论与成员信息更易辨认。

我们正在让 SnowUI 组件成为 AI 对话中可直接操作的界面。目前对话交互能力仍在建设中；本页展示网站用法，支持的对话平台与组件版本将在验证后公布。 AI 对话内生成和使用 SnowUI 界面完全免费，不属于项目，不占项目或开发者席位额度，无需 SnowUI 注册、激活或付费证明。

如何使用

用于用户或团队身份。单个头像用 Avatar，重叠成员用 AvatarGroup；纵向联系人列表使用 Avatar 配合普通列表和文本。

通过 src 显示头像，使用 fallback / fallbackText 配置回退；为同一身份提供稳定 fallbackSeed。
附属角标用 as="badge"，替换头像视觉用 as="avatar-image"；尺寸优先使用显式 size，其次父级头像尺寸。

导入

import { Avatar } from '@snowui-design-system/components';

用法

带徽标的头像

尺寸

API 参考

属性	类型	默认值	示例	描述
`src`	`string \| Component`	`—`	`src={ExampleIcon}`	头像图片 URL 或图标组件
`size`	`ResourceSize`	`—`	`size={value}`	头像尺寸档位为 12/16/20/24/28/32/40/48/80；显式值优先，其次父级头像或通用尺寸上下文，无上下文时为 16。
`fallback`	`Component`	`—`	`fallback={ExampleIcon}`	无 `src` 或图片不可用时渲染的自定义头像组件；未传时默认内置 Gradient。动效头像场景可传 `GradientMotion`，Avatar 会传入 `as="avatar-image"`、`size="100%"`、`radius="inherit"` 与解析后的稳定 `seed`。
`fallbackText`	`string`	`—`	`fallbackText="Example"`	图片不可用时显示的显式回退文字；去除首尾空格，非空时替代默认 Gradient，显式 fallback 组件仍优先。不会从姓名自动生成首字母。
`fallbackColor`	`GradientVariant`	`—`	`fallbackColor={value}`	显式选择默认 Gradient 的具名艺术配色；优先级高于 `fallbackSeed` 和名称回退。
`fallbackSeed`	`string \| number`	`—`	`fallbackSeed="Example"`	稳定身份种子，推荐传入 `user.id`；组件以确定性哈希映射到六种具名配色，相同 seed 始终得到相同颜色，无需持久化颜色字段。
`variant`	`AvatarVariant`	`"default"`	`variant={value}`	默认样式使用稳定身份 seed 或显式具名颜色的 Gradient 配色；空头像样式使用灰色背景与默认用户图标。
`gradientMotion`	`boolean`	`false`	`gradientMotion`	是否常驻运行默认 Gradient fallback 的四层基础矢量形变；为 false 时 Gradient 仍会在 hover 期间按需运行水波形变和多色 Overlay
`children`	`Snippet`	`—`	`<Avatar>Content</Avatar>`	头像附属内容；as="badge" 声明角标，as="avatar-image" 声明外置头像视觉并覆盖默认回退层。
`badgePosition`	`"top" \| "bottom"`	`"top"`	`badgePosition="top"`	as="badge" 子内容定位在头像右上或右下；Dot 角标同时参与头像切割。