Avatar 头像

LhAvatar 用于展示用户或事物的头像，支持图片、图标和文字三种形态，图片加载失败时自动回退。

基础用法

图片头像

fit 控制裁切模式（原生 object-fit），alt 提供替代文本。

<script setup lang="ts">
</script>

<template>
  <!-- 图片头像 -->
  <LhAvatar src="https://api.dicebear.com/9.x/notionists/svg?seed=mo" />
  <!-- fit 裁切 + alt 替代文本 -->
  <LhAvatar
    src="https://api.dicebear.com/9.x/notionists/svg?seed=f"
    fit="cover"
    alt="用户头像"
  />
</template>

<script>
export default {}
</script>

<template>
  <!-- 图片头像 -->
  <LhAvatar src="https://api.dicebear.com/9.x/notionists/svg?seed=mo" />
  <!-- fit 裁切 + alt 替代文本 -->
  <LhAvatar
    src="https://api.dicebear.com/9.x/notionists/svg?seed=f"
    fit="cover"
    alt="用户头像"
  />
</template>

形状与尺寸

圆形与方形、四种尺寸

小中大圆

<script setup lang="ts">
</script>

<template>
  <div style="display: flex; align-items: center; gap: 12px">
    <LhAvatar
      shape="square"
      size="small"
      text="小"
    />
    <LhAvatar
      shape="square"
      size="medium"
      text="中"
    />
    <LhAvatar
      shape="square"
      size="large"
      text="大"
    />
    <LhAvatar
      size="large"
      text="圆"
    />
  </div>
</template>

<script>
export default {}
</script>

<template>
  <div style="display: flex; align-items: center; gap: 12px">
    <LhAvatar
      shape="square"
      size="small"
      text="小"
    />
    <LhAvatar
      shape="square"
      size="medium"
      text="中"
    />
    <LhAvatar
      shape="square"
      size="large"
      text="大"
    />
    <LhAvatar
      size="large"
      text="圆"
    />
  </div>
</template>

文字与图标兜底

无图片时按 icon、text 顺序回退

水A

<script setup lang="ts">
</script>

<template>
  <div style="display: flex; align-items: center; gap: 12px">
    <LhAvatar text="水墨" />
    <LhAvatar icon="user" />
    <LhAvatar text="Alice Chen" />
  </div>
</template>

<script>
export default {}
</script>

<template>
  <div style="display: flex; align-items: center; gap: 12px">
    <LhAvatar text="水墨" />
    <LhAvatar icon="user" />
    <LhAvatar text="Alice Chen" />
  </div>
</template>

文字头像自动取首字展示（中文取首字、英文取首字母大写）。

图片加载失败

失败后回退到 text 并触发 error 事件

<template>
  <LhAvatar
    src="/broken-avatar.png"
    text="备"
    @error="onError"
  />
</template>

<script setup lang="ts">
function onError(e: Event) {
  console.log('avatar load error', e)
}
</script>

<template>
  <LhAvatar
    src="/broken-avatar.png"
    text="备"
    @error="onError"
  />
</template>

<script>
export default {
  methods: {
    onError(e) {
      console.log('avatar load error', e)
    },
  },
}
</script>

API

Props

属性	说明	类型	默认值
src	图片地址，为空时回退到图标/文字	string	—
alt	替代文本	string	—
icon	图标名称（内置 LhIcon 图标，src 缺省时展示）	LhIconName	—
text	文字内容（src 与 icon 缺省时取首字展示）	string	—
shape	头像形状	"circle" | "square"	'circle'
size	头像大小	"small" | "medium" | "large" | "mini" | "x-large"	'medium'
fit	图片加载模式：fill / contain / cover	"fill" | "contain" | "cover" | "none" | "scale-down"	'cover'
sx	sx 快速布局属性	LhSxProps	—

Events

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

无障碍

• 图片模式由 <img alt> 自身提供替代文本；未传 alt 时回退到 text，再回退到 avatar
• 图标 / 文字模式由根元素承担 role="img"，传 alt 时作为无障碍名称；图标本身标记为 aria-hidden

类型定义

本组件对外导出的 TypeScript 类型结构如下（自动提取自 packages/components/avatar/src/types.ts 与 @lh-ui/share/core/* 源码，点击各条目展开查看完整定义；属性说明见上方 Props 表）：

LhAvatarProps

export interface LhAvatarProps {
  /** 图片地址；为空时依次回退到图标、文字 */
  src?: string
  /** 图片加载失败的替代文本，同时作为 alt */
  alt?: string
  /** 图标名（src 为空或加载失败时展示，取内置 LhIcon 图标） */
  icon?: LhIconName
  /** 文字头像内容（src 与 icon 都缺省时取首字展示） */
  text?: string
  /** 头像形状 */
  shape?: LhAvatarComponentShape
  /** 头像大小 */
  size?: LhAvatarSize
  /** 图片加载模式：fill / contain / cover */
  fit?: 'fill' | 'contain' | 'cover' | 'none' | 'scale-down'
  /** sx 快速布局属性 */
  sx?: LhSxProps
}

LhAvatarSize

export type LhAvatarSize = LhComponentSize

LhAvatarShape

export type LhAvatarShape = LhAvatarComponentShape

LhAvatarComponentShape _{（来自 @lh-ui/share/core/avatar）}

export type LhAvatarShape = 'circle' | 'square'

LhIconName _{（来自 @lh-ui/share/core/icon (svgs.ts)）}

export type LhIconName = keyof typeof LH_ICON_SVGS_CONST

LhComponentSize _{（来自 @lh-ui/share/core/shared）}

export type LhComponentSize = (typeof LH_SIZE_CONST)[keyof typeof LH_SIZE_CONST]