Radio 单选框
在一组互斥的选项里选一个。选项比较多时建议改用 Select。
引入
import { NsRadio, NsRadioGroup } from '@ns/ui'
基础用法
几个 NsRadio 用 v-model 绑定同一个变量,各自用 value 指定自己的值。绑定值等于哪一项的 value,哪一项就是选中的。
<script setup lang="ts">
import { ref } from 'vue'
import { NsRadio, NsSpace } from '@ns/ui'
const gender = ref('male')
</script>
<template>
<NsSpace wrap>
<NsRadio v-model="gender" value="male" name="gender">男</NsRadio>
<NsRadio v-model="gender" value="female" name="gender">女</NsRadio>
</NsSpace>
<p style="margin-top: 12px">绑定值:'{{ gender }}'</p>
</template>
用 label 写文字
没写默认插槽时,字符串或数字类型的 label 会当文字显示。只写 label 不写 value 时,label 同时也是这一项的值。
<script setup lang="ts">
import { ref } from 'vue'
import { NsRadio, NsSpace } from '@ns/ui'
const plan = ref('month')
const city = ref('北京')
</script>
<template>
<NsSpace direction="vertical" align="start">
<!-- value 是值,label 是文字 -->
<NsSpace wrap>
<NsRadio v-model="plan" value="month" label="按月付费" name="plan" />
<NsRadio v-model="plan" value="year" label="按年付费" name="plan" />
<span>绑定值:'{{ plan }}'</span>
</NsSpace>
<!-- 只写 label:文字和值都是它 -->
<NsSpace wrap>
<NsRadio v-model="city" label="北京" name="city" />
<NsRadio v-model="city" label="上海" name="city" />
<span>绑定值:'{{ city }}'</span>
</NsSpace>
</NsSpace>
</template>
禁用
disabled 禁用后不能点击,也不能获得焦点,整个单选框变淡(透明度 0.5)。单选框没有只读属性,要只展示选中项时用禁用状态。
<script setup lang="ts">
import { ref } from 'vue'
import { NsRadio, NsSpace } from '@ns/ui'
const value = ref('b')
</script>
<template>
<NsSpace wrap>
<NsRadio v-model="value" value="a" disabled>禁用未选中</NsRadio>
<NsRadio v-model="value" value="b" disabled>禁用已选中</NsRadio>
</NsSpace>
</template>
单选框组
用 NsRadioGroup 包起来以后,v-model 只写在组上,里面的 NsRadio 只写 value。组内可以用方向键切换,Tab 键只在组上停一次。换了选中项时组触发 change,参数是新选中项的值。
<script setup lang="ts">
import { ref } from 'vue'
import { NsRadio, NsRadioGroup } from '@ns/ui'
const city = ref('bj')
const lastChange = ref('')
const handleChange = (value: string | number | boolean) => {
lastChange.value = String(value)
}
</script>
<template>
<NsRadioGroup v-model="city" @change="handleChange">
<NsRadio value="bj" label="北京" />
<NsRadio value="sh" label="上海" />
<NsRadio value="gz" label="广州" />
</NsRadioGroup>
<p style="margin-top: 12px">change 事件:{{ lastChange || '还没有触发' }}</p>
</template>
组的禁用
组上的 disabled 对里面所有单选框生效。某一项自己写了 disabled 时以自己的为准,所以可以只禁用其中一项,也可以用 :disabled="false" 让某一项不跟随组。
<script setup lang="ts">
import { ref } from 'vue'
import { NsRadio, NsRadioGroup, NsSpace } from '@ns/ui'
const a = ref('1')
const b = ref('1')
</script>
<template>
<NsSpace direction="vertical" align="start">
<!-- 整组禁用,第三项不跟随组 -->
<NsRadioGroup v-model="a" disabled>
<NsRadio value="1" label="选项一" />
<NsRadio value="2" label="选项二" />
<NsRadio value="3" label="选项三(不跟随组)" :disabled="false" />
</NsRadioGroup>
<!-- 只禁用其中一项 -->
<NsRadioGroup v-model="b">
<NsRadio value="1" label="选项一" />
<NsRadio value="2" label="选项二(禁用)" disabled />
<NsRadio value="3" label="选项三" />
</NsRadioGroup>
</NsSpace>
</template>
数字和布尔值
值可以是字符串、数字或布尔值,比较时区分类型:1 和 '1' 不相等。传数字、布尔值时要用 :value。
<script setup lang="ts">
import { ref } from 'vue'
import { NsRadio, NsRadioGroup, NsSpace } from '@ns/ui'
const level = ref(2)
const enabled = ref(true)
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<NsRadioGroup v-model="level">
<NsRadio :value="1">一级</NsRadio>
<NsRadio :value="2">二级</NsRadio>
<NsRadio :value="3">三级</NsRadio>
</NsRadioGroup>
<span>{{ level }}({{ typeof level }})</span>
</NsSpace>
<NsSpace wrap>
<NsRadioGroup v-model="enabled">
<NsRadio :value="true">启用</NsRadio>
<NsRadio :value="false">停用</NsRadio>
</NsRadioGroup>
<span>{{ enabled }}({{ typeof enabled }})</span>
</NsSpace>
</NsSpace>
</template>
不同尺寸
size 可以写在单个 NsRadio 上,也可以写在 NsRadioGroup 上:large、default、small 的圆圈是 18、16、14px,文字是 16、14、12px。
不写时按“单选框自己 > 所在的组 > NsFormItem > NsForm > NsConfigProvider”的顺序取,都没有时是 default。放进表单时,选项文字和表单项标签在同一条基线上。
<script setup lang="ts">
import { ref } from 'vue'
import { NsRadio, NsRadioGroup, NsSpace } from '@ns/ui'
const single = ref('a')
const level = ref('b')
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<span class="row-label">large</span>
<NsRadioGroup v-model="level" size="large">
<NsRadio value="a" label="选项 A" />
<NsRadio value="b" label="选项 B" />
<NsRadio value="c" label="禁用" disabled />
</NsRadioGroup>
</NsSpace>
<NsSpace wrap>
<span class="row-label">default</span>
<NsRadioGroup v-model="level">
<NsRadio value="a" label="选项 A" />
<NsRadio value="b" label="选项 B" />
<NsRadio value="c" label="禁用" disabled />
</NsRadioGroup>
</NsSpace>
<NsSpace wrap>
<span class="row-label">small</span>
<NsRadioGroup v-model="level" size="small">
<NsRadio value="a" label="选项 A" />
<NsRadio value="b" label="选项 B" />
<NsRadio value="c" label="禁用" disabled />
</NsRadioGroup>
</NsSpace>
<!-- 写在单个单选框上 -->
<NsSpace wrap>
<span class="row-label">单个</span>
<NsRadio v-model="single" value="a" size="large" name="size-demo">large</NsRadio>
<NsRadio v-model="single" value="b" name="size-demo">default</NsRadio>
<NsRadio v-model="single" value="c" size="small" name="size-demo">small</NsRadio>
</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" 时,里面的单选框显示成一排相连的按钮,选中的那一个用主色填充。写法和普通的单选框组一样,不用换组件。
size 设置按钮的尺寸:large、default、small 的高度分别是 40、32、24px,内边距、字号、圆角和同尺寸的 NsButton 一致。不写 size 时跟随所在的 NsFormItem、NsForm、NsConfigProvider,都没有时是 default。下面每一行最后放一个同尺寸的按钮对比高度:
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsRadio, NsRadioGroup, NsSpace } from '@ns/ui'
const period = ref('week')
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<span class="row-label">large</span>
<NsRadioGroup v-model="period" type="button" size="large">
<NsRadio value="day" label="日" />
<NsRadio value="week" label="周" />
<NsRadio value="month" label="月" />
<NsRadio value="year" label="年" />
</NsRadioGroup>
<NsButton size="large">按钮</NsButton>
</NsSpace>
<NsSpace wrap>
<span class="row-label">default</span>
<NsRadioGroup v-model="period" type="button">
<NsRadio value="day" label="日" />
<NsRadio value="week" label="周" />
<NsRadio value="month" label="月" />
<NsRadio value="year" label="年" />
</NsRadioGroup>
<NsButton>按钮</NsButton>
</NsSpace>
<NsSpace wrap>
<span class="row-label">small</span>
<NsRadioGroup v-model="period" type="button" size="small">
<NsRadio value="day" label="日" />
<NsRadio value="week" label="周" />
<NsRadio value="month" label="月" />
<NsRadio value="year" label="年" />
</NsRadioGroup>
<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 只禁用这一项。
<script setup lang="ts">
import { ref } from 'vue'
import { NsRadio, NsRadioGroup, NsSpace } from '@ns/ui'
const all = ref('sh')
const one = ref('sh')
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsSpace wrap>
<span class="row-label">整组禁用</span>
<NsRadioGroup v-model="all" type="button" disabled>
<NsRadio value="bj" label="北京" />
<NsRadio value="sh" label="上海" />
<NsRadio value="gz" label="广州" />
</NsRadioGroup>
</NsSpace>
<NsSpace wrap>
<span class="row-label">禁用一项</span>
<NsRadioGroup v-model="one" type="button">
<NsRadio value="bj" label="北京" />
<NsRadio value="sh" label="上海" />
<NsRadio value="gz" label="广州" disabled />
</NsRadioGroup>
</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 规则(组和单独使用的单选框都一样),组会通过 aria-labelledby 关联表单项的标签。不需要校验时设 :validate-event="false"。
校验不通过时表单项下面显示错误信息,单选框本身的颜色不变(不像输入框那样边框变红)。点“提交”看看:
<script setup lang="ts">
import { reactive, ref } from 'vue'
import { NsButton, NsForm, NsFormItem, NsRadio, NsRadioGroup } from '@ns/ui'
import type { FormRule } from '@ns/ui'
const formRef = ref<InstanceType<typeof NsForm>>()
const model = reactive<{ delivery?: string; payment?: string }>({})
const rules: Record<string, FormRule[]> = {
delivery: [{ required: true, message: '请选择配送方式', trigger: 'change' }],
payment: [{ required: true, message: '请选择支付方式', trigger: 'change' }]
}
const submit = () => {
formRef.value?.validate()
}
</script>
<template>
<NsForm ref="formRef" :model="model" :rules="rules" @submit.prevent>
<NsFormItem label="配送方式" prop="delivery">
<NsRadioGroup v-model="model.delivery">
<NsRadio value="express" label="快递" />
<NsRadio value="pickup" label="自提" />
</NsRadioGroup>
</NsFormItem>
<NsFormItem label="支付方式" prop="payment">
<NsRadioGroup v-model="model.payment" type="button">
<NsRadio value="online" label="在线支付" />
<NsRadio value="cod" label="货到付款" />
</NsRadioGroup>
</NsFormItem>
<NsFormItem>
<NsButton type="primary" @click="submit">提交</NsButton>
</NsFormItem>
</NsForm>
</template>
NsRadio Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| modelValue | string | number | boolean | - | 绑定值,支持 v-model。放在 NsRadioGroup 里时不用写,以组的绑定值为准 |
| value | string | number | boolean | - | 这一项的值 |
| label | string | number | boolean | - | 选项文字:没写默认插槽、并且是字符串或数字时显示出来。没传 value 时也当这一项的值用 |
| disabled | boolean | - | 是否禁用。不写时跟随所在的 NsRadioGroup,不在组里时是 false |
| name | string | - | 原生 name 属性。不写时用所在组的 name |
| size | 'large' | 'default' | 'small' | - | 尺寸:圆圈 18 / 16 / 14px,文字 16 / 14 / 12px。不写时跟随所在的组、FormItem、Form、ConfigProvider,都没有时是 default |
| validateEvent | boolean | true | 值变化时是否触发所在表单项的校验。在单选框组里时由组负责校验 |
NsRadioGroup Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| modelValue | string | number | boolean | - | 绑定值,支持 v-model,等于选中那一项的值 |
| disabled | boolean | false | 是否禁用组里所有单选框 |
| name | string | - | 传给组里每个单选框的原生 name 属性。不写时用 Vue 的 useId 自动生成一个(ns-radio-group- 加 Vue 生成的序号) |
| type | 'default' | 'button' | 'default' | 样式:default 是圆形单选框,button 是一排相连的按钮 |
| size | 'large' | 'default' | 'small' | - | 组里单选框的尺寸:按钮样式高 40 / 32 / 24px,圆形样式见 NsRadio 的 size。单选框自己写了 size 时以自己的为准。不写时跟随 FormItem、Form、ConfigProvider,都没有时是 default |
| validateEvent | boolean | true | 值变化时是否触发所在表单项的校验 |
NsRadio Events
放在 NsRadioGroup 里时,单个 NsRadio 不触发下面两个事件,要监听组上的事件。
| 事件 | 回调参数 | 说明 |
|---|---|---|
| update:modelValue | (value: string | number | boolean) | 用户选中这一项时触发,v-model 用的就是它 |
| change | (value: string | number | boolean) | 用户选中这一项时触发,参数是这一项的值。点已经选中的项不触发 |
NsRadioGroup Events
| 事件 | 回调参数 | 说明 |
|---|---|---|
| update:modelValue | (value: string | number | boolean) | 用户换了选中项时触发,v-model 用的就是它 |
| change | (value: string | number | boolean) | 用户换了选中项时触发,参数是新选中项的值 |
NsRadio Slots
| 插槽 | 作用域参数 | 说明 |
|---|---|---|
| default | - | 选项文字。写了以后不再显示 label |
NsRadioGroup Slots
| 插槽 | 作用域参数 | 说明 |
|---|---|---|
| default | - | 放 NsRadio,中间可以隔着其他元素 |
类型
import type { RadioProps, RadioSize, RadioGroupProps, RadioGroupType, RadioGroupSize } from '@ns/ui'
/** 单选框的尺寸 */
type RadioSize = 'large' | 'default' | 'small'
interface RadioProps {
modelValue?: string | number | boolean
/** 选项文字(没写默认插槽时显示)。没传 value 时也当选项的值用 */
label?: string | number | boolean
/** 选项的值 */
value?: string | number | boolean
disabled?: boolean
name?: string
/** 值变化时是否触发所在表单项的校验,默认 true。在单选框组里时由组负责校验 */
validateEvent?: boolean
/** 尺寸:圆圈 18 / 16 / 14px,文字 16 / 14 / 12px。不写时跟随单选框组、FormItem、Form、ConfigProvider */
size?: RadioSize
}
/** 单选框组的样式:default 是圆形单选框,button 是一排相连的按钮 */
type RadioGroupType = 'default' | 'button'
/** 单选框组的尺寸,和 RadioSize 相同 */
type RadioGroupSize = RadioSize
interface RadioGroupProps {
modelValue?: string | number | boolean
disabled?: boolean
name?: string
/** 值变化时是否触发所在表单项的校验,默认 true */
validateEvent?: boolean
/** 样式:'default' 圆形单选框,'button' 一排相连的按钮。默认 'default' */
type?: RadioGroupType
/** 组里单选框的尺寸。单选框自己写了 size 时以自己的为准;不写时跟随 FormItem、Form、ConfigProvider */
size?: RadioGroupSize
}
另外还导出了 RadioGroupContext 和注入用的 RADIO_GROUP_INJECTION_KEY,自己写和 NsRadioGroup 配合的子组件时才用得到。
注意事项
- 这一项的值按
value、label的顺序取第一个有值的。两个都没写的单选框永远不会被选中,点击也不触发事件。 - 组件是受控的,不保存自己的选中状态。只写
:model-value不处理update:modelValue时,点击后显示不会变。 - 单选框选中以后不能通过再点一次取消。要清空选择,把绑定值改成一个不等于任何选项的值(例如
undefined)。 - 方向键切换、Tab 只停一次是浏览器对同名原生单选框的行为。
NsRadioGroup会自动给子项带上相同的name;不用组、几个NsRadio直接绑定同一个变量时,要自己给它们写相同的name,否则每一项都是单独的 Tab 停靠点,方向键也不能切换。 - 自动生成的
name由 Vue 的useId生成,服务端渲染时两端一致。表单要按name提交时,自己在组上写name。 - 组件没有暴露方法。
- 按钮样式下,组里各项最好用同一个尺寸:某一项自己写了不同的
size时,它会比旁边的按钮高或矮。 - 按钮样式靠“第一个、最后一个子元素”给两头加圆角,相邻按钮靠重叠 1px 合并边框,所以
NsRadio要直接放在组里。中间隔了别的元素(例如每一项外面又包了一层)时,圆角和边框会不对。按钮样式的组不换行,选项太多放不下时改用 Select。 - 按钮样式下圆形单选圈不显示,原生单选框仍在(视觉上隐藏),读屏、表单提交、方向键切换和普通样式一样。
优化点
- [ ] 支持单选框边框样式
- [ ] 支持自定义图标
- [ ] 暴露
focus、blur方法