Element Plus Avatar 头像组件完全指南基本用法、图片降级回退与 AvatarGroup 头像组【免费下载链接】element-plus A Vue.js 3 UI Library made by Element team项目地址: https://gitcode.com/GitHub_Trending/el/element-plusElement Plus 的 Avatar头像组件用于在界面中直观地表示用户、组织或任意对象支持图片、图标Icon与文本字符三种渲染形态。本文以 docs/en-US/component/avatar.md 为骨架结合 packages/components/avatar 的源码实现、测试用例与 docs/examples/avatar 官方示例系统讲解 Avatar 的尺寸/形状控制、图片适配、加载失败回退机制以及 2.13.1 起新增的 AvatarGroup 头像组折叠能力帮助你在一线业务中正确、高效地使用该组件。组件概述Avatar 是 Element Plus 组件库中用于展示人物或对象标识的轻量级组件。它在渲染上始终是一个span容器并根据传入的内容类型决定内部节点传入src/srcSet且图片未加载失败时渲染img图片元素否则传入icon时渲染el-icon图标两者都没有时渲染默认插槽中的字符内容。这一渲染优先级在 avatar.vue 模板 中体现得十分直观v-if(src || srcSet) !hasLoadError→v-else-ificon→v-else默认插槽。组件对外注册名称为ElAvatar包入口位于 packages/components/avatar/index.ts并配有独立的style子包。头像的视觉尺寸、圆角、背景与文字颜色均由主题变量驱动可在 packages/theme-chalk/src/avatar.scss 中查看其样式定义。基本用法shape 与 sizeAvatar 通过shape与size两个属性控制外观shape头像形状可选circle圆形默认或square圆角方形。size头像尺寸可以是number数字像素值如 50也可以是large | default | small三个预设枚举。参考官方示例 docs/examples/avatar/basic.vue一个覆盖圆形/方形与多尺寸的头像集合写法如下template div classdemo-basic div classsub-titlecircle/div div classdemo-basic--circle el-avatar :size50 :srccircleUrl / el-avatar :sizesmall :srccircleUrl / el-avatar :srccircleUrl / el-avatar :sizelarge :srccircleUrl / /div div classsub-titlesquare/div div classdemo-basic--circle el-avatar shapesquare :size50 :srcsquareUrl / el-avatar shapesquare :sizesmall :srcsquareUrl / el-avatar shapesquare :srcsquareUrl / el-avatar shapesquare :sizelarge :srcsquareUrl / /div /div /template尺寸的底层实现从 avatar.ts 的属性定义可以看到size同时接受Number与String类型并对字符串做了componentSizes枚举校验。而在 avatar.vue 中尺寸的实现方式分为两种数字尺寸通过 CSS 变量--el-avatar-size注入即sizeStyle计算属性中的ns.cssVarBlock({ size: addUnit(size.value) })将数字自动补上px单位枚举尺寸直接挂载修饰类名el-avatar--small/el-avatar--large由 SCSS 在 avatar.scss 中通过each $size in (small, large)覆盖--el-avatar-size变量。对应的单元测试avatar.test.tsx也验证了这两种路径数字 50 时断言内联样式包含--el-avatar-size: 50px;字符串small时断言类名包含el-avatar--small。三种类型图片、图标与字符Avatar 支持的三种内容形态见官方示例 docs/examples/avatar/types.vuetemplate div classdemo-type div el-avatar :iconUserFilled / /div div el-avatar srchttps://cube.elemecdn.com/0/88/03b0d39583f48206768a7534e55bcpng.png / /div div el-avatar user /el-avatar /div /div /template script setup langts import { UserFilled } from element-plus/icons-vue /script图片头像传入src可选配合alt、src-set、fit图标头像传入icon其类型为string | ComponenticonPropType可直接引用 element-plus/icons-vue 提供的图标组件字符头像不传src与icon直接在使用处放入文本如用户名首字母通过默认插槽渲染。图标模式会额外追加el-avatar--icon修饰类见 avatar.vue并放大字号以适配--el-avatar-icon-size。测试 avatar.test.tsx 验证了icon{markRaw(User)}会渲染出图标组件且带el-avatar--icon类。Fallback图片加载失败回退当图片头像的src加载出错时Avatar 会触发error事件并提供回退渲染能力。事件与回退机制error事件在 avatar.ts 中定义为(e: Event) void。底层逻辑位于 avatar.vue图片触发原生error时hasLoadError置为true同时抛出error事件模板据此隐藏img转而渲染icon或默认插槽中的回退内容。官方回退示例 docs/examples/avatar/fallback.vue 中图片加载失败后在插槽内放置一张本地备选图片template div classdemo-type el-avatar :size60 srchttps://empty errorerrorHandler img srchttps://cube.elemecdn.com/e/fd/0fc7d20532fdaf769a25683617711png.png / /el-avatar /div /template script langts setup const errorHandler () true /script关键细节src 变更后自动复位一个容易踩坑的细节是当src或srcSet发生变化时组件会通过watch将hasLoadError自动重置为falseavatar.vue从而允许重新加载新图片。测试用例 avatar.test.tsx 覆盖了src与srcSet两条路径从失败地址切换到成功地址后hasLoadError恢复为false且img重新出现。这意味着在头像地址动态变化如用户更换头像的场景下无需手动重置组件状态。Fit Container图片适配方式对于图片头像fit属性控制图片如何适配容器语义与 CSSobject-fit完全一致可选值值效果fill拉伸填充可能变形contain等比缩放完整显示可能留有空白cover等比缩放铺满容器裁切溢出部分默认值none保持原始尺寸不做缩放scale-down取none与contain中较小的结果在源码中fit的默认值为coveravatar.ts渲染时直接以内联样式object-fit: fit应用到img上avatar.vue。官方示例 docs/examples/avatar/fit.vue 以方形100px头像遍历展示五种适配效果测试用例 avatar.test.tsx 也逐一断言了五种fit值对应的内联object-fit样式。Avatar Group 头像组2.13.1从 2.13.1 版本起Element Plus 提供了el-avatar-group用于将多个头像成组展示并支持折叠collapse能力见官方示例 docs/examples/avatar/group.vue。基础分组template div classm-4 el-avatar-group el-avatar v-fornumber in 5 :keynumber :srccircleUrl / /el-avatar-group /div /templateel-avatar-group会通过 Vue 的provide向下注入size与shape上下文avatar-group.tsx、constants.ts组内未显式声明size/shape的单个 Avatar 会自动继承组的设置单个头像显式传入时则覆盖组级配置avatar.vue。测试 avatar.test.tsx 验证了组级sizesmall、shapesquare与个别头像large/circle覆盖的类名组合。折叠与 Tooltip 提示头像组还提供一组折叠相关属性collapse-avatars是否折叠超出数量的头像默认falsemax-collapse-avatars最多展示的头像数量默认1需配合collapse-avatars使用collapse-avatars-tooltip鼠标悬停折叠头像时是否通过 Tooltip 展示所有被隐藏的头像需配合collapse-avatars使用effectTooltip 主题内置dark/light默认lightplacementTooltip 出现位置支持top、top-start、top-end、bottom、bottom-start、bottom-end、left、left-start、left-end、right、right-start、right-end默认toppopper-class/popper-styleTooltip 自定义类名与样式collapse-class/collapse-style折叠头像自身的自定义类名与样式。折叠判定逻辑在 avatar-group.tsx当collapseAvatars为真且头像数量大于maxCollapseAvatars时将超出部分替换为一个内容为 NN 为隐藏数量的折叠头像若开启collapseAvatarsTooltip则用ElTooltip包裹Tooltip 内容中逐一会话式cloneVNode渲染所有隐藏头像。注意折叠头像会显式继承组的size/shape因此在使用max-collapse-avatars时其尺寸可能与组内其他头像保持一致。一个综合使用示例摘自 docs/examples/avatar/group.vuetemplate div classm-4 puse collapse-avatars-tooltip/p el-avatar-group collapse-avatars :max-collapse-avatars3 collapse-avatars-tooltip el-avatar v-fornumber in 5 :keynumber :srccircleUrl / /el-avatar-group /div /template对应测试 avatar.test.tsx 验证了折叠头像触发mouseenter后 Tooltip 出现并包含头像内容。属性定义完整清单见 avatar-group-props.ts其中popperClass/popperStyle直接复用了 Tooltip 的内容属性定义useTooltipContentProps保证了两组件样式行为的一致性。API 速查Avatar Attributes名称说明类型默认值icon图标类型头像的图标详见 Icon 组件string/Component—size头像尺寸number/large \| default \| small—shape头像形状circle \| square—src图片头像的图片来源string—src-set图片头像的原生srcset属性string—alt图片头像的原生alt属性string—fit图片如何适配容器同 CSSobject-fitfill \| contain \| cover \| none \| scale-downcoverAvatar Events名称说明类型error图片加载失败时触发(e: Event) voidAvatar Slots名称说明default自定义头像内容AvatarGroup Attributes名称说明类型默认值size控制组内头像尺寸number/large \| default \| small—shape控制组内头像形状circle \| square—collapse-avatars是否折叠头像booleanfalsecollapse-avatars-tooltip悬停折叠头像时是否展示全部被折叠头像需collapse-avatars为 truebooleanfalsemax-collapse-avatars最多展示的头像数量需collapse-avatars为 truenumber1effectTooltip 主题dark \| light/stringlightplacementTooltip 位置top \| top-start \| top-end \| bottom \| bottom-start \| bottom-end \| left \| left-start \| left-end \| right \| right-start \| right-endtoppopper-classTooltip 自定义类名stringpopper-styleTooltip 自定义样式string/object—collapse-class折叠头像自定义类名stringcollapse-style折叠头像自定义样式string/object—小结与延伸阅读Avatar 虽小但设计上覆盖了「内容形态切换、尺寸变量化、加载失败回退、组级上下文继承、折叠 Tooltip」等完整场景。想深入探究实现细节可按以下路径继续阅读当前仓库组件声明与类型packages/components/avatar/src/avatar.ts、packages/components/avatar/src/avatar-group-props.ts渲染与逻辑packages/components/avatar/src/avatar.vue、packages/components/avatar/src/avatar-group.tsx测试用例packages/components/avatar/tests/avatar.test.tsx样式变量packages/theme-chalk/src/avatar.scss官方示例docs/examples/avatar 目录下的basic.vue、types.vue、fallback.vue、fit.vue、group.vue在实际项目中建议优先为头像设置统一尺寸枚举或明确的数字像素值并为图片头像预留error回退内容当头像数量较多如参与成员、群成员列表时直接启用collapse-avatarscollapse-avatars-tooltip组合即可获得整洁且信息完整的展示效果。【免费下载链接】element-plus A Vue.js 3 UI Library made by Element team项目地址: https://gitcode.com/GitHub_Trending/el/element-plus创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考