Avatar 头像

Avatar 组件用于表示用户，可显示个人资料图片、姓名首字母或后备图标。

安装

The above command is for individual installation only. You may skip this step if @heroui/react is already installed globally.

导入

HeroUI 导出了 3 个与头像相关的组件：

• Avatar：用于显示头像的主要组件。
• AvatarGroup：用于显示一组头像的包装组件。
• AvatarIcon：当图片加载失败时使用的默认后备图标。

用法

尺寸

禁用状态

带边框

圆角

颜色

头像后备方案

当头像的 src 加载失败时，有两种后备方案：

• 如果提供了 name 属性，则用其生成姓名首字母和一个随机的、无障碍的背景色。
• 如果没有提供 name 属性，则使用默认头像。

如果未传入 showFallback，则不会显示后备内容。

自定义后备内容

你也可以提供一个自定义的后备组件，在 src 加载失败时显示。

自定义实现

如果你需要进一步自定义头像，可以使用 useAvatar 钩子来创建你自己的实现。

自定义姓名首字母逻辑

可以通过向 getInitials 属性传递一个函数来自定义生成姓名首字母的逻辑。 默认情况下，我们会合并 name 属性中每个单词的首字符。

头像组 (Avatar Group)

组禁用状态

组最大数量限制

你可以通过向 AvatarGroup 组件传递 max 属性来限制显示的头像数量。

组总数显示

你可以通过向 AvatarGroup 组件传递 total 属性来显示头像的总数。

组自定义计数

AvatarGroup 提供了一个 renderCount 属性，用于自定义在传入 total 属性时显示的计数。

组网格布局

通过向 AvatarGroup 组件传递 isGrid 属性，头像将以网格布局显示。

组自定义实现

如果你需要进一步自定义头像组，可以使用 useAvatarGroup 钩子和 AvatarGroupProvider 来创建你自己的实现。

插槽 (Slots)

• base：头像包装器，包含焦点环、位置和整体外观的样式。
• img：头像内的图片元素，包含透明度过渡和尺寸的样式。
• fallback：图片加载失败或未提供时显示的后备内容，包含内容居中样式。
• name：未提供图片或图片加载失败时显示的姓名首字母，包含字体、文本对齐和继承的样式。
• icon：头像内的图标元素，包含内容居中、文本继承和尺寸的样式。

自定义头像样式

你可以使用 classNames 属性自定义头像的任何部分，每个 slot 都有其自己的 className。

数据属性 (Data Attributes)

Avatar 在 base 元素上具有以下属性：

• data-hover： 当头像被悬停时。基于 useHover
• data-focus： 当头像获得焦点时。基于 useFocusRing，当 isFocusable 为 true 或 as 属性被指定为 button 时应用。
• data-focus-visible： 当头像通过键盘获得焦点时。基于 useFocusRing，当 isFocusable 为 true 或 as 属性被指定为 button 时应用。

API

Avatar 属性

Avatar Group 属性