uView Next
4.0.105

外观

Radio 单选框

约 1391 字大约 5 分钟

2025-10-31

Radio 单选框组件是用于用户进行单选操作的表单控件，支持多种样式和交互方式。该组件具有高度的可定制性，可以满足各种单选场景的需求，包括选项筛选、性别选择、支付方式等。通过丰富的属性配置和事件支持，可以轻松实现美观且功能完善的单选界面。

基本使用

该组件需要搭配radioGroup组件使用，通过v-model给radioGroup组件绑定一个变量，对应的name将会被选中。

<template>
	<un-radio-group v-model="radioValue1" placement="column" @change="groupChange">
		<un-radio :customStyle="{marginBottom: '8px'}" v-for="(item, index) in radioList1" :key="index" :label="item.name" :name="item.name" @change="radioChange"></un-radio>
	</un-radio-group>
</template>

<script setup lang="uts">
import { ref } from 'vue'

const radioList1 = ref([
	{ name: "苹果", disabled: false },
	{ name: "香蕉", disabled: false },
	{ name: "橙子", disabled: false },
	{ name: "榴莲", disabled: false }
])

const radioValue1 = ref("苹果")

const groupChange = (value) => {
	console.log("groupChange", value)
}

const radioChange = (value) => {
	console.log("radioChange", value)
}
</script>

自定义形状

通过设置shape为square、circle或button，将单选框设置为方形、圆形或按钮样式。

<template>
	<!-- 圆形样式 -->
	<un-radio-group v-model="shapeValue">
		<un-radio shape="circle" label="月明人倚楼"></un-radio>
	</un-radio-group>

	<!-- 按钮样式 - 镂空效果 -->
	<un-radio-group v-model="shapeValue" shape="button">
		<un-radio label="月明人倚楼"></un-radio>
	</un-radio-group>

	<!-- 按钮样式 - 非镂空效果 -->
	<un-radio-group v-model="shapeValue" shape="button" inactiveColor="#f1f1f1" :plain="false">
		<un-radio label="月明人倚楼"></un-radio>
	</un-radio-group>
</template>

<script setup lang="uts">
import { ref } from 'vue'

const shapeValue = ref("月明人倚楼")
</script>

禁用状态

设置disabled为true，即可禁用某个组件，让用户无法点击。

<template>
	<un-radio-group v-model="disabledValue">
		<un-radio :disabled="true" label="明月几时有"></un-radio>
	</un-radio-group>
</template>

<script setup lang="uts">
import { ref } from 'vue'

const disabledValue = ref("明月几时有")
</script>

禁止点击文本选中

设置labelDisabled为true，即可禁止点击提示语选中单选框。

<template>
	<un-radio-group v-model="labelDisabledValue">
		<un-radio :labelDisabled="true" label="明月几时有"></un-radio>
	</un-radio-group>
</template>

<script setup lang="uts">
import { ref } from 'vue'

const labelDisabledValue = ref("明月几时有")
</script>

自定义颜色

通过activeColor参数设置单选框选中时的背景颜色。

<template>
	<un-radio-group v-model="colorValue">
		<un-radio activeColor="red" label="思悠悠，恨悠悠，恨到归时方始休"></un-radio>
	</un-radio-group>
</template>

<script setup lang="uts">
import { ref } from 'vue'

const colorValue = ref("思悠悠，恨悠悠，恨到归时方始休")
</script>

横向排列

通过设置placement为row，将单选框设置为横向排列。

<template>
	<un-radio-group v-model="placementValue" placement="row">
		<un-radio activeColor="red" label="思悠悠，恨悠悠，恨到归时方始休"></un-radio>
	</un-radio-group>
</template>

<script setup lang="uts">
import { ref } from 'vue'

const placementValue = ref("思悠悠，恨悠悠，恨到归时方始休")
</script>

横向两端排列

通过设置iconPlacement为right，将单选框勾选图标设置为右对齐。

<template>
	<un-radio-group v-model="iconPlacementValue" iconPlacement="right">
		<un-radio activeColor="red" label="思悠悠，恨悠悠，恨到归时方始休"></un-radio>
	</un-radio-group>
</template>

<script setup lang="uts">
import { ref } from 'vue'

const iconPlacementValue = ref("思悠悠，恨悠悠，恨到归时方始休")
</script>

API

Props

参数说明类型默认值
nameradio的名称string | number-
shaperadio形状
Enum
square
disabled是否禁用booleanfalse
labelDisabled是否禁止点击提示语选中单选框booleanfalse
activeColor选中状态下的颜色，如设置此值，将会覆盖parent的activeColor值string#2979ff
inactiveColor未选中的颜色string#c8c9cc
icon自定义图标string-
iconSize图标的大小，单位pxstring | number12
labelSizelabel的字体大小，px单位string | number14
labellabel提示文字string | number-
size整体的大小string | number18
iconColor图标颜色string#ffffff
labelColorlabel的颜色string#303133
activeLabelColor选中状态下label的颜色string-
plain镂空样式booleantrue
modelValue绑定的值string | number | boolean-
placement布局方式，可选值为row(横向)或column(纵向)
Enum
row
borderBottom竖向排列时，是否显示下划线booleanfalse
iconPlacement勾选图标的对齐方式，可选值为left(左边)或right(右边)
Enum
left

Event

事件名说明类型
change任意一个radio状态发生变化时触发
Function

Slot

名称说明
default自定义label样式
icon自定义icon图标

Scss 变量

变量名默认值说明
$un-radio-label-border0.5px solid $border-color单选框label边框样式
$un-radio-icon-margin-right6px单选框图标右侧外边距
$un-radio-icon-size18px单选框图标大小
$un-radio-icon-border1px solid $border-color单选框图标边框样式
$un-radio-icon-border-radius$radius-base单选框图标圆角半径
$un-radio-icon-checked-bg-color$color-primary单选框图标选中时背景色
$un-radio-icon-checked-border1px solid $color-primary单选框图标选中时边框样式
$un-radio-icon-disabled-bg-color$bg-color-disabled单选框图标禁用时背景色
$un-radio-icon-disabled-border1px solid $border-color单选框图标禁用时边框样式
$un-radio-button-padding5px 15px单选框按钮内边距
$un-radio-button-border1px solid $border-color单选框按钮边框样式
$un-radio-button-border-radius100px单选框按钮圆角半径
$un-radio-button-checked-bg-color$color-primary单选框按钮选中时背景色
$un-radio-button-checked-border1px solid $color-primary单选框按钮选中时边框样式
$un-radio-label-text-font-size$text-base单选框label文字大小
$un-radio-label-text-color$text-color单选框label文字颜色
$un-radio-label-disabled-color$text-color-disabled单选框label禁用时文字颜色

提示

组件内部默认使用 scss 变量，如需修改，请查看 scss 变量使用 文档

Copyright © 2026 uView Next