Checkbox 复选框组件 #
基本用法 #
jsx
import { Checkbox } from '@chakra-ui/react'
function Example() {
return <Checkbox>默认复选框</Checkbox>
}
复选框状态 #
选中状态 #
jsx
<Checkbox defaultIsChecked>默认选中</Checkbox>
禁用状态 #
jsx
<Checkbox isDisabled>禁用复选框</Checkbox>
<Checkbox isDisabled defaultIsChecked>禁用且选中</Checkbox>
只读状态 #
jsx
<Checkbox isReadOnly>只读复选框</Checkbox>
无效状态 #
jsx
<Checkbox isInvalid>无效复选框</Checkbox>
复选框尺寸 #
jsx
<Checkbox size="sm">小复选框</Checkbox>
<Checkbox size="md">中等复选框(默认)</Checkbox>
<Checkbox size="lg">大复选框</Checkbox>
复选框颜色 #
jsx
<Checkbox colorScheme="red">红色</Checkbox>
<Checkbox colorScheme="green">绿色</Checkbox>
<Checkbox colorScheme="blue">蓝色</Checkbox>
<Checkbox colorScheme="orange">橙色</Checkbox>
<Checkbox colorScheme="purple">紫色</Checkbox>
受控复选框 #
jsx
function ControlledCheckbox() {
const [isChecked, setIsChecked] = useState(false)
return (
<Checkbox
isChecked={isChecked}
onChange={(e) => setIsChecked(e.target.checked)}
>
受控复选框
</Checkbox>
)
}
CheckboxGroup 复选框组 #
jsx
import { CheckboxGroup } from '@chakra-ui/react'
function CheckboxGroupExample() {
const [value, setValue] = useState(['apple'])
return (
<CheckboxGroup
value={value}
onChange={setValue}
colorScheme="green"
>
<VStack align="start">
<Checkbox value="apple">苹果</Checkbox>
<Checkbox value="banana">香蕉</Checkbox>
<Checkbox value="orange">橙子</Checkbox>
</VStack>
</CheckboxGroup>
)
}
配合 FormControl #
jsx
import { FormControl, FormLabel, FormErrorMessage } from '@chakra-ui/react'
function FormCheckbox() {
const [agreed, setAgreed] = useState(false)
const isError = !agreed
return (
<FormControl isInvalid={isError}>
<Checkbox
isChecked={agreed}
onChange={(e) => setAgreed(e.target.checked)}
>
我同意用户协议和隐私政策
</Checkbox>
{isError && (
<FormErrorMessage>请先同意用户协议</FormErrorMessage>
)}
</FormControl>
)
}
自定义图标 #
jsx
<Checkbox icon={<MinusIcon />} iconColor="blue.500">
自定义图标
</Checkbox>
实用示例 #
用户偏好设置 #
jsx
function UserPreferences() {
const [preferences, setPreferences] = useState({
email: true,
sms: false,
push: true,
})
return (
<VStack align="start" spacing={4}>
<Heading size="sm">通知设置</Heading>
<Checkbox
isChecked={preferences.email}
onChange={(e) => setPreferences({
...preferences,
email: e.target.checked
})}
>
邮件通知
</Checkbox>
<Checkbox
isChecked={preferences.sms}
onChange={(e) => setPreferences({
...preferences,
sms: e.target.checked
})}
>
短信通知
</Checkbox>
<Checkbox
isChecked={preferences.push}
onChange={(e) => setPreferences({
...preferences,
push: e.target.checked
})}
>
推送通知
</Checkbox>
</VStack>
)
}
权限选择 #
jsx
function PermissionSelect() {
const [permissions, setPermissions] = useState(['read'])
return (
<Box>
<Text fontWeight="medium" mb={2}>权限设置</Text>
<CheckboxGroup
value={permissions}
onChange={setPermissions}
>
<VStack align="start" spacing={2}>
<Checkbox value="read">读取</Checkbox>
<Checkbox value="write">写入</Checkbox>
<Checkbox value="delete">删除</Checkbox>
<Checkbox value="admin">管理</Checkbox>
</VStack>
</CheckboxGroup>
</Box>
)
}
全选功能 #
jsx
function SelectAll() {
const allItems = ['item1', 'item2', 'item3', 'item4']
const [selected, setSelected] = useState([])
const allChecked = selected.length === allItems.length
const isIndeterminate = selected.length > 0 && selected.length < allItems.length
return (
<Box>
<Checkbox
isChecked={allChecked}
isIndeterminate={isIndeterminate}
onChange={(e) => {
if (e.target.checked) {
setSelected(allItems)
} else {
setSelected([])
}
}}
>
全选
</Checkbox>
<Divider my={2} />
<CheckboxGroup value={selected} onChange={setSelected}>
<VStack align="start">
{allItems.map((item) => (
<Checkbox key={item} value={item}>{item}</Checkbox>
))}
</VStack>
</CheckboxGroup>
</Box>
)
}
服务条款同意 #
jsx
function TermsAgreement() {
const [agreements, setAgreements] = useState([])
return (
<VStack align="start" spacing={4}>
<CheckboxGroup value={agreements} onChange={setAgreements}>
<VStack align="start">
<Checkbox value="terms">
我已阅读并同意《用户服务协议》
</Checkbox>
<Checkbox value="privacy">
我已阅读并同意《隐私政策》
</Checkbox>
<Checkbox value="marketing">
我同意接收营销推广信息(可选)
</Checkbox>
</VStack>
</CheckboxGroup>
<Button
colorScheme="blue"
isDisabled={!agreements.includes('terms') || !agreements.includes('privacy')}
>
继续
</Button>
</VStack>
)
}
Checkbox 属性速查表 #
| 属性 | 说明 | 值 |
|---|---|---|
| isChecked | 是否选中 | true, false |
| defaultIsChecked | 默认选中 | true, false |
| isDisabled | 禁用 | true, false |
| isInvalid | 无效 | true, false |
| isReadOnly | 只读 | true, false |
| isIndeterminate | 不确定状态 | true, false |
| size | 尺寸 | sm, md, lg |
| colorScheme | 颜色方案 | blue, green, red… |
| icon | 自定义图标 | React 元素 |
下一步 #
现在你已经掌握了 Checkbox 组件,接下来学习 Radio 单选框,了解如何使用单选按钮组件!
最后更新:2026-03-28