Checkbox 复选框

介绍

在一组备选项中进行多选。

引入

import { Checkbox } from "@taroify/core"

代码演示

基础用法

通过 checked 绑定复选框的勾选状态。

<Checkbox>复选框</Checkbox>

禁用状态

通过设置 disabled 属性可以禁用复选框。

<Checkbox disabled checked={false}>复选框</Checkbox>
<Checkbox disabled checked>复选框</Checkbox>

自定义形状

将 shape 属性设置为 square，复选框的形状会变成方形。

<Checkbox shape="square">自定义形状</Checkbox>

按钮形状

将 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>

自定义颜色

通过 css 设置选中状态的图标颜色。

<Checkbox className="custom-color">
  自定义颜色
</Checkbox>

.custom-color {
  --checkbox-checked-icon-border-color: #ee0a24;
  --checkbox-checked-icon-background-color: #ee0a24;
}

自定义大小

通过 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>
  )
}

复选框组

复选框可以与复选框组一起使用，复选框组通过 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>

搭配单元格组件使用

此时你需要再引入 Cell 和 Cell.Group 组件，并通过 Checkbox 实例上的 toggle 方法触发切换。

<Checkbox.Group max={2}>
  <Cell.Group clickable>
    <Cell title="复选框 a">
      <Checkbox name="a" />
    </Cell>
    <Cell title="复选框 b">
      <Checkbox name="b" />
    </Cell>
  </Cell.Group>
</Checkbox.Group>

API

Checkbox Props

参数	说明	类型	默认值
defaultChecked	默认是否为选中状态	boolean	`false`
checked	是否为选中状态	boolean	`false`
name	标识符	any	-
shape v1.0.0	形状，可选值为 `square` `button`	string	`round`
disabled	是否禁用复选框	boolean	`false`
size	图标大小，默认单位为 `px`	number \| string	`20px`

CheckboxGroup Props

参数	说明	类型	默认值
defaultValue	默认所有选中项的标识符	any[]	-
value	所有选中项的标识符	any[]	-
disabled	是否禁用所有复选框	boolean	`false`
max	最大可选数，`0` 为无限制	number \| string	`0`
direction	排列方向，可选值为 `horizontal`	string	`vertical`
size	所有复选框的图标大小，默认单位为 `px`	number \| string	`20px`

Checkbox Events

事件名	说明	回调参数
onChange	当绑定值变化时触发的事件	checked: boolean

CheckboxGroup Events

事件名	说明	回调参数
onChange	当绑定值变化时触发的事件	names: any[]

主题定制

样式变量

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。

名称	默认值	描述
--checkbox-size	20px $hd*	-
--checkbox-font-size	var(--font-size-lg)	-
--checkbox-border-color	var(--gray-5)	-
--checkbox-transition-duration	var(--animation-duration-fast)	-
--checkbox-gap	var(--padding-sm)	-
--checkbox-label-margin	var(--padding-xs)	-
--checkbox-label-color	var(--text-color)	-
--checkbox-label-line-height	var(--checkbox-size)	-
--checkbox-disabled-label-color	var(--gray-5)	-
--checkbox-icon-font-size	var(--checkbox-size)	-
--checkbox-checked-icon-color	var(--white)	-
--checkbox-checked-icon-border-color	var(--primary-color)	-
--checkbox-checked-icon-background-color	var(--primary-color)	-
--checkbox-disabled-icon-color	var(--gray-5)	-
--checkbox-disabled-icon-border-color	var(--gray-5)	-
--checkbox-disabled-icon-background-color	var(--border-color)	-
--checkbox-button-padding v1.0.0	5px $hd 18px * $hd*	-
--checkbox-button-border-radius v1.0.0	var(--border-radius-max)	-
--checkbox-button-color v1.0.0	var(--text-color)	-
--checkbox-button-background-color v1.0.0	var(--gray-1)	-
--checkbox-button-border-color v1.0.0	var(--checkbox-button-background-color)	-
--checkbox-button-checked-color v1.0.0	var(--primary-color)	-
--checkbox-button-checked-background-color v1.0.0	var(--white)	-
--checkbox-button-checked-border-color v1.0.0	var(--primary-color)	-
--checkbox-button-disabled-opacity v1.0.0	var(--disabled-opacity)	-

#Checkbox 复选框

#介绍

#引入

#代码演示

#基础用法

#禁用状态

#自定义形状

#按钮形状

#自定义颜色

#自定义大小

#自定义图标

#复选框组

#水平排列

#限制最大可选数

#搭配单元格组件使用

#API

#Checkbox Props

#CheckboxGroup Props

#Checkbox Events

#CheckboxGroup Events

#主题定制

#样式变量