Avatar 头像
代表用户身份的图片、首字母或图标
用法
基础
示例加载中...
尺寸
size 取预设名或自定义像素值。
示例加载中...
文字头像
示例加载中...
图标头像
示例加载中...
头像组
超过 max 的头像折叠为 +N。
示例加载中...
悬浮效果
hoverEffect 控制单个头像的悬浮反馈，spreadOnHover 让整组悬浮时展开。
示例加载中...
溢出浮层
overflowPopover 在 +N 上弹出被折叠的头像，overflow 插槽可替换面板内容。
示例加载中...
状态
示例加载中...
最佳实践
- 生成身份标识时传
name，不要手写首字母。 src是真实用户图片时提供有意义的alt。status只表示在线状态；文字型系统状态用TxStatusBadge。- 组内显示
status时加大overlap或开启spreadOnHover，避免状态点被遮住。 - 溢出浮层只用于查看成员；需要操作成员时用列表组件。
API 参考
TxAvatar
属性
| 属性名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
src | string | - | 图片地址；加载失败时回退。 |
alt | string | - | 图片替代文本，src 为真实用户图片时提供。 |
name | string | - | 用于生成首字母的名称。 |
icon | string | - | 回退图标名，传给 TxIcon。 |
size | 'small' | 'medium' | 'large' | 'xlarge' | number | \${number}` | `${number}px`` | 'medium' | 预设名或正数像素尺寸；无效值被忽略。 |
status | 'online' | 'offline' | 'busy' | 'away' | - | 角落的状态点，位置随 shape 内缩。 |
shape | 'circle' | 'square' | 'rounded' | 'circle' | 头像形状。 |
clickable | boolean | false | 启用点击样式、按钮语义与 click 事件。 |
backgroundColor | string | - | 回退内容的背景色。 |
textColor | string | 设置 backgroundColor 时默认为 '#ffffff' | 回退内容的文字颜色；仅与 backgroundColor 一起生效。 |
事件
| 事件名 | 参数 | 说明 |
|---|---|---|
click | - | clickable 时点击或按 Enter / Space 触发。 |
插槽
| 插槽名 | Props | 说明 |
|---|---|---|
default | - | 自定义回退内容，优先于 icon 与 name。 |
TxAvatarGroup
属性
| 属性名 | 类型 | 默认值 | 说明 |
|---|---|---|---|
max | number | 子节点数量 | 折叠为 +N 前最多显示的头像数；负数按 0 处理。 |
size | AvatarSize | - | 注入未自行设置 size 的子头像。 |
overlap | number | string | 8 | 相邻头像的重叠距离，数字按 px 计。 |
hoverEffect | 'none' | 'lift' | 'lift' | 单个头像的悬浮反馈；lift 上浮、加阴影并置顶。 |
spreadOnHover | boolean | false | 整组悬浮时把重叠过渡到 spreadOverlap。 |
spreadOverlap | number | string | 0 | 展开后的重叠距离，负值留出间隙。 |
overflowPopover | boolean | false | 在 +N 上挂载溢出浮层。 |
overflowPopoverTrigger | 'hover' | 'click' | 'hover' | 浮层触发方式。 |
overflowPopoverPlacement | PopoverPlacement | 'top' | 浮层相对 +N 的位置。 |
插槽
| 插槽名 | Props | 说明 |
|---|---|---|
default | - | TxAvatar 或兼容的头像 VNode。 |
overflow | { nodes: VNode[], count: number } | 溢出浮层的面板内容；nodes 为被 max 截掉的头像。 |
概述
- 内容按图片、默认插槽、
icon、name首字母、默认user图标的顺序回退；图片加载失败同样回退。 - 首字母取第一个与最后一个单词的首字符，并转为大写。
clickable时根节点带role="button"与tabindex="0"，Enter / Space 与点击一样触发click。- 组内
z-index自左向右递增，右侧头像盖住左侧头像的右下角（含状态点）；lift将悬浮头像置顶。 - 开启
overflowPopover且有溢出时，+N由TxPopover包裹；否则是普通头像，不产生浮层。 - 减少动态效果时取消悬浮位移与过渡，保留置顶与阴影。
技术实现
- 根节点不裁切，裁切在图片与回退层上，状态点因此能伸出形状。
- 组内的负 margin 与
z-index来自样式表（--tx-avatar-group-overlap、--tx-avatar-group-index），子头像只内联描边。 - 源码：
packages/tuffex/packages/components/src/avatar/。
查看源码
packages/tuffex/packages/components/src/avatar/index.ts
自定义
| 变量 | 写入方 | 用途 |
|---|---|---|
--tx-avatar-size | 自定义 size | 宽高。 |
--tx-avatar-font-size | 自定义 size | 回退文字与图标字号。 |
--tx-avatar-status-size | 自定义 size | 状态点外径（含描边）。 |
--tx-avatar-status-border | 自定义 size | 状态点描边宽度。 |
--tx-avatar-bg | backgroundColor | 回退背景色。 |
--tx-avatar-text | textColor（需 backgroundColor） | 回退文字颜色。 |
--tx-avatar-ring | 调用方 / 主题 | 状态点与组内头像的描边色，默认 --tx-bg-color。 |
--tx-avatar-group-overlap | overlap | 解析后的重叠距离。 |
--tx-avatar-group-spread-overlap | spreadOverlap | 展开后的重叠距离。 |
--tx-avatar-group-hover-z | 调用方 / 主题 | 悬浮置顶的 z-index，默认 999。 |
--tx-avatar-group-overflow-width | 调用方 / 主题 | 溢出面板换行前的最大宽度，默认 232px。 |
--tx-avatar-group-border | 调用方 / 主题 | 组内头像的描边色。 |
--tx-avatar-*-preset、--tx-avatar-status-diameter、--tx-avatar-status-ring、--tx-avatar-status-inset、--tx-avatar-group-gap、--tx-avatar-group-index、--tx-avatar-group-more-z 是内部变量，不要直接设置。