Avatar 头像

用于表示用户或实体的图像占位。核心在于回退链：只要图片拿不到，组件会自己退到可读的内容上，业务侧不必再写 onerror 逻辑。

代码演示

基础用法

图片、alt 首字符、默认插槽、人形兜底四种形态。没有 src 也没有 alt 时落到内置人形占位。

李

第一个头像用内联 SVG 作为图片源，避免演示依赖外部网络。

avatar/basic.vue

源码

<script setup lang="ts">
import { mdiAccountOutline } from '@mdi/js'

/** 用内联 SVG 当图片源，避免演示依赖外部网络 */
const svg = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 40 40"><rect width="40" height="40" fill="#4f46e5"/><circle cx="20" cy="15" r="6" fill="#fff"/><path d="M6 38c0-7 6.3-11 14-11s14 4 14 11z" fill="#fff"/></svg>`
const photo = `data:image/svg+xml,${encodeURIComponent(svg)}`
</script>

<template>
  <div class="m-row-demo">
    <MAvatar :src="photo" alt="张三" :size="44" />
    <MAvatar alt="李四" :size="44" />
    <MAvatar :size="44" color="secondary">
      <MIcon :path="mdiAccountOutline" :size="24" />
    </MAvatar>
    <MAvatar :size="44" color="info" />
  </div>
</template>

尺寸

size 传 'small' / 'default' / 'large' 走预设尺寸（32 / 40 / 56 px），传数字则直接按像素生效。

S

D

L

2

6

数字尺寸下字号按 size * 0.42 自动换算。

avatar/sizes.vue

源码

<template>
  <div class="m-row-demo">
    <MAvatar size="small" alt="Small" />
    <MAvatar size="default" alt="Default" />
    <MAvatar size="large" alt="Large" />
    <MAvatar :size="24" alt="24" color="secondary" />
    <MAvatar :size="64" alt="64" color="success" />
  </div>
</template>

形状

circle 正圆、rounded 圆角方形、square 直角方形。

C

R

S

avatar/shapes.vue

源码

<template>
  <div class="m-row-demo">
    <MAvatar shape="circle" :size="48" alt="Circle" />
    <MAvatar shape="rounded" :size="48" alt="Rounded" color="success" />
    <MAvatar shape="square" :size="48" alt="Square" color="warning" />
  </div>
</template>

语义色

color 只在文本 / 插槽 / 人形占位时起作用，图片模式下会被忽略。

P

S

S

W

E

I

avatar/colors.vue

源码

<script setup lang="ts">
const colors = ['primary', 'secondary', 'success', 'warning', 'error', 'info'] as const
</script>

<template>
  <div class="m-row-demo">
    <MAvatar
      v-for="color in colors"
      :key="color"
      :color="color"
      :size="44"
      :alt="color.slice(0, 1).toUpperCase()" />
  </div>
</template>

加载失败与重新加载

第一排的头像指向一个不存在的路径，图片 error 后自动回退；点按钮换 src，组件会重置失败标记重新尝试加载。

第二个头像演示了「有 #default 插槽时，插槽内容优先于 alt 首字符」。

avatar/fallback.vue

源码

<script setup lang="ts">
import { ref } from 'vue'

/** 一个必然 404 的本地路径，用来触发图片加载失败的回退 */
const brokenSrc = '/miao-demo-missing-avatar.png'
const okSvg = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 40 40"><rect width="40" height="40" fill="#0ea5e9"/><circle cx="20" cy="15" r="6" fill="#fff"/><path d="M6 38c0-7 6.3-11 14-11s14 4 14 11z" fill="#fff"/></svg>`
const okSrc = `data:image/svg+xml,${encodeURIComponent(okSvg)}`

const src = ref(brokenSrc)

function toggle() {
  src.value = src.value === brokenSrc ? okSrc : brokenSrc
}
</script>

<template>
  <div class="m-row-demo">
    <MAvatar :src="src" alt="张三" :size="52" />
    <MAvatar :src="src" :size="52" color="success">
      <span>自定义</span>
    </MAvatar>
    <MButton variant="outlined" color="primary" size="small" @click="toggle">
      切换 src 重新加载
    </MButton>
  </div>
</template>

API

Props

属性	类型	默认值	说明
src	string	undefined	图片地址；加载失败自动回退到默认插槽 / 首字符 / 人形占位
alt	string	undefined	图片 alt；无图片时作为首字符占位的来源
size	number | 'small' | 'default' | 'large'	40	数字按 px 处理，预设值对应 32 / 40 / 56 px
shape	'circle' | 'square' | 'rounded'	'circle'	形状
color	'primary' | 'secondary' | 'success' | 'warning' | 'error' | 'info'	'primary'	文本 / 图标占位的背景色，图片模式忽略

Events

无。

Slots

插槽	参数	说明
default	无	自定义占位内容，优先级高于 alt 首字符与人形兜底

使用建议

回退优先级

渲染顺序为「图片 → 默认插槽 → alt 首字符（取第一个字符并大写）→ 内置人形 SVG」。只想用一个名字做占位时，写 <MAvatar alt="张三" /> 即可得到「张」字头像。

src 变化会重置失败标记

组件内部用 failed 记录加载失败。src 一旦变化就会把 failed 置回 false 并重新尝试加载，因此切换用户头像时不需要换 key 或重建组件。

数字尺寸会同时改写字号

传数字 size 时，组件会把 width / height 设为该值，并把 fontSize 设为 size * 0.42。如果传入的默认插槽内容自带 font-size，它会覆盖这一换算。

相关组件

• Icon 图标：默认插槽里放 MIcon 可以做图标头像。
• Nav 导航：导航项常配头像或图标作视觉标识。