头像组件（Avatar）

Element UI 的 Avatar 组件用于展示用户或事物的头像，可以是图标、图片或字符。常用于用户信息展示、列表项等场景。

提示

头像（Avatar）组件官方文档：https://element.eleme.cn/#/zh-CN/component/avatar (opens new window)

1. 基本用法

基本语法：使用 <el-avatar> 标签创建头像，支持通过 src 属性指定图片路径，也可以通过 icon 属性设置图标类型。

<template>
  <el-avatar icon="el-icon-user-solid"></el-avatar>
  <el-avatar src="https://example.com/avatar.png"></el-avatar>
</template>

• 图标头像：通过 icon 属性指定图标类型，如 el-icon-user-solid。
• 图片头像：通过 src 属性指定图片路径，如 https://example.com/avatar.png。

Avatar 属性

参数	说明	类型	可选值	默认值
icon	设置头像的图标类型，参考 Icon 组件	string	—	—
size	设置头像的大小	number/string	number / large / medium / small	large
shape	设置头像的形状	string	circle / square	circle
src	图片头像的资源地址	string	—	—
srcSet	以逗号分隔的一个或多个字符串列表，表明一系列用户代理使用的可能的图像	string	—	—
alt	描述图像的替换文本	string	—	—
fit	当展示类型为图片时，设置图片如何适应容器框	string	fill / contain / cover / none / scale-down	cover

Avatar 事件

事件名	说明	回调参数
error	图片类头像加载失败的回调，返回 false 会关闭组件默认的 fallback 行为	(e: Event)

Avatar 插槽

名称	说明
default	自定义头像展示内容

2. 常见用法示例

2.1 使用图标作为头像

通过 icon 属性，使用内置图标库中的图标来展示头像。适用于当用户没有上传头像图片时，使用默认图标进行占位。

<template>
  <el-avatar icon="el-icon-user-solid" size="medium"></el-avatar>
  <el-avatar icon="el-icon-edit" size="large" shape="square"></el-avatar>
</template>

• 图标头像：在头像中使用图标，通过 icon 属性指定图标类型。
• 大小与形状：通过 size 属性设置头像大小，shape 属性控制形状。
• 

2.2 使用图片作为头像

通过 src 属性设置图片地址来展示头像，可以为用户设置自定义头像图片。

<template>
  <el-avatar src="https://fuss10.elemecdn.com/e/5d/4a731a90594a4af544c0c25941171jpeg.jpeg" size="large"></el-avatar>
  <el-avatar src="https://fuss10.elemecdn.com/e/5d/4a731a90594a4af544c0c25941171jpeg.jpeg" shape="square"></el-avatar>
</template>

• 图片头像：通过 src 属性设置图片路径，展示用户头像。
• 形状控制：使用 shape 属性控制头像形状，如 circle（圆形）或 square（方形）。
• 

2.3 自定义头像内容

可以通过默认插槽自定义头像的内容，例如使用文字或自定义的图标。

<template>
  <el-avatar size="large">
    <span style="font-size: 20px; color: #fff;">A</span>
  </el-avatar>
</template>

• 自定义内容：通过插槽自定义头像内容，可以是文字、图标或其他自定义元素。
• 

2.4 处理图片加载失败

可以通过 error 事件捕获图片加载失败的情况，并执行自定义逻辑，如显示默认图标或提示信息。

<template>
  <el-avatar
    :src="avatarUrl"
    @error="handleError"
    size="large">
  </el-avatar>
</template>

<script>
export default {
  data() {
    return {
      avatarUrl: 'https://invalid-url.com/avatar.png' // 无效的图片地址
    };
  },
  methods: {
    handleError() {
      this.avatarUrl = ''; // 图片加载失败时清空路径或设置默认图标
      this.$message.error('图片加载失败，已显示默认头像');
      return false; // 禁用默认的 fallback 行为
    }
  }
};
</script>

• 错误处理：在图片加载失败时，通过 error 事件执行自定义逻辑，如设置默认图标或显示提示。

2.5 图片如何适应容器框

当使用 Avatar 组件展示图片时，可以通过 fit 属性来控制图片如何适应容器框。fit 属性的可选值与 CSS 的 object-fit 属性一致。

• fill：图片会被拉伸以完全填充容器框，无论图片的原始宽高比是什么。虽然可以填满整个容器，但这可能导致图片失真。
• contain：图片会保持其原有宽高比，同时尽可能大地显示在容器框内。这样可以避免图片失真，但容器内可能会有空白区域。
• cover：图片会保持其原有宽高比，并填充整个容器框。如果图片的宽高比与容器不匹配，图片的部分内容可能会被裁剪掉，以确保图片能够完全覆盖容器。
• none：图片会按原始尺寸显示，不会被拉伸或缩放。如果图片尺寸大于容器框，会导致部分图片超出容器框。如果图片尺寸小于容器框，则图片会在容器内显示，剩余部分为空白。
• scale-down：图片会根据容器的大小进行自适应缩放，选择 none 或 contain 的效果。它会优先保持图片的完整性，既不失真也尽量展示较大的图片部分。如果图片的原始尺寸小于容器框，它会按原尺寸显示；如果大于容器框，则会缩小到容器框内。

<template>
  <div class="demo-fit">
    <div class="block" v-for="fit in fits" :key="fit">
        <span class="title">{{ fit }}</span>
        <el-avatar shape="square" :size="100" :fit="fit" :src="url"></el-avatar>
    </div>
  </div>
</template>
<script>
  export default {
    data() {
      return {
        fits: ['fill', 'contain', 'cover', 'none', 'scale-down'],
        url: 'https://fuss10.elemecdn.com/e/5d/4a731a90594a4af544c0c25941171jpeg.jpeg'
      }
    }
  }
</script>

3. 综合示例：用户信息卡片

在实际开发中，Avatar 组件通常与其他 UI 组件一起使用，比如展示在用户信息卡片中，提供用户的基本信息和头像。

<template>
  <el-card class="user-card">
    <el-avatar :src="user.avatar" size="large" shape="circle"></el-avatar>
    <div class="user-info">
      <h3>{{ user.name }}</h3>
      <p>{{ user.email }}</p>
    </div>
  </el-card>
</template>

<script>
export default {
  data() {
    return {
      user: {
        avatar: 'https://example.com/user-avatar.png',
        name: 'John Doe',
        email: 'john.doe@example.com'
      }
    };
  }
};
</script>

<style scoped>
.user-card {
  display: flex;
  align-items: center;
  padding: 20px;
  width: 400px;
}

.user-info {
  margin-left: 15px;
}

.user-info h3 {
  margin: 0;
  font-size: 18px;
}

.user-info p {
  margin: 0;
  color: #999;
}
</style>

• 综合应用：将 Avatar 与 Card 组件结合，构建一个用户信息卡片，展示用户头像、姓名和邮箱等信息。