Skip to content
Lenso UI

Avatar

Avatar 从 HeroUI v2 到 v3 的迁移指南。

完整的 API 参考、样式指南与高级示例请参阅 v3 Avatar 文档。本指南只关注从 HeroUI v2 的迁移。

结构变化

在 v2 中，Avatar 是单个组件，通过 props 传入图片地址、姓名、后备内容等：

import { Avatar } from "@lenso/ui";
export default function App() {  return (    <Avatar       src="https://example.com/avatar.jpg"      name="John Doe"      showFallback    />  );}

在 v3 中，Avatar 采用显式子组件的复合组件模式：

import { Avatar } from "@lenso/ui";
export default function App() {  return (    <Avatar>      <Avatar.Image src="https://example.com/avatar.jpg" alt="John Doe" />      <Avatar.Fallback>JD</Avatar.Fallback>    </Avatar>  );}

主要变化

1. 组件结构

v2： 单个带 props 的 Avatar
v3： 复合组件：Avatar、Avatar.Image、Avatar.Fallback

2. Prop 变更

v2 propv3 位置说明
srcAvatar.Image使用 <Avatar.Image src="..." />
name—请自行生成首字母缩写并传入 <Avatar.Fallback />
showFallback—已移除（图片加载失败或未提供时显示后备）
fallback, iconAvatar.Fallback将内容放在 <Avatar.Fallback /> 内
colorAvatar相同；primary → accent，secondary → default
variantAvatarv3 新增；"default" | "soft"
sizeAvatar相同
isBordered—已移除（请使用 Tailwind，例如 ring-2 ring-background）
radius—已移除（请使用 Tailwind，例如 rounded-full）
isDisabled, isFocusable—已移除（如需请用 Tailwind / asChild）
getInitials—请手动生成首字母缩写
ImgComponent, imgProps—如需请在 Avatar.Image 上使用 asChild
onErrorAvatar.Image在 <Avatar.Image /> 上使用 onError
—Avatar.Image新增：srcSet、sizes、loading（响应式图片）
—Avatar.Fallback新增：delayMs 延迟显示后备（减少闪烁）
classNames—请在各部分使用 className
AvatarGroupAvatarGroup已重新提供 — 复合 Avatar 子组件，支持 max / color / variant / isGrid / overlap（clip|ring）与可选的 AvatarGroup.Count；v2 total → 显式 Count；参见 AvatarGroup

3. variant prop（v3 新增）

v2： 无 variant prop，仅通过 color 控制样式
v3： 新增 variant prop，可选 "default" 与 "soft"。"soft" 使用更浅的背景样式。

<Avatar variant="soft" color="accent">  <Avatar.Image src="..." alt="User" />  <Avatar.Fallback>JD</Avatar.Fallback></Avatar>

4. Avatar.Image 响应式属性（v3 新增）

v2： 仅支持 src 与 onError
v3： Avatar.Image 现支持 srcSet、sizes、loading，用于响应式图片

<Avatar>  <Avatar.Image    src="avatar-400.jpg"    srcSet="avatar-200.jpg 200w, avatar-400.jpg 400w"    sizes="(max-width: 600px) 200px, 400px"    loading="lazy"    alt="User"  />  <Avatar.Fallback>JD</Avatar.Fallback></Avatar>

5. Avatar.Fallback 的 delayMs prop（v3 新增）

v2： 立即显示后备，或由 showFallback 控制
v3： Avatar.Fallback 支持 delayMs，可延后渲染，避免图片很快加载完成时出现后备闪烁

<Avatar>  <Avatar.Image src="..." alt="User" />  <Avatar.Fallback delayMs={600}>JD</Avatar.Fallback></Avatar>

6. 图片与后备内容

v2： 使用 src、name、showFallback、fallback 等 props
v3： 需显式渲染 <Avatar.Image /> 与 <Avatar.Fallback />

7. color 映射

v2 colorv3 color说明
defaultdefault相同
primaryaccent已重命名
secondarydefault使用 default
successsuccess相同
warningwarning相同
dangerdanger相同

8. AvatarGroup（v3 已提供）

v2： 独立 AvatarGroup，支持 isBordered、max、total 等 props
v3： AvatarGroup 再次作为独立组件提供。包裹复合 Avatar 子组件，通过 Context 继承 size / color / variant，并支持 max、isGrid、overlap（默认 "clip"，或 "ring"）。v2 的 total 已移除 — 已知服务端总量时渲染显式的 AvatarGroup.Count（会抑制 max 的自动计数）。isBordered 已移除；可用 Tailwind 或 overlap="ring"。参见 AvatarGroup 文档。

import { Avatar, AvatarGroup } from "@lenso/ui";
<AvatarGroup max={3} size="md">  <Avatar>    <Avatar.Image src="https://example.com/1.jpg" alt="User 1" />    <Avatar.Fallback>U1</Avatar.Fallback>  </Avatar>  <Avatar>    <Avatar.Image src="https://example.com/2.jpg" alt="User 2" />    <Avatar.Fallback>U2</Avatar.Fallback>  </Avatar>  <Avatar>    <Avatar.Image src="https://example.com/3.jpg" alt="User 3" />    <Avatar.Fallback>U3</Avatar.Fallback>  </Avatar>  <Avatar>    <Avatar.Image src="https://example.com/4.jpg" alt="User 4" />    <Avatar.Fallback>U4</Avatar.Fallback>  </Avatar></AvatarGroup>

迁移示例

尺寸与颜色

<Avatar size="md" color="primary" src="..." name="John" />

自定义后备

import { Icon } from "@iconify/react";
<Avatar   src="https://broken-url.com/image.jpg"  showFallback  fallback={<Icon icon="mdi:account" />}/>

Avatar 组

import { Avatar, AvatarGroup } from "@lenso/ui";
<AvatarGroup isBordered>  <Avatar src="https://example.com/1.jpg" />  <Avatar src="https://example.com/2.jpg" />  <Avatar src="https://example.com/3.jpg" /></AvatarGroup>

带头像数量上限的组

import { Avatar, AvatarGroup } from "@lenso/ui";
<AvatarGroup max={3}>  <Avatar src="https://example.com/1.jpg" />  <Avatar src="https://example.com/2.jpg" />  <Avatar src="https://example.com/3.jpg" />  <Avatar src="https://example.com/4.jpg" />  <Avatar src="https://example.com/5.jpg" /></AvatarGroup>

AvatarGroup：total → Count

import { Avatar, AvatarGroup } from "@lenso/ui";
<AvatarGroup max={3} total={12}>  <Avatar src="https://example.com/1.jpg" />  <Avatar src="https://example.com/2.jpg" />  <Avatar src="https://example.com/3.jpg" /></AvatarGroup>

变体

{/* v2 doesn't have variants, but uses color prop */}<Avatar color="primary" name="John" />

样式变化

v2：classNames prop

<Avatar   classNames={{    base: "custom-base",    img: "custom-img",    fallback: "custom-fallback"  }}/>

v3：直接使用 className prop

<Avatar className="custom-base">  <Avatar.Image className="custom-img" src="..." alt="..." />  <Avatar.Fallback className="custom-fallback">    JD  </Avatar.Fallback></Avatar>

组件组成

v3 Avatar 的结构如下：

Avatar (Root)  ├── Avatar.Image (optional)  └── Avatar.Fallback (optional; shown when image fails or not provided)

生成首字母缩写的辅助函数

v3 没有 name prop，需要自行生成首字母缩写：

function getInitials(name: string): string {  return name    .split(" ")    .map(n => n[0])    .join("")    .toUpperCase()    .slice(0, 2);}
// Usage<Avatar>  <Avatar.Fallback>{getInitials("John Doe")}</Avatar.Fallback></Avatar>

总结

  1. 组件结构：必须使用复合组件（Avatar.Image、Avatar.Fallback）
  2. name prop 已移除：请手动生成首字母缩写
  3. showFallback 已移除：图片失败时仍会显示后备
  4. 新增 variant prop："default" | "soft"，用于视觉样式
  5. 响应式图片：Avatar.Image 支持 srcSet、sizes、loading
  6. 后备延迟：Avatar.Fallback 支持 delayMs，减轻后备闪烁
  7. 颜色映射：primary → accent，secondary → default
  8. isBordered 已移除：请使用 Tailwind ring-2 ring-background 等类
  9. radius 已移除：请使用 Tailwind rounded-* 类
  10. isDisabled 等已移除：请使用 Tailwind opacity-50 等类
  11. AvatarGroup 已提供：使用独立的 AvatarGroup 组件（文档），配合复合 Avatar 子组件与 max / overlap / isGrid，以及可选的 AvatarGroup.Count（替代 v2 total）
  12. icon prop 已移除：请将图标内容放入 Avatar.Fallback
  13. classNames 已移除：请在各子组件上使用 className prop