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]