Skip to content
Lenso UI

CheckboxGroup

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

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

结构变化

在 v2 中，CheckboxGroup 是单个组件，通过 label prop 描述分组，子项为简单的 Checkbox：

import { Checkbox, CheckboxGroup } from "@lenso/ui";
export default function App() {  return (    <CheckboxGroup label="Select interests">      <Checkbox value="coding">Coding</Checkbox>      <Checkbox value="design">Design</Checkbox>      <Checkbox value="writing">Writing</Checkbox>    </CheckboxGroup>  );}

在 v3 中，CheckboxGroup 仍是单个组件，但改为以 Label / Description 作为子节点，并使用全新的 Checkbox 复合结构：

import { CheckboxGroup, Checkbox, Label, Description } from "@lenso/ui";
export default function App() {  return (    <CheckboxGroup name="interests">      <Label>Select interests</Label>      <Checkbox value="coding">        <Checkbox.Content>          <Checkbox.Control>            <Checkbox.Indicator />          </Checkbox.Control>          Coding        </Checkbox.Content>      </Checkbox>      <Checkbox value="design">        <Checkbox.Content>          <Checkbox.Control>            <Checkbox.Indicator />          </Checkbox.Control>          Design        </Checkbox.Content>      </Checkbox>      <Checkbox value="writing">        <Checkbox.Content>          <Checkbox.Control>            <Checkbox.Indicator />          </Checkbox.Control>          Writing        </Checkbox.Content>      </Checkbox>    </CheckboxGroup>  );}

主要变化

1. 组件名称保持一致

v2： CheckboxGroup（单一组件，通过 label prop 描述分组）
v3： CheckboxGroup（单一组件，使用 Label 组件代替 label prop）

2. Label prop

v2： 在 CheckboxGroup 上使用 label prop
v3： 改用 Label 组件作为 CheckboxGroup 的子节点

3. Checkbox 结构

v2： 简单的 Checkbox 组件，子节点直接作为标签
v3： 复合 Checkbox 组件，由 Checkbox.Content、Checkbox.Control 与 Checkbox.Indicator 组成

4. 事件处理函数

v2： 使用 onValueChange prop
v3： 改用 onChange prop（来自 React Aria Components）

5. 变体支持

v3： 新增 variant prop，用于设置分组容器的样式

迁移示例

受控复选框组

import { useState } from "react";import { Checkbox, CheckboxGroup } from "@lenso/ui";
const [selected, setSelected] = useState(["coding"]);
<CheckboxGroup  value={selected}  onValueChange={setSelected}  label="Select interests">  <Checkbox value="coding">Coding</Checkbox>  <Checkbox value="design">Design</Checkbox>  <Checkbox value="writing">Writing</Checkbox></CheckboxGroup>

总结

  • 继续使用 CheckboxGroup；用 Label 子组件取代 label prop
  • 将 Checkbox 子项更新为复合组件结构（Checkbox.Content、Checkbox.Control、Checkbox.Indicator）
  • 将 onValueChange 改为 onChange
  • 添加 name prop 以便集成到表单中
  • 基于 React Aria Components 构建，更易实现无障碍