尧图网站建设 
前端UI组件设计系统【免费下载链接】semi-designA modern, comprehensive, flexible design system and React UI library, AI-friendly built-in.Provide 3000 Design Tokens, easy to build your design system. Make Semi Design to Any Design. Design to Code in one click项目地址https://gitcode.com/gh_mirrors/se/semi-design点击查看免费下载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.tsxAvatarGroup 则是基于PureComponent的聚合容器通过React.cloneElement向每个子 Avatar 注入统一的尺寸与形状见 avatarGroup.tsx。尺寸Size通过size属性设置头像尺寸支持以下七档预设值与任意合法的 CSS 宽度值如10pxextra-extra-small、extra-small、small、default、medium、large、extra-largeimport React from react; import { Avatar } from douyinfe/semi-ui; () ( div Avatar sizeextra-extra-small style{{ margin: 4 }} altUserU/Avatar Avatar sizeextra-small style{{ margin: 4 }} altUserU/Avatar Avatar sizesmall style{{ margin: 4 }} altUserU/Avatar Avatar sizedefault style{{ margin: 4 }} altUserU/Avatar Avatar style{{ margin: 4 }} altUserU/Avatar Avatar sizelarge style{{ margin: 4 }} altUserU/Avatar Avatar sizeextra-large style{{ margin: 4 }} altUserU/Avatar /div );size的默认值为medium见 index.tsx。当传入的size不在预设集合内时组件会将size直接作为宽度与高度写入行内样式{ width: size, height: size }因此传10px这类合法宽度值即可实现任意自定义尺寸见 index.tsx。各预设尺寸在 variables.scss 中定义了具体像素值便于理解实际渲染效果预设值头像宽高文本字号extra-extra-small20px10pxextra-small24px10pxsmall32px—default40px—medium48px—large72px—extra-large128px64px颜色Color字符型头像支持 17 种预设颜色通过color属性指定默认值为greywhite、amber、blue、cyan、green、grey、indigo、light-blue、light-green、lime、orange、pink、purple、red、teal、violet、yellowimport React from react; import { Avatar } from douyinfe/semi-ui; () ( div Avatar style{{ margin: 4 }} altAlice SwiftAS/Avatar Avatar colorred style{{ margin: 4 }} altBob MatteoBM/Avatar Avatar colorlight-blue style{{ margin: 4 }} altTaylor JoyTJ/Avatar Avatar style{{ color: #f56a00, backgroundColor: #fde3cf, margin: 4 }} altZank LanceZL/Avatar Avatar style{{ backgroundColor: #87d068, margin: 4 }} altYouself ZhangYZ/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 altbeautiful cat srchttps://lf3-static.bytednsdoc.com/obj/eden-cn/ptlz_zlp/ljhwZthlaukjlkulzlp/root-web-sites/dy.png style{{ margin: 4 }} / Avatar altcute cat sizesmall srchttps://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。形状ShapeAvatar 支持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 }} altUserU/Avatar Avatar shapesquare style{{ margin: 4 }} altUserU/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} colorred altBob DowntonBD/Avatar ); };hover 覆盖层通常用于「点击更换头像/查看大图」等交互场景可将hoverMask与onClick组合使用。实现上鼠标移入时notifyEnter将hoverMask写入hoverContent状态并渲染.semi-avatar-hover覆盖层移出时清空见 index.tsx。顶部与底部 SlottopSlot / 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 altbeautiful cat srchttps://lf3-static.bytednsdoc.com/obj/eden-cn/ptlz_zlp/ljhwZthlaukjlkulzlp/root-web-sites/dy.png style{{ margin: 4 }} sizelarge 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 coloramber topSlot{{ text: LIVE, gradientStart:rgb(255,23,100), gradientEnd:rgb(237,52,148) }}T/Avatar Avatar coloramber sizelarge topSlot{{ text: LIVE, gradientStart:rgb(255,23,100), gradientEnd:rgb(237,52,148) }}T/Avatar Avatar coloramber sizeextra-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内容、shapecircle圆形 /square方形、bgColor背景色、textColor文字颜色、className、style以及render完全接管渲染。(){ return div Avatar coloramber bottomSlot{{ shape: square, bgColor:#FE2C55, text: LIVE }}T/Avatar Avatar coloramber sizelarge bottomSlot{{ shape: square, bgColor:#FE2C55, text: LIVE }}T/Avatar Avatar coloramber sizeextra-large bottomSlot{{ shape: square, bgColor:#FE2C55, text: LIVE }}T/Avatar br/br/br/ Avatar coloramber bottomSlot{{ shape: circle, bgColor:#FE2C55, text: IconPlus/ }}T/Avatar Avatar coloramber sizelarge bottomSlot{{ shape: circle, bgColor:#FE2C55, text: IconPlus/ }}T/Avatar Avatar coloramber sizeextra-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 coloramber border{true} style{{marginRight:8px}}T/Avatar Avatar coloramber border{true} style{{marginRight:8px}}T/Avatar Avatar coloramber 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 coloramber border{true} style{{marginRight:8px}} borderMotion{true} contentMotion{true}T/Avatar Avatar coloramber border{true} size{large} style{{marginRight:8px}} borderMotion{true} contentMotion{true}T/Avatar Avatar coloramber border{true} size{extra-large} style{{marginRight:8px}} borderMotion{true} contentMotion{true}T/Avatar /div }contentMotion为true时头像根元素会挂载.semi-avatar-animatedclass见 index.tsx具体的动画 keyframes 定义在 animation.scss 中。AvatarGroup 头像组AvatarGroup 将多个 Avatar 以组的形式展示适合团队成员、点赞用户列表等聚合场景并支持堆叠覆盖、数量截断与自定义「更多」标签。基础使用import React from react; import { Avatar, AvatarGroup } from douyinfe/semi-ui; () ( div AvatarGroup Avatar colorred altLisa LeBlancLL/Avatar Avatar altCaroline XiaoCX/Avatar Avatar coloramber altRafal MatinRM/Avatar Avatar style{{ color: #f56a00, backgroundColor: #fde3cf }} altZank LanceZL/Avatar Avatar style{{ backgroundColor: #87d068 }} altYouself ZhangYZ/Avatar /AvatarGroup /div );maxCount 数量截断通过maxCount设置展示的头像数量超出部分自动折叠为N标签import React from react; import { Avatar, AvatarGroup } from douyinfe/semi-ui; () ( div AvatarGroup maxCount{3} Avatar colorred altLisa LeBlancLL/Avatar Avatar altCaroline XiaoCX/Avatar Avatar coloramber altRafal MatinRM/Avatar Avatar style{{ color: #f56a00, backgroundColor: #fde3cf }} altZank LanceZL/Avatar Avatar style{{ backgroundColor: #87d068 }} altYouself ZhangYZ/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 colorred altLisa LeBlancLL/Avatar Avatar altCaroline XiaoCX/Avatar Avatar coloramber altRafal MatinRM/Avatar Avatar style{{ color: #f56a00, backgroundColor: #fde3cf }} altZank LanceZL/Avatar Avatar style{{ backgroundColor: #87d068 }} altYouself ZhangYZ/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 colorred altLisa LeBlancLL/Avatar Avatar altCaroline XiaoCX/Avatar Avatar coloramber altRafal MatinRM/Avatar Avatar style{{ color: #f56a00, backgroundColor: #fde3cf }} altZank LanceZL/Avatar Avatar style{{ backgroundColor: #87d068 }} altYouself ZhangYZ/Avatar /AvatarGroup /div div AvatarGroup overlapFrom{end} Avatar colorred altLisa LeBlancLL/Avatar Avatar altCaroline XiaoCX/Avatar Avatar coloramber altRafal MatinRM/Avatar Avatar style{{ color: #f56a00, backgroundColor: #fde3cf }} altZank LanceZL/Avatar Avatar style{{ backgroundColor: #87d068 }} altYouself ZhangYZ/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 //是否开启动画 }或 booleanobject / boolean-bottomSlot底部 Slot 配置 2.52.0render?: () ReactNode //完全控制渲染、shape?: circle | square //Slot 形状、text: ReactNode //Slot 内容、bgColor: string //Slot 背景色、textColor: string //文字颜色、className: string、style?: CSSPropertiesobject-className类名string-color头像颜色amber、blue、cyan、green、grey、indigo、light-blue、light-green、lime、orange、pink、purple、red、teal、violet、yellow、whitestringgreycontentMotion头像内容区域动效2.xx.0boolean-gap字符头像距左右两侧的像素大小number3hoverMaskhover 时头像内容覆盖层ReactNode-imgAttr原生 img 属性React.ImgHTMLAttributesHTMLImageElement-shape头像形状circle、squarestringcirclesize头像大小extra-extra-small、extra-small、small、default、medium、large、extra-large及合法宽度值如10pxstringmediumsrc图片类头像的资源地址string-srcSet图片类头像的响应式资源地址string-style样式CSSProperties-topSlot顶部 Slot 配置 2.52.0render?: () ReactNode //完全控制渲染、gradientStart?: string //顶部背景渐变起始色、gradientEnd?: string //顶部背景渐变结束色、text: ReactNode、textColor: string //文字颜色、className: string、style?: CSSPropertiesobject-onClick单击头像的回调(e: Event) void-onError图片加载失败事件返回false关闭组件默认的 fallback 行为(e: Event) boolean-onMouseEnterMouseEnter 事件回调(e: Event) void-onMouseLeaveMouseLeave 事件回调(e: Event) void-AvatarGroup属性说明类型默认值maxCount最大展示数量超出后显示 Nnumber-overlapFrom头像覆盖方向start、endstringstartrenderMore自定义渲染 more 标签(restNumber: number, restAvatars: ReactNode[]) ReactNode-shape头像形状circle、squarestringcirclesize头像大小extra-extra-small、extra-small、small、default、medium、large、extra-large及合法宽度值如10pxstringmediumAccessibility 无障碍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 altA cut cat srchttps://lf3-static.bytednsdoc.com/obj/eden-cn/ptlz_zlp/ljhwZthlaukjlkulzlp/root-web-sites/dy.png style{{ margin: 4 }} / Avatar altJiang Pengzhi srchttps://lf3-static.bytednsdoc.com/obj/eden-cn/ptlz_zlp/ljhwZthlaukjlkulzlp/root-web-sites/dy.png style{{ margin: 4 }} / {/* 反面示例alt 为空 */} Avatar alt srchttps://lf3-static.bytednsdoc.com/obj/eden-cn/ptlz_zlp/ljhwZthlaukjlkulzlp/root-web-sites/dy.png style{{ margin: 4 }} / {/* 反面示例无需在 alt 中包含 picture/image 等冗余描述 */} Avatar altPicture of Jiang Pengzhi srchttps://lf3-static.bytednsdoc.com/obj/eden-cn/ptlz_zlp/ljhwZthlaukjlkulzlp/root-web-sites/dy.png style{{ margin: 4 }} / / ); };对于字符型头像即使未传alt组件也会自动以字符内容作为aria-labeltempAlt alt ?? children并在可点击时拼接clickable Avatar:前缀见 index.tsx。设计变量Design TokensAvatar 的视觉表现完全基于 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 化的样式变量开发者既能快速上手也能深度定制到自有设计体系。赞分享前端UI组件设计系统【免费下载链接】semi-designA modern, comprehensive, flexible design system and React UI library, AI-friendly built-in.Provide 3000 Design Tokens, easy to build your design system. Make Semi Design to Any Design. Design to Code in one click项目地址https://gitcode.com/gh_mirrors/se/semi-design点击查看免费下载相关推荐Naive UI Avatar 组件实战指南尺寸形状、懒加载与头像组AvatarGroupNaive UI Avatar 组件实战指南尺寸形状、懒加载与头像组AvatarGroup 导读 Avatar 头像是 Naive UI 组件库中用于前端UI组件gpui-kit Avatar 头像组件实战指南图片回退、OkLCH 自动配色与 AvatarGroup 分组gpui kit Avatar 头像组件实战指南图片回退、OkLCH 自动配色与 AvatarGroup 分组 Avatar 是 gpui kit基于 GP桌面应用UI组件前端naive-ui 头像组件 Avatar 完全指南Props、Slots、头像组与懒加载实战naive ui 头像组件 Avatar 完全指南Props、Slots、头像组与懒加载实战 naive ui 的 Avatar头像组件用于展示用户头像、前端UI组件上一篇英雄联盟国服换肤工具5分钟解锁全皮肤体验的完整指南下一篇PDF补丁丁20份受限PDF五分钟批量处理免费搞定书签、合并与解限创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Semi Design Avatar 头像组件完全指南：尺寸、颜色、Slot 扩展与 AvatarGroup 头像组实战
前端UI组件设计系统【免费下载链接】semi-designA modern, comprehensive, flexible design system and React UI library, AI-friendly built-in.Provide 3000 Design Tokens, easy to build your design system. Make Semi Design to Any Design. Design to Code in one click项目地址https://gitcode.com/gh_mirrors/se/semi-design点击查看免费下载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.tsxAvatarGroup 则是基于PureComponent的聚合容器通过React.cloneElement向每个子 Avatar 注入统一的尺寸与形状见 avatarGroup.tsx。尺寸Size通过size属性设置头像尺寸支持以下七档预设值与任意合法的 CSS 宽度值如10pxextra-extra-small、extra-small、small、default、medium、large、extra-largeimport React from react; import { Avatar } from douyinfe/semi-ui; () ( div Avatar sizeextra-extra-small style{{ margin: 4 }} altUserU/Avatar Avatar sizeextra-small style{{ margin: 4 }} altUserU/Avatar Avatar sizesmall style{{ margin: 4 }} altUserU/Avatar Avatar sizedefault style{{ margin: 4 }} altUserU/Avatar Avatar style{{ margin: 4 }} altUserU/Avatar Avatar sizelarge style{{ margin: 4 }} altUserU/Avatar Avatar sizeextra-large style{{ margin: 4 }} altUserU/Avatar /div );size的默认值为medium见 index.tsx。当传入的size不在预设集合内时组件会将size直接作为宽度与高度写入行内样式{ width: size, height: size }因此传10px这类合法宽度值即可实现任意自定义尺寸见 index.tsx。各预设尺寸在 variables.scss 中定义了具体像素值便于理解实际渲染效果预设值头像宽高文本字号extra-extra-small20px10pxextra-small24px10pxsmall32px—default40px—medium48px—large72px—extra-large128px64px颜色Color字符型头像支持 17 种预设颜色通过color属性指定默认值为greywhite、amber、blue、cyan、green、grey、indigo、light-blue、light-green、lime、orange、pink、purple、red、teal、violet、yellowimport React from react; import { Avatar } from douyinfe/semi-ui; () ( div Avatar style{{ margin: 4 }} altAlice SwiftAS/Avatar Avatar colorred style{{ margin: 4 }} altBob MatteoBM/Avatar Avatar colorlight-blue style{{ margin: 4 }} altTaylor JoyTJ/Avatar Avatar style{{ color: #f56a00, backgroundColor: #fde3cf, margin: 4 }} altZank LanceZL/Avatar Avatar style{{ backgroundColor: #87d068, margin: 4 }} altYouself ZhangYZ/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 altbeautiful cat srchttps://lf3-static.bytednsdoc.com/obj/eden-cn/ptlz_zlp/ljhwZthlaukjlkulzlp/root-web-sites/dy.png style{{ margin: 4 }} / Avatar altcute cat sizesmall srchttps://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。形状ShapeAvatar 支持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 }} altUserU/Avatar Avatar shapesquare style{{ margin: 4 }} altUserU/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} colorred altBob DowntonBD/Avatar ); };hover 覆盖层通常用于「点击更换头像/查看大图」等交互场景可将hoverMask与onClick组合使用。实现上鼠标移入时notifyEnter将hoverMask写入hoverContent状态并渲染.semi-avatar-hover覆盖层移出时清空见 index.tsx。顶部与底部 SlottopSlot / 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 altbeautiful cat srchttps://lf3-static.bytednsdoc.com/obj/eden-cn/ptlz_zlp/ljhwZthlaukjlkulzlp/root-web-sites/dy.png style{{ margin: 4 }} sizelarge 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 coloramber topSlot{{ text: LIVE, gradientStart:rgb(255,23,100), gradientEnd:rgb(237,52,148) }}T/Avatar Avatar coloramber sizelarge topSlot{{ text: LIVE, gradientStart:rgb(255,23,100), gradientEnd:rgb(237,52,148) }}T/Avatar Avatar coloramber sizeextra-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内容、shapecircle圆形 /square方形、bgColor背景色、textColor文字颜色、className、style以及render完全接管渲染。(){ return div Avatar coloramber bottomSlot{{ shape: square, bgColor:#FE2C55, text: LIVE }}T/Avatar Avatar coloramber sizelarge bottomSlot{{ shape: square, bgColor:#FE2C55, text: LIVE }}T/Avatar Avatar coloramber sizeextra-large bottomSlot{{ shape: square, bgColor:#FE2C55, text: LIVE }}T/Avatar br/br/br/ Avatar coloramber bottomSlot{{ shape: circle, bgColor:#FE2C55, text: IconPlus/ }}T/Avatar Avatar coloramber sizelarge bottomSlot{{ shape: circle, bgColor:#FE2C55, text: IconPlus/ }}T/Avatar Avatar coloramber sizeextra-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 coloramber border{true} style{{marginRight:8px}}T/Avatar Avatar coloramber border{true} style{{marginRight:8px}}T/Avatar Avatar coloramber 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 coloramber border{true} style{{marginRight:8px}} borderMotion{true} contentMotion{true}T/Avatar Avatar coloramber border{true} size{large} style{{marginRight:8px}} borderMotion{true} contentMotion{true}T/Avatar Avatar coloramber border{true} size{extra-large} style{{marginRight:8px}} borderMotion{true} contentMotion{true}T/Avatar /div }contentMotion为true时头像根元素会挂载.semi-avatar-animatedclass见 index.tsx具体的动画 keyframes 定义在 animation.scss 中。AvatarGroup 头像组AvatarGroup 将多个 Avatar 以组的形式展示适合团队成员、点赞用户列表等聚合场景并支持堆叠覆盖、数量截断与自定义「更多」标签。基础使用import React from react; import { Avatar, AvatarGroup } from douyinfe/semi-ui; () ( div AvatarGroup Avatar colorred altLisa LeBlancLL/Avatar Avatar altCaroline XiaoCX/Avatar Avatar coloramber altRafal MatinRM/Avatar Avatar style{{ color: #f56a00, backgroundColor: #fde3cf }} altZank LanceZL/Avatar Avatar style{{ backgroundColor: #87d068 }} altYouself ZhangYZ/Avatar /AvatarGroup /div );maxCount 数量截断通过maxCount设置展示的头像数量超出部分自动折叠为N标签import React from react; import { Avatar, AvatarGroup } from douyinfe/semi-ui; () ( div AvatarGroup maxCount{3} Avatar colorred altLisa LeBlancLL/Avatar Avatar altCaroline XiaoCX/Avatar Avatar coloramber altRafal MatinRM/Avatar Avatar style{{ color: #f56a00, backgroundColor: #fde3cf }} altZank LanceZL/Avatar Avatar style{{ backgroundColor: #87d068 }} altYouself ZhangYZ/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 colorred altLisa LeBlancLL/Avatar Avatar altCaroline XiaoCX/Avatar Avatar coloramber altRafal MatinRM/Avatar Avatar style{{ color: #f56a00, backgroundColor: #fde3cf }} altZank LanceZL/Avatar Avatar style{{ backgroundColor: #87d068 }} altYouself ZhangYZ/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 colorred altLisa LeBlancLL/Avatar Avatar altCaroline XiaoCX/Avatar Avatar coloramber altRafal MatinRM/Avatar Avatar style{{ color: #f56a00, backgroundColor: #fde3cf }} altZank LanceZL/Avatar Avatar style{{ backgroundColor: #87d068 }} altYouself ZhangYZ/Avatar /AvatarGroup /div div AvatarGroup overlapFrom{end} Avatar colorred altLisa LeBlancLL/Avatar Avatar altCaroline XiaoCX/Avatar Avatar coloramber altRafal MatinRM/Avatar Avatar style{{ color: #f56a00, backgroundColor: #fde3cf }} altZank LanceZL/Avatar Avatar style{{ backgroundColor: #87d068 }} altYouself ZhangYZ/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 //是否开启动画 }或 booleanobject / boolean-bottomSlot底部 Slot 配置 2.52.0render?: () ReactNode //完全控制渲染、shape?: circle | square //Slot 形状、text: ReactNode //Slot 内容、bgColor: string //Slot 背景色、textColor: string //文字颜色、className: string、style?: CSSPropertiesobject-className类名string-color头像颜色amber、blue、cyan、green、grey、indigo、light-blue、light-green、lime、orange、pink、purple、red、teal、violet、yellow、whitestringgreycontentMotion头像内容区域动效2.xx.0boolean-gap字符头像距左右两侧的像素大小number3hoverMaskhover 时头像内容覆盖层ReactNode-imgAttr原生 img 属性React.ImgHTMLAttributesHTMLImageElement-shape头像形状circle、squarestringcirclesize头像大小extra-extra-small、extra-small、small、default、medium、large、extra-large及合法宽度值如10pxstringmediumsrc图片类头像的资源地址string-srcSet图片类头像的响应式资源地址string-style样式CSSProperties-topSlot顶部 Slot 配置 2.52.0render?: () ReactNode //完全控制渲染、gradientStart?: string //顶部背景渐变起始色、gradientEnd?: string //顶部背景渐变结束色、text: ReactNode、textColor: string //文字颜色、className: string、style?: CSSPropertiesobject-onClick单击头像的回调(e: Event) void-onError图片加载失败事件返回false关闭组件默认的 fallback 行为(e: Event) boolean-onMouseEnterMouseEnter 事件回调(e: Event) void-onMouseLeaveMouseLeave 事件回调(e: Event) void-AvatarGroup属性说明类型默认值maxCount最大展示数量超出后显示 Nnumber-overlapFrom头像覆盖方向start、endstringstartrenderMore自定义渲染 more 标签(restNumber: number, restAvatars: ReactNode[]) ReactNode-shape头像形状circle、squarestringcirclesize头像大小extra-extra-small、extra-small、small、default、medium、large、extra-large及合法宽度值如10pxstringmediumAccessibility 无障碍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 altA cut cat srchttps://lf3-static.bytednsdoc.com/obj/eden-cn/ptlz_zlp/ljhwZthlaukjlkulzlp/root-web-sites/dy.png style{{ margin: 4 }} / Avatar altJiang Pengzhi srchttps://lf3-static.bytednsdoc.com/obj/eden-cn/ptlz_zlp/ljhwZthlaukjlkulzlp/root-web-sites/dy.png style{{ margin: 4 }} / {/* 反面示例alt 为空 */} Avatar alt srchttps://lf3-static.bytednsdoc.com/obj/eden-cn/ptlz_zlp/ljhwZthlaukjlkulzlp/root-web-sites/dy.png style{{ margin: 4 }} / {/* 反面示例无需在 alt 中包含 picture/image 等冗余描述 */} Avatar altPicture of Jiang Pengzhi srchttps://lf3-static.bytednsdoc.com/obj/eden-cn/ptlz_zlp/ljhwZthlaukjlkulzlp/root-web-sites/dy.png style{{ margin: 4 }} / / ); };对于字符型头像即使未传alt组件也会自动以字符内容作为aria-labeltempAlt alt ?? children并在可点击时拼接clickable Avatar:前缀见 index.tsx。设计变量Design TokensAvatar 的视觉表现完全基于 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 化的样式变量开发者既能快速上手也能深度定制到自有设计体系。赞分享前端UI组件设计系统【免费下载链接】semi-designA modern, comprehensive, flexible design system and React UI library, AI-friendly built-in.Provide 3000 Design Tokens, easy to build your design system. Make Semi Design to Any Design. Design to Code in one click项目地址https://gitcode.com/gh_mirrors/se/semi-design点击查看免费下载相关推荐Naive UI Avatar 组件实战指南尺寸形状、懒加载与头像组AvatarGroupNaive UI Avatar 组件实战指南尺寸形状、懒加载与头像组AvatarGroup 导读 Avatar 头像是 Naive UI 组件库中用于前端UI组件gpui-kit Avatar 头像组件实战指南图片回退、OkLCH 自动配色与 AvatarGroup 分组gpui kit Avatar 头像组件实战指南图片回退、OkLCH 自动配色与 AvatarGroup 分组 Avatar 是 gpui kit基于 GP桌面应用UI组件前端naive-ui 头像组件 Avatar 完全指南Props、Slots、头像组与懒加载实战naive ui 头像组件 Avatar 完全指南Props、Slots、头像组与懒加载实战 naive ui 的 Avatar头像组件用于展示用户头像、前端UI组件上一篇英雄联盟国服换肤工具5分钟解锁全皮肤体验的完整指南下一篇PDF补丁丁20份受限PDF五分钟批量处理免费搞定书签、合并与解限创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考