Checkbox 复选框
介绍
在一组备选项中进行多选。
引入
import { Checkbox } from "@taroify/core"
代码演示
基础用法
通过 checked 绑定复选框的勾选状态。
禁用状态
通过设置 disabled 属性可以禁用复选框。
<Checkbox disabled checked={false}>复选框</Checkbox>
<Checkbox disabled checked>复选框</Checkbox>
自定义形状
将 shape 属性设置为 square，复选框的形状会变成方形。
<Checkbox shape="square">自定义形状</Checkbox>
复选框组自定义形状 v1.0.5
通过 Checkbox.Group 的 shape 属性统一设置组内复选框的形状。
<Checkbox.Group shape="square" defaultValue={["a"]}>
<Checkbox name="a">复选框 a</Checkbox>
<Checkbox name="b">复选框 b</Checkbox>
</Checkbox.Group>
按钮形状
将 shape 属性设置为 button，复选框会变成适合规格选择等场景的按钮。按钮形状下，icon 和 size 属性不生效。
<Checkbox.Group defaultValue={["a"]} direction="horizontal">
<Checkbox name="a" shape="button">复选框 a</Checkbox>
<Checkbox name="b" shape="button">复选框 b</Checkbox>
</Checkbox.Group>
自定义颜色 v1.0.5
通过 checkedColor 属性设置选中状态的图标颜色。
<Checkbox defaultChecked checkedColor="#ee0a24">自定义颜色</Checkbox>
自定义大小
通过 size 属性可以自定义图标的大小。
<Checkbox size={24}>自定义大小</Checkbox>
自定义图标
通过 icon 属性自定义图标。
function CheckboxWithCustomIcon() {
const [value, setValue] = useState(false)
return (
<Checkbox
icon={
<Image
src={`https://img.yzcdn.cn/vant/user-${value ? "active" : "inactive"}.png`}
style={{
width: "25px",
height: "20px",
}}
/>
}
checked={value}
onChange={setValue}
>
自定义图标
</Checkbox>
)
}
左侧文本 v1.0.5
将 labelPosition 属性设置为 left，可以将文本位置调整到复选框左侧。
<Checkbox labelPosition="left">复选框</Checkbox>
禁用文本点击 v1.0.5
设置 labelDisabled 属性后，点击图标以外的内容不会触发复选框切换。
<Checkbox labelDisabled>复选框</Checkbox>
复选框组
复选框可以与复选框组一起使用，复选框组通过 value 数组绑定复选框的勾选状态。
<Checkbox.Group>
<Checkbox name="a">复选框 a</Checkbox>
<Checkbox name="b">复选框 b</Checkbox>
</Checkbox.Group>
水平排列
将 direction 属性设置为 horizontal 后，复选框组会变成水平排列。
<Checkbox.Group direction="horizontal">
<Checkbox name="a">复选框 a</Checkbox>
<Checkbox name="b">复选框 b</Checkbox>
</Checkbox.Group>
限制最大可选数
通过 max 属性可以限制复选框组的最大可选数。
<Checkbox.Group max={2}>
<Checkbox name="a">复选框 a</Checkbox>
<Checkbox name="b">复选框 b</Checkbox>
<Checkbox name="c">复选框 c</Checkbox>
</Checkbox.Group>
全选与反选 v1.0.3
通过 Checkbox.Group 实例上的 toggleAll 方法可以实现全选、取消全选和反选。
function CheckboxToggleAll() {
const groupRef = useRef<CheckboxGroupInstance>(null)
return (
<>
<Checkbox.Group ref={groupRef}>
<Checkbox name="a">复选框 a</Checkbox>
<Checkbox name="b">复选框 b</Checkbox>
<Checkbox name="c" disabled>复选框 c</Checkbox>
</Checkbox.Group>
<Space>
<Button onClick={() => groupRef.current?.toggleAll(true)}>全选</Button>
<Button onClick={() => groupRef.current?.toggleAll(false)}>取消全选</Button>
<Button onClick={() => groupRef.current?.toggleAll()}>反选</Button>
</Space>
</>
)
}
搭配单元格组件使用
此时你需要再引入 Cell 和 Cell.Group 组件，并通过 Checkbox 实例上的 toggle 方法触发切换。Checkbox 外层通过 View 阻止事件冒泡，避免点击 Checkbox 时被 Cell 再次切换。
function CheckboxWithCell() {
const checkboxRefs = useRef<Array<CheckboxInstance | null>>([])
const options = ["a", "b"]
return (
<Checkbox.Group max={2}>
<Cell.Group clickable>
{options.map((name, index) => (
<Cell
key={name}
title={`复选框 ${name}`}
onClick={() => checkboxRefs.current[index]?.toggle()}
>
<View onClick={(event) => event.stopPropagation()}>
<Checkbox
ref={(instance) => {
checkboxRefs.current[index] = instance
}}
name={name}
/>
</View>
</Cell>
))}
</Cell.Group>
</Checkbox.Group>
)
}
不确定状态 v1.0.5
通过 indeterminate 设置复选框是否为不确定状态。
function CheckboxIndeterminate() {
const options = ["a", "b", "c"]
const [value, setValue] = useState(["a", "b"])
const checked = value.length === options.length
const indeterminate = value.length > 0 && !checked
return (
<>
<Checkbox
checked={checked}
indeterminate={indeterminate}
onChange={(nextChecked) => setValue(nextChecked ? options : [])}
>
全选
</Checkbox>
<Checkbox.Group value={value} onChange={setValue}>
{options.map((name) => (
<Checkbox key={name} name={name}>复选框 {name}</Checkbox>
))}
</Checkbox.Group>
</>
)
}
API
Checkbox Props
CheckboxGroup Props
Checkbox Events
CheckboxGroup Events
Checkbox 方法 v1.0.3
通过 ref 可以获取 Checkbox 实例并调用实例方法。
CheckboxGroup 方法 v1.0.3
通过 ref 可以获取 CheckboxGroup 实例并调用实例方法。
interface CheckboxGroupToggleAllOptions {
checked?: boolean
skipDisabled?: boolean
}
const checkboxRef = useRef<CheckboxInstance>(null)
const checkboxGroupRef = useRef<CheckboxGroupInstance>(null)
checkboxRef.current?.toggle()
checkboxRef.current?.toggle(true)
checkboxGroupRef.current?.toggleAll()
checkboxGroupRef.current?.toggleAll(true)
checkboxGroupRef.current?.toggleAll({ checked: true, skipDisabled: true })
类型定义 v1.0.3
组件导出以下实例类型：
import type {
CheckboxLabelPosition,
CheckboxProps,
CheckboxShape,
CheckboxInstance,
CheckboxGroupProps,
CheckboxGroupInstance,
CheckboxGroupToggleAll,
CheckboxGroupToggleAllOptions,
} from "@taroify/core"
主题定制
样式变量
组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。
