• 简体中文
  • Checkbox 复选框

    用于从一组选项中选择多项。

    基础用法

    交互预览基础用法
    basic.tsx
    import { Checkbox } from '@sudden3/leaf-ui';
    
    export function CheckboxBasic() {
      return (
        <>
          <Checkbox defaultChecked>接收项目动态</Checkbox>
          <Checkbox>接收每周摘要</Checkbox>
          <Checkbox disabled>暂不可用</Checkbox>
          <Checkbox disabled defaultChecked>
            已锁定
          </Checkbox>
        </>
      );
    }
    

    全选与半选

    indeterminate 表示部分选中,用于汇总子选项。它只影响显示与辅助技术识别;全选和提交值由 checked 决定。

    交互预览全选与半选
    已选择 1 项
    check-all.tsx
    import { Checkbox } from '@sudden3/leaf-ui';
    import { useState } from 'react';
    
    const options = ['设计更新', '产品动态', '每周摘要'];
    
    export function CheckboxCheckAll() {
      const [selected, setSelected] = useState<string[]>(['设计更新']);
      const allChecked = selected.length === options.length;
      return (
        <div className="leaf-demo-stack">
          <Checkbox
            checked={allChecked}
            indeterminate={selected.length > 0 && !allChecked}
            onChange={(event) => setSelected(event.target.checked ? [...options] : [])}
          >
            订阅全部
          </Checkbox>
          <div className="leaf-demo-row">
            {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>
            ))}
          </div>
          <span className="leaf-demo-note">已选择 {selected.length} 项</span>
        </div>
      );
    }
    

    Checkbox API

    属性类型默认值说明
    checked / defaultCheckedboolean—受控选中状态 / 非受控初始状态
    indeterminatebooleanfalse半选状态
    onChangeChangeEventHandler<HTMLInputElement>—从 event.target.checked 读取选中状态
    disabledbooleanfalse禁用选项
    size'sm' | 'md' | 'lg''md'复选框尺寸
    childrenReactNode—可点击的选项标签
    refRef<HTMLInputElement>—复选框引用

    name、value、required、form 等原生属性可直接使用。只有已勾选且未禁用的复选框参与原生表单提交。没有文字标签时必须提供 aria-label。className 与 style 作用于标签容器。

    类型

    可导入 CheckboxProps 定义组件属性,或使用尺寸类型:

    import type { CheckboxProps, ControlSize } from '@sudden3/leaf-ui';