uView Next
4.1.6

外观

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 属性

参数说明类型默认值
nameradio的名称string | number | boolean-
shape外观形状
Enum
circle
disabled是否禁用booleanfalse
labelDisabled是否禁止点击提示语选中单选框booleanfalse
activeColor选中状态下的颜色，如设置此值，将会覆盖parent的activeColor值string-
inactiveColor未选中的颜色string-
icon自定义图标string-
iconSize图标的大小，单位pxstring | number-
labelSizelabel的字体大小，px单位string | number14
labellabel提示文字string | number-
size整体的大小string | number-
iconColor图标颜色string-
labelColorlabel的颜色string-
activeLabelColor选中状态下label的颜色string-
iconPlacement勾选图标的对齐方式
Enum
left
customStyle自定义样式object | string''

RadioGroup Props 属性

参数说明类型默认值
name标识符string-
v-model / modelValue绑定的值string | number | boolean-
shape外观形状
Enum
circle
disabled是否禁用所有radiobooleanfalse
activeColor选中时的颜色，应用到所有子Radio组件string-
inactiveColor未选中的颜色string-
size组件整体的大小，单位pxstring | number20
placement布局方式，row-横向，column-纵向
Enum
row
label文本string-
labelColorlabel的颜色string-
labelSizelabel的字体大小，px单位string | number-
labelDisabled是否禁止点击文本操作checkboxbooleanfalse
iconColor图标颜色string-
iconSize图标的大小，单位pxstring | number-
borderBottomplacement为row时，是否显示下边框booleanfalse
iconPlacement图标与文字的对齐方式
Enum
left
activeLabelColorlabel的颜色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 (当前是否选中)

Copyright © 2026 uView Next