Checkbox

复选框（Checkbox）用于在一组选项中选择一个或多个值。组件同时提供基础复选框、数据驱动的复选框组、卡片式复选框和卡片式复选框组。

import {
  Checkbox,
  CheckboxCard,
  CheckboxControl,
  CheckboxGroup,
  CheckboxGroupCard,
  CheckboxIndicator,
  CheckboxRoot
} from '@skyroc/web-ui';

架构说明

Checkbox 由 Radix Checkbox 封装而来，基础组件负责单个选中状态，Group 组件负责多值集合状态。

• Checkbox：单个复选框，支持 checked、defaultChecked 和 indeterminate。
• CheckboxGroup：数据驱动的复选框组，通过 items 渲染多个 Checkbox。
• CheckboxCard：卡片样式的单个复选框，支持图标、标题、描述和左右控制器位置。
• CheckboxGroupCard：数据驱动的卡片式复选框组，状态模型与 CheckboxGroup 一致。
• CheckboxRoot、CheckboxControl、CheckboxIndicator：基础结构子组件，适合需要完全自定义组合时使用。

何时使用

• 用户可以选择多个选项，且每个选项可以独立开关时。
• 需要通过“全选”展示部分选中状态时。
• 需要从一组配置项、权限项、偏好项中选择多个值时。
• 选项需要图标、描述或更大点击区域时，使用 CheckboxCard 或 CheckboxGroupCard。
• 如果用户只能选择一个选项，应使用 Radio；如果只是开关单一功能状态，应使用 Switch。

基础用法

Checkbox 支持受控与非受控模式。受控模式通过 checked 和 onCheckedChange 管理状态。

颜色

通过 color 控制选中和半选状态的颜色。基础 Checkbox 和卡片 Checkbox 都使用同一套主题颜色。

尺寸

通过 size 控制控制器尺寸、文字间距以及 Group 间距，从 xs 到 2xl 共 6 个尺寸。

状态

checked 可以是 true、false 或 'indeterminate'。半选状态常用于全选控件，表示子项只选中了其中一部分。

禁用

设置 disabled 后，复选框不可交互。Group 上的 disabled 会传递给所有子项，子项也可以单独设置 disabled。

复选框组

CheckboxGroup 使用 items 渲染选项列表，value / defaultValue 是当前选中的 value 数组。onValueChange 返回完整的新数组。

卡片复选框

CheckboxCard 适合展示更丰富的可选项。icon、label 和 description 组成内容区，checkboxPosition 控制复选框在左侧还是右侧。

卡片复选框组

CheckboxGroupCard 与 CheckboxGroup 使用相同的多值状态模型，但每个选项会渲染为 CheckboxCard。适合权限、能力、套餐、偏好等更强调内容说明的选择场景。

API

Checkbox

通用属性参考：支持 Radix Checkbox Root 的属性，如 checked、defaultChecked、disabled、required、name、value 和 onCheckedChange。

CheckboxGroup

CheckboxGroup 是数据驱动组件。items 中每一项都会渲染为一个 Checkbox，Group 负责维护 value 数组。

CheckboxCard

CheckboxCard 支持 Radix Checkbox Root 的属性，并额外提供卡片内容和布局属性。

CheckboxGroupCard

CheckboxGroupCard 使用 CheckboxGroupCardItem[] 渲染卡片式选项，受控和非受控规则与 CheckboxGroup 一致。

子组件

类型