外观
Radio 单选框
约 2298 字大约 8 分钟
2025-10-31
Radio 单选框组件是用于用户进行单选操作的表单控件,支持多种样式和交互方式。该组件具有高度的可定制性,可以满足各种单选场景的需求,包括选项筛选、性别选择、支付方式等。通过丰富的属性配置和事件支持,可以轻松实现美观且功能完善的单选界面。
基本使用
该组件需要搭配radioGroup组件使用,通过v-model给radioGroup组件绑定一个变量,对应的name将会被选中。
<template>
<un-radio-group v-model="radioValueCity">
<un-radio v-for="(item, index) in radioListCity" :key="index" :label="item.name" :name="item.name"></un-radio>
</un-radio-group>
</template>
<script setup lang="ts">
import { ref } from 'vue'
type RadioItem = {
name: string;
desc?: string;
}
const radioListCity = ref<RadioItem[]>([
{ name: '苹果' },
{ name: '香蕉' },
{ name: '橙子' },
{ name: '草莓' },
{ name: '葡萄' },
{ name: '西瓜' },
{ name: '猕猴桃' }
]);
const radioValueCity = ref<string>('苹果');
</script>自定义形状
通过设置shape为不同的值,可以将单选框设置为多种样式,包括方形、圆点、勾选和按钮样式。
<template>
<!-- 方形样式 -->
<un-radio-group v-model="radioValueSquare" shape="square">
<un-radio v-for="(item, index) in radioListSquare" :key="index" :label="item.name" :name="item.name">
</un-radio>
</un-radio-group>
<!-- 圆点样式 v4.1.0 开始支持 -->
<un-radio-group v-model="radioValueDot" shape="dot">
<un-radio v-for="(item, index) in radioListDot" :key="index" :label="item.name" :name="item.name">
</un-radio>
</un-radio-group>
<!-- 勾选样式 v4.1.0 开始支持 -->
<un-radio-group v-model="radioValueCheck" shape="check">
<un-radio v-for="(item, index) in radioListCheck" :key="index" :label="item.name" :name="item.name">
</un-radio>
</un-radio-group>
<!-- 按钮样式 v4.1.0 开始支持 -->
<un-radio-group v-model="radioValueButton" shape="button">
<un-radio v-for="(item, index) in radioListButton" :key="index" :label="item.name" :name="item.name">
</un-radio>
</un-radio-group>
</template>
<script setup lang="ts">
import { ref } from 'vue'
type RadioItem = {
name: string;
desc?: string;
}
// 方形样式案例
const radioListSquare = ref<RadioItem[]>([
{ name: '红色' },
{ name: '橙色' },
{ name: '黄色' },
{ name: '绿色' },
{ name: '蓝色' },
{ name: '靛色' },
{ name: '紫色' },
{ name: '黑色' }
]);
const radioValueSquare = ref<string>('红色');
// 圆点样式案例
const radioListDot = ref<RadioItem[]>([
{ name: '春节' },
{ name: '元宵节' },
{ name: '清明节' },
{ name: '端午节' },
{ name: '中秋节' },
{ name: '国庆节' }
]);
const radioValueDot = ref<string>('春节');
// 勾选样式案例
const radioListCheck = ref<RadioItem[]>([
{ name: '流行音乐' },
{ name: '摇滚音乐' },
{ name: '古典音乐' },
{ name: '爵士音乐' },
{ name: '电子音乐' },
{ name: '民谣音乐' },
{ name: '嘻哈音乐' }
]);
const radioValueCheck = ref<string>('流行音乐');
// 按钮样式案例
const radioListButton = ref<RadioItem[]>([
{ name: '动作游戏' },
{ name: '角色扮演' },
{ name: '射击游戏' },
{ name: '策略游戏' },
{ name: '模拟经营' },
{ name: '体育游戏' },
{ name: '解谜游戏' }
]);
const radioValueButton = ref<string>('动作游戏');
</script>禁用状态
通过设置disabled属性为true,可以禁用单选框,使其无法被点击。
<template>
<un-radio-group v-model="radioValueDisabled" :disabled="disabled">
<un-radio v-for="(item, index) in radioListDisabled" :key="index" :label="item.name" :name="item.name"></un-radio>
</un-radio-group>
<un-radio-group v-model="radioValueDisabled" :disabled="disabled" shape="square">
<un-radio v-for="(item, index) in radioListDisabled" :key="index" :label="item.name" :name="item.name"></un-radio>
</un-radio-group>
<un-radio-group v-model="radioValueDisabled" :disabled="disabled" shape="dot">
<un-radio v-for="(item, index) in radioListDisabled" :key="index" :label="item.name" :name="item.name"></un-radio>
</un-radio-group>
<un-radio-group v-model="radioValueDisabled" :disabled="disabled" shape="check">
<un-radio v-for="(item, index) in radioListDisabled" :key="index" :label="item.name" :name="item.name"></un-radio>
</un-radio-group>
<un-radio-group v-model="radioValueDisabled" :disabled="disabled" shape="button">
<un-radio v-for="(item, index) in radioListDisabled" :key="index" :label="item.name" :name="item.name"></un-radio>
</un-radio-group>
</template>
<script setup lang="ts">
import { ref } from 'vue'
type RadioItem = {
name: string;
desc?: string;
}
// 禁用状态案例
const radioListDisabled = ref<RadioItem[]>([
{ name: '自行车' },
{ name: '电动车' },
{ name: '汽车' },
{ name: '火车' },
{ name: '飞机' },
]);
const radioValueDisabled = ref<string>('自行车');
const disabled = ref<boolean>(false);
// 1秒后自动禁用
setTimeout(() => {
disabled.value = true;
}, 1000);
</script>自定义颜色
通过activeColor属性可以设置单选框选中时的颜色。
<template>
<un-radio-group v-model="radioValueCustom" activeColor="#19be6b">
<un-radio v-for="(item, index) in radioListDisabled" :key="index" :label="item.name" :name="item.name"></un-radio>
</un-radio-group>
<un-radio-group v-model="radioValueCustom" shape="square" activeColor="#19be6b">
<un-radio v-for="(item, index) in radioListDisabled" :key="index" :label="item.name" :name="item.name"></un-radio>
</un-radio-group>
<un-radio-group v-model="radioValueCustom" shape="dot" activeColor="#19be6b">
<un-radio v-for="(item, index) in radioListDisabled" :key="index" :label="item.name" :name="item.name"></un-radio>
</un-radio-group>
<un-radio-group v-model="radioValueCustom" shape="check" activeColor="#19be6b">
<un-radio v-for="(item, index) in radioListDisabled" :key="index" :label="item.name" :name="item.name"></un-radio>
</un-radio-group>
<un-radio-group v-model="radioValueCustom" shape="button" activeColor="#19be6b">
<un-radio v-for="(item, index) in radioListDisabled" :key="index" :label="item.name" :name="item.name"></un-radio>
</un-radio-group>
</template>
<script setup lang="ts">
import { ref } from 'vue'
type RadioItem = {
name: string;
desc?: string;
}
// 自定义颜色案例
const radioListDisabled = ref<RadioItem[]>([
{ name: '自行车' },
{ name: '电动车' },
{ name: '汽车' },
{ name: '火车' },
{ name: '飞机' },
]);
const radioValueCustom = ref<string>('自行车');
</script>纵向排列
通过设置placement为column,可以将单选框设置为纵向排列。
<template>
<un-radio-group v-model="radioValueDot" placement="column">
<un-radio
v-for="(item, index) in radioListDot"
:key="index"
:label="item.name"
:name="item.name"
>
</un-radio>
</un-radio-group>
</template>
<script setup lang="ts">
import { ref } from 'vue'
type RadioItem = {
name: string;
desc?: string;
}
// 圆点样式案例
const radioListDot = ref<RadioItem[]>([
{ name: '春节' },
{ name: '元宵节' },
{ name: '清明节' },
{ name: '端午节' },
{ name: '中秋节' },
{ name: '国庆节' }
]);
const radioValueDot = ref<string>('春节');
</script>使用插槽自定义图标
通过插槽可以自定义单选框的图标和内容,实现更加个性化的效果。
<template>
<un-radio-group v-model="radioValueCustom">
<un-radio label="男" name="man">
<template #icon="{ checked }">
<un-icon type="primary" name="man" :color="checked == true ? '' : '#ccc'" size="20"></un-icon>
</template>
</un-radio>
<un-radio label="女" name="woman">
<template #icon="{ checked }">
<un-icon type="primary" name="woman" :color="checked == true ? '' : '#ccc'" size="20"></un-icon>
</template>
</un-radio>
</un-radio-group>
<un-radio-group v-model="radioValueCustom" shape="button">
<un-radio name="man">
<template #default="{ checked }">
<un-icon type="primary" name="man" :color="checked == true ? '' : '#ccc'" size="20"></un-icon>
<text style="font-size: 14px;margin-left: 5px;">男</text>
</template>
</un-radio>
<un-radio name="woman">
<template #default="{ checked }">
<un-icon type="primary" name="woman" :color="checked == true ? '' : '#ccc'" size="20"></un-icon>
<text style="font-size: 14px;margin-left: 5px;">女</text>
</template>
</un-radio>
</un-radio-group>
</template>
<script setup lang="ts">
import { ref } from 'vue'
const radioValueCustom = ref<string>('自行车');
</script>横向两端排列形式
通过设置iconPlacement为right,可以将单选框勾选图标设置为右对齐,实现两端排列的效果。
<template>
<un-radio-group
v-model="radioValueOpinion"
:borderBottom="true"
placement="column"
iconPlacement="right"
>
<un-radio v-for="(item, index) in radioListOpinion" :key="index" :name="item.name">
<view class="radio-item">
<text class="label">{{ item.name }}</text>
<text class="desc">{{ item.desc }}</text>
</view>
</un-radio>
</un-radio-group>
</template>
<script setup lang="ts">
import { ref } from 'vue'
type RadioItem = {
name: string;
desc?: string;
}
// 横向两端排列案例
const radioListOpinion = ref<RadioItem[]>([
{ name: '天天美食', desc: '北京市朝阳区建国路88号华贸中心购物中心B1层123号' },
{ name: '小幸福家常菜馆', desc: '上海市黄浦区南京东路123号新世界城6楼666室' },
{ name: '舌尖上的中国', desc: '广州市天河区天河路666号正佳广场7层789号铺' },
{ name: '味之道', desc: '深圳市福田区深南大道999号平安金融中心裙楼5层505号' },
{ name: '川香阁老火锅', desc: '成都市锦江区春熙路77号IFS国际金融中心LG2层234号' },
{ name: '江南小筑', desc: '杭州市西湖区文三路333号华星时代广场A座2楼201室' },
{ name: '长安印象陕菜博物馆', desc: '西安市雁塔区大雁塔南广场大唐不夜城步行街1234号' }
]);
const radioValueOpinion = ref<string>('天天美食');
</script>
<style scoped lang="scss">
.radio-item {
margin: 10px 0;
}
.label {
font-size: 14px;
color: #303133;
}
.desc {
font-size: 12px;
margin-top: 4px;
color: #909399;
}
</style>API
Radio Props 属性
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| name | radio的名称 | string | number | boolean | - |
| shape | 外观形状 | Enum | circle |
| disabled | 是否禁用 | boolean | false |
| labelDisabled | 是否禁止点击提示语选中单选框 | boolean | false |
| activeColor | 选中状态下的颜色,如设置此值,将会覆盖parent的activeColor值 | string | - |
| inactiveColor | 未选中的颜色 | string | - |
| icon | 自定义图标 | string | - |
| iconSize | 图标的大小,单位px | string | number | - |
| labelSize | label的字体大小,px单位 | string | number | 14 |
| label | label提示文字 | string | number | - |
| size | 整体的大小 | string | number | - |
| iconColor | 图标颜色 | string | - |
| labelColor | label的颜色 | string | - |
| activeLabelColor | 选中状态下label的颜色 | string | - |
| iconPlacement | 勾选图标的对齐方式 | Enum | left |
| customStyle | 自定义样式 | object | string | '' |
RadioGroup Props 属性
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| name | 标识符 | string | - |
| v-model / modelValue | 绑定的值 | string | number | boolean | - |
| shape | 外观形状 | Enum | circle |
| disabled | 是否禁用所有radio | boolean | false |
| activeColor | 选中时的颜色,应用到所有子Radio组件 | string | - |
| inactiveColor | 未选中的颜色 | string | - |
| size | 组件整体的大小,单位px | string | number | 20 |
| placement | 布局方式,row-横向,column-纵向 | Enum | row |
| label | 文本 | string | - |
| labelColor | label的颜色 | string | - |
| labelSize | label的字体大小,px单位 | string | number | - |
| labelDisabled | 是否禁止点击文本操作checkbox | boolean | false |
| iconColor | 图标颜色 | string | - |
| iconSize | 图标的大小,单位px | string | number | - |
| borderBottom | placement为row时,是否显示下边框 | boolean | false |
| iconPlacement | 图标与文字的对齐方式 | Enum | left |
| activeLabelColor | label的颜色 | string | - |
Radio Event 事件
| 事件名 | 说明 | 类型 |
|---|---|---|
| change | 某个radio状态发生变化时触发(选中状态) | Function |
| update:checked | 某个radio状态发生变化时触发(v-model:checked双向绑定) | Function |
RadioGroup Event 事件
| 事件名 | 说明 | 类型 |
|---|---|---|
| change | 任一个radio状态发生变化时触发 | Function |
| update:modelValue | 任一个radio状态发生变化时触发(v-model双向绑定) | Function |
Radio Slot 插槽
| 名称 | 说明 | 参数 |
|---|---|---|
| default | 自定义label内容 | checked: boolean (当前是否选中) |
| icon | 自定义icon图标 | checked: boolean (当前是否选中) |
