Semi Design Avatar 头像组件完全指南:尺寸、颜色、Slot 扩展与 AvatarGroup 头像组实战
Semi Design Avatar 头像组件完全指南:尺寸、颜色、Slot 扩展与 AvatarGroup 头像组实战
Avatar(头像)是 Semi Design React UI 库中用于展示用户身份信息的核心组件,支持图片与字符两种形态,并提供从极小的 20px 到 128px 的七档标准尺寸、17 种预设颜色、顶部/底部 Slot 装饰、额外描边动效以及 AvatarGroup 头像组聚合能力。本文将基于官方文档并结合 Avatar 组件源码、Foundation 逻辑层 与 样式变量定义,系统讲解 Avatar 与 AvatarGroup 的完整 API、实现原理与实战用法,帮助你快速构建社交、直播、协作等场景的用户头像体系。
如何引入
Avatar 与 AvatarGroup 均从 @douyinfe/semi-ui 统一入口导出,无需额外安装子包:
import { Avatar, AvatarGroup } from '@douyinfe/semi-ui';
从源码看,Avatar 是一个继承 BaseComponent 的 class 组件,内部通过 AvatarFoundation 处理状态逻辑(见 index.tsx);AvatarGroup 则是基于 PureComponent 的聚合容器,通过 React.cloneElement 向每个子 Avatar 注入统一的尺寸与形状(见 avatarGroup.tsx)。
尺寸(Size)
通过 size 属性设置头像尺寸,支持以下七档预设值与任意合法的 CSS 宽度值(如 "10px"):
extra-extra-small、extra-small、small、default、medium、large、extra-large
import React from 'react';
import { Avatar } from '@douyinfe/semi-ui';
() => (
<div>
<Avatar size="extra-extra-small" style={{ margin: 4 }} alt='User'>U</Avatar>
<Avatar size="extra-small" style={{ margin: 4 }} alt='User'>U</Avatar>
<Avatar size="small" style={{ margin: 4 }} alt='User'>U</Avatar>
<Avatar size="default" style={{ margin: 4 }} alt='User'>U</Avatar>
<Avatar style={{ margin: 4 }} alt='User'>U</Avatar>
<Avatar size="large" style={{ margin: 4 }} alt='User'>U</Avatar>
<Avatar size="extra-large" style={{ margin: 4 }} alt='User'>U</Avatar>
</div>
);
size 的默认值为 medium(见 index.tsx)。当传入的 size 不在预设集合内时,组件会将 size 直接作为宽度与高度写入行内样式({ width: size, height: size }),因此传 "10px" 这类合法宽度值即可实现任意自定义尺寸(见 index.tsx)。
各预设尺寸在 variables.scss 中定义了具体像素值,便于理解实际渲染效果:
| 预设值 | 头像宽高 | 文本字号 |
|---|---|---|
extra-extra-small |
20px | 10px |
extra-small |
24px | 10px |
small |
32px | — |
default |
40px | — |
medium |
48px | — |
large |
72px | — |
extra-large |
128px | 64px |
颜色(Color)
字符型头像支持 17 种预设颜色,通过 color 属性指定,默认值为 grey:
white、amber、blue、cyan、green、grey、indigo、light-blue、light-green、lime、orange、pink、purple、red、teal、violet、yellow
import React from 'react';
import { Avatar } from '@douyinfe/semi-ui';
() => (
<div>
<Avatar style={{ margin: 4 }} alt='Alice Swift'>AS</Avatar>
<Avatar color="red" style={{ margin: 4 }} alt='Bob Matteo'>BM</Avatar>
<Avatar color="light-blue" style={{ margin: 4 }} alt='Taylor Joy'>TJ</Avatar>
<Avatar style={{ color: '#f56a00', backgroundColor: '#fde3cf', margin: 4 }} alt='Zank Lance'>ZL</Avatar>
<Avatar style={{ backgroundColor: '#87d068', margin: 4 }} alt='Youself Zhang'>YZ</Avatar>
</div>
);
从实现细节看:
- 预设色集合在 constants.ts 中统一维护,
propTypes也会据此校验传入值; - 渲染时颜色以
semi-avatar-${color}的 class 形式挂载(见 index.tsx),具体背景色由 avatar.scss 中的色板映射生成; - 当
src有效(图片头像)时,颜色 class 不会生效(${prefixCls}-${color}仅在!isImg时添加),避免颜色覆盖图片展示; - 除预设色外,随时可通过
style属性自由定制背景色与文字色(如示例中的#f56a00/#fde3cf/#87d068)。
字符头像的自适应缩放与 gap
字符型头像的字体大小会根据头像宽度自适应调整,保证长文本(如全名)也能完整展示在头像内。这是通过 gap 属性配合内部 scale 状态实现的:gap 表示字符距头像左右两侧的像素距离,默认值为 3。
import React from 'react';
import { Avatar } from '@douyinfe/semi-ui';
() => (
<div>
<Avatar style={{ margin: 4 }}>AS</Avatar>
<Avatar style={{ margin: 4 }} gap={4}>Semi</Avatar>
<Avatar style={{ margin: 4 }} gap={10}>Semi</Avatar>
</div>
);
其底层算法位于 foundation.ts 的 changeScale 方法中:
- 挂载时若
children是字符串,Foundation 会在init()阶段调用changeScale(); - 获取头像节点宽度
nodeWidth与文本节点宽度stringNodeWidth; - 若
gap * 2 < nodeWidth,则计算缩放比:scale = (nodeWidth - gap * 2) / stringNodeWidth(当文本不超宽时结果为 1,即不缩放); - 缩放值写入 state,最终以
transform: scale(...)应用在文本外层.semi-avatar-content上(见 index.tsx)。
当 children 内容更新时,componentDidUpdate 会再次触发 changeScale 重新计算(见 index.tsx)。对应测试用例也验证了 transform: scale 的断言(见 avatar.test.js)。
图片头像与加载失败处理
通过 src 设置图片资源地址即可渲染图片头像,srcSet 可用于响应式图片资源,alt 作为替代文本;imgAttr 可透传任意原生 <img> 属性(如 loading、referrerPolicy 等)。
import React from 'react';
import { Avatar } from '@douyinfe/semi-ui';
() => (
<div>
<Avatar
alt="beautiful cat"
src="https://lf3-static.bytednsdoc.com/obj/eden-cn/ptlz_zlp/ljhwZthlaukjlkulzlp/root-web-sites/dy.png"
style={{ margin: 4 }}
/>
<Avatar
alt="cute cat"
size="small"
src="https://lf3-static.bytednsdoc.com/obj/eden-cn/ptlz_zlp/ljhwZthlaukjlkulzlp/root-web-sites/dy.png"
style={{ margin: 4 }}
/>
</div>
);
图片加载失败(onerror)时组件默认会回退为字符/子内容展示,这一 fallback 行为通过 onError 回调控制:
onError返回false时,关闭默认回退行为(即保持图片区域不切换为字符);- 其他情况下(不传或返回非
false),内部将isImgExist置为false,走字符渲染分支。
对应实现位于 foundation.ts,测试用例 avatar.test.js 覆盖了该回调的触发。此外,当 src 在运行期变化时,componentDidUpdate 会重建 Image 对象预加载新地址以更新展示状态(见 index.tsx)。
形状(Shape)
Avatar 支持 circle(圆形)与 square(方形)两种形状,默认 circle。方形头像的圆角根据尺寸自适应(如 default 为 3px、extra-large 为 12px,见 variables.scss)。
import React from 'react';
import { Avatar } from '@douyinfe/semi-ui';
() => (
<div>
<Avatar style={{ margin: 4 }} alt="User">U</Avatar>
<Avatar shape="square" style={{ margin: 4 }} alt="User">U</Avatar>
</div>
);
事件与 hover 覆盖层
Avatar 支持 onClick、onMouseEnter、onMouseLeave 三个事件回调。其中 hover 状态可通过 hoverMask 属性传入覆盖层内容(覆盖层无默认样式,需要自行定义样式与布局):
import React from 'react';
import { Avatar } from '@douyinfe/semi-ui';
import { IconCamera } from '@douyinfe/semi-icons';
() => {
const style = {
backgroundColor: 'var(--semi-color-overlay-bg)',
height: '100%',
width: '100%',
display: 'flex',
alignItems: 'center',
justifyContent: 'center',
};
const hover = (
<div style={style}>
<IconCamera />
</div>
);
return (
<Avatar hoverMask={hover} color="red" alt='Bob Downton'>BD</Avatar>
);
};
hover 覆盖层通常用于「点击更换头像/查看大图」等交互场景,可将 hoverMask 与 onClick 组合使用。实现上,鼠标移入时 notifyEnter 将 hoverMask 写入 hoverContent 状态并渲染 .semi-avatar-hover 覆盖层,移出时清空(见 index.tsx)。
顶部与底部 Slot(topSlot / bottomSlot)
自 v2.52.0 起,Avatar 支持通过 topSlot 与 bottomSlot 在头像顶部/底部叠加内容,非常适合直播「LIVE」角标、在线状态、加号按钮等场景。
组合示例
import React from 'react';
import { Avatar } from '@douyinfe/semi-ui';
import { IconPlus } from '@douyinfe/semi-icons';
<Avatar
alt="beautiful cat"
src="https://lf3-static.bytednsdoc.com/obj/eden-cn/ptlz_zlp/ljhwZthlaukjlkulzlp/root-web-sites/dy.png"
style={{ margin: 4 }}
size="large"
border={{color:"#FE2C55",motion:true}}
contentMotion={true}
topSlot={{
text: "LIVE",
gradientStart:"rgb(255,23,100)",
gradientEnd:"rgb(237,52,148)"
}}
bottomSlot={{
shape: "circle",
bgColor:"#FE2C55",
text: <IconPlus/>
}}
/>
topSlot(顶部)
topSlot 配置项支持:text(内容)、gradientStart / gradientEnd(顶部背景渐变起始/结束色)、textColor(文字颜色)、className、style,以及 render(完全接管渲染,传入后其余字段忽略)。
()=>{
return <div>
<Avatar color="amber" topSlot={{
text: "LIVE",
gradientStart:"rgb(255,23,100)",
gradientEnd:"rgb(237,52,148)"
}}>T</Avatar>
<Avatar color="amber" size="large" topSlot={{
text: "LIVE",
gradientStart:"rgb(255,23,100)",
gradientEnd:"rgb(237,52,148)"
}}>T</Avatar>
<Avatar color="amber" size="extra-large" topSlot={{
text: "LIVE",
gradientStart:"rgb(255,23,100)",
gradientEnd:"rgb(237,52,148)"
}}>T</Avatar>
</div>
}
实现要点(见 index.tsx):顶部 Slot 由 SVG 渐变背景(TopSlotSvg,默认渐变色为 var(--semi-color-primary))叠加文字层组成,其定位通过各尺寸在 variables.scss 中预定义的偏移量(shift)与缩放比例(scale)控制,以保证不同尺寸下角标贴合头像边缘。
bottomSlot(底部)
bottomSlot 配置项支持:text(内容)、shape(circle 圆形 / square 方形)、bgColor(背景色)、textColor(文字颜色)、className、style,以及 render(完全接管渲染)。
()=>{
return <div>
<Avatar color="amber" bottomSlot={{
shape: "square",
bgColor:'#FE2C55',
text: "LIVE"
}}>T</Avatar>
<Avatar color="amber" size="large" bottomSlot={{
shape: "square",
bgColor:'#FE2C55',
text: "LIVE"
}}>T</Avatar>
<Avatar color="amber" size="extra-large" bottomSlot={{
shape: "square",
bgColor:'#FE2C55',
text: "LIVE"
}}>T</Avatar>
<br/><br/><br/>
<Avatar color="amber" bottomSlot={{
shape: "circle",
bgColor:'#FE2C55',
text: <IconPlus/>
}}>T</Avatar>
<Avatar color="amber" size="large" bottomSlot={{
shape: "circle",
bgColor:'#FE2C55',
text: <IconPlus/>
}}>T</Avatar>
<Avatar color="amber" size="extra-large" bottomSlot={{
shape: "circle",
bgColor:'#FE2C55',
text: <IconPlus/>
}}>T</Avatar>
</div>
}
注意:当 bottomSlot 配置了 render 时,组件会优先执行 render() 并忽略其余字段(见 index.tsx)。底部 Slot 的圆形/方形尺寸与字号同样按头像尺寸在 variables.scss 中预设(如 medium 圆形角标 18px、square 圆角 4px)。
额外边框与内容动效(border / contentMotion)
自 v2.52.0 起,Avatar 支持额外描边装饰,适用于需要视觉强调的直播、动态等场景。
额外边框
border 可传 boolean 或对象 { color?: string, motion?: boolean }:
()=>{
return <div>
<Avatar color="amber" border={true} style={{marginRight:'8px'}}>T</Avatar>
<Avatar color="amber" border={true} style={{marginRight:'8px'}}>T</Avatar>
<Avatar color="amber" border={true} style={{marginRight:'8px'}}>T</Avatar>
</div>
}
边框默认使用 var(--semi-color-primary) 作为描边色,宽 1.5px,与头像本体留有 2px 间距(见 variables.scss)。从源码看,border 渲染时会在头像外包裹一层 position: relative 容器并追加 .semi-avatar-additionalBorder 元素;当 border.motion 为 true 时还会额外渲染一层带动画 class 的描边,用于实现流光/呼吸效果(见 index.tsx)。
内容动效
通过 contentMotion 开启头像内容区域的额外动效,可与 border.motion 组合使用:
()=>{
return <div>
<Avatar color="amber" border={true} style={{marginRight:'8px'}} borderMotion={true} contentMotion={true}>T</Avatar>
<Avatar color="amber" border={true} size={"large"} style={{marginRight:'8px'}} borderMotion={true} contentMotion={true}>T</Avatar>
<Avatar color="amber" border={true} size={"extra-large"} style={{marginRight:'8px'}} borderMotion={true} contentMotion={true}>T</Avatar>
</div>
}
contentMotion 为 true 时,头像根元素会挂载 .semi-avatar-animated class(见 index.tsx),具体的动画 keyframes 定义在 animation.scss 中。
AvatarGroup 头像组
AvatarGroup 将多个 Avatar 以组的形式展示,适合团队成员、点赞用户列表等聚合场景,并支持堆叠覆盖、数量截断与自定义「更多」标签。
基础使用
import React from 'react';
import { Avatar, AvatarGroup } from '@douyinfe/semi-ui';
() => (
<div>
<AvatarGroup>
<Avatar color="red" alt='Lisa LeBlanc'>LL</Avatar>
<Avatar alt='Caroline Xiao'>CX</Avatar>
<Avatar color="amber" alt='Rafal Matin'>RM</Avatar>
<Avatar style={{ color: '#f56a00', backgroundColor: '#fde3cf' }} alt='Zank Lance'>ZL</Avatar>
<Avatar style={{ backgroundColor: '#87d068' }} alt='Youself Zhang'>YZ</Avatar>
</AvatarGroup>
</div>
);
maxCount 数量截断
通过 maxCount 设置展示的头像数量,超出部分自动折叠为 +N 标签:
import React from 'react';
import { Avatar, AvatarGroup } from '@douyinfe/semi-ui';
() => (
<div>
<AvatarGroup maxCount={3}>
<Avatar color="red" alt='Lisa LeBlanc'>LL</Avatar>
<Avatar alt='Caroline Xiao'>CX</Avatar>
<Avatar color="amber" alt='Rafal Matin'>RM</Avatar>
<Avatar style={{ color: '#f56a00', backgroundColor: '#fde3cf' }} alt='Zank Lance'>ZL</Avatar>
<Avatar style={{ backgroundColor: '#87d068' }} alt='Youself Zhang'>YZ</Avatar>
</AvatarGroup>
</div>
);
实现上,maxCount 为数字时,AvatarGroup 通过 getMergeAvatars 将头像数组切分为「正常展示部分 + 剩余部分」,并为剩余头像自动生成一个 +N 的 Avatar 追加到末尾(见 avatarGroup.tsx)。测试用例 avatarGroup.test.js 对该行为进行了断言。
renderMore 自定义「更多」标签
renderMore 接收两个参数:restNumber(剩余数量)与 restAvatars(剩余头像数组),返回自定义 ReactNode。下面示例将剩余头像放入 Popover 中展示:
import React from 'react';
import { Avatar, AvatarGroup, Popover } from '@douyinfe/semi-ui';
function Demo() {
const renderMore = (restNumber, restAvatars) => {
const content = (
restAvatars.map((avatar, index) => {
return (
<div style={{ paddingBottom: '12px' }} key={index}>
{React.cloneElement(avatar, { size: 'extra-small' })}
<span style={{ marginLeft: 8, fontSize: 14 }}>This is a sentence</span>
</div>
);
})
);
return (
<Popover content={content} autoAdjustOverflow={false} position={'bottomRight'} style={{ padding: '12px 8px', paddingBottom: 0 }}>
<Avatar>{`+${restNumber}`}</Avatar>
</Popover>
);
};
return (
<AvatarGroup maxCount={3} renderMore={renderMore}>
<Avatar color="red" alt='Lisa LeBlanc'>LL</Avatar>
<Avatar alt='Caroline Xiao'>CX</Avatar>
<Avatar color="amber" alt='Rafal Matin'>RM</Avatar>
<Avatar style={{ color: '#f56a00', backgroundColor: '#fde3cf' }} alt='Zank Lance'>ZL</Avatar>
<Avatar style={{ backgroundColor: '#87d068' }} alt='Youself Zhang'>YZ</Avatar>
</AvatarGroup>
);
}
默认的 +N 标签也会自动聚合剩余头像的 alt / 字符内容作为无障碍描述(见 avatarGroup.tsx)。
overlapFrom 覆盖方向
overlapFrom 控制头像堆叠时的覆盖方向:start(左侧头像覆盖右侧,默认值)或 end(右侧头像覆盖左侧):
import React from 'react';
import { Avatar, AvatarGroup } from '@douyinfe/semi-ui';
() => (
<div>
<div>
<AvatarGroup overlapFrom={'start'}>
<Avatar color="red" alt='Lisa LeBlanc'>LL</Avatar>
<Avatar alt='Caroline Xiao'>CX</Avatar>
<Avatar color="amber" alt='Rafal Matin'>RM</Avatar>
<Avatar style={{ color: '#f56a00', backgroundColor: '#fde3cf' }} alt='Zank Lance'>ZL</Avatar>
<Avatar style={{ backgroundColor: '#87d068' }} alt='Youself Zhang'>YZ</Avatar>
</AvatarGroup>
</div>
<div>
<AvatarGroup overlapFrom={'end'}>
<Avatar color="red" alt='Lisa LeBlanc'>LL</Avatar>
<Avatar alt='Caroline Xiao'>CX</Avatar>
<Avatar color="amber" alt='Rafal Matin'>RM</Avatar>
<Avatar style={{ color: '#f56a00', backgroundColor: '#fde3cf' }} alt='Zank Lance'>ZL</Avatar>
<Avatar style={{ backgroundColor: '#87d068' }} alt='Youself Zhang'>YZ</Avatar>
</AvatarGroup>
</div>
</div>
);
堆叠间距按尺寸预设:例如 extra-extra-small 的负左边距为 -4px、medium 为 -12px、extra-large 为 -32px(见 variables.scss),同时头像组内的头像带有白/浅色描边(--semi-color-bg-1)以区分层次。AvatarGroup 的 size 与 shape 默认分别为 medium 与 circle,并会统一应用到每个子 Avatar 上(见 avatarGroup.tsx)。
API 参考
Avatar
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| alt | 图像的替代文本描述 | string | - |
| border | 额外边框(>=2.52.0),{ color?: string //颜色, motion?: boolean //是否开启动画 } 或 boolean |
object / boolean | - |
| bottomSlot | 底部 Slot 配置(>= 2.52.0):render?: () => ReactNode //完全控制渲染、`shape?: "circle" |
"square" //Slot 形状、text: ReactNode //Slot 内容、bgColor: string //Slot 背景色、textColor: string //文字颜色、className: string、style?: CSSProperties` |
object |
| className | 类名 | string | - |
| color | 头像颜色:amber、blue、cyan、green、grey、indigo、light-blue、light-green、lime、orange、pink、purple、red、teal、violet、yellow、white |
string | grey |
| contentMotion | 头像内容区域动效(>=2.xx.0) | boolean | - |
| gap | 字符头像距左右两侧的像素大小 | number | 3 |
| hoverMask | hover 时头像内容覆盖层 | ReactNode | - |
| imgAttr | 原生 img 属性 | React.ImgHTMLAttributes<HTMLImageElement> | - |
| shape | 头像形状:circle、square |
string | circle |
| size | 头像大小:extra-extra-small、extra-small、small、default、medium、large、extra-large 及合法宽度值(如 "10px") |
string | medium |
| src | 图片类头像的资源地址 | string | - |
| srcSet | 图片类头像的响应式资源地址 | string | - |
| style | 样式 | CSSProperties | - |
| topSlot | 顶部 Slot 配置(>= 2.52.0):render?: () => ReactNode //完全控制渲染、gradientStart?: string //顶部背景渐变起始色、gradientEnd?: string //顶部背景渐变结束色、text: ReactNode、textColor: string //文字颜色、className: string、style?: CSSProperties |
object | - |
| onClick | 单击头像的回调 | (e: Event) => void | - |
| onError | 图片加载失败事件,返回 false 关闭组件默认的 fallback 行为 |
(e: Event) => boolean | - |
| onMouseEnter | MouseEnter 事件回调 | (e: Event) => void | - |
| onMouseLeave | MouseLeave 事件回调 | (e: Event) => void | - |
AvatarGroup
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| maxCount | 最大展示数量,超出后显示 +N | number | - |
| overlapFrom | 头像覆盖方向:start、end |
string | start |
| renderMore | 自定义渲染 more 标签 | (restNumber: number, restAvatars: ReactNode[]) => ReactNode | - |
| shape | 头像形状:circle、square |
string | circle |
| size | 头像大小:extra-extra-small、extra-small、small、default、medium、large、extra-large 及合法宽度值(如 "10px") |
string | medium |
Accessibility 无障碍
- Avatar 一般不用于操作,无需获取焦点;但当 Avatar 可被点击(如 Semi 官网顶部的头像)时,需要支持聚焦并响应键盘
Enter事件。源码中当传入onClick时,组件会自动挂载tabIndex: 0与onKeyDown处理(Enter触发点击、Escape失焦),见 index.tsx; - 当 Avatar 与其他组件组合使用时,需同时遵循该组件的无障碍指南;
alt属性可被屏幕阅读器读取,使用 Avatar 时必须通过alt说明头像内容;可点击头像的alt还会自动拼接clickable Avatar:前缀,帮助读屏用户理解其可交互性(见 index.tsx)。
import React from 'react';
import { Avatar } from '@douyinfe/semi-ui';
() => {
return (
<>
{/* 良好实践:alt 描述内容 */}
<Avatar
alt="A cut cat"
src="https://lf3-static.bytednsdoc.com/obj/eden-cn/ptlz_zlp/ljhwZthlaukjlkulzlp/root-web-sites/dy.png"
style={{ margin: 4 }}
/>
<Avatar
alt="Jiang Pengzhi"
src="https://lf3-static.bytednsdoc.com/obj/eden-cn/ptlz_zlp/ljhwZthlaukjlkulzlp/root-web-sites/dy.png"
style={{ margin: 4 }}
/>
{/* 反面示例:alt 为空 */}
<Avatar
alt=""
src="https://lf3-static.bytednsdoc.com/obj/eden-cn/ptlz_zlp/ljhwZthlaukjlkulzlp/root-web-sites/dy.png"
style={{ margin: 4 }}
/>
{/* 反面示例:无需在 alt 中包含 "picture"/"image" 等冗余描述 */}
<Avatar
alt="Picture of Jiang Pengzhi"
src="https://lf3-static.bytednsdoc.com/obj/eden-cn/ptlz_zlp/ljhwZthlaukjlkulzlp/root-web-sites/dy.png"
style={{ margin: 4 }}
/>
</>
);
};
对于字符型头像,即使未传 alt,组件也会自动以字符内容作为 aria-label(tempAlt = alt ?? children),并在可点击时拼接 clickable Avatar: 前缀(见 index.tsx)。
设计变量(Design Tokens)
Avatar 的视觉表现完全基于 Semi Design 的设计变量(Design Tokens)体系。上文涉及的尺寸、圆角、描边、间距等均定义于 variables.scss,并通过 --semi-* CSS 变量接入主题定制能力,例如:
- 头像描边色:
--semi-color-bg-1 - 聚焦轮廓色:
--semi-color-primary-light-active - 顶部 Slot 渐变默认色:
--semi-color-primary - 额外描边默认色:
--semi-color-primary
这意味着你可以通过 Semi Design 的主题定制机制(如 ConfigProvider 或自定义主题包)统一调整头像组件的观感,使其融入自有设计体系,无需改动组件代码。
小结
Semi Design 的 Avatar 组件以「图片 + 字符」双形态为基础,配合七档预设尺寸、17 种预设色、自适应文本缩放、图片 fallback、hover 覆盖层,以及自 v2.52.0 加入的 topSlot / bottomSlot 角标与额外边框动效,足以覆盖从基础用户头像到直播、社交聚合场景的绝大部分需求;AvatarGroup 则通过 maxCount、overlapFrom、renderMore 提供了灵活的头像组聚合与截断方案。配合源码中 Foundation 层的状态管理(foundation.ts)与 Design Token 化的样式变量,开发者既能快速上手,也能深度定制到自有设计体系。