Checkbox

• 组件说明：复选框控件，支持选中、未选中、半选三种状态。
• 交互特征：当前规范覆盖未选中、选中、半选、禁用和悬停主矩阵。
• 实现约定：Checkbox 保留基础选择语义，design 层统一接管边框、填充和图标视觉。
• Figma 规范

基础用法

结果

Loading...

实时编辑器

render(
  <div style={{ display: 'flex', gap: 16, alignItems: 'center' }}>
    <Checkbox aria-label="Option A" />
    <Checkbox defaultChecked aria-label="Option B" />
    <Checkbox checked="indeterminate" aria-label="Option C" />
  </div>,
)

禁用状态

结果

Loading...

实时编辑器

render(
  <div style={{ display: 'flex', gap: 16, alignItems: 'center' }}>
    <Checkbox disabled aria-label="Disabled unchecked" />
    <Checkbox disabled defaultChecked aria-label="Disabled checked" />
    <Checkbox disabled checked="indeterminate" aria-label="Disabled indeterminate" />
  </div>,
)

悬停与主矩阵

结果

Loading...

实时编辑器

render(
  <div style={{ display: 'flex', flexWrap: 'wrap', gap: 24, alignItems: 'center' }}>
    <div style={{ display: 'flex', flexDirection: 'column', gap: 8, alignItems: 'center' }}>
      <Checkbox aria-label="Unchecked default" />
      <span style={{ fontSize: 12, color: '#999' }}>未选中 Default</span>
    </div>
    <div style={{ display: 'flex', flexDirection: 'column', gap: 8, alignItems: 'center' }}>
      <Checkbox className="border-(--Labels-Primary)" aria-label="Unchecked hover" />
      <span style={{ fontSize: 12, color: '#999' }}>未选中 Hover</span>
    </div>
    <div style={{ display: 'flex', flexDirection: 'column', gap: 8, alignItems: 'center' }}>
      <Checkbox defaultChecked aria-label="Checked default" />
      <span style={{ fontSize: 12, color: '#999' }}>选中 Default</span>
    </div>
    <div style={{ display: 'flex', flexDirection: 'column', gap: 8, alignItems: 'center' }}>
      <Checkbox checked="indeterminate" aria-label="Indeterminate default" />
      <span style={{ fontSize: 12, color: '#999' }}>半选 Default</span>
    </div>
  </div>,
)

带标签

传入 label 后整行（控件 + 文字）均可点击。

结果

Loading...

实时编辑器

render(<Checkbox label="同意服务条款" />)

圆形变体

shape="round" 对应 Figma Checkmark - Fill 组件，适用于需要圆形选框的场景（如列表选择项）。圆形变体不包含半选状态。

结果

Loading...

实时编辑器

render(
  <div style={{ display: 'flex', gap: 16, alignItems: 'center' }}>
    <Checkbox shape="round" aria-label="圆形未选中" />
    <Checkbox shape="round" defaultChecked aria-label="圆形选中" />
    <Checkbox shape="round" disabled aria-label="圆形禁用未选中" />
    <Checkbox shape="round" disabled defaultChecked aria-label="圆形禁用选中" />
  </div>,
)

命名空间用法

结果

Loading...

实时编辑器

render(
  <div style={{ display: 'flex', gap: 8, alignItems: 'center' }}>
    <Controls.Checkbox defaultChecked aria-label="Namespace checkbox" />
    <span style={{ fontSize: 14 }}>Controls.Checkbox</span>
  </div>,
)

Checkbox Props

属性	类型	默认值	说明
checked	boolean | 'indeterminate'	—	受控选中状态
defaultChecked	boolean	—	非受控默认选中
shape	'square' | 'round'	'square'	形状变体；round 对应 Figma Checkmark - Fill
label	string	—	标签文字，传入后整行均可点击
disabled	boolean	false	禁用
labelClassName	string	—	label 行的自定义样式类
onCheckedChange	(checked: boolean) => void	—	选中状态变化回调
aria-label	string	—	无障碍标签
className	string	—	自定义样式类