Checkbox 复选框 | uView Next - 企业级、高质量、更贴近业务场景的 uniapp ui框架

# Checkbox 复选框

复选框组件一般用于需要多个选择的场景，该组件功能完整，使用方便。

# 基本使用

<template>
  <view>
    <un-checkbox-group
      v-model="checkboxValue1"
      placement="column"
      @change="checkboxChange"
    >
      <un-checkbox
        :customStyle="{marginBottom: '8px'}"
        v-for="(item, index) in checkboxList1"
        :key="index"
        :label="item.name"
        :name="item.name"
      >
      </un-checkbox>
    </un-checkbox-group>
  </view>
</template>

<script setup lang="uts">
import { ref } from 'vue'

type CheckboxItem = {
  name: string
  disabled: boolean
}

const checkboxValue1 = ref<string[]>([])
const checkboxList1 = ref<CheckboxItem[]>([
  {
    name: '苹果',
    disabled: false
  },
  {
    name: '香蕉',
    disabled: false
  },
  {
    name: '橙子',
    disabled: false
  }
])

const checkboxChange = (n: string[]) => {
  console.log('change', n)
}
</script>
✅ Copy success!

# 自定义图标

可以通过设置 icon 和 activeIcon 属性，自定义复选框的图标：

<template>
  <view>
    <un-checkbox-group
      v-model="checkboxValue4"
      placement="column"
      @change="checkboxChange"
    >
      <un-checkbox
        :customStyle="{marginBottom: '8px'}"
        v-for="(item, index) in checkboxList4"
        :key="index"
        :label="item.name"
        :name="item.name"
        icon="star"
        activeIcon="star-fill"
      >
      </un-checkbox>
    </un-checkbox-group>
  </view>
</template>

<script setup lang="uts">
import { ref } from 'vue'

type CheckboxItem = {
  name: string
  disabled: boolean
}

const checkboxValue4 = ref<string[]>([])
const checkboxList4 = ref<CheckboxItem[]>([
  {
    name: '苹果',
    disabled: false
  },
  {
    name: '香蕉',
    disabled: false
  },
  {
    name: '橙子',
    disabled: false
  }
])

const checkboxChange = (n: string[]) => {
  console.log('change', n)
}
</script>
✅ Copy success!

# 禁用 checkbox

设置 disabled 为 true，即可禁用某个组件，让用户无法点击。禁用分为两种状态：

未勾选前禁用：只显示一个灰色的区域
已勾选后禁用：会有灰色的已勾选的图标，但此时依然是不可操作的

<template>
  <view>
    <un-checkbox-group
      v-model="checkboxValue2"
      placement="column"
      @change="checkboxChange"
    >
      <un-checkbox
        :customStyle="{marginBottom: '8px'}"
        v-for="(item, index) in checkboxList2"
        :key="index"
        :label="item.name"
        :name="item.name"
        :disabled="item.disabled"
      >
      </un-checkbox>
    </un-checkbox-group>
  </view>
</template>

<script setup lang="uts">
import { ref } from 'vue'

type CheckboxItem = {
  name: string
  disabled: boolean
}

const checkboxValue2 = ref<string[]>([])
const checkboxList2 = ref<CheckboxItem[]>([
  {
    name: '苹果',
    disabled: false
  },
  {
    name: '香蕉',
    disabled: true
  },
  {
    name: '橙子',
    disabled: false
  }
])

const checkboxChange = (n: string[]) => {
  console.log('change', n)
}
</script>
✅ Copy success!

# 自定义形状

可以通过设置 shape 为 square 或者 circle 或者 button ，将复选框设置为方形或者圆形：

<template>
  <view>
    <un-checkbox-group
      v-model="checkboxValue3"
      placement="column"
      @change="checkboxChange"
    >
      <un-checkbox
        :customStyle="{marginBottom: '8px'}"
        v-for="(item, index) in checkboxList3"
        :key="index"
        :label="item.name"
        :name="item.name"
        shape="square"
      >
      </un-checkbox>
    </un-checkbox-group>
  </view>
</template>

<script setup lang="uts">
import { ref } from 'vue'

type CheckboxItem = {
  name: string
  disabled: boolean
}

const checkboxValue3 = ref<string[]>([])
const checkboxList3 = ref<CheckboxItem[]>([
  {
    name: '苹果',
    disabled: false
  },
  {
    name: '香蕉',
    disabled: false
  },
  {
    name: '橙子',
    disabled: false
  }
])

const checkboxChange = (n: string[]) => {
  console.log('change', n)
}
</script>
✅ Copy success!

# 自定义颜色

此处所指的颜色，为 checkbox 选中时的背景颜色，参数为 activeColor：

<template>
  <view>
    <un-checkbox-group v-model="checked">
      <un-checkbox activeColor="red" label="光影"></un-checkbox>
    </un-checkbox-group>
  </view>
</template>

<script setup lang="uts">
import { ref } from 'vue'

const checked = ref<string[]>([])
</script>
✅ Copy success!

# 独立使用 un-checkbox 组件

<template>
  <view>
    <un-checkbox v-model:checked="checked">
      <view class="u-flex">
        <text>我已经阅读并同意</text>
        <text style="color:#007AFF" @click.stop="handleClick">《用户协议》</text>
        <text>和</text>
        <text style="color:#007AFF" @click.stop="handleClick">《隐私政策》</text>
      </view>
    </un-checkbox>
  </view>
</template>

<script setup lang="uts">
import { ref } from 'vue'

const checked = ref<boolean>(false)

const handleClick = () => {
  console.log('协议被点击')
}
</script>
✅ Copy success!

# 横向排列形式

可以通过设置 placement 为 row 或者 column，将复选框设置为横向排列或者竖向排列：

<template>
  <view>
    <un-checkbox-group v-model="checked" placement="row">
      <un-checkbox activeColor="red" label="红色"></un-checkbox>
      <un-checkbox activeColor="green" label="绿色"></un-checkbox>
    </un-checkbox-group>
  </view>
</template>

<script setup lang="uts">
import { ref } from 'vue'

const checked = ref<string[]>([])
</script>
✅ Copy success!

# 横向两端排列形式

可以通过设置 iconPlacement 为 left 或者 right，将复选框勾选图标的对齐设置为左对齐或者右对齐：

<template>
  <view>
    <un-checkbox-group 
      v-model="checked"
      iconPlacement="right" 
      placement="row"
    >
      <un-checkbox activeColor="red" label="红色"></un-checkbox>
      <un-checkbox activeColor="green" label="绿色"></un-checkbox>
    </un-checkbox-group>
  </view>
</template>

<script setup lang="uts">
import { ref } from 'vue'

const checked = ref<string[]>([])
</script>
✅ Copy success!

# API

# Checkbox Props

参数	说明	类型	默认值	可选值
name	checkbox 的名称	string \| number \| boolean	-	-
shape	形状，square 为方形，circle 为圆型，button 为按钮	string	square	circle \| button
size	整体的大小	string \| number	-	-
checked	是否默认选中	boolean	false	true
indeterminate	设置不确定状态，仅负责样式控制	boolean	false	true
disabled	是否禁用	string \| boolean	-	-
activeColor	选中状态下的颜色，如设置此值，将会覆盖 parent 的 activeColor 值	string	-	-
inactiveColor	未选中的颜色	string	-	-
iconSize	图标的大小，单位 px	string \| number	-	-
iconColor	图标颜色	string	-	-
label	label提示文字，因为nvue下，直接slot进来的文字，由于特殊的结构，无法修改样式	string \| number	-	-
labelSize	label的字体大小，px单位	string \| number	-	-
labelColor	label的颜色	string	-	-
labelDisabled	是否禁止点击提示语选中复选框	string \| boolean	-	-
activeLabelColor	选中状态下label的颜色	string	-	-
plain	镂空样式	boolean	true	false

# CheckboxGroup Props

参数	说明	类型	默认值	可选值
name	标识符	string	-	-
v-model / modeValue / value	绑定的值	array	[]	-
shape	形状，circle-圆形，square-方形, button为按钮	string	square	circle \| button
disabled	是否禁用全部checkbox	boolean	false	true
activeColor	选中状态下的颜色，如子`Checkbox`组件设置此值，将会覆盖本值	string	#2979ff	-
inactiveColor	未选中的颜色	string	#c8c9cc	-
size	整个组件的尺寸，默认px	string	18	-
placement	布局方式，row-横向，column-纵向	string	row	column
labelSize	label的字体大小，px单位	string \| number	14	-
labelColor	label的字体颜色	string	#303133	-
labelDisabled	是否禁止点击文本操作	boolean	false	true
icon	图标	string	-	-
iconColor	图标颜色	string	#ffffff	-
iconSize	图标的大小，单位px	string \| number	12	-
iconPlacement	勾选图标的对齐方式，left-左边，right-右边	string	left	right
borderBottom	竖向排列时，是否显示下划线	boolean	false	true
activeLabelColor	选中状态下label的颜色	string	-	-
plain	镂空样式	boolean	true	false

# Checkbox Slot

名称	说明
-(default)	自定义label样式
icon	自定义icon图标

# CheckboxGroup Event

事件名	说明	回调参数
change	任一个`checkbox`状态发生变化时触发	value: string[]

← Textarea 文本域 Radio 单选框 →