# Checkbox

* category: UI
* chinese: 复选框组件
* type: UI 组件

---

<a href="http://nuke.alibaba-inc.com/" target="_blank"> Nuke UI </a>

![nuke-checkbox@ALINPM](http://web.npm.alibaba-inc.com/badge/v/nuke-checkbox.svg?style=flat-square)
![nuke-checkbox@ALINPM](http://web.npm.alibaba-inc.com/badge/d/nuke-checkbox.svg?style=flat-square)

## 何时使用

Checkbox 组件与 Switch 组件类似，只有开、关 2 种状态，但使用场景不同：

Switch 通常用于单个零散的配置项设置，而 Checkbox 通常用于某数据源中多项数据的选择。

## API

| 参数           | 说明                                                                                  | 类型                | 默认值              |
| -------------- | ------------------------------------------------------------------------------------- | ------------------- | ------------------- |
| size           | 大小                                                                                  | string              | medium( 可选 small) |
| checked        | 是否选中                                                                              | boolean             | 无                  |
| defaultChecked | 默认选中                                                                              | boolean             | false               |
| disabled       | 是否禁用                                                                              | boolean             | false               |
| onChange       | 状态改变时的回调函数                                                                  | function(checked,e) | 无                  |
| type           | 复选框类型                                                                            | string              | normal(list,empty)  |
| touchStyle     | 触摸区域样式                                                                          | object              | {}                  |
| ignoreContext  | 忽略上层父级 context，当 radio.group 的子级存在非 group 模式的 radio 时需设置为 false | bool(false)         |

### Checkbox.Group

| 参数           | 说明                                             | 类型                | 默认值 |
| -------------- | ------------------------------------------------ | ------------------- | ------ |
| dataSource     | 数据源                                           | array               | []     |
| reverse        | 翻转 label 与 checkbox 的渲染顺序                | bool                | false  |
| value          | 选中项目                                         | array               | []     |
| onChange       | 状态改变时的回调函数                             | function(checked,e) | 无     |
| style          | group 整个 container 上的样式                    | Object              | {}     |
| renderItem     | 自定义 item 的渲染方式，可通过此方法扩大点击范围 | function            | ()     |
| groupItemStyle | 每个 item 的外层渲染样式                         | object              | {}     |
| labelStyle     | 每个 item 的 label 文案样式                      | object              | {}     |

### 受控用法与非受控用法

所有的输入、交互类组件都有受控用法和非受控用法。

* 受控用法： 组件状态受到外部传入的 props 影响，外部 props 改变，组件才改变，如下 demo :

```js
constructor() {
    super();
    this.state = {
        checked: true
    }
}
change = (value) => {
    this.setState({
        checked:!value
    });
}
//...
render(){
    return (<Checkbox checked={this.state.checked} onChange={this.change}/>)
}
```

* 非受控用法： 组件自身自由改变，并通过事件通知外部改变成了什么。如下 demo :

```js
change = (value) => {
    console.log('switch 改变成了：',value);
}
//...
render(){
    return (<Checkbox defaultChecked={true} onChange={this.change}/>)
}
```

## demo 参考

<img src="https://img.alicdn.com/tfs/TB1OnHvX3MPMeJjy1XcXXXpppXa-1242-2208.png" width="240" />

扫码预览 ( 手淘、千牛、天猫等 )

<img src="https://img.alicdn.com/tfs/TB1.XfvX3MPMeJjy1XbXXcwxVXa-280-280.png" width="160" />

## 使用方法

* 安装

```bash
// 切换到你的 rax 项目中
npm i nuke-checkbox --save
// 参考如下 demo 您可能还需要安装
// npm i nuke-view nuke-page nuke-text --save
```

* 调用示例

```js
/** @jsx createElement */
import { createElement, Component, render } from 'rax';
import View from 'nuke-view';
import Text from 'nuke-text';
import Checkbox from 'nuke-checkbox';
import Page from 'nuke-page';
const themeOrange = '#ff6600';
let App = class NukeDemoIndex extends Component {
  constructor() {
    super();
    this.state = {
      checked: false,
    };
  }

  onChange(value) {
    console.log(value);
  }
  changeControl(value) {
    this.setState({
      checked: value,
    });
  }

  render() {
    return (
      <Page title="Checkbox">
        <Page.Intro sub="普通样式" />
        <View style={styles.demo_item}>
          <View style={styles.group_item}>
            <Checkbox
              defaultChecked={true}
              size="small"
              onChange={this.onChange.bind(this)}
            />
            <Text>苹果</Text>
          </View>
          <View style={styles.group_item}>
            <Checkbox size="small" onChange={this.onChange.bind(this)} />
            <Text>梨</Text>
          </View>
        </View>
        <Page.Intro sub="空心样式" />
        <View style={styles.demo_item}>
          <View style={styles.group_item}>
            <Checkbox
              defaultChecked={true}
              type="empty"
              size="small"
              onChange={this.onChange.bind(this)}
            />
            <Text>苹果</Text>
          </View>
          <View style={styles.group_item}>
            <Checkbox
              size="small"
              type="empty"
              onChange={this.onChange.bind(this)}
            />
            <Text>梨</Text>
          </View>
        </View>
        <Page.Intro sub="list 样式" />
        <View style={[styles.demo_item, { flexDirection: 'column' }]}>
          <View style={styles.group_item}>
            <Checkbox
              defaultChecked={true}
              type="list"
              size="small"
              onChange={this.onChange.bind(this)}
            />
            <Text>浙江省杭州市余杭区</Text>
          </View>
          <View style={styles.group_item}>
            <Checkbox
              size="small"
              type="list"
              onChange={this.onChange.bind(this)}
            />
            <Text>浙江省杭州市临安市</Text>
          </View>
        </View>

        <Page.Intro main="自定义大小颜色" />
        <View style={styles.demo_item}>
          <Checkbox
            style={{ width: '30rem', height: '30rem', fontSize: '20rem' }}
            defaultChecked={true}
            size="small"
            checkedStyle={{ backgroundColor: themeOrange }}
            unCheckedStyle={{ backgroundColor: themeOrange }}
            onChange={this.onChange.bind(this)}
          />
          <Checkbox
            defaultChecked={true}
            size="small"
            type="empty"
            checkedStyle={{ borderColor: themeOrange, color: themeOrange }}
            unCheckedStyle={{ borderColor: themeOrange }}
            onChange={this.onChange.bind(this)}
          />
          <Checkbox
            defaultChecked={true}
            size="small"
            type="list"
            checkedStyle={{ color: themeOrange }}
            onChange={this.onChange.bind(this)}
          />
        </View>
      </Page>
    );
  }
};

const styles = {
  demo_item: {
    width: 750,
    marginTop: 30,
    backgroundColor: '#ffffff',
    flexDirection: 'row',
    alignItem: 'center',
    paddingLeft: 12,
  },
  group_item: {
    height: 104,
    flexDirection: 'row',
    borderBottomWidth: '2rem',
    borderBottomStyle: 'solid',
    borderBottomColor: '#F7F8FA',
    alignItems: 'center',
  },
};

render(<App />);
```