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

结构变化

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

import { Checkbox, CheckboxGroup } from "@heroui/react";

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 "@heroui/react";

export default function App() {
  return (
    <CheckboxGroup name="interests">
      <Label>Select interests</Label>
      <Checkbox value="coding">
        <Checkbox.Control>
          <Checkbox.Indicator />
        </Checkbox.Control>
        <Checkbox.Content>
          <Label>Coding</Label>
        </Checkbox.Content>
      </Checkbox>
      <Checkbox value="design">
        <Checkbox.Control>
          <Checkbox.Indicator />
        </Checkbox.Control>
        <Checkbox.Content>
          <Label>Design</Label>
        </Checkbox.Content>
      </Checkbox>
      <Checkbox value="writing">
        <Checkbox.Control>
          <Checkbox.Indicator />
        </Checkbox.Control>
        <Checkbox.Content>
          <Label>Writing</Label>
        </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.Control、Checkbox.Indicator 与 Checkbox.Content 组成

4. 事件处理函数

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

5. 变体支持

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

迁移示例

受控复选框组

import { useState } from "react";
import { Checkbox, CheckboxGroup } from "@heroui/react";

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>

import { useState } from "react";
import { CheckboxGroup, Checkbox, Label } from "@heroui/react";

const [selected, setSelected] = useState(["coding"]);

<CheckboxGroup
  name="interests"
  value={selected}
  onChange={setSelected}
>
  <Label>Select interests</Label>
  <Checkbox value="coding">
    <Checkbox.Control>
      <Checkbox.Indicator />
    </Checkbox.Control>
    <Checkbox.Content>
      <Label>Coding</Label>
    </Checkbox.Content>
  </Checkbox>
  <Checkbox value="design">
    <Checkbox.Control>
      <Checkbox.Indicator />
    </Checkbox.Control>
    <Checkbox.Content>
      <Label>Design</Label>
    </Checkbox.Content>
  </Checkbox>
  <Checkbox value="writing">
    <Checkbox.Control>
      <Checkbox.Indicator />
    </Checkbox.Control>
    <Checkbox.Content>
      <Label>Writing</Label>
    </Checkbox.Content>
  </Checkbox>
</CheckboxGroup>

总结

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

CheckboxGroup

本页目录