Checkbox#
数据录入
@rockshin/tao-ui选择一个或多个相互独立的布尔选项。
#何时使用
独立选择使用 Checkbox;从一组选项中多选时使用 CheckboxGroup。
推荐
- 标签应准确描述选中后的状态。
- 相关选项使用 CheckboxGroup 组织。
避免
- 只能选一个选项时不要使用 CheckboxGroup,应改用 RadioGroup。
#代码演示
#基础用法
TSX
import { Checkbox, CheckboxGroup, Stack } from '@rockshin/tao-ui';
import { useState } from 'react';
function CheckboxExample() {
const [updates, setUpdates] = useState(true);
const [channels, setChannels] = useState(['email', 'push']);
return (
<Stack gap="md">
<Checkbox
checked={updates}
onChange={(event) => setUpdates(event.target.checked)}
>
Send product updates
</Checkbox>
<CheckboxGroup
value={channels}
onChange={setChannels}
options={[
{ label: 'Email', value: 'email' },
{ label: 'Push', value: 'push' },
{ label: 'SMS', value: 'sms', disabled: true },
]}
/>
</Stack>
);
}
export default CheckboxExample;#独立状态
TSX
import { Checkbox, Stack } from '@rockshin/tao-ui';
import { useState } from 'react';
function CheckboxStates() {
const [unchecked, setUnchecked] = useState(false);
const [checked, setChecked] = useState(true);
const [mixed, setMixed] = useState(false);
return (
<Stack direction="horizontal" gap="lg" style={{ flexWrap: 'wrap' }}>
<Checkbox
checked={unchecked}
onChange={(event) => setUnchecked(event.target.checked)}
>
Unchecked
</Checkbox>
<Checkbox
checked={checked}
onChange={(event) => setChecked(event.target.checked)}
>
Checked
</Checkbox>
<Checkbox
checked={mixed}
indeterminate={!mixed}
onChange={(event) => setMixed(event.target.checked)}
>
Indeterminate
</Checkbox>
<Checkbox disabled>Disabled</Checkbox>
<Checkbox checked disabled onChange={() => {}}>
Checked disabled
</Checkbox>
</Stack>
);
}
export default CheckboxStates;#纵向选项组
TSX
import { CheckboxGroup, FormField } from '@rockshin/tao-ui';
import { useState } from 'react';
function VerticalCheckboxGroup() {
const [value, setValue] = useState(['email']);
return (
<FormField label="Notifications">
<CheckboxGroup
direction="vertical"
value={value}
onChange={setValue}
options={[
{ label: 'Email updates', value: 'email' },
{ label: 'Push notifications', value: 'push' },
{ label: 'SMS alerts', value: 'sms', disabled: true },
]}
/>
</FormField>
);
}
export default VerticalCheckboxGroup;#受控复选框
onChange 提供原生事件,从 target.checked 读取新值。
TSX
import { useState } from 'react';
import { Checkbox, Stack } from '@rockshin/tao-ui';
export default function Example() {
const [checked, setChecked] = useState(false);
return (
<Stack direction="vertical">
<Checkbox
checked={checked}
onChange={(e) => setChecked(e.target.checked)}
>
Receive updates
</Checkbox>
<output>{checked ? 'Subscribed' : 'Not subscribed'}</output>
</Stack>
);
}#全选与半选
由当前选项数量计算半选状态,避免分别维护互相矛盾的状态。
TSX
import { useState } from 'react';
import { Checkbox, CheckboxGroup, Stack } from '@rockshin/tao-ui';
export default function Example() {
const [values, setValues] = useState<string[]>(['Read']);
return (
<Stack direction="vertical">
<Checkbox
checked={values.length === 3}
indeterminate={values.length > 0 && values.length < 3}
onChange={(e) =>
setValues(e.target.checked ? ['Read', 'Write', 'Share'] : [])
}
>
Select all
</Checkbox>
<CheckboxGroup
options={['Read', 'Write', 'Share']}
value={values}
onChange={setValues}
/>
<output>{values.join(', ') || 'None selected'}</output>
</Stack>
);
}#垂直排列与禁用选项
对象形式的 options 可单独禁用选项,direction 控制排列方向。
TSX
import { CheckboxGroup } from '@rockshin/tao-ui';
export default function Example() {
return (
<CheckboxGroup
direction="vertical"
options={[
{ label: 'Email', value: 'email' },
{ label: 'SMS', value: 'sms' },
{ label: 'Phone (unavailable)', value: 'phone', disabled: true },
]}
defaultValue={['email']}
/>
);
}#原生表单值
将受控选项写入隐藏输入,再通过 FormData 读取。
TSX
import { useState } from 'react';
import { CheckboxGroup, Button, Stack } from '@rockshin/tao-ui';
export default function Example() {
const [values, setValues] = useState<string[]>(['email']);
const [result, setResult] = useState('');
return (
<form
onSubmit={(e) => {
e.preventDefault();
setResult(
new FormData(e.currentTarget).getAll('channel').join(', ') || 'None',
);
}}
>
<Stack direction="vertical">
<CheckboxGroup
options={['email', 'sms']}
value={values}
onChange={setValues}
/>
{values.map((value) => (
<input key={value} type="hidden" name="channel" value={value} />
))}
<Button type="submit">Read values</Button>
<output>{result}</output>
</Stack>
</form>
);
}#尺寸与共享禁用
局部 Provider 统一尺寸,也可统一禁用一组控件。
TSX
import { Checkbox, TaoProvider, Stack } from '@rockshin/tao-ui';
export default function Example() {
return (
<Stack direction="vertical">
{(['small', 'medium', 'large'] as const).map((size) => (
<TaoProvider key={size} size={size}>
<Checkbox>{size}</Checkbox>
</TaoProvider>
))}
<TaoProvider disabled>
<Checkbox defaultChecked>Disabled by provider</Checkbox>
</TaoProvider>
</Stack>
);
}