Avatar 头像

用图标、图片或字符的形式展示用户或事物。

基础用法

通过 icon, src 或默认插槽展示头像。

USER

基础用法

不同尺寸

通过 size 属性设置头像大小，支持预设值 small (28px)、default (40px)、large (56px) 或自定义像素数值。

不同尺寸

头像形状

支持 circle 和 square 两种形状。

头像形状

图片适配

通过 fit 属性设置图片在头像中的适配方式，与 CSS object-fit 一致。

图片适配

自定义颜色

通过 background-color 属性自定义头像背景色。

YH

自定义颜色

加载失败

当图片加载失败时，可以通过 error 事件进行处理，默认插槽可作为降级展示。

加载失败

在 Nuxt 中使用

Avatar 组件完全支持 Nuxt 3/4 的 SSR 渲染。头像的尺寸、形状和图片在服务端渲染时即可正确展示，确保首屏即呈现完整的用户头像信息。

张

Nuxt 中使用

SSR 注意事项：

• ✅ 头像尺寸 (size)、形状 (shape)、图片适配 (fit) 首屏正确渲染
• ✅ 自定义背景色 (background-color) 和文字内容支持 SSR
• ✅ 图片 src / srcset 在服务端即包含在 HTML 中
• 💡 图片加载失败的降级处理在客户端激活后自动完成

Nuxt 自动导入

在安装 @yh-ui/nuxt 模块后，YhAvatar 组件会被自动注册，无需手动导入。

API

Props

属性名	说明	类型	默认值
shape	头像形状	'circle' | 'square'	'circle'
size	头像大小，支持预设值或像素数值	number | 'large' | 'default' | 'small'	'default'
src	图片地址	string	—
src-set	图片懒加载地址列表（srcset）	string	—
alt	图片 alt 描述文字	string	—
fit	图片适配方式	'fill' | 'contain' | 'cover' | 'none' | 'scale-down'	'cover'
icon	图标组件，当无图片时显示	string | Component	—
color	背景色（兼容旧 API）	string	—
background-color	背景颜色	string	—
theme-overrides	主题覆盖变量	ComponentThemeVars	—

Events

事件名	说明	回调参数
error	图片加载失败时触发	(event: Event) => void

Slots

插槽名	说明
default	自定义内容（文字或图标）

主题变量

变量名	说明	默认值
--yh-avatar-bg-color	背景颜色	var(--yh-color-primary-light-8, #d9ecff)
--yh-avatar-text-color	文字颜色	var(--yh-color-primary, #409eff)
--yh-avatar-radius	方形头像圆角	var(--yh-border-radius-base, 4px)