Button

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

结构变化

在 v2 中，Button 通过 color 与 variant 组合使用：

1import { Button } from "@lenso/ui";2
3export default function App() {4  return <Button color="primary" variant="solid">Button</Button>;5}

在 v3 中，Button 仅使用 variant prop（不再有独立的 color prop）：

1import { Button } from "@lenso/ui";2
3export default function App() {4  return <Button variant="primary">Button</Button>;5}

主要变化

1. 变体与颜色

v2： 使用 color + variant 组合
v3： 仅使用 variant（无独立 color prop）

v2 变体： solid、bordered、light、flat、faded、shadow、ghost
v3 变体： primary、secondary、tertiary、outline、ghost、danger、danger-soft

2. 加载状态：isLoading → isPending

v2： 使用 isLoading prop
v3： 使用 isPending prop

3. 默认宽度行为

v2： 按钮按尺寸带有最小宽度（sm：min-w-16，md：min-w-20，lg：min-w-24）
v3： 按钮默认使用 w-fit（宽度随内容，无最小宽度）

因此当文案较短时，v3 按钮会比 v2 更窄。若要保留 v2 的最小宽度行为，请添加 Tailwind 类，请见下方 尺寸与最小宽度 示例小节。

4. Prop 变更

5. ButtonGroup 仍可用

v2： 提供独立的 ButtonGroup 组件
v3： ButtonGroup 仍然存在。详见 ButtonGroup 迁移指南。

迁移示例

变体

1<Button color="primary" variant="solid">Solid</Button>2<Button color="primary" variant="bordered">Bordered</Button>3<Button color="primary" variant="ghost">Ghost</Button>

danger-soft 变体

danger-soft 变体为 v3 新增，用于替代 v2 中 color="danger" variant="flat" 的用法。

1<Button color="danger" variant="flat">Delete</Button>

仅图标（isIconOnly）

isIconOnly prop 在 v2 与 v3 中均可用，用于渲染适配单个图标的方形按钮。v3 中请用 variant 替代 color 控制样式。

1<Button isIconOnly aria-label="Like" color="danger" variant="flat">2  <HeartIcon />3</Button>4<Button isIconOnly aria-label="Search" color="primary" variant="bordered" size="sm">5  <SearchIcon />6</Button>

加载状态

1{/* Simple loading */}2<Button isLoading color="primary">3  Loading4</Button>5
6{/* Loading with conditional content */}7<Button 8  isLoading={isLoading}9  spinnerPlacement="start"10  color="primary"11  onPress={() => setIsLoading(true)}12>13  Upload File14</Button>

带图标

1import { Icon } from "@iconify/react";2
3<Button 4  color="success" 5  endContent={<Icon icon="gravity-ui:camera" />}6>7  Take a photo8</Button>9<Button 10  color="danger" 11  startContent={<Icon icon="gravity-ui:trash-bin" />}12  variant="bordered"13>14  Delete user15</Button>

仅图标按钮

1<Button isIconOnly aria-label="Like" color="danger">2  <HeartIcon />3</Button>

按钮组

1import { Button, ButtonGroup } from "@lenso/ui";2
3<ButtonGroup size="sm" color="primary" variant="solid">4  <Button>One</Button>5  <Button>Two</Button>6  <Button>Three</Button>7</ButtonGroup>

尺寸与最小宽度

1{/* v2 automatically applies minimum widths */}2<Button size="md" color="primary">Save</Button>

渲染 prop 模式

v3 Button 支持渲染 prop 模式，可拿到状态信息：

1<Button isPending={isLoading}>2  {({isPending, isPressed, isHovered, isFocused, isFocusVisible, isDisabled}) => (3    <>4      {isPending && <Spinner size="sm" />}5      {isPressed ? "Pressed!" : "Click me"}6    </>7  )}8</Button>

可用的渲染 prop：

• isPending — 是否处于加载状态
• isPressed — 是否正被按下
• isHovered — 是否悬停
• isFocused — 是否聚焦
• isFocusVisible — 是否应显示焦点环
• isDisabled — 是否禁用

总结

1. color prop 已移除：请用 variant 替代 color + variant 组合
2. 变体体系变更：新变体系统（primary、secondary、tertiary、outline、ghost、danger、danger-soft）
3. danger-soft 变体：v3 新增，替代 v2 的 color="danger" variant="flat"
4. isLoading → isPending：加载相关 prop 已重命名
5. isIconOnly：v3 仍支持 — 用于仅图标的方形按钮
6. 默认宽度变更：按钮默认 w-fit，不再内置最小宽度 — 可添加 min-w-* 贴近 v2
7. 图标：startContent / endContent 已移除 — 请将图标作为 children
8. 加载指示器：需通过渲染 prop 自行组合 Spinner 等
9. 渲染 prop：v3 Button 的 children 可为函数，参数包含 isPending、isPressed、isHovered、isFocused、isFocusVisible、isDisabled
10. radius 已移除：请使用 Tailwind CSS 类
11. 波纹已移除：v3 无波纹效果
12. ButtonGroup：参见 ButtonGroup 迁移指南
13. classNames 已移除：请使用 className prop