Semi Design Avatar 头像组件完全指南:尺寸、颜色、Slot 扩展与 AvatarGroup 头像组实战

原创2026-09-23 23:28:381,924 阅读
文章标签:前端UI组件设计系统

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 方法中:

  1. 挂载时若 children 是字符串,Foundation 会在 init() 阶段调用 changeScale();
  2. 获取头像节点宽度 nodeWidth 与文本节点宽度 stringNodeWidth;
  3. 若 gap * 2 < nodeWidth,则计算缩放比:scale = (nodeWidth - gap * 2) / stringNodeWidth(当文本不超宽时结果为 1,即不缩放);
  4. 缩放值写入 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 化的样式变量,开发者既能快速上手,也能深度定制到自有设计体系。

登录后查看全文
semi-design