# Radio 单选框

单选框用于有一个选择,用户只能选择其中一个的场景。

# 基本使用

  • 该组件需要搭配 radioGroup 组件使用,以便用户进行操作时,获得当前单选框组的选中情况
  • 通过 v-modelradioGroup 组件绑定一个变量,对应的 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="ts">
import { ref } from 'vue'

// 定义RadioItem类型
type RadioItem = {
  name: string
  disabled: boolean
}

// 基本案例数据
const radioList1 = ref<RadioItem[]>([
  { name: '苹果', disabled: false },
  { name: '香蕉', disabled: false },
  { name: '橙子', disabled: false },
  { name: '榴莲', disabled: false }
])

// un-radio-group的v-model绑定的值如果设置为某个radio的name,就会被默认选中
const radioValue1 = ref<string>('苹果')

// 事件处理函数
const groupChange = (value: string | number) => {
  console.log('groupChange', value)
}

const radioChange = (value: string | number) => {
  console.log('radioChange', value)
}
</script>
✅ Copy success!

# 自定义形状

可以通过设置 shapesquare 或者 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="ts">
import { ref } from 'vue'

const shapeValue = ref<string>('月明人倚楼')
</script>
✅ Copy success!

# 禁用 radio

设置 disabledtrue,即可禁用某个组件,让用户无法点击

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

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

const disabledValue = ref<string>('明月几时有')
</script>
✅ Copy success!

# 是否禁止点击提示语选中单选框

设置 labelDisabledtrue,即可禁止点击提示语选中单选框

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

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

const labelDisabledValue = ref<string>('明月几时有')
</script>
✅ Copy success!

# 自定义颜色

此处所指的颜色,为 radio 选中时的背景颜色,参数为 activeColor

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

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

const colorValue = ref<string>('思悠悠,恨悠悠,恨到归时方始休')
</script>
✅ Copy success!

# 横向排列形式

可以通过设置 placementrow 或者 column,将复选框设置为横向排列或者竖向排列

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

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

const placementValue = ref<string>('思悠悠,恨悠悠,恨到归时方始休')
</script>
✅ Copy success!

# 横向两端排列形式

可以通过设置 iconPlacementleft 或者 right,将复选框勾选图标的对齐设置为左对齐或者右对齐

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

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

const iconPlacementValue = ref<string>('思悠悠,恨悠悠,恨到归时方始休')
</script>
✅ Copy success!

# API

# Radio Props

注意:radioradio-group 二者同名参数中,radio 的参数优先级更高。

参数 说明 类型 默认值 可选值
name radio的名称 string | number - -
shape 形状,square为方形,circle为圆型, button为按钮 string square circle | button
disabled 是否禁用 boolean - -
labelDisabled 是否禁止点击提示语选中单选框 boolean - -
activeColor 选中状态下的颜色,如设置此值,将会覆盖parent的activeColor值 string - -
inactiveColor 未选中的颜色 string - -
icon 图标 string - -
iconSize 图标的大小,单位px string | number - -
labelSize label的字体大小,px单位 string | number - -
label label提示文字,因为nvue下,直接slot进来的文字,由于特殊的结构,无法修改样式 string | number - -
size 整体的大小 string | number - -
iconColor 图标颜色 string - -
labelColor label的颜色 string - -
activeLabelColor 选中状态下label的颜色 string - -
plain 镂空样式 boolean true false

# RadioGroup Props

参数 说明 类型 默认值 可选值
modelValue 绑定的值 string | number | boolean - -
disabled 是否禁用全部radio boolean false true
shape 形状,circle-圆形,square-方形, button-按钮 string circle square | button
activeColor 选中状态下的颜色,如子Radio组件设置此值,将会覆盖本值 string #2979ff -
inactiveColor 未选中的颜色 string #c8c9cc -
name 标识符 string - -
size 整个组件的尺寸,默认px string | number 18 -
placement 布局方式,row-横向,column-纵向 string row column
label 文本 string - -
labelColor label的字体颜色 string #303133 -
labelSize label的字体大小,px单位 string | number 14 -
labelDisabled 是否禁止点击文本操作 boolean false true
iconColor 图标颜色 string #ffffff -
iconSize 图标的大小,单位px string | number 12 -
borderBottom 竖向排列时,是否显示下划线 boolean false true
iconPlacement 勾选图标的对齐方式,left-左边,right-右边 string left right
activeLabelColor 选中状态下label的颜色 string - -
plain 镂空样式 boolean true false

# Radio Slot

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

# Radio Event

事件名 说明 回调参数
change 某个radio状态发生变化时触发(选中状态) value: string | number

# RadioGroup Event

事件名 说明 回调参数
change 任一个radio状态发生变化时触发 value: string | number
上次更新时间: 2025/10/28 21:19:58
当前文档拷贝至3.x版本,尚不完善,我们正在努力完善中,欢迎您的反馈和参与改进。
×