#Checkbox 复选框
用于从一组选项中选择多项。
#基础用法
basic.tsx
import { Checkbox, Space } from '@ifhover/leaf-ui';
export function CheckboxBasic() {
return (
<Space wrap>
<Checkbox defaultChecked>接收项目动态</Checkbox>
<Checkbox>接收每周摘要</Checkbox>
<Checkbox disabled>暂不可用</Checkbox>
<Checkbox disabled defaultChecked>
已锁定
</Checkbox>
</Space>
);
}
#全选与半选
indeterminate 表示部分选中,用于汇总子选项。它只影响显示与辅助技术识别;全选和提交值由 checked 决定。
已选择 1 项
check-all.tsx
import { Checkbox, Flex, Space, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';
const options = ['设计更新', '产品动态', '每周摘要'];
export function CheckboxCheckAll() {
const [selected, setSelected] = useState<string[]>(['设计更新']);
const allChecked = selected.length === options.length;
return (
<Space direction="vertical" align="stretch">
<Checkbox
checked={allChecked}
indeterminate={selected.length > 0 && !allChecked}
onChange={(event) => setSelected(event.target.checked ? [...options] : [])}
>
订阅全部
</Checkbox>
<Flex gap="md" align="center" wrap justify="center">
{options.map((option) => (
<Checkbox
key={option}
checked={selected.includes(option)}
onChange={(event) =>
setSelected(
event.target.checked
? [...selected, option]
: selected.filter((item) => item !== option),
)
}
>
{option}
</Checkbox>
))}
</Flex>
<Text tone="muted">已选择 {selected.length} 项</Text>
</Space>
);
}
#扩展用法
extensions.tsx
import { CheckboxGroup } from '@ifhover/leaf-ui';
export function ExtensionDemo() {
return (
<CheckboxGroup
legend="选择 1–2 个兴趣"
options={['设计', '开发', '摄影']}
defaultValue={['设计']}
minCount={1}
maxCount={2}
/>
);
}
#卡片选项
卡片整块可点击,适合包含图标和说明的选项。
surfaces.tsx
import { Checkbox, CheckboxGroup, Space } from '@ifhover/leaf-ui';
import { HardDrive, Mail, MessageSquare } from 'lucide-react';
export function CheckboxCards() {
return (
<Space direction="vertical" align="stretch">
<CheckboxGroup
variant="card"
legend={'连接服务'}
defaultValue={['mail']}
options={[
{
value: 'mail',
label: '邮件',
description: '读取与整理邮件',
icon: <Mail />,
},
{
value: 'drive',
label: '云端文件',
description: '查找与整理文件',
icon: <HardDrive />,
},
{
value: 'chat',
label: '团队沟通',
description: '当前不可用',
icon: <MessageSquare />,
disabled: true,
},
]}
/>
<Checkbox
variant="card"
indeterminate
description={'部分服务已启用'}
>
{'全部服务'}
</Checkbox>
</Space>
);
}
#成组选项
相关选项共用边框和行分隔线;状态标签放在右侧。
surfaces.tsx
import { CheckboxGroup, Tag } from '@ifhover/leaf-ui';
export function CheckboxList() {
return (
<CheckboxGroup
variant="list"
legend={'邮件权限'}
defaultValue={['read']}
options={[
{ value: 'read', label: '读取邮件', description: 'mail.readonly' },
{
value: 'send',
label: '发送邮件',
description: 'mail.send',
extra: (
<Tag color="warning" size="sm">
{'需要审批'}
</Tag>
),
},
{
value: 'delete',
label: '删除邮件',
description: 'mail.modify',
extra: <Tag size="sm">{'策略限制'}</Tag>,
disabled: true,
},
]}
/>
);
}
#Checkbox API
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
size | 'sm' | 'md' | 'lg' | 'md' | 复选框尺寸 |
variant | 'plain' | 'card' | 'plain' | 普通选项或整块可点击的卡片选项。 |
description | ReactNode | — | 补充说明。 |
icon | ReactNode | — | 图标内容。 |
extra | ReactNode | — | 补充状态文字或标签;不要放置交互控件。 |
indeterminate | boolean | false | 半选状态 |
checked | boolean | — | 受控选中状态 / 非受控初始状态 |
defaultChecked | boolean | — | 受控选中状态 / 非受控初始状态 |
onChange | ChangeEventHandler<HTMLInputElement> | — | 值发生变化时调用。 |
disabled | boolean | false | 禁用交互。 |
children | ReactNode | — | 子内容;嵌套数据类型表示子节点。 |
ref | Ref<HTMLInputElement> | — | 复选框引用 |
name、value、required、form 等原生属性可直接使用。只有已勾选且未禁用的复选框参与原生表单提交。没有文字标签时必须提供 aria-label。className 与 style 作用于标签容器。
#类型
可导入 CheckboxProps 定义组件属性,或使用尺寸类型:
import type { CheckboxProps, ControlSize } from '@ifhover/leaf-ui';#扩展类型
import type { CheckboxGroupProps, CheckboxOption } from '@ifhover/leaf-ui';#CheckboxGroupProps API
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
options | readonly (CheckboxOption | string)[] | 必填 | 必需。可用选项 |
value | readonly string[] | — | 受控值 |
defaultValue | readonly string[] | [] | 初始值;非受控表单 reset 时恢复 |
onChange | (values: string[]) => void | — | 值变化回调 |
legend | ReactNode | — | 字段组名称 |
size | 'sm' | 'md' | 'lg' | — | 尺寸或间距预设 |
variant | 'plain' | 'card' | 'list' | 'plain' | 普通排列、卡片网格或带分隔线的成组列表。 |
minCount | number | 0 | 最少勾选数量 |
maxCount | number | Infinity | 最多勾选或展示数量 |
required | boolean | — | 要求整体值非空,复合控件只校验一次。 |
direction | 'horizontal' | 'vertical' | 'horizontal' | 排列方向或移动方向 |
#CheckboxOption API
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
value | string | 必填 | 必需。受控值 |
label | ReactNode | 必填 | 必需。显示内容 |
description | ReactNode | — | 补充说明。 |
icon | ReactNode | — | 图标内容。 |
extra | ReactNode | — | 补充状态文字或标签;不要放置交互控件。 |
disabled | boolean | — | 禁用交互。 |
#外观与丰富内容
Checkbox 的 variant="card" 让标签整体成为可点击卡片;CheckboxGroup 的 variant="card" 自动排列卡片,variant="list" 使用成组列表。description 与 extra 会作为辅助描述,icon 为装饰内容。extra 适合状态标签,不应包含按钮或链接。原生 name、value、form、表单重置与键盘操作保持可用。