TinyVue Radio单选框组件使用指南

如果超人不会飞2026-06-10 9:50

TinyVue Radio 单选框组件使用指南

组件介绍

Radio（单选框）是表单中常用的选择组件，用于在一组互斥选项中选择一个。TinyVue 提供了完整的单选框体系，包括 Radio（单选框）、RadioGroup（单选框组）和 RadioButton（按钮式单选框）三个组件，支持配置式渲染、垂直布局、自定义颜色、只读态等特性。

引入方式：

js 复制代码 
import { TinyRadio, TinyRadioGroup, TinyRadioButton } from '@opentiny/vue'

基本用法

通过 v-model 绑定变量，变量值对应 label 属性的值，相同则选中：

vue 复制代码 
<template>
  <div>
    <tiny-radio v-model="value" label="1">选项一</tiny-radio>
    <tiny-radio v-model="value" label="2">选项二</tiny-radio>
  </div>
</template>

<script setup>
import { ref } from 'vue'
import { TinyRadio } from '@opentiny/vue'

const value = ref('1')
</script>

单选框组

RadioGroup 将多个 Radio 或 RadioButton 组合起来，通过 v-model 统一绑定选中值：

vue 复制代码 
<template>
  <div>
    <!-- 普通单选框组 -->
    <tiny-radio-group v-model="value">
      <tiny-radio label="1">备选项 1</tiny-radio>
      <tiny-radio label="2">备选项 2</tiny-radio>
      <tiny-radio label="3">备选项 3</tiny-radio>
    </tiny-radio-group>

    <!-- 按钮式单选框组 -->
    <tiny-radio-group v-model="value">
      <tiny-radio-button label="1">备选项 1</tiny-radio-button>
      <tiny-radio-button label="2">备选项 2</tiny-radio-button>
      <tiny-radio-button label="3">备选项 3</tiny-radio-button>
    </tiny-radio-group>
  </div>
</template>

<script setup>
import { ref } from 'vue'
import { TinyRadio, TinyRadioGroup, TinyRadioButton } from '@opentiny/vue'

const value = ref('1')
</script>

配置式单选组

通过 options 属性配置式渲染单选组，无需在标签中手动插入 Radio 元素。配合 type 属性可切换为按钮形式：

vue 复制代码 
<template>
  <div>
    <!-- 普通单选形式 -->
    <tiny-radio-group v-model="value" :options="options"></tiny-radio-group>

    <!-- 按钮形式 -->
    <tiny-radio-group v-model="value" type="button" :options="buttonOptions"></tiny-radio-group>
  </div>
</template>

<script setup>
import { ref } from 'vue'
import { TinyRadioGroup } from '@opentiny/vue'

const value = ref('A')
const options = ref([
  { label: 'A', text: '很好' },
  { label: 'B', text: '一般' }
])
const buttonOptions = ref([
  { label: 'A', text: '公交' },
  { label: 'B', text: '地铁' }
])
</script>

options 配置项类型 IRadioGroupOptions：

字段 类型 说明
label string 选中时对应的值
text string 描述文本
events { click?, change? } 原生事件回调

禁用状态

通过 disabled 属性禁用单个单选框或整组：

vue 复制代码 
<template>
  <div>
    <!-- 禁用单个 -->
    <tiny-radio disabled v-model="radio" label="禁用">选中禁用</tiny-radio>
    <tiny-radio disabled v-model="radio" label="不选中">不选中禁用</tiny-radio>

    <!-- 禁用整组 -->
    <tiny-radio-group disabled v-model="radio1">
      <tiny-radio label="1">备选项 1</tiny-radio>
      <tiny-radio label="2">备选项 2</tiny-radio>
    </tiny-radio-group>

    <!-- 按钮组中单项禁用 -->
    <tiny-radio-group v-model="radio2">
      <tiny-radio-button disabled label="1">日度</tiny-radio-button>
      <tiny-radio-button label="2">月度</tiny-radio-button>
      <tiny-radio-button label="3">年度</tiny-radio-button>
    </tiny-radio-group>
  </div>
</template>

<script setup>
import { ref } from 'vue'
import { TinyRadio, TinyRadioButton, TinyRadioGroup } from '@opentiny/vue'

const radio = ref('禁用')
const radio1 = ref('1')
const radio2 = ref('2')
</script>

垂直布局

在 RadioGroup 上设置 vertical 属性，使单选框垂直排列：

vue 复制代码 
<template>
  <div>
    <!-- 普通单选框垂直 -->
    <tiny-radio-group v-model="value" vertical>
      <tiny-radio label="1">备选项 1</tiny-radio>
      <tiny-radio label="2">备选项 2</tiny-radio>
      <tiny-radio label="3">备选项 3</tiny-radio>
    </tiny-radio-group>

    <!-- 按钮式单选框垂直 -->
    <tiny-radio-group v-model="value" vertical>
      <tiny-radio-button label="1">备选项 1</tiny-radio-button>
      <tiny-radio-button label="2">备选项 2</tiny-radio-button>
      <tiny-radio-button label="3">备选项 3</tiny-radio-button>
    </tiny-radio-group>
  </div>
</template>

<script setup>
import { ref } from 'vue'
import { TinyRadio, TinyRadioGroup, TinyRadioButton } from '@opentiny/vue'

const value = ref('1')
</script>

自定义颜色

通过 RadioGroup 的 fill 属性设置按钮选中时的背景和边框颜色，text-color 设置选中时的文本颜色：

vue 复制代码 
<template>
  <tiny-radio-group v-model="value" fill="#fa9841" text-color="#fff">
    <tiny-radio-button label="1">日度</tiny-radio-button>
    <tiny-radio-button label="2">月度</tiny-radio-button>
    <tiny-radio-button label="3">年度</tiny-radio-button>
  </tiny-radio-group>
</template>

<script setup>
import { ref } from 'vue'
import { TinyRadioButton, TinyRadioGroup } from '@opentiny/vue'

const value = ref('1')
</script>

尺寸

对按钮形式的单选框，通过 RadioGroup 的 size 属性设置尺寸，可选值：medium、small、mini：

vue 复制代码 
<template>
  <div>
    <tiny-radio-group v-model="value" size="medium">
      <tiny-radio-button label="1">选项一</tiny-radio-button>
      <tiny-radio-button label="2">选项二</tiny-radio-button>
    </tiny-radio-group>

    <tiny-radio-group v-model="value" size="small">
      <tiny-radio-button label="1">选项一</tiny-radio-button>
      <tiny-radio-button label="2">选项二</tiny-radio-button>
    </tiny-radio-group>

    <tiny-radio-group v-model="value" size="mini">
      <tiny-radio-button label="1">选项一</tiny-radio-button>
      <tiny-radio-button label="2">选项二</tiny-radio-button>
    </tiny-radio-group>
  </div>
</template>

<script setup>
import { ref } from 'vue'
import { TinyRadioButton, TinyRadioGroup } from '@opentiny/vue'

const value = ref('1')
</script>

文字内容

单选框的描述文本有三种提供方式，优先级依次为：默认插槽 > text 属性 > label 属性：

vue 复制代码 
<template>
  <div>
    <!-- 使用默认插槽（优先级最高） -->
    <tiny-radio v-model="value" label="1" text="1">选项一</tiny-radio>

    <!-- 使用 text 属性 -->
    <tiny-radio v-model="value" label="2" text="选项二"></tiny-radio>

    <!-- 使用 label 作为文字 -->
    <tiny-radio v-model="value" label="3"></tiny-radio>
  </div>
</template>

<script setup>
import { ref } from 'vue'
import { TinyRadio } from '@opentiny/vue'

const value = ref('1')
</script>

默认插槽

通过默认插槽自定义单选框的描述内容，支持富文本和自定义样式：

vue 复制代码 
<template>
  <div>
    <tiny-radio v-model="value" label="1">
      <span style="color: #fa9841;">内容一：</span>
      <span>选项描述</span>
    </tiny-radio>
    <tiny-radio v-model="value" label="2">
      <span style="color: #fa9841;">内容二：</span>
      <span>选项描述</span>
    </tiny-radio>
  </div>
</template>

<script setup>
import { ref } from 'vue'
import { TinyRadio } from '@opentiny/vue'

const value = ref('1')
</script>

事件

在 Radio 或 RadioGroup 上监听 change 事件，当绑定值变化时触发：

vue 复制代码 
<template>
  <div>
    <!-- 单个 Radio 事件 -->
    <tiny-radio v-model="value" label="1" @change="onChange">选项一</tiny-radio>
    <tiny-radio v-model="value" label="2" @change="onChange">选项二</tiny-radio>

    <!-- RadioGroup 事件 -->
    <tiny-radio-group v-model="radio" @change="onChange">
      <tiny-radio-button label="1">日度</tiny-radio-button>
      <tiny-radio-button label="2">月度</tiny-radio-button>
      <tiny-radio-button label="3">年度</tiny-radio-button>
    </tiny-radio-group>
  </div>
</template>

<script setup>
import { ref } from 'vue'
import { TinyRadio, TinyRadioButton, TinyRadioGroup } from '@opentiny/vue'

const value = ref('1')
const radio = ref('1')

function onChange(label) {
  console.log('选中的 label 值为：', label)
}
</script>

只读态

通过 display-only 属性开启只读模式，适用于详情页等非编辑场景：

vue 复制代码 
<template>
  <div>
    <!-- 单选组只读 -->
    <tiny-radio-group display-only v-model="value" :options="options"></tiny-radio-group>

    <!-- 单个单选框只读 -->
    <tiny-radio display-only v-model="value" label="1">选项一</tiny-radio>
    <tiny-radio display-only v-model="value" label="2" text="选项二"></tiny-radio>
  </div>
</template>

<script setup>
import { ref } from 'vue'
import { TinyRadio, TinyRadioGroup } from '@opentiny/vue'

const value = ref('1')
const options = ref([
  { label: 'A', text: '很好' },
  { label: 'B', text: '一般' }
])
</script>

API 参考

Radio Props

属性名 类型 默认值 说明
disabled boolean false 是否禁用
display-only boolean false 是否只读状态
label `boolean number string`
modelValue / v-model `boolean number string`
name string - 原生 name 属性
tabindex string - tabindex，默认值为 1
text string - 单选框文本内容

Radio Events

事件名 回调参数 说明
change `(value: boolean number

Radio Slots

插槽名 说明
default 自定义单选框内容

RadioGroup Props

属性名 类型 默认值 说明
disabled boolean false 是否禁用整组
display-only boolean false 是否只读状态
fill string - 按钮选中时的背景颜色
modelValue / v-model `string[] number[]` -
options IRadioGroupOptions[] - 配置式单选组列表
size `'medium' 'small' 'mini'`
text-color string - 按钮选中时的文本颜色
type `'radio' 'button'` 'radio'
vertical boolean false 是否垂直排列

RadioGroup Events

事件名 回调参数 说明
change `(value: number[] string[])`

RadioGroup Slots

插槽名 说明
default 单选框组内容

RadioButton Props

属性名 类型 默认值 说明
disabled boolean false 是否禁用
label `boolean number string`
name string - 原生 name 属性
text string - 单选框文本内容

RadioButton Slots

插槽名 说明
default 自定义按钮内容

最佳实践

  1. 优先使用 RadioGroup ：单选场景始终使用 RadioGroup 包裹，通过 v-model 统一管理选中值，避免多个独立 Radio 手动同步状态。

  2. 配置式优于插槽式 ：当选项数据来自接口或配置时，使用 options 属性配置式渲染，代码更简洁、更易维护。

  3. 按钮形式用于工具栏：RadioButton 适合工具栏、切换面板等场景（如日度/月度/年度切换）；普通 Radio 适合表单、设置项等场景。

  4. 垂直布局节省空间 ：选项较多或水平空间有限时，使用 vertical 垂直排列，避免水平溢出。

  5. 自定义颜色统一品牌 ：使用 fill 和 text-color 统一按钮式单选框的选中颜色，保持品牌一致性。

  6. 只读态替代禁用 ：详情页等非编辑场景，使用 display-only 替代 disabled，视觉上更清晰地传达"只读"语义。

  7. label 值保持唯一 ：同一 RadioGroup 内各 Radio 的 label 值必须唯一，否则会导致选中状态异常。

  8. 事件处理注意值类型 ：change 事件回调参数为 label 的值，注意与 v-model 绑定值的类型保持一致（同为 string 或同为 number）。

OpenTiny NEXT 是一套企业智能前端开发解决方案，以生成式 UI 和 WebMCP 两大核心技术为基础，对现有传统的 TinyVue 组件库、TinyEngine 低代码引擎等产品进行智能化升级，构建出面向 Agent 应用的前端 NEXT-SDKs、AI Extension、TinyRobot智能助手、GenUI等新产品，实现AI理解用户意图自主完成任务，加速企业应用的智能化改造。

相关推荐
鲁班小子1 小时前
Vite resolve.dedupe 使用教程
vue.js·vite
如果超人不会飞1 小时前
TinyVue Input输入框组件使用指南
vue.js
如果超人不会飞2 小时前
TinyVue Pager分页组件使用指南
前端·vue.js
大刚测试开发实战2 小时前
TestHub重磅更新！AI用例生成增加流式输出、Markdown文档上传、模型配置检测、AI评审开关控制...
vue.js·后端·github
可别3902 小时前
Vue 极简实现语音实时转写（录音转文字，低网络依赖、开箱即用）
前端·javascript·vue.js
阿猫的故乡3 小时前
Vue插槽从入门到项目实战：默认插槽、具名插槽、作用域插槽，一次讲明白
前端·javascript·vue.js
向日的葵0063 小时前
vue3路由的replace属性（四）
前端·javascript·vue.js·vue路由
阿猫的故乡3 小时前
Vue模板引用和组件暴露：ref拿DOM、defineExpose调方法，案例多到眼花
前端·javascript·vue.js
薛定谔的猫-菜鸟程序员3 小时前
从Electron到Tauri，Rust+Vue(Tauri) 实现超高性能桌面日志应用开发，以及开发避坑指南
vue.js·rust·electron
热门推荐
01【AI】2026 年具身智能模型和世界模型总结02GitHub 镜像站点03Codex 下载安装指南：Windows 和 macOS 官方版下载042026 年 AI 编程工具终极横评：Cursor vs Claude Code vs Copilot vs Windsurf052026 AI 编程工具终极实战指南：Cursor vs Claude Code vs Copilot，开发者该怎么选？06AI科技热点日报 | 2026年6月1日07【踩坑记录 | 第一篇】微软商店无法使用时，如何手动安装 OpenAI Codex？附`.msix`文件系统错误解决方法08《置身钉内》原文-可播放阅读09CC-Switch 下载、安装与使用配置指南【2026.5.29】10Agnes AI 全模态 API 免费实测报告：文生图 + 文生视频完整测试