FxAvatar 头像

头像可用于代表人员或对象，支持图片、图标或字符。不依赖任何 UI 框架。

基础用法

用 shape 和 size 属性设置头像的形状与尺寸。

<template>
  <div class="demo-basic">
    <div class="col">
      <div class="sub-title">circle</div>
      <div class="row">
        <div class="block"><FxAvatar :size="50" :src="circleUrl" /></div>
        <div v-for="s in sizeList" :key="s" class="block">
          <FxAvatar :size="s || undefined" :src="circleUrl" />
        </div>
      </div>
    </div>
    <div class="col">
      <div class="sub-title">square</div>
      <div class="row">
        <div class="block">
          <FxAvatar shape="square" :size="50" :src="squareUrl" />
        </div>
        <div v-for="s in sizeList" :key="s" class="block">
          <FxAvatar shape="square" :size="s || undefined" :src="squareUrl" />
        </div>
      </div>
    </div>
  </div>
</template>

<script setup lang="ts">
const circleUrl =
  "https://cube.elemecdn.com/3/7c/3ea6beec64369c2642b92c6726f1epng.png"
const squareUrl =
  "https://cube.elemecdn.com/9/c2/f0ee8a3c7c9638a54940382568c9dpng.png"
const sizeList = ["small", "", "large"] as const
</script>

<style scoped>
.demo-basic {
  display: flex;
  gap: 24px;
}

.col {
  flex: 1;
  text-align: center;
}

.sub-title {
  margin-bottom: 10px;
  font-size: 14px;
  color: var(--fx-text-color-secondary);
}

.row {
  display: flex;
  justify-content: space-between;
  align-items: center;
}

.block {
  flex: 1;
}
</style>

类型

支持图片、图标或字符。

<template>
  <div class="flex flex-wrap items-center gap-4">
    <FxAvatar icon="ep:user-filled" />
    <FxAvatar :src="src" />
    <FxAvatar>user</FxAvatar>
  </div>
</template>

<script setup lang="ts">
const src = "https://cube.elemecdn.com/0/88/03b0d39583f48206768a7534e55bcpng.png"
</script>

回退

图片加载失败时的回退内容。

<template>
  <!--
    回退演示：src 故意填无效地址 "https://empty" 触发图片加载失败，
    浏览器控制台会报 `GET https://empty/ net::ERR_CONNECTION_RESET`——
    属预期行为（demo 要的就是触发 @error 走回退逻辑），不是 bug。
  -->
  <FxAvatar :size="60" src="https://empty" @error="errorHandler">
    <img
      src="https://cube.elemecdn.com/e/fd/0fc7d20532fdaf769a25683617711png.png"
    />
  </FxAvatar>
</template>

<script setup lang="ts">
const errorHandler = () => true
</script>

默认插槽内容会在图片加载失败时自动展示，同时触发 error 事件。

适应容器

设置图片如何适应容器，等同于 object-fit。

<template>
  <div class="demo-fit">
    <div v-for="fit in fits" :key="fit" class="block">
      <span class="title">{{ fit }}</span>
      <FxAvatar shape="square" :size="100" :fit="fit" :src="url" />
    </div>
  </div>
</template>

<script setup lang="ts">
const fits = ["fill", "contain", "cover", "none", "scale-down"]
const url =
  "https://fuss10.elemecdn.com/e/5d/4a731a90594a4af544c0c25941171jpeg.jpeg"
</script>

<style scoped>
.demo-fit {
  display: flex;
  text-align: center;
  justify-content: space-between;
  gap: 12px;
}

.block {
  flex: 1;
  display: flex;
  flex-direction: column;
}

.title {
  margin-bottom: 10px;
  font-size: 14px;
  color: var(--fx-text-color-secondary);
}
</style>

头像组（AvatarGroup）

以头像组形式展示。

<template>
  <div>
    <p>default</p>
    <FxAvatarGroup>
      <FxAvatar v-for="n in 5" :key="n" :src="url" />
    </FxAvatarGroup>
  </div>
  <div style="margin-top: 24px">
    <p>collapse-avatars</p>
    <FxAvatarGroup collapse-avatars>
      <FxAvatar v-for="n in 5" :key="n" :src="url" />
    </FxAvatarGroup>
  </div>
  <div style="margin-top: 24px">
    <p>collapse-class + collapse-style</p>
    <FxAvatarGroup
      collapse-avatars
      :collapse-style="{ backgroundColor: '#d9ecff' }"
      collapse-class="my-collapse"
    >
      <FxAvatar v-for="n in 5" :key="n" :src="url" />
    </FxAvatarGroup>
  </div>
  <div style="margin-top: 24px">
    <p>max-collapse-avatars</p>
    <FxAvatarGroup collapse-avatars :max-collapse-avatars="3">
      <FxAvatar v-for="n in 5" :key="n" :src="url" />
    </FxAvatarGroup>
  </div>
  <div style="margin-top: 24px">
    <p>collapse-avatars-tooltip</p>
    <FxAvatarGroup
      collapse-avatars
      :max-collapse-avatars="3"
      collapse-avatars-tooltip
    >
      <FxAvatar v-for="n in 5" :key="n" :src="url" />
    </FxAvatarGroup>
  </div>
</template>

<script setup lang="ts">
const url = "https://cube.elemecdn.com/3/7c/3ea6beec64369c2642b92c6726f1epng.png"
</script>

<style scoped>
.my-collapse {
  color: var(--fx-color-primary);
}
</style>

使用 <FxAvatarGroup> 包裹头像。collapse-avatars 可折叠超出 max-collapse-avatars 的头像。

FxAvatar API

Attributes

属性	说明	类型	默认值
icon	图标头像，字符串为 IconString 类型（即 FxIcon 图标名，如 ep:edit、ant-design:home、svg:xxx），亦可传组件	string / Component	—
size	头像尺寸	number / 'large' | 'default' | 'small'	—
shape	头像形状	'circle' | 'square'	circle
src	图片地址	string	—
src-set	图片原生 srcset	string	—
alt	图片原生 alt	string	—
fit	图片适应方式（object-fit）	'fill' | 'contain' | 'cover' | 'none' | 'scale-down'	cover

Events

事件名	说明	类型
error	图片加载失败时触发	(e: Event) => void

Slots

插槽名	说明
default	自定义头像内容

FxAvatarGroup API

Attributes

属性	说明	类型	默认值
size	统一控制组内头像尺寸	number / 'large' | 'default' | 'small'	—
shape	统一控制组内头像形状	'circle' | 'square'	—
collapse-avatars	是否折叠头像	boolean	false
collapse-avatars-tooltip	hover 计数头像时是否用 tooltip 展示收起的头像	boolean	false
max-collapse-avatars	折叠时最多显示的头像数	number	1
effect	tooltip 主题	'dark' | 'light'	light
placement	tooltip 位置	'top' | 'top-start' | 'top-end' | 'bottom' | 'bottom-start' | 'bottom-end' | 'left' | 'right' | …	top
popper-class	tooltip 自定义类名	string	—
popper-style	tooltip 自定义样式	string /	—
collapse-class	折叠计数头像自定义类名	string	—
collapse-style	折叠计数头像自定义样式	string /	—