React 组件

UGCheckbox 复选框

UGCheckbox 用于在表单中进行多项选择，支持受控/非受控模式、indeterminate 半选状态与三种尺寸。

导入方式

按需从包入口导入组件，并在应用入口引入一次样式文件。

tsx

import { UGCheckbox, UGCheckboxGroup } from '@ug666/ui-react'

基础勾选

最基础的复选框，携带标签并受控绑定选中状态。

启用邮件通知默认已选中未选中项

indeterminate 半选

父级复选框在子项部分选中时呈现半选中状态（Minus 图标），全选时呈现选中状态。

全选任务

设计稿评审接口联调内容复核

复选框组

组统一维护选中值、字段名、尺寸和禁用状态，并可限制最少与最多选择数量。

读取编辑发布

当前值：read

状态

禁用后不可交互；aria-invalid 同步无障碍语义和可见错误边框。

三种尺寸

sm / default / lg 三档尺寸适配不同密度界面。

小号 sm默认 default大号 lg

原生表单

组统一传递 name 和 form；非受控值在 reset 后恢复 defaultValue。

完整场景代码

全选与子项联动的完整状态管理示例。

tsx

import { useState } from 'react'
import { UGCheckbox } from '@ug666/ui-react'

export function TaskList() {
  const [items, setItems] = useState([
    { id: 1, label: '设计稿评审', checked: true },
    { id: 2, label: '接口联调', checked: false },
    { id: 3, label: '内容复核', checked: false },
  ])

  const allChecked = items.every((i) => i.checked)
  const someChecked = items.some((i) => i.checked) && !allChecked

  function toggleAll() {
    setItems((prev) => prev.map((i) => ({ ...i, checked: !allChecked })))
  }

  function toggle(id: number) {
    setItems((prev) =>
      prev.map((i) => (i.id === id ? { ...i, checked: !i.checked } : i)),
    )
  }

  return (
    <div className="space-y-2">
      <UGCheckbox
        checked={allChecked}
        indeterminate={someChecked}
        onCheckedChange={toggleAll}
        label="全选任务"
      />
      <div className="ml-6 space-y-1.5">
        {items.map((item) => (
          <UGCheckbox
            key={item.id}
            checked={item.checked}
            onCheckedChange={() => toggle(item.id)}
            label={item.label}
          />
        ))}
      </div>
    </div>
  )
}

属性

Checkbox 属性

属性	类型	默认值	说明
checked	boolean	false	是否选中（受控）。
defaultChecked	boolean	false	非受控模式的初始选中状态。
indeterminate	boolean	false	半选状态，优先级高于 checked 的视觉表现。
onCheckedChange	(checked: boolean) => void	—	选中状态变化时触发。
onChange	ChangeEventHandler<HTMLInputElement>	—	原生 change 事件，供表单库和事件型接入使用。
label	ReactNode	—	同行标签文案，有值时整块可点击。
size	'sm' \| 'default' \| 'lg'	'default'	控制复选框尺寸。
disabled	boolean	false	禁用点击与焦点交互。
aria-invalid	原生 ARIA 属性	—	表单校验失败时同步无障碍语义和危险色边框。
value	string \| number	—	作为 CheckboxGroup 子项时的选项值。
name / required	原生 input 属性	— / false	参与原生表单提交和校验。
ref	Ref<HTMLInputElement>	—	访问真实 checkbox，可调用 focus、blur 和原生属性。

CheckboxGroup 属性

属性	类型	默认值	说明
value / defaultValue	readonly (string \| number)[]	[]	受控选中值或非受控初始值。
onValueChange	(value: (string \| number)[]) => void	—	组内选中值变化时触发。
min / max	number	0 / —	限制最少与最多选中数量，达到边界后对应选项不可操作。
orientation	'horizontal' \| 'vertical'	'horizontal'	控制组内选项排列方向。
name / form	string / string	—	传递原生字段名，并可关联指定 id 的外部 form。
size	'sm' \| 'default' \| 'lg'	ConfigProvider / default	统一组内复选框尺寸，子项可以覆盖。
disabled	boolean	ConfigProvider / false	禁用整组复选框。