Translation in progress
This page hasn't been translated into English yet, so the content below is in Chinese. The code examples work the same way.
Checkbox 多选框
在一组选项里选多个,或者单独用来表示一个“是 / 否”的状态。多个选项共用一个数组时配合 NsCheckboxGroup 使用。
引入
import { NsCheckbox, NsCheckboxGroup } from '@ns/ui'
基础用法
单独使用时用 v-model 绑定一个布尔值,文字写在默认插槽里。
<script setup lang="ts">
import { ref } from 'vue'
import { NsCheckbox } from '@ns/ui'
const checked = ref(false)
</script>
<template>
<NsCheckbox v-model="checked">同意用户协议</NsCheckbox>
<p style="margin-top: 12px">绑定值:{{ checked }}</p>
</template>
用 label 写文字
没写默认插槽时,字符串或数字类型的 label 会当文字显示。默认插槽和 label 都写了时显示插槽。
<script setup lang="ts">
import { ref } from 'vue'
import { NsCheckbox, NsSpace } from '@ns/ui'
const remember = ref(true)
const agree = ref(false)
</script>
<template>
<NsSpace wrap>
<NsCheckbox v-model="remember" label="记住密码" />
<NsCheckbox v-model="agree" label="label 的文字">插槽的文字(优先显示)</NsCheckbox>
</NsSpace>
</template>
禁用和只读
disabled 禁用后不能点击也不能获得焦点,方框换成禁用的底色、文字变淡,已选中和半选的保留淡一些的主色底。readonly 外观不变,保持当前状态,点击不改变值,也不触发事件,仍然能获得焦点。
<script setup lang="ts">
import { ref } from 'vue'
import { NsCheckbox, NsSpace } from '@ns/ui'
const off = ref(false)
const on = ref(true)
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<span class="row-label">disabled</span>
<NsCheckbox v-model="off" disabled>未选中</NsCheckbox>
<NsCheckbox v-model="on" disabled>已选中</NsCheckbox>
<NsCheckbox v-model="off" indeterminate disabled>半选</NsCheckbox>
</NsSpace>
<NsSpace wrap>
<span class="row-label">readonly</span>
<NsCheckbox v-model="off" readonly>未选中</NsCheckbox>
<NsCheckbox v-model="on" readonly>已选中</NsCheckbox>
<NsCheckbox v-model="off" indeterminate readonly>半选</NsCheckbox>
</NsSpace>
</NsSpace>
</template>
<style scoped>
.row-label {
display: inline-block;
width: 64px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
半选与全选
indeterminate 只控制显示成半选的样子,不会改绑定值,也不会在点击后自动取消,要由使用方根据子项的选中情况算出来。
<script setup lang="ts">
import { computed, ref } from 'vue'
import { NsCheckbox, NsCheckboxGroup, NsSpace } from '@ns/ui'
import type { CheckboxValueType } from '@ns/ui'
const cities = ['北京', '上海', '广州', '深圳']
const checkedCities = ref<CheckboxValueType[]>(['北京', '上海'])
const checkAll = computed(() => checkedCities.value.length === cities.length)
const indeterminate = computed(
() => checkedCities.value.length > 0 && checkedCities.value.length < cities.length
)
const toggleAll = (value: CheckboxValueType | CheckboxValueType[]) => {
checkedCities.value = value ? [...cities] : []
}
</script>
<template>
<NsSpace wrap>
<NsCheckbox :model-value="checkAll" :indeterminate="indeterminate" @change="toggleAll">
全选
</NsCheckbox>
<NsCheckboxGroup v-model="checkedCities">
<NsCheckbox v-for="city in cities" :key="city" :value="city" :label="city" />
</NsCheckboxGroup>
</NsSpace>
</template>
自定义选中值
用 true-value 和 false-value 指定选中、未选中时的值,不写时是 true 和 false。
<script setup lang="ts">
import { ref } from 'vue'
import { NsCheckbox, NsSpace } from '@ns/ui'
const answer = ref('yes')
const flag = ref(0)
</script>
<template>
<NsSpace wrap>
<NsCheckbox v-model="answer" true-value="yes" false-value="no" label="字符串 yes / no" />
<NsCheckbox v-model="flag" :true-value="1" :false-value="0" label="数字 1 / 0" />
</NsSpace>
<p style="margin-top: 12px">answer:'{{ answer }}',flag:{{ flag }}</p>
</template>
绑定数组
不用 NsCheckboxGroup 也可以让几个多选框绑定同一个数组:选中时把自己的 value 加进数组,取消时去掉。
<script setup lang="ts">
import { ref } from 'vue'
import { NsCheckbox, NsSpace } from '@ns/ui'
import type { CheckboxValueType } from '@ns/ui'
const types = ref<CheckboxValueType[]>(['online'])
</script>
<template>
<NsSpace wrap>
<NsCheckbox v-model="types" value="online" label="线上活动" />
<NsCheckbox v-model="types" value="offline" label="线下活动" />
<NsCheckbox v-model="types" value="hybrid" label="线上线下结合" />
</NsSpace>
<p style="margin-top: 12px">绑定值:{{ types }}</p>
</template>
多选框组
NsCheckboxGroup 用 v-model 绑定一个数组,里面每个 NsCheckbox 用 value 指定自己的值。组上的 name 会传给每个子项的原生 name。选中项变化时组触发 change,参数是新的数组。
<script setup lang="ts">
import { ref } from 'vue'
import { NsCheckbox, NsCheckboxGroup } from '@ns/ui'
import type { CheckboxValueType } from '@ns/ui'
const checkedCities = ref<CheckboxValueType[]>(['bj', 'sh'])
const lastChange = ref('')
const handleChange = (value: CheckboxValueType[]) => {
lastChange.value = value.join('、') || '(空)'
}
</script>
<template>
<NsCheckboxGroup v-model="checkedCities" name="city" @change="handleChange">
<NsCheckbox value="bj" label="北京" />
<NsCheckbox value="sh" label="上海" />
<NsCheckbox value="gz" label="广州" />
<NsCheckbox value="sz">深圳(用插槽写文字)</NsCheckbox>
</NsCheckboxGroup>
<p style="margin-top: 12px">change 事件:{{ lastChange || '还没有触发' }}</p>
</template>
限制可选数量
min 和 max 限制组里能选中的数量。选中数量到了 max,没选中的项不能再点;选中数量不超过 min 时,已选中的项不能取消。每次变更后数量到了下限或上限会触发 limit-reach。
<script setup lang="ts">
import { ref } from 'vue'
import { NsCheckbox, NsCheckboxGroup } from '@ns/ui'
import type { CheckboxValueType } from '@ns/ui'
const checkedCities = ref<CheckboxValueType[]>(['北京'])
const tip = ref('')
const handleLimitReach = (limit: 'min' | 'max') => {
tip.value = limit === 'min' ? '至少选 1 个' : '最多选 3 个'
}
</script>
<template>
<NsCheckboxGroup v-model="checkedCities" :min="1" :max="3" @limit-reach="handleLimitReach">
<NsCheckbox label="北京" />
<NsCheckbox label="上海" />
<NsCheckbox label="广州" />
<NsCheckbox label="深圳" />
<NsCheckbox label="杭州" />
</NsCheckboxGroup>
<p style="margin-top: 12px">
{{ tip || '已选 ' + checkedCities.length + ' 个,可选 1 到 3 个' }}
</p>
</template>
组的禁用和只读
组上的 disabled、readonly 对里面所有子项生效。子项自己写了 disabled 或 readonly 时以自己的为准,例如写 :disabled="false" 让某一项不跟随组。
<script setup lang="ts">
import { ref } from 'vue'
import { NsCheckbox, NsCheckboxGroup, NsSpace } from '@ns/ui'
import type { CheckboxValueType } from '@ns/ui'
const disabledGroup = ref<CheckboxValueType[]>(['a'])
const readonlyGroup = ref<CheckboxValueType[]>(['a'])
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<span class="row-label">disabled</span>
<NsCheckboxGroup v-model="disabledGroup" disabled>
<NsCheckbox value="a" label="选项 A" />
<NsCheckbox value="b" label="选项 B" />
<NsCheckbox value="c" label="选项 C(不跟随组)" :disabled="false" />
</NsCheckboxGroup>
</NsSpace>
<NsSpace wrap>
<span class="row-label">readonly</span>
<NsCheckboxGroup v-model="readonlyGroup" readonly>
<NsCheckbox value="a" label="选项 A" />
<NsCheckbox value="b" label="选项 B" />
<NsCheckbox value="c" label="选项 C(不跟随组)" :readonly="false" />
</NsCheckboxGroup>
</NsSpace>
</NsSpace>
</template>
<style scoped>
.row-label {
display: inline-block;
width: 64px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
不同尺寸
size 可选 large、default、small:方框 18、16、14px,文字 16、14、12px,对勾和半选的横线跟着方框等比缩放。写在 NsCheckboxGroup 上时组里每一项都用这个尺寸,子项自己写了 size 时以自己的为准。不写时依次跟随所在的组、NsFormItem、NsForm、NsConfigProvider,都没有时是 default。放进表单项时文字和标签文字在同一条基线上。
下面每一行是一种尺寸,前三个是单独使用的未选中、选中、半选,后面是写在组上的尺寸:
<script setup lang="ts">
import { ref } from 'vue'
import { NsCheckbox, NsCheckboxGroup, NsSpace } from '@ns/ui'
import type { CheckboxValueType } from '@ns/ui'
const off = ref(false)
const on = ref(true)
const checked = ref<CheckboxValueType[]>(['a'])
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<span class="row-label">large</span>
<NsCheckbox v-model="off" size="large">未选中</NsCheckbox>
<NsCheckbox v-model="on" size="large">选中</NsCheckbox>
<NsCheckbox v-model="off" size="large" indeterminate>半选</NsCheckbox>
<NsCheckboxGroup v-model="checked" size="large">
<NsCheckbox value="a" label="组 A" />
<NsCheckbox value="b" label="组 B" />
</NsCheckboxGroup>
</NsSpace>
<NsSpace wrap>
<span class="row-label">default</span>
<NsCheckbox v-model="off">未选中</NsCheckbox>
<NsCheckbox v-model="on">选中</NsCheckbox>
<NsCheckbox v-model="off" indeterminate>半选</NsCheckbox>
<NsCheckboxGroup v-model="checked">
<NsCheckbox value="a" label="组 A" />
<NsCheckbox value="b" label="组 B" />
</NsCheckboxGroup>
</NsSpace>
<NsSpace wrap>
<span class="row-label">small</span>
<NsCheckbox v-model="off" size="small">未选中</NsCheckbox>
<NsCheckbox v-model="on" size="small">选中</NsCheckbox>
<NsCheckbox v-model="off" size="small" indeterminate>半选</NsCheckbox>
<NsCheckboxGroup v-model="checked" size="small">
<NsCheckbox value="a" label="组 A" />
<NsCheckbox value="b" label="组 B(自己写 large)" size="large" />
</NsCheckboxGroup>
</NsSpace>
</NsSpace>
</template>
<style scoped>
.row-label {
display: inline-block;
width: 56px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
按钮样式
组上的 type 可选 default(默认,方形多选框)和 button。写 type="button" 时,里面的多选框显示成一排相连的按钮,选中的项用主色填充,可以同时选中多项,相邻两项都选中时中间用浅一档的主色隔开。写法和普通的多选框组一样,不用换组件,min、max、readonly 照常生效。
size 设置按钮的尺寸:large、default、small 的高度分别是 40、32、24px,内边距、字号、圆角和同尺寸的 NsButton 一致。不写 size 时跟随所在的 NsFormItem、NsForm、NsConfigProvider,都没有时是 default。
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsCheckbox, NsCheckboxGroup, NsSpace } from '@ns/ui'
import type { CheckboxValueType } from '@ns/ui'
const days = ref<CheckboxValueType[]>(['mon', 'wed'])
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<span class="row-label">large</span>
<NsCheckboxGroup v-model="days" type="button" size="large">
<NsCheckbox value="mon" label="周一" />
<NsCheckbox value="tue" label="周二" />
<NsCheckbox value="wed" label="周三" />
<NsCheckbox value="thu" label="周四" />
</NsCheckboxGroup>
<NsButton size="large">按钮</NsButton>
</NsSpace>
<NsSpace wrap>
<span class="row-label">default</span>
<NsCheckboxGroup v-model="days" type="button">
<NsCheckbox value="mon" label="周一" />
<NsCheckbox value="tue" label="周二" />
<NsCheckbox value="wed" label="周三" />
<NsCheckbox value="thu" label="周四" />
</NsCheckboxGroup>
<NsButton>按钮</NsButton>
</NsSpace>
<NsSpace wrap>
<span class="row-label">small</span>
<NsCheckboxGroup v-model="days" type="button" size="small">
<NsCheckbox value="mon" label="周一" />
<NsCheckbox value="tue" label="周二" />
<NsCheckbox value="wed" label="周三" />
<NsCheckbox value="thu" label="周四" />
</NsCheckboxGroup>
<NsButton size="small">按钮</NsButton>
</NsSpace>
</NsSpace>
</template>
<style scoped>
.row-label {
display: inline-block;
width: 56px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
禁用的规则和普通多选框组一样:组上的 disabled 禁用整组,某一项自己写 disabled 只禁用这一项。按钮样式下禁用的项(包括选满 max 后不能再选的项)整体变淡,选中且禁用的项仍是淡一些的主色底,看得出是选中的。readonly 时外观不变,点击不改变选中项。外观和 NsRadioGroup 的按钮样式一致。
<script setup lang="ts">
import { ref } from 'vue'
import { NsCheckbox, NsCheckboxGroup, NsSpace } from '@ns/ui'
import type { CheckboxValueType } from '@ns/ui'
const all = ref<CheckboxValueType[]>(['sh'])
const one = ref<CheckboxValueType[]>(['sh'])
const limited = ref<CheckboxValueType[]>(['bj', 'sh'])
const readonlyValue = ref<CheckboxValueType[]>(['sh'])
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<span class="row-label">整组禁用</span>
<NsCheckboxGroup v-model="all" type="button" disabled>
<NsCheckbox value="bj" label="北京" />
<NsCheckbox value="sh" label="上海" />
<NsCheckbox value="gz" label="广州" />
</NsCheckboxGroup>
</NsSpace>
<NsSpace wrap>
<span class="row-label">禁用一项</span>
<NsCheckboxGroup v-model="one" type="button">
<NsCheckbox value="bj" label="北京" />
<NsCheckbox value="sh" label="上海" />
<NsCheckbox value="gz" label="广州" disabled />
</NsCheckboxGroup>
</NsSpace>
<NsSpace wrap>
<span class="row-label">max = 2</span>
<NsCheckboxGroup v-model="limited" type="button" :max="2">
<NsCheckbox value="bj" label="北京" />
<NsCheckbox value="sh" label="上海" />
<NsCheckbox value="gz" label="广州" />
<NsCheckbox value="sz" label="深圳" />
</NsCheckboxGroup>
</NsSpace>
<NsSpace wrap>
<span class="row-label">只读</span>
<NsCheckboxGroup v-model="readonlyValue" type="button" readonly>
<NsCheckbox value="bj" label="北京" />
<NsCheckbox value="sh" label="上海" />
<NsCheckbox value="gz" label="广州" />
</NsCheckboxGroup>
</NsSpace>
</NsSpace>
</template>
<style scoped>
.row-label {
display: inline-block;
width: 72px;
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
</style>
在表单里使用
放在 NsFormItem 里时,值变化触发 change 规则。单个多选框绑定布尔值时,false 不算空,required 拦不住没勾选,要写 validator 判断是否为 true;多选框组绑定数组,required 把空数组当成没填,min、max 按选中个数比较。不需要校验时设 :validate-event="false"。
校验不通过时表单项下面显示错误信息,多选框本身的颜色不变(不像输入框那样边框变红)。点“提交”看看:
<script setup lang="ts">
import { reactive, ref } from 'vue'
import { NsButton, NsCheckbox, NsCheckboxGroup, NsForm, NsFormItem } from '@ns/ui'
import type { CheckboxValueType, FormRule } from '@ns/ui'
const formRef = ref<InstanceType<typeof NsForm>>()
const model = reactive({ hobbies: [] as CheckboxValueType[], agree: false })
const rules: Record<string, FormRule[]> = {
hobbies: [
{ required: true, message: '请至少选一项', trigger: 'change' },
{ max: 2, message: '最多选两项', trigger: 'change' }
],
agree: [
{ validator: (_rule, value) => value === true, message: '请勾选同意', trigger: 'change' }
]
}
const submit = () => {
formRef.value?.validate()
}
</script>
<template>
<NsForm ref="formRef" :model="model" :rules="rules" @submit.prevent>
<NsFormItem label="爱好" prop="hobbies">
<NsCheckboxGroup v-model="model.hobbies">
<NsCheckbox value="read" label="阅读" />
<NsCheckbox value="music" label="音乐" />
<NsCheckbox value="sport" label="运动" />
</NsCheckboxGroup>
</NsFormItem>
<NsFormItem prop="agree">
<NsCheckbox v-model="model.agree">已阅读并同意用户协议</NsCheckbox>
</NsFormItem>
<NsFormItem>
<NsButton type="primary" @click="submit">提交</NsButton>
</NsFormItem>
</NsForm>
</template>
控制焦点
通过 ref 调用 focus()、blur()。获得焦点后按空格可以切换选中状态。ref 上的 inputRef 是内部的原生 <input type="checkbox">。
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsCheckbox, NsSpace } from '@ns/ui'
const checked = ref(false)
const checkboxRef = ref<InstanceType<typeof NsCheckbox>>()
</script>
<template>
<NsSpace wrap>
<NsCheckbox ref="checkboxRef" v-model="checked">通过 ref 控制焦点</NsCheckbox>
<NsButton @click="checkboxRef?.focus()">获得焦点</NsButton>
<NsButton @click="checkboxRef?.blur()">失去焦点</NsButton>
</NsSpace>
</template>
NsCheckbox Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| modelValue | CheckboxValueType | CheckboxValueType[] | - | 绑定值,支持 v-model。是数组时按自己的值在不在数组里判断是否选中;不是数组时等于 trueValue 才算选中。放在 NsCheckboxGroup 里时不用写 |
| value | CheckboxValueType | - | 选项的值,在 NsCheckboxGroup 里或绑定数组时使用 |
| label | CheckboxValueType | - | 选项文字:没写默认插槽、并且是字符串或数字时显示出来。没传 value 时也当选项的值用 |
| disabled | boolean | - | 是否禁用。不写时跟随所在的 NsCheckboxGroup,不在组里时是 false |
| readonly | boolean | - | 是否只读:保持当前状态,点击不改变。不写时跟随所在的 NsCheckboxGroup,不在组里时是 false |
| indeterminate | boolean | false | 是否显示成半选。只影响显示,不改变绑定值 |
| trueValue | CheckboxValueType | true | 选中时的值(绑定值不是数组、也不在组里时使用) |
| falseValue | CheckboxValueType | false | 未选中时的值(同上) |
| name | string | - | 原生 name 属性。不写时用所在组的 name |
| size | 'large' | 'default' | 'small' | - | 尺寸:方框 18 / 16 / 14px,文字 16 / 14 / 12px。不写时跟随所在的组、FormItem、Form、ConfigProvider,都没有时是 default |
| validateEvent | boolean | true | 值变化时是否触发所在表单项的校验。在多选框组里时由组负责校验 |
NsCheckboxGroup Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| modelValue | CheckboxValueType[] | [] | 绑定值,支持 v-model,内容是选中项的值 |
| disabled | boolean | false | 是否禁用组里所有多选框 |
| readonly | boolean | false | 是否让组里所有多选框只读 |
| min | number | - | 最少选中数量,不传或写 0 表示不限制 |
| max | number | - | 最多选中数量,不传或写 0 表示不限制 |
| name | string | - | 传给组里每个多选框的原生 name 属性 |
| type | 'default' | 'button' | 'default' | 样式:default 是方形多选框,button 是一排相连的按钮 |
| size | 'large' | 'default' | 'small' | - | 尺寸,组里的多选框都用它:方形多选框的方框 18 / 16 / 14px、文字 16 / 14 / 12px,按钮样式的高度 40 / 32 / 24px。不写时跟随 FormItem、Form、ConfigProvider,都没有时是 default |
| validateEvent | boolean | true | 值变化时是否触发所在表单项的校验 |
NsCheckbox Events
放在 NsCheckboxGroup 里时,单个 NsCheckbox 不触发下面两个事件,要监听组上的事件。
| 事件 | 回调参数 | 说明 |
|---|---|---|
| update:modelValue | (value: CheckboxValueType | CheckboxValueType[]) | 用户点击改变状态时触发,v-model 用的就是它 |
| change | (value: CheckboxValueType | CheckboxValueType[]) | 用户点击改变状态时触发,参数是新的值(绑定数组时是新数组) |
NsCheckboxGroup Events
| 事件 | 回调参数 | 说明 |
|---|---|---|
| update:modelValue | (value: CheckboxValueType[]) | 选中项变化时触发,v-model 用的就是它 |
| change | (value: CheckboxValueType[]) | 选中项变化时触发,参数是新的数组 |
| limit-reach | (limit: 'min' | 'max') | 变更后选中数量到了 min(参数 'min')或 max(参数 'max')时触发 |
NsCheckbox Slots
| 插槽 | 作用域参数 | 说明 |
|---|---|---|
| default | - | 选项文字。写了以后不再显示 label |
NsCheckboxGroup Slots
| 插槽 | 作用域参数 | 说明 |
|---|---|---|
| default | - | 放 NsCheckbox,中间可以隔着其他元素 |
NsCheckbox 方法
通过组件的 ref 调用。
| 方法 | 参数 | 返回值 | 说明 |
|---|---|---|---|
| focus | - | void | 让多选框获得焦点 |
| blur | - | void | 让多选框失去焦点 |
ref 上还有 inputRef,是内部的原生 <input type="checkbox"> 元素。
类型
import type {
CheckboxValueType,
CheckboxProps,
CheckboxGroupProps,
CheckboxGroupType,
CheckboxGroupSize,
CheckboxSize
} from '@ns/ui'
type CheckboxValueType = boolean | string | number | object
/** 多选框的尺寸 */
type CheckboxSize = 'large' | 'default' | 'small'
interface CheckboxProps {
modelValue?: CheckboxValueType | CheckboxValueType[]
label?: CheckboxValueType
value?: CheckboxValueType
disabled?: boolean
readonly?: boolean
indeterminate?: boolean
trueValue?: CheckboxValueType
falseValue?: CheckboxValueType
name?: string
/** 值变化时是否触发所在表单项的校验,默认 true。在多选框组里时由组负责校验 */
validateEvent?: boolean
/** 尺寸。不写时跟随所在的组、FormItem、Form、ConfigProvider,都没有时是 'default' */
size?: CheckboxSize
}
/** 多选框组的样式:default 是方形多选框,button 是一排相连的按钮 */
type CheckboxGroupType = 'default' | 'button'
/** 多选框组的尺寸 */
type CheckboxGroupSize = CheckboxSize
interface CheckboxGroupProps {
modelValue?: CheckboxValueType[]
disabled?: boolean
readonly?: boolean
min?: number
max?: number
name?: string
/** 值变化时是否触发所在表单项的校验,默认 true */
validateEvent?: boolean
/** 样式:'default' 方形多选框,'button' 一排相连的按钮。默认 'default' */
type?: CheckboxGroupType
/** 尺寸,组里的多选框都用它。不写时跟随所在的 FormItem、Form、ConfigProvider,都没有时是 'default' */
size?: CheckboxGroupSize
}
另外还导出了 CheckboxEmits、CheckboxGroupEmits、CheckboxGroupContext 和注入用的 CHECKBOX_GROUP_INJECTION_KEY,自己写和 NsCheckboxGroup 配合的子组件时才用得到。
注意事项
- 选项的值按
value、label、trueValue的顺序取第一个有值的。同时写了value和label时,value是值,label只当文字。 - 组件是受控的,不保存自己的选中状态。只写
:model-value不处理update:modelValue时,点击后显示不会变。 indeterminate为true时框里显示横线,不管当前是否选中。点击后它不会自己变回false。- 值是对象时按引用比较,数组里要放同一个对象才算选中。
- 在
NsCheckboxGroup里,子项的modelValue、trueValue、falseValue不起作用,选中状态只看组的绑定值里有没有这个子项的值。 min、max只限制用户点击,不会修正绑定值:初始值的数量不在范围内时组件不会改它。- 只读的多选框仍然能获得焦点,禁用的不能。
- 不写
size的多选框会跟随所在NsForm、NsFormItem的尺寸,large的表单里方框是 18px、文字 16px。 - 按钮样式靠“第一个、最后一个子元素”给两头加圆角,相邻按钮靠重叠 1px 合并边框,所以
NsCheckbox要直接放在组里。中间隔了别的元素(例如每一项外面又包了一层)时,圆角和边框会不对。按钮样式的组不换行,选项太多放不下时改用多选的 Select。 - 按钮样式下方框不显示,原生多选框仍在(视觉上隐藏),读屏、表单提交、Tab 聚焦、空格切换和普通样式一样。
indeterminate在按钮样式下不显示。
优化点
- [ ] 支持多选框边框样式
- [ ] 支持自定义图标(现在勾和横线是用样式画的,不能换)
- [ ] 支持不绑定
v-model的非受控用法(如default-checked) - [x] 方形多选框也跟随
size变大变小