ElyriCheckbox
复选框：视觉隐藏的原生 input 承载键盘与表单行为，自绘勾选与半选图形。
安装
添加组件
pnpm dlx @elyri/cli@latest add checkbox示例
基础用法
children 作为标签文案，点击文案即可切换。
import { Checkbox } from './components/elyri/Checkbox';
export function Example() {
return (
<div>
<Checkbox defaultChecked>记住我</Checkbox>
<Checkbox>接收产品动态</Checkbox>
</div>
);
}受控用法
checked 与 onCheckedChange 驱动，外部状态为唯一数据源。
import { useState } from 'react';
import { Checkbox } from './components/elyri/Checkbox';
export function Example() {
const [checked, setChecked] = useState(false);
return <Checkbox checked={checked} onCheckedChange={setChecked}>订阅周报</Checkbox>;
}半选态
常见于「全选」场景，标记 aria-checked="mixed"。
import { Checkbox } from './components/elyri/Checkbox';
export function Example() {
return <Checkbox indeterminate>全部项目</Checkbox>;
}复选组
CheckboxGroup 统一管理多选，value / onValueChange 驱动选中项集合。
import { useState } from 'react';
import { CheckboxGroup } from './components/elyri/Checkbox';
export function Example() {
const [value, setValue] = useState(['email', 'sms']);
return (
<CheckboxGroup value={value} onValueChange={setValue}>
<CheckboxGroup.Checkbox value="email">邮件</CheckboxGroup.Checkbox>
<CheckboxGroup.Checkbox value="sms">短信</CheckboxGroup.Checkbox>
<CheckboxGroup.Checkbox value="push">推送</CheckboxGroup.Checkbox>
</CheckboxGroup>
);
}纵向排列
orientation="vertical" 让选项纵向堆叠，默认横向。
import { CheckboxGroup } from './components/elyri/Checkbox';
export function Example() {
return (
<CheckboxGroup orientation="vertical" defaultValue={['apple']}>
<CheckboxGroup.Checkbox value="apple">Apple</CheckboxGroup.Checkbox>
<CheckboxGroup.Checkbox value="banana">Banana</CheckboxGroup.Checkbox>
<CheckboxGroup.Checkbox value="cherry">Cherry</CheckboxGroup.Checkbox>
</CheckboxGroup>
);
}禁用
勾选与未勾选两种禁用状态。
import { Checkbox } from './components/elyri/Checkbox';
export function Example() {
return (
<div>
<Checkbox disabled defaultChecked>已选且禁用</Checkbox>
<Checkbox disabled>未选且禁用</Checkbox>
</div>
);
}属性
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
checked | boolean | — | 受控选中状态；不传则为非受控 |
defaultChecked | boolean | false | 非受控初始状态，默认 false |
onCheckedChange | (checked: boolean) => void | — | 选中状态变化回调，受控与非受控都会触发 |
indeterminate | boolean | false | 半选态：横线图形 + aria-checked="mixed" |
children | ReactNode | — | 标签文案，渲染在复选框右侧 |
value | string | — | 选项值，放入 CheckboxGroup 时决定该选项是否选中 |
size | 'sm' | 'md' | 'md' | 控件尺寸：sm / md |
...rest | InputHTMLAttributes | — | 其余属性透传给原生 input |
CheckboxGroup.value | string[] | — | 受控选中项集合（CheckboxGroup） |
CheckboxGroup.defaultValue | string[] | — | 非受控初始选中项集合（CheckboxGroup） |
CheckboxGroup.onValueChange | (value: string[]) => void | — | 选中项变化回调，受控与非受控都会触发（CheckboxGroup） |
CheckboxGroup.orientation | 'horizontal' | 'vertical' | 'horizontal' | 排列方向，默认 horizontal（CheckboxGroup） |
CheckboxGroup.disabled | boolean | false | 组级禁用，作用于全部选项（CheckboxGroup） |