Badge

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

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

结构变化

在 v2 中，Badge 是一个包装组件，相对其子元素进行内容定位：

1import { Badge, Avatar } from "@lenso/ui";2
3export default function App() {4  return (5    <Badge content="5" color="primary">6      <Avatar src="https://i.pravatar.cc/300" />7    </Badge>8  );9}

在 v3 中，Badge 改为复合组件模式，由 Badge.Anchor 负责定位：

1import { Badge, Avatar } from "@lenso/ui";2
3export default function App() {4  return (5    <Badge.Anchor>6      <Avatar>7        <Avatar.Image src="https://i.pravatar.cc/300" alt="User" />8        <Avatar.Fallback>U</Avatar.Fallback>9      </Avatar>10      <Badge color="accent">5</Badge>11    </Badge.Anchor>12  );13}

主要变化

1. 组件结构

v2： 单一 Badge 组件包裹子节点，通过 content prop 设置徽章文本
v3： 复合组件：Badge.Anchor（定位包装器）、Badge（徽章本身）、Badge.Label（文本插槽，字符串子节点会自动包裹）

2. 变体

v2： solid、flat、faded、shadow
v3： primary、secondary、soft

3. 颜色

v2： default、primary、secondary、success、warning、danger
v3： default、accent、success、warning、danger

4. Prop 变更

v2 prop	v3 位置	说明
`content`	`Badge` 子节点	内容现在以子节点传入
`children`	`Badge.Anchor`	锚定元素放入 `Badge.Anchor` 内部
`variant`	`Badge`	取值变化（详见变体映射）
`color`	`Badge`	`primary` → `accent`，`secondary` 已移除
`size`	`Badge`	相同（`sm`、`md`、`lg`）
`placement`	`Badge`	相同（`top-right`、`top-left`、`bottom-right`、`bottom-left`）
`shape`	-	已移除（请改用 Tailwind CSS）
`showOutline`	-	已移除（请改用 Tailwind CSS，例如 `border-2`）
`disableOutline`	-	已移除
`disableAnimation`	-	已移除
`isInvisible`	-	已移除（请使用条件渲染）
`isOneChar`	-	已移除（请改用 Tailwind CSS）
`isDot`	-	省略子节点即可渲染为圆点
`classNames`	-	改在各子组件上使用 `className`

5. 变体映射

v2 变体	v3 对应项	说明
`solid`	`primary`	实心背景
`flat`	`soft`	浅色背景
`faded`	`secondary`	边框 + 背景
`shadow`	`primary`	配合 Tailwind 的 `shadow-*` 类

6. 颜色映射

v2 颜色	v3 对应项	说明
`default`	`default`	相同
`primary`	`accent`	已重命名
`secondary`	`default` 或 `accent`	视上下文而定
`success`	`success`	相同
`warning`	`warning`	相同
`danger`	`danger`	相同

迁移示例

基本徽章

1import { Badge, Avatar } from "@lenso/ui";2
3<Badge content="5" color="primary">4  <Avatar src="https://i.pravatar.cc/300" />5</Badge>

圆点徽章

1<Badge content="" isDot color="success">2  <Avatar src="https://i.pravatar.cc/300" />3</Badge>

位置

1<Badge content="5" placement="bottom-right" color="danger">2  <Avatar src="https://i.pravatar.cc/300" />3</Badge>

可见性切换

1const [isInvisible, setIsInvisible] = useState(false);2
3<Badge content="5" isInvisible={isInvisible} color="danger">4  <Avatar src="https://i.pravatar.cc/300" />5</Badge>

带图标内容

1import { Icon } from "@iconify/react";2
3<Badge content={<Icon icon="gravity-ui:check" />} color="success">4  <Avatar src="https://i.pravatar.cc/300" />5</Badge>

样式变更

v2：`classNames` prop

1<Badge2  classNames={{3    base: "custom-base",4    badge: "custom-badge"5  }}6/>

v3：直接使用 `className` prop

1<Badge.Anchor className="custom-anchor">2  <Avatar />3  <Badge className="custom-badge">4    <Badge.Label className="custom-label">5</Badge.Label>5  </Badge>6</Badge.Anchor>

组件结构

v3 Badge 遵循以下结构：

1Badge.Anchor (positioning wrapper)2  ├── [Anchored element: Avatar, Button, etc.]3  └── Badge (the badge indicator)4      └── Badge.Label (auto-wrapped for string/number children)

总结

组件结构：Badge 包裹子节点 → Badge.Anchor + Badge 作为同级
移除 content prop：content prop → 将内容作为 Badge 的子节点传入
圆点徽章：isDot prop → 省略子节点
可见性：isInvisible prop → 改用条件渲染
变体收敛：从 4 个变体减少为 3 个（primary、secondary、soft）
颜色变化：primary → accent，secondary 已移除
移除的 prop：shape、showOutline、disableAnimation、isOneChar —— 请改用 Tailwind CSS
移除 classNames：改在各复合子组件上使用 className