Avatar 头像 - Semi Design

展示类 · Avatar

头像

头像，支持图片或字符展示。

API 文档

设计文档

代码演示

如何引入


import { Avatar, AvatarGroup } from '@douyinfe/semi-ui';

尺寸

可以通过 size 属性设置图标大小，支持extra-extra-small，extra-small，small，default，medium，large，extra-large。

颜色

Avatar 支持默认色板的 15 种颜色和白色，包括：amber、 blue、 cyan、 green、 grey、 indigo、 light-blue、 light-green、 lime、 orange、 pink、 purple、 red、 teal、 violet、 yellow。也可以通过 style 来自定义颜色样式。默认为grey。

自适应字符大小

字符类型的头像，字体大小会根据头像宽度自适应调整。使用gap调整字符头像距离左右两侧的像素大小。

图片

可以通过 src 设置图片格式的头像。

形状

Avatar 支持 circle、square 两种形状，默认为 circle。

事件

Avatar 支持 onClick、onMouseEnter、onMouseLeave。其中 hover 状态下可以通过 hoverMask 属性传入覆盖层的内容。覆盖层无默认样式。

顶部和底部 Slot

顶部

底部

额外边框

额外动效

通过 border={motion:true} 和 contentMotion 开启边框和内容区域的额外动效

头像组

可以通过 AvatarGroup 将 avatar 显示为组。

可以通过 maxCount 设置展示的头像数量。

可以通过 renderMore 自定义 more 标签。

可以通过 overlapFrom 控制头像组的覆盖方式。可选值有 start 和 end，分别表示左边覆盖右边和右边覆盖左边。默认值为 start。

API 参考

Avatar

属性	说明	类型	默认值
alt	图像的替代文本描述	string	-
border	额外边框（>=2.52.0）	{color?:string //颜色, motion?:boolean //是否开启动画} or boolean	-
bottomSlot	底部 Slot 配置（>= 2.52.0 ）	{ render?: () => React.ReactNode //完全控制渲染, shape?: "circle" or "square" // Slot 形状, text: React.ReactNode // Slot 内容, bgColor:string // Slot 背景色 textColor:string // 文字颜色 className:string style?:CSSProperties }	-
className	类名	string	-
color	指定头像的颜色，支持 `amber`、 `blue`、 `cyan`、 `green`、 `grey`、 `indigo`、 `light-blue`、 `light-green`、 `lime`、 `orange`、 `pink`、 `purple`、 `red`、 `teal`、 `violet`、 `yellow`	string	`grey`
contentMotion	头像内容区域动效（>=2.xx.0）	boolean	-
hoverMask	hover 时头像内容覆盖层	ReactNode	-
gap	字符头像距离左右两侧的像素大小	number	3
imgAttr	原生 img 属性 >=1.5.0	React.ImgHTMLAttributes<HTMLImageElement>	-
shape	指定头像的形状，支持 `circle`、`square`	string	`circle`
size	设置头像的大小，支持 `extra-extra-small`、`extra-small`、`small`、`default`、`medium`、`large`、`extra-large` 和合法的 width 属性值例如 "10px"	string	`medium`
src	图片类头像的资源地址	string	-
srcSet	设置图片类头像响应式资源地址	string	-
style	样式名	CSSProperties	-
topSlot	顶部 Slot 配置（>= 2.52.0 ）	{ render?: () => React.ReactNode //完全控制渲染, gradientStart?: string // 顶部背景渐变起始色 gradientEnd?: string // 顶部背景渐变结束色 text: React.ReactNode textColor:string //文字颜色 className:string style?:CSSProperties }	-
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` 和合法的 width 属性值例，如 "10px"	string	`medium`

Accessibility

Avatar 一般不用于操作，不需要被获取焦点。但当 Avatar 可以被点击操作时（如：Semi 官网上方的头像）需要被聚焦，并响应键盘 Enter 事件。
当 Avatar 与其他组件结合使用时，需要同时检查该组件的可访问性指南。
Avatar的alt属性可以被屏幕阅读器读取，使用头像组件时，请使用alt 属性解释头像的内容。


import React from 'react';
import { Avatar } from '@douyinfe/semi-ui';

() => {
    return (
        <>
            {/* Good case */ }
            <Avatar
                alt="一只可爱的猫咪"
                src="https://lf3-static.bytednsdoc.com/obj/eden-cn/ptlz_zlp/ljhwZthlaukjlkulzlp/root-web-sites/dy.png"
                style={{ margin: 4 }}
            />
            <Avatar
                alt="姜鹏志"
                src="https://lf3-static.bytednsdoc.com/obj/eden-cn/ptlz_zlp/ljhwZthlaukjlkulzlp/root-web-sites/dy.png"
                style={{ margin: 4 }}
            />
            {/* Bad case */ }
            <Avatar
                alt=""
                src="https://lf3-static.bytednsdoc.com/obj/eden-cn/ptlz_zlp/ljhwZthlaukjlkulzlp/root-web-sites/dy.png"
                style={{ margin: 4 }}
            />
            <Avatar
                alt="姜鹏志的图片"
                src="https://lf3-static.bytednsdoc.com/obj/eden-cn/ptlz_zlp/ljhwZthlaukjlkulzlp/root-web-sites/dy.png"
                style={{ margin: 4 }}
            />
        </>
    );
};