--- localeCode: zh-CN order: 62 category: 展示类 title: Avatar 头像 icon: doc-avatar brief: 头像，支持图片或字符展示。 --- ## 代码演示 ### 如何引入 ```jsx import import { Avatar, AvatarGroup } from '@douyinfe/semi-ui'; ``` ### 尺寸 可以通过 `size` 属性设置图标大小，支持`extra-extra-small`，`extra-small`，`small`，`default`，`medium`，`large`，`extra-large`。 ```jsx live=true import React from 'react'; import { Avatar } from '@douyinfe/semi-ui'; () => (
U U U U U U U
); ``` ### 颜色 Avatar 支持默认色板的 15 种颜色和白色，包括：`amber`、 `blue`、 `cyan`、 `green`、 `grey`、 `indigo`、 `light-blue`、 `light-green`、 `lime`、 `orange`、 `pink`、 `purple`、 `red`、 `teal`、 `violet`、 `yellow`。也可以通过 `style` 来自定义颜色样式。默认为`grey`。 ```jsx live=true import React from 'react'; import { Avatar } from '@douyinfe/semi-ui'; () => (
AS BM TJ ZL YZ
); ``` ### 自适应字符大小 字符类型的头像，字体大小会根据头像宽度自适应调整。使用`gap`调整字符头像距离左右两侧的像素大小。 ```jsx live=true import React from 'react'; import { Avatar } from '@douyinfe/semi-ui'; () => (
AS Semi Semi
); ``` ### 图片 可以通过 `src` 设置图片格式的头像。 ```jsx live=true import React from 'react'; import { Avatar } from '@douyinfe/semi-ui'; () => (
); ``` ### 形状 Avatar 支持 `circle`、`square` 两种形状，默认为 `circle`。 ```jsx live=true import React from 'react'; import { Avatar } from '@douyinfe/semi-ui'; () => (
U U
); ``` ### 事件 Avatar 支持 `onClick`、`onMouseEnter`、`onMouseLeave`。其中 `hover` 状态下可以通过 `hoverMask` 属性传入覆盖层的内容。覆盖层无默认样式。 ```jsx live=true 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 = (
); return ( BD ); }; ``` ### 顶部和底部 Slot ```jsx live=true import React from 'react'; import { Avatar } from '@douyinfe/semi-ui'; }} /> ``` #### 顶部 ```jsx live=true ()=>{ return
T T T
} ``` #### 底部 ```jsx live=true ()=>{ return
T T T


}}>T }}>T }}>T
} ``` ### 额外边框 ```jsx live=true ()=>{ return
T T T
} ``` ### 额外动效 通过 `border={motion:true}` 和 contentMotion 开启边框和内容区域的额外动效 ```jsx live=true ()=>{ return
T T T
} ``` ### 头像组 可以通过 AvatarGroup 将 `avatar` 显示为组。 ```jsx live=true import React from 'react'; import { AvatarGroup, Avatar } from '@douyinfe/semi-ui'; () => (
LL CX RM ZL YZ
); ``` 可以通过 `maxCount` 设置展示的头像数量。 ```jsx live=true import React from 'react'; import { AvatarGroup, Avatar } from '@douyinfe/semi-ui'; () => (
LL CX RM ZL YZ
); ``` 可以通过 `renderMore` 自定义 more 标签。 ```jsx live=true import React from 'react'; import { AvatarGroup, Avatar, Popover } from '@douyinfe/semi-ui'; function Demo() { const renderMore = (restNumber, restAvatars) => { const content = restAvatars.map((avatar, index) => { return (
{React.cloneElement(avatar, { size: 'extra-small' })} 这是段文字描述
); }); return ( {`+${restNumber}`} ); }; return ( LL CX RM ZL YZ ); } ``` 可以通过 `overlapFrom` 控制头像组的覆盖方式。可选值有 `start` 和 `end`，分别表示左边覆盖右边和右边覆盖左边。默认值为 `start`。 ```jsx live=true import React from 'react'; import { AvatarGroup, Avatar } from '@douyinfe/semi-ui'; () => (
LL CX RM ZL YZ
LL CX RM ZL YZ
); ``` ## 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 属性 | React.ImgHTMLAttributes | - | | 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` 属性解释头像的内容。 ```jsx import React from 'react'; import { Avatar } from '@douyinfe/semi-ui'; () => { return ( <> {/* Good case */ } {/* Bad case */ } ); }; ``` ## 设计变量