Checkbox 多选框

多选框允许用户从一组选项中选择多个选项。

何时使用

在一组选项中进行多项选择时使用。
单独使用可以表示两种状态之间的切换，和 switch 类似。区别在于切换 switch 会直接触发状态改变，而 checkbox 一般用于状态标记，需要和提交操作配合。

代码演示

基本用法

简单的 checkbox。

Live Editor

function BasicCheckboxDemo() {
  return (
    <Checkbox>Checkbox</Checkbox>
  );
}

Result

不可用状态

Checkbox 不可用状态。

Live Editor

function DisabledCheckboxDemo() {
  return (
    <div className="flex flex-col space-y-4">
      <Checkbox disabled>不可用</Checkbox>
      <Checkbox disabled checked>不可用（已选中）</Checkbox>
    </div>
  );
}

Result

受控组件

联动 checkbox。

Live Editor

function ControlledCheckboxDemo() {
  const [checked, setChecked] = React.useState(true);
  const [disabled, setDisabled] = React.useState(false);

  const toggleChecked = () => {
    setChecked(!checked);
  };

  const toggleDisable = () => {
    setDisabled(!disabled);
  };

  const onChange = (e) => {
    setChecked(e.target.checked);
  };

  const label = `${checked ? '选中' : '未选中'}-${disabled ? '不可用' : '可用'}`;

  return (
    <div className="flex flex-col space-y-4">
      <p className="mb-2">
        <Checkbox
          checked={checked}
          disabled={disabled}
          onChange={onChange}
        >
          {label}
        </Checkbox>
      </p>
      <div className="flex space-x-4">
        <Button type="primary" size="small" onClick={toggleChecked}>
          {!checked ? '选中' : '取消选中'}
        </Button>
        <Button type="primary" size="small" onClick={toggleDisable}>
          {!disabled ? '不可用' : '可用'}
        </Button>
      </div>
    </div>
  );
}

Result

Checkbox 组

方便的从数组生成 Checkbox 组。

Live Editor

function CheckboxGroupDemo() {
  function onChange(checkedValues) {
    console.log('checked = ', checkedValues);
  }
  
  const plainOptions = ['Apple', 'Pear', 'Orange'];
  const options = [
    { label: '苹果', value: 'Apple' },
    { label: '梨', value: 'Pear' },
    { label: '橙子', value: 'Orange' }
  ];
  const optionsWithDisabled = [
    { label: '苹果', value: 'Apple' },
    { label: '梨', value: 'Pear' },
    { label: '橙子', value: 'Orange', disabled: true }
  ];
  
  return (
    <div className="flex flex-col space-y-8">
      <div>
        <h4 className="mb-2 text-gray-600">普通数组</h4>
        <Checkbox.Group options={plainOptions} defaultValue={['Apple']} onChange={onChange} />
      </div>
      
      <div>
        <h4 className="mb-2 text-gray-600">配置对象数组</h4>
        <Checkbox.Group options={options} defaultValue={['Pear']} onChange={onChange} />
      </div>
      
      <div>
        <h4 className="mb-2 text-gray-600">含禁用选项</h4>
        <Checkbox.Group options={optionsWithDisabled} defaultValue={['Apple']} onChange={onChange} />
      </div>
    </div>
  );
}

Result

全选

实现全选/全不选功能。

Live Editor

function CheckAllDemo() {
  const plainOptions = ['Apple', 'Pear', 'Orange'];
  const [checkedList, setCheckedList] = React.useState(['Apple', 'Orange']);
  const [indeterminate, setIndeterminate] = React.useState(true);
  const [checkAll, setCheckAll] = React.useState(false);

  const onChange = (list) => {
    setCheckedList(list);
    setIndeterminate(!!list.length && list.length < plainOptions.length);
    setCheckAll(list.length === plainOptions.length);
  };

  const onCheckAllChange = (e) => {
    setCheckedList(e.target.checked ? plainOptions : []);
    setIndeterminate(false);
    setCheckAll(e.target.checked);
  };

  return (
    <div className="flex flex-col space-y-4">
      <div className="border-b pb-2">
        <Checkbox 
          indeterminate={indeterminate} 
          onChange={onCheckAllChange} 
          checked={checkAll}
        >
          全选
        </Checkbox>
      </div>
      <Checkbox.Group 
        options={plainOptions} 
        value={checkedList} 
        onChange={onChange} 
      />
    </div>
  );
}

Result

布局

Checkbox.Group 内嵌 Checkbox 并与 Grid 组件一起使用可以实现灵活的布局。

Live Editor

function CheckboxLayoutDemo() {
  function onChange(checkedValues) {
    console.log('checked = ', checkedValues);
  }
  
  return (
    <Checkbox.Group onChange={onChange}>
      <div className="grid grid-cols-1 md:grid-cols-3 gap-4">
        <div>
          <Checkbox value="A">A</Checkbox>
        </div>
        <div>
          <Checkbox value="B">B</Checkbox>
        </div>
        <div>
          <Checkbox value="C">C</Checkbox>
        </div>
        <div>
          <Checkbox value="D">D</Checkbox>
        </div>
        <div>
          <Checkbox value="E">E</Checkbox>
        </div>
        <div>
          <Checkbox value="F">F</Checkbox>
        </div>
      </div>
    </Checkbox.Group>
  );
}

Result

自定义样式

组件允许你采用自定义样式和 Tailwind 类名。

Live Editor

function CustomCheckboxDemo() {
  return (
    <div className="flex flex-col space-y-6">
      <Checkbox.Group className="bg-gray-100 p-4 rounded-md">
        <div className="flex flex-col space-y-2">
          <Checkbox value="1" className="text-blue-600">蓝色文本选项</Checkbox>
          <Checkbox value="2" className="text-red-600">红色文本选项</Checkbox>
          <Checkbox value="3" className="text-green-600">绿色文本选项</Checkbox>
        </div>
      </Checkbox.Group>
      
      <Checkbox className="checkbox-custom">
        <span className="font-bold text-purple-600">自定义样式选项</span>
      </Checkbox>
    </div>
  );
}

Result

限制选择数量

限制选择的数量。

Live Editor

function LimitedCheckboxDemo() {
  const options = [
    { label: '选项 A', value: 'A' },
    { label: '选项 B', value: 'B' },
    { label: '选项 C', value: 'C' },
    { label: '选项 D', value: 'D' },
    { label: '选项 E', value: 'E' },
  ];

  const [checkedList, setCheckedList] = React.useState(['A', 'B']);
  const [disabledList, setDisabledList] = React.useState([]);
  
  const onChange = (list) => {
    setCheckedList(list);
    
    // 如果已经选择了2项，禁用其他未选择的选项
    if (list.length >= 2) {
      const disabled = options
        .filter(o => !list.includes(o.value))
        .map(o => o.value);
      setDisabledList(disabled);
    } else {
      // 否则清除禁用状态
      setDisabledList([]);
    }
  };

  // 修改options，添加disabled属性
  const optionsWithDisabled = options.map(option => ({
    ...option,
    disabled: disabledList.includes(option.value)
  }));

  return (
    <div className="flex flex-col space-y-4">
      <p>最多选择2项:</p>
      <Checkbox.Group
        options={optionsWithDisabled}
        value={checkedList}
        onChange={onChange}
      />
      <div>
        <p>已选择: {checkedList.join(', ')}</p>
      </div>
    </div>
  );
}

Result

API

Checkbox

属性	说明	类型	默认值
checked	指定当前是否选中	boolean	false
defaultChecked	初始是否选中	boolean	false
disabled	失效状态	boolean	false
indeterminate	设置 indeterminate 状态，只负责样式控制	boolean	false
onChange	变化时的回调函数	function(e:Event)	-
className	自定义类名	string	-

Checkbox.Group

属性	说明	类型	默认值
defaultValue	默认选中的选项	string[]	[]
disabled	整组失效	boolean	false
options	指定可选项	string[] \| Array<{ label: string value: string disabled?: boolean }>	[]
value	指定选中的选项	string[]	[]
onChange	变化时的回调函数	function(checkedValues)	-
className	自定义类名	string	-

设计指南

Checkbox 多选框主要用于状态标记，需要与提交操作配合。
单独使用时可作为两种状态之间的切换，类似于开关按钮但具有不同的视觉效果。
多个选项组合使用时，可以从一组数据中选择多个值。
当选项数量过多时，可以考虑使用折叠面板或分组展示。

最佳实践

使用积极的表述方式来描述选择框标签，避免使用否定语句。
当存在大量选项时，考虑使用全选/取消全选功能简化用户操作。
对于有依赖关系的选项，可以使用级联选择或禁用相关选项的方式处理。
在表单中使用时，应与其他表单控件保持一致的对齐和间距。
若需要用户必须完成某个选择才能继续操作，请明确指示该多选框为必填项。

何时使用​

代码演示​

基本用法​

不可用状态​

受控组件​

Checkbox 组​

全选​

布局​

自定义样式​

限制选择数量​

API​

Checkbox​

Checkbox.Group​

设计指南​

最佳实践​

何时使用

代码演示

基本用法

不可用状态

受控组件

Checkbox 组

全选

布局

自定义样式

限制选择数量

API

Checkbox

Checkbox.Group

设计指南

最佳实践