Switch

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

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

结构变化

在 v2 中，Switch 结构简单，children 作为标签：

1import { Switch } from "@lenso/ui";2
3export default function App() {4  return <Switch>Enable notifications</Switch>;5}

在 v3 中，Switch 需要复合组件：

1import { Switch, Label } from "@lenso/ui";2
3export default function App() {4  return (5    <Switch>6      <Switch.Content>7        <Switch.Control>8          <Switch.Thumb />9        </Switch.Control>10        Enable notifications11      </Switch.Content>12    </Switch>13  );14}

主要变化

1. 组件结构

v2： children 作为标签的简单 Switch
v3： 复合组件（Switch.Content、Switch.Control、Switch.Thumb）与 Label 组件

2. Prop 变更

v2 prop	v3 位置	说明
`onValueChange`	`onChange`	事件处理函数已重命名
`size`	`size`	仍在根上（`sm` \| `md` \| `lg`）
`label`	—	请使用 `Label` 组件
`color`	—	已移除（请使用 Tailwind CSS）
`thumbIcon`	—	请在 `Switch.Thumb` 内使用 `Switch.Icon`
`startContent`	—	请直接自定义控件
`endContent`	—	请直接自定义控件
`classNames`	—	请在各子组件上使用 `className`
`disableAnimation`	—	已移除（动画机制已不同）

3. 新组件

SwitchGroup — 用于将多个 Switch 成组
Switch.Content — 可点击的标签，包裹控件与 Label
Switch.Icon — 拇指（Thumb）内的图标

迁移示例

受控 Switch

1import { useState } from "react";2
3const [isSelected, setIsSelected] = useState(true);4
5<Switch isSelected={isSelected} onValueChange={setIsSelected}>6  Airplane mode7</Switch>

无标签

1<Switch defaultSelected aria-label="Automatic updates" />

带拇指图标

1<Switch thumbIcon={<CheckIcon />}>Enable notifications</Switch>

带起始 / 结束内容

1<Switch2  startContent={<SunIcon />}3  endContent={<MoonIcon />}4>5  Dark mode6</Switch>

带标签与描述

1<Switch description="You will receive notifications for all activity">2  Enable notifications3</Switch>

尺寸与颜色

1{/* Sizes */}2<div className="flex gap-4">3  <Switch size="sm">Small</Switch>4  <Switch size="md">Medium</Switch>5  <Switch size="lg">Large</Switch>6</div>7
8{/* Colors */}9<Switch color="primary">Primary</Switch>10<Switch color="success">Success</Switch>11<Switch color="danger">Danger</Switch>

Switch 组

1{/* No built-in group component in v2 */}2<div className="flex flex-col gap-2">3  <Switch name="notifications">Allow Notifications</Switch>4  <Switch name="marketing">Marketing emails</Switch>5</div>

组件组成

v3 Switch 的结构如下：

1Switch (Root)2  ├── Switch.Content (the clickable label)3  │   ├── Switch.Control4  │   │   └── Switch.Thumb5  │   │       └── Switch.Icon (optional)6  │   └── Label7  ├── Description (optional, sibling)8  └── FieldError (optional, sibling)

分组时：

1SwitchGroup2  ├── Switch3  │   ├── Switch.Content4  │   │   ├── Switch.Control5  │   │   │   └── Switch.Thumb6  │   │   └── Label7  │   └── Description (optional)8  └── Switch9      ├── Switch.Content10      │   ├── Switch.Control11      │   │   └── Switch.Thumb12      │   └── Label13      └── Description (optional)

说明

事件处理函数

v2： onValueChange prop
v3： onChange prop（签名相同：(isSelected: boolean) => void）

图标

v2： thumbIcon 用于拇指内图标，startContent / endContent 用于外侧图标
v3： 拇指内图标用 Switch.Icon（置于 Switch.Thumb 内）；起始 / 结束内容请自定义 Switch.Control

总结

组件结构：必须使用复合组件（Switch.Content、Switch.Control、Switch.Thumb）
可点击的标签：用 Switch.Content 包裹 Switch.Control 与 Label；将 Description / FieldError 作为 Switch.Content 的同级元素
标签：不再用 children 作为标签 — 请在 Switch.Content 内使用 Label
事件处理函数：onValueChange → onChange
样式相关 prop 已移除：color — 请使用 Tailwind CSS
图标相关 prop 已移除：thumbIcon、startContent、endContent — 请用子组件或直接自定义
classNames 已移除：请在各子组件上使用 className prop
新组件：SwitchGroup 用于成组；Switch.Content 作为可点击的标签，包裹控件与 Label