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.
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方法