Avatar
头像：支持图片(src/srcSet)、加载失败降级到 children/alt 首字，circle/square 形状，7 档尺寸(默认 medium)或自定义 width，16 档语义色 + white(默认 grey)，字符按 gap 自适应缩放，hoverMask 悬浮遮罩，topSlot/bottomSlot 对象配置的顶部/底部标记，border 额外描边环 + contentMotion 内容动效。Avatar.Group 把多个头像层叠排列，maxCount 折叠出「+N」溢出头像，overlapFrom 控制压盖方向，组级 shape/size 强制下发(对齐 Semi cloneElement)。
如何引入
import { Avatar, AvatarGroup } from '@chenzy-design/svelte';尺寸
size 支持 extra-extra-small 到 extra-large 共 7 档，默认 medium。
颜色
支持默认色板 16 种颜色（默认 grey），也可用 style 自定义颜色。
自适应字符大小
字符头像字号随宽度自适应，gap 调整字符距左右两侧的像素。
图片
通过 src 设置图片格式的头像，加载失败自动降级。
形状
支持 circle、square 两种形状，默认 circle。
事件
onClick / onMouseEnter / onMouseLeave；hover 时通过 hoverMask 传入覆盖层内容。
顶部 Slot
topSlot 对象配置顶部渐变标记（gradientStart/gradientEnd/text）。
底部 Slot
bottomSlot 对象配置底部圆形/方形标记（shape/bgColor/text）。
组合效果
图片头像叠加边框呼吸动画、内容动效、顶部直播气泡与底部圆形图标（抖音直播头像）。
额外边框
border 渲染一圈额外描边环，对象形式可定制 color。
额外动效
border={{ motion: true }} 与 contentMotion 开启边框与内容区域动效。
头像组
AvatarGroup 将多个头像叠加展示为组。
maxCount 折叠
通过 maxCount 设置展示数量，超出折叠为 +N。
自定义 more
renderMore 自定义 +N 溢出头像，可结合 Popover 展开剩余成员。
覆盖方式
overlapFrom 控制层叠压盖方向：start=前压后，end=后压前。
RTL
dir="rtl" 作用域下头像组层叠方向、hover 遮罩定位随之镜像。
direction="rtl" 渲染 cd-rtl 包裹层建立方向作用域：RTL
下头像组层叠方向、hover 遮罩定位随之镜像。 API 参考
Avatar
Props
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
src | 图片地址；加载失败自动降级 | string | undefined |
srcSet | 响应式图片源集 | string | undefined |
alt | a11y 文本，也作文字降级来源 | string | undefined |
shape | — | 'circle'|'square' | 'circle' |
size | 7 档枚举映射 token，number/合法 width 值内联 | 'extra-extra-small'|'extra-small'|'small'|'default'|'medium'|'large'|'extra-large'|number|string | 'medium' |
color | 16 档语义色 + white；图片头像不上色；也可用 style 自定义 | 'amber'|'blue'|'cyan'|'green'|'grey'|'indigo'|'light-blue'|'light-green'|'lime'|'orange'|'pink'|'purple'|'red'|'teal'|'violet'|'yellow'|'white' | 'grey' |
border | 额外描边环：true 用默认主色；对象可定制 color 并用 motion 开启呼吸动画 | boolean | { color?: string; motion?: boolean } | false |
contentMotion | 头像内容区域动效 | boolean | false |
gap | 字符头像距左右两侧像素(用于自适应缩放) | number | 3 |
hoverMask | hover 时头像内容覆盖层(无默认样式) | Snippet | undefined |
topSlot | 顶部渐变标记(仅 circle 且枚举尺寸) | { render?; gradientStart?: string; gradientEnd?: string; text?; textColor?: string; className?: string; style?: string } | undefined |
bottomSlot | 底部圆形/方形标记(仅枚举尺寸) | { render?; shape?: 'circle'|'square'; text?; bgColor?: string; textColor?: string; className?: string; style?: string } | undefined |
imgAttr | 额外传给 img 的原生属性 | Record<string, unknown> | undefined |
onError | img 加载失败回调；返回 false 关闭默认降级 | () => boolean|void | undefined |
onClick | 单击回调；提供时头像可聚焦并响应键盘 Enter(对齐 Semi clickable) | (e: MouseEvent|KeyboardEvent) => void | undefined |
onMouseEnter | — | (e: MouseEvent) => void | undefined |
onMouseLeave | — | (e: MouseEvent) => void | undefined |
class | 附加类名(对齐 Semi className) | string | undefined |
style | 内联样式(对齐 Semi style) | string | undefined |
children | 文字/图标内容 | Snippet | undefined |
Events
| 事件 | 载荷 | 说明 |
|---|---|---|
click | — | onClick：头像被点击或键盘 Enter 激活 |
mouseenter | — | onMouseEnter |
mouseleave | — | onMouseLeave |
error | — | onError：图片加载失败 |
Slots
| 名称 | 说明 |
|---|---|
children | 文字或图标降级内容 |
hoverMask | hover 覆盖层 |
AvatarGroup
把多个头像层叠排列。可用 items 数据驱动(配合 maxCount 折叠)，或用 children 自由传入 <Avatar>。组级 shape/size 经 context 强制下发(对齐 Semi cloneElement)。
Props
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
items | 数据驱动成员；启用 maxCount 折叠 | AvatarGroupItem[] | undefined |
maxCount | 最多显示 N 个，其余折叠为「+N」 | number | undefined |
shape | 组级形状，强制下发给子头像 | 'circle'|'square' | 'circle' |
size | 组级尺寸，强制下发给子头像 | AvatarSizeEnum | number | 'medium' |
overlapFrom | 层叠压盖方向：start=前压后，end=后压前 | 'start'|'end' | 'start' |
renderMore | 自定义「+N」溢出头像渲染 | Snippet<[{ restNumber: number; restAvatars: AvatarGroupItem[] }]> | undefined |
children | 不用 items 时自由传入的头像 | Snippet | undefined |
Accessibility
- 图片头像用 <img alt>；纯文字头像 role=img + aria-label(alt 或文字)。提供 onClick 时内部 img/label 加 tabindex=0 + 键盘 Enter/Escape(对齐 Semi clickable Avatar)；纯展示头像不可聚焦。
设计变量
| 变量 | 默认值 | 用法 |
|---|---|---|
--cd-avatar-additional-border-color | var(--cd-color-avatar-additional-border) | 额外描边环颜色（组件消费） |
--cd-avatar-amber-bg | var(--cd-color-avatar-amber-bg) | amber 头像背景（组件消费） |
--cd-avatar-bg | var(--cd-color-fill-1) | 文字/缺省头像背景（组件消费；Semi 头像文字底为 fill） |
--cd-avatar-blue-bg | var(--cd-color-avatar-blue-bg) | blue 头像背景（组件消费） |
--cd-avatar-border | var(--cd-color-avatar-default-border-default) | 头像组描边颜色（组件消费） |
--cd-avatar-bottom-slot-bg | var(--cd-color-avatar-bottom-slot-bg) | 底部 Slot 背景色（组件消费） |
--cd-avatar-bottom-slot-square-border | var(--cd-color-avatar-bottom-slot-square-border) | 底部方形 Slot 边框色（组件消费） |
--cd-avatar-bottom-slot-text | var(--cd-color-avatar-bottom-slot-text) | 底部 Slot 文字色（组件消费） |
--cd-avatar-color | var(--cd-color-text-1) | 头像文字颜色（组件消费） |
--cd-avatar-cyan-bg | var(--cd-color-avatar-cyan-bg) | cyan 头像背景（组件消费） |