跳转到内容
AsterUI v0.12.76

Checkbox 复选框

用于选择多个选项的复选框组件，支持各种样式和分组功能。

引入

Section titled “引入”
import { Checkbox } from 'asterui'

示例

Section titled “示例”

基本用法

带标签的简单复选框。

 
import { Checkbox } from 'asterui'

function App() {
  return (
      <Checkbox>Accept terms and conditions</Checkbox>
    )
}

export default App

颜色

用于各种上下文的不同复选框颜色。

 
import { Checkbox, Space } from 'asterui'

function App() {
  return (
      <Space direction="vertical" size="sm">
        <Checkbox color="primary" defaultChecked>Primary</Checkbox>
        <Checkbox color="secondary" defaultChecked>Secondary</Checkbox>
        <Checkbox color="accent" defaultChecked>Accent</Checkbox>
        <Checkbox color="success" defaultChecked>Success</Checkbox>
        <Checkbox color="warning" defaultChecked>Warning</Checkbox>
        <Checkbox color="info" defaultChecked>Info</Checkbox>
        <Checkbox color="error" defaultChecked>Error</Checkbox>
      </Space>
    )
}

export default App

尺寸

从 xs 到 xl 的五种复选框尺寸。

 
import { Checkbox, Space } from 'asterui'

function App() {
  return (
      <Space direction="horizontal" size="md" align="center">
        <Checkbox size="xs" defaultChecked>XS</Checkbox>
        <Checkbox size="sm" defaultChecked>SM</Checkbox>
        <Checkbox size="md" defaultChecked>MD</Checkbox>
        <Checkbox size="lg" defaultChecked>LG</Checkbox>
        <Checkbox size="xl" defaultChecked>XL</Checkbox>
      </Space>
    )
}

export default App

禁用状态

禁用的复选框状态。

 
import { Checkbox, Space } from 'asterui'

function App() {
  return (
      <Space direction="horizontal" size="md">
        <Checkbox disabled>Disabled</Checkbox>
        <Checkbox disabled defaultChecked>Disabled Checked</Checkbox>
      </Space>
    )
}

export default App

不确定状态

用于全选功能的不确定状态。

 
import { Checkbox, Space } from 'asterui'
import { useState } from 'react'

function App() {
  const [items, setItems] = useState([true, false, true])
  const allChecked = items.every(Boolean)
  const someChecked = items.some(Boolean) && !allChecked
  
  const handleSelectAll = () => {
    setItems(allChecked ? [false, false, false] : [true, true, true])
  }
  
  return (
      <Space direction="vertical" size="sm">
        <Checkbox
          checked={allChecked}
          indeterminate={someChecked}
          onChange={handleSelectAll}
          className="font-medium"
        >
          Select All
        </Checkbox>
        <div className="ml-6">
          <Space direction="vertical" size="xs">
            {['Item 1', 'Item 2', 'Item 3'].map((item, i) => (
              <Checkbox
                key={i}
                checked={items[i]}
                onChange={() => {
                  const newItems = [...items]
                  newItems[i] = !newItems[i]
                  setItems(newItems)
                }}
              >
                {item}
              </Checkbox>
            ))}
          </Space>
        </div>
      </Space>
    )
}

export default App

复选框组

使用共享状态分组多个复选框。

 
import { Checkbox, Modal } from 'asterui'

function App() {
  const options = [
    { label: 'Apple', value: 'apple' },
    { label: 'Banana', value: 'banana' },
    { label: 'Orange', value: 'orange' },
    { label: 'Mango', value: 'mango' },
  ]
  
  return (
      <Checkbox.Group
        options={options}
        defaultValue={['apple', 'orange']}
        onChange={(values) => Modal.info({ title: 'Selected', content: values.join(', ') })}
      />
    )
}

export default App

带选项的组

从选项数组生成复选框，支持禁用。

 
import { Checkbox } from 'asterui'

function App() {
  const options = [
    { label: 'Read', value: 'read' },
    { label: 'Write', value: 'write' },
    { label: 'Delete', value: 'delete', disabled: true },
  ]
  
  return (
      <Checkbox.Group
        options={options}
        defaultValue={['read']}
      />
    )
}

export default App

组方向

横向和纵向组布局。

Horizontal (default)

Vertical

 
import { Checkbox, Space } from 'asterui'

function App() {
  const options = ['Option A', 'Option B', 'Option C']
  
  return (
      <Space direction="vertical" size="lg">
        <div>
          <p className="text-sm font-medium mb-2">Horizontal (default)</p>
          <Checkbox.Group options={options} direction="horizontal" defaultValue={['Option A']} />
        </div>
        <div>
          <p className="text-sm font-medium mb-2">Vertical</p>
          <Checkbox.Group options={options} direction="vertical" defaultValue={['Option B']} />
        </div>
      </Space>
    )
}

export default App

受控模式

带外部状态管理的受控复选框。

Checked: No

 
import { Checkbox, Space } from 'asterui'
import { useState } from 'react'

function App() {
  const [checked, setChecked] = useState(false)
  
  return (
      <Space direction="vertical" size="sm">
        <Checkbox
          checked={checked}
          onChange={(e) => setChecked(e.target.checked)}
        >
          Controlled checkbox
        </Checkbox>
        <p className="text-sm text-base-content/70">
          Checked: {checked ? 'Yes' : 'No'}
        </p>
      </Space>
    )
}

export default App

交换模式

使用动画效果在两个视觉状态之间切换。

 
import { Checkbox, Space } from 'asterui'
import { SpeakerWaveIcon, SpeakerXMarkIcon } from '@aster-ui/icons/solid'
import { useState } from 'react'

function App() {
  const [volume, setVolume] = useState(true)
  
  return (
      <Space size="lg">
        <Checkbox
          checked={volume}
          onChange={(e) => setVolume(e.target.checked)}
          swap={{
            on: <SpeakerWaveIcon size={32} />,
            off: <SpeakerXMarkIcon size={32} />,
          }}
        />
        <Checkbox
          swap={{
            on: <span className="text-2xl">😀</span>,
            off: <span className="text-2xl">😴</span>,
            effect: 'rotate',
          }}
        />
        <Checkbox
          swap={{
            on: <span className="text-xl font-bold text-success">ON</span>,
            off: <span className="text-xl font-bold text-error">OFF</span>,
            effect: 'flip',
          }}
        />
      </Space>
    )
}

export default App

API

Section titled “API”

Checkbox

Section titled “Checkbox”
属性描述类型默认值
checked受控的选中状态boolean-
defaultChecked默认选中状态boolean-
disabled禁用复选框booleanfalse
indeterminate不确定状态（部分选择）booleanfalse
size复选框大小'xs' | 'sm' | 'md' | 'lg' | 'xl'-
color复选框颜色'primary' | 'secondary' | 'accent' | 'neutral' | 'success' | 'warning' | 'info' | 'error'-
swap交换模式配置CheckboxSwapConfig-
value在组中使用时的值string | number-
onChange改变事件处理函数(e: ChangeEvent) => void-
name输入的 HTML name 属性string-
autoFocus挂载时自动聚焦booleanfalse
className额外的 CSS 类名string-
children标签内容（自动包裹在 label 元素中）ReactNode-

Checkbox.Group

Section titled “Checkbox.Group”
属性描述类型默认值
value受控的选中值(string | number)[]-
defaultValue默认选中值(string | number)[]-
onChange选择改变回调函数(values: (string | number)[]) => void-
disabled禁用所有复选框booleanfalse
options复选框选项(string | number | CheckboxOptionType)[]-
direction布局方向'horizontal' | 'vertical''vertical'
name所有复选框的 HTML name 属性（用于表单提交）string-
children手动复选框元素ReactNode-

CheckboxSwapConfig

Section titled “CheckboxSwapConfig”
属性描述类型默认值
on选中时显示的内容ReactNode-
off未选中时显示的内容ReactNode-
effect动画效果'rotate' | 'flip'-

CheckboxOptionType

Section titled “CheckboxOptionType”
属性描述类型默认值
label选项标签ReactNode-
value选项值string | number-
disabled禁用此选项booleanfalse

无障碍

Section titled “无障碍”
  • 使用原生复选框输入以获得键盘和屏幕阅读器支持
  • 正确地将标签与复选框关联
  • 不确定状态通过原生 indeterminate 属性传达
  • 禁用状态防止交互并传达给辅助技术
  • 焦点状态对键盘导航可见