Radio 单选框 - Vant 4

🔘 Radio 单选框

🎯 介绍

Radio 组件用于在一组备选项中进行单选，支持垂直/水平排列、禁用、图标定制等能力，常用于表单选择场景。

📦 引入

通过以下方式来全局注册组件，更多注册方式请参考组件注册。

import { createApp } from'vue'; import { RadioGroup, Radio } from'vant'; const app = createApp(); app.use(Radio); app.use(RadioGroup);

🎯 代码演示

🔧 基础用法

最简单的单选框使用方式！通过 v-model 绑定当前选中项的 name，让用户在多个选项中做出唯一选择。

html

<template>
  <van-radio-group v-model="checked">
    <van-radio name="1">单选框 1</van-radio>
    <van-radio name="2">单选框 2</van-radio>
  </van-radio-group>
</template>

<script>
import { ref } from 'vue';

export default {
  setup() {
    const checked = ref('1');
    return { checked };
  },
};
</script>

↔️ 水平排列

想让单选框横着排列？将 direction 属性设置为 horizontal，瞬间变身水平布局，特别适合选项较少的场景！

html

<template>
  <van-radio-group v-model="checked" direction="horizontal">
    <van-radio name="1">单选框 1</van-radio>
    <van-radio name="2">单选框 2</van-radio>
  </van-radio-group>
</template>

<script>
import { ref } from 'vue';

export default {
  setup() {
    const checked = ref('1');
    return { checked };
  },
};
</script>

🚫 禁用状态

有些选项暂时不可用？通过 disabled 属性轻松禁用整个组或单个选项，给用户清晰的视觉反馈。

html

<template>
  <van-radio-group v-model="checked" disabled>
    <van-radio name="1">单选框 1</van-radio>
    <van-radio name="2">单选框 2</van-radio>
  </van-radio-group>

  <van-radio-group v-model="checked2">
    <van-radio name="1">单选框 1</van-radio>
    <van-radio name="2" disabled>单选框 2</van-radio>
  </van-radio-group>
</template>

<script>
import { ref } from 'vue';

export default {
  setup() {
    const checked = ref('1');
    const checked2 = ref('1');
    return { checked, checked2 };
  },
};
</script>

🔲 自定义形状

厌倦了圆形？试试方形或圆点形状！shape 属性支持 square（方形）和 dot（圆点），让你的界面更有个性。

html

<template>
  <van-radio-group v-model="checked">
    <van-radio name="1" shape="square">方形</van-radio>
    <van-radio name="2" shape="dot">圆点形</van-radio>
  </van-radio-group>
</template>

<script>
import { ref } from 'vue';

export default {
  setup() {
    const checked = ref('1');
    return { checked };
  },
};
</script>

🎨 自定义颜色

想要品牌色？通过 checked-color 属性设置选中状态的颜色，让单选框完美融入你的设计风格！

html

<template>
  <van-radio-group v-model="checked">
    <van-radio name="1" checked-color="#ee0a24">红色</van-radio>
    <van-radio name="2" checked-color="#07c160">绿色</van-radio>
  </van-radio-group>
</template>

<script>
import { ref } from 'vue';

export default {
  setup() {
    const checked = ref('1');
    return { checked };
  },
};
</script>

📏 自定义大小

图标太小看不清？通过 icon-size 属性调整图标大小，支持数字和字符串格式，满足不同场景需求。

html

<template>
  <van-radio-group v-model="checked">
    <van-radio name="1" icon-size="24px">大号图标</van-radio>
    <van-radio name="2" icon-size="16px">小号图标</van-radio>
  </van-radio-group>
</template>

<script>
import { ref } from 'vue';

export default {
  setup() {
    const checked = ref('1');
    return { checked };
  },
};
</script>

🖼️ 自定义图标

想要更个性化的图标？通过 icon 插槽自定义图标，配合 slotProps 判断选中状态，打造独一无二的选择体验！

html

<template>
  <van-radio-group v-model="checked">
    <van-radio name="1">
      <template #icon="props">
        <img :src="props.checked ? activeIcon : inactiveIcon" />
      </template>
      自定义图标
    </van-radio>
    <van-radio name="2">
      <template #icon="props">
        <van-icon :name="props.checked ? 'star' : 'star-o'" />
      </template>
      星星图标
    </van-radio>
  </van-radio-group>
</template>

<script>
import { ref } from 'vue';

export default {
  setup() {
    const checked = ref('1');
    return {
      checked,
      activeIcon: 'https://fastly.jsdelivr.net/npm/@vant/assets/user-active.png',
      inactiveIcon: 'https://fastly.jsdelivr.net/npm/@vant/assets/user-inactive.png',
    };
  },
};
</script>

⬅️ 左侧文本

想让文本显示在左边？将 label-position 属性设置为 left，文本瞬间移到单选框左侧，适合特殊布局需求。

html

<template>
  <van-radio-group v-model="checked">
    <van-radio name="1" label-position="left">左侧文本</van-radio>
    <van-radio name="2" label-position="left">左侧文本</van-radio>
  </van-radio-group>
</template>

<script>
import { ref } from 'vue';

export default {
  setup() {
    const checked = ref('1');
    return { checked };
  },
};
</script>

🚫 禁用文本点击

只想让用户点击图标？设置 label-disabled 属性后，点击文本不会触发选择，只有点击图标才有效果。

html

<template>
  <van-radio-group v-model="checked">
    <van-radio name="1" label-disabled>只能点击图标</van-radio>
    <van-radio name="2" label-disabled>只能点击图标</van-radio>
  </van-radio-group>
</template>

<script>
import { ref } from 'vue';

export default {
  setup() {
    const checked = ref('1');
    return { checked };
  },
};
</script>

📱 搭配单元格组件使用

想要更丰富的列表样式？搭配 Cell 组件使用，打造类似设置页面的选择列表，用户体验更佳！

html

<template>
  <van-radio-group v-model="checked">
    <van-cell-group>
      <van-cell title="单选框 1" clickable @click="checked = '1'">
        <template #right-icon>
          <van-radio name="1" />
        </template>
      </van-cell>
      <van-cell title="单选框 2" clickable @click="checked = '2'">
        <template #right-icon>
          <van-radio name="2" />
        </template>
      </van-cell>
    </van-cell-group>
  </van-radio-group>
</template>

<script>
import { ref } from 'vue';

export default {
  setup() {
    const checked = ref('1');
    return { checked };
  },
};
</script>

📋 API

Radio Props

参数	说明	类型	默认值
name	🏷️ 标识符，每个单选框的唯一身份证，通常为字符串或数字	any	-
shape	🔲 形状风格，`round`（圆形）、`square`（方形）、`dot`（圆点）	string	`round`
disabled	🚫 是否禁用，禁用后无法点击选择	boolean	`false`
label-disabled	🖱️ 是否禁用文本点击，开启后只能点击图标进行选择	boolean	`false`
label-position	📍 文本位置，`left`（左侧）或 `right`（右侧）	string	`right`
icon-size	📏 图标大小，支持数字和字符串，默认单位为 `px`	number \| string	`20px`
checked-color	🎨 选中状态的颜色，支持任何有效的 CSS 颜色值	string	`#1989fa`

RadioGroup Props

参数	说明	类型	默认值
v-model	🎯 当前选中项的标识符，双向绑定的核心	any	-
disabled	🚫 是否禁用所有单选框，一键禁用整个组	boolean	`false`
direction	📐 排列方向，`vertical`（垂直）或 `horizontal`（水平）	string	`vertical`
icon-size	📏 所有单选框的图标大小，统一设置更方便	number \| string	`20px`
checked-color	🎨 所有单选框的选中状态颜色，统一品牌色调	string	`#1989fa`
shape `v4.6.3`	🔲 所有单选框的形状，`round`、`square`、`dot`	string	`round`

Radio Events

事件名	说明	回调参数
click	🖱️ 点击单选框时触发，包括图标和文本区域	event: MouseEvent

RadioGroup Events

事件名	说明	回调参数
change	🔄 选中值变化时触发，监听用户的选择变化	name: string

Radio Slots

名称	说明	参数
default	📝 自定义文本内容，替换默认的文本显示	{ checked: boolean, disabled: boolean }
icon	🖼️ 自定义图标，打造个性化的选择样式	{ checked: boolean, disabled: boolean }

🔧 类型定义

组件导出以下类型定义，让 TypeScript 开发更加顺畅：

import type {
  RadioProps,
  RadioShape,
  RadioGroupProps,
  RadioLabelPosition,
  RadioGroupDirection,
} from 'vant';

🎨 主题定制

🎭 样式变量

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。

名称	默认值	描述
--van-radio-size	20px	📏 单选框图标的整体大小
--van-radio-dot-size	8px	🔘 圆点形状时内部圆点的大小
--van-radio-border-color	var(--van-gray-5)	🖼️ 未选中状态的边框颜色
--van-radio-duration	var(--van-duration-fast)	⏱️ 选中状态切换的动画时长
--van-radio-label-margin	var(--van-padding-xs)	📐 文本标签与图标之间的间距
--van-radio-label-color	var(--van-text-color)	🔤 文本标签的颜色
--van-radio-checked-icon-color	var(--van-primary-color)	✅ 选中状态图标的颜色
--van-radio-disabled-icon-color	var(--van-gray-5)	🚫 禁用状态图标的颜色
--van-radio-disabled-label-color	var(--van-text-color-3)	🔇 禁用状态文本的颜色
--van-radio-disabled-background	var(--van-border-color)	🎭 禁用状态的背景颜色

📚 相关文档

🔗 表单组件

Checkbox 复选框 - ☑️ 多选场景的最佳伙伴，支持全选、半选等高级功能
Field 输入框 - ✏️ 文本输入的核心组件，支持各种验证和格式化
Form 表单 - 📋 表单验证和数据收集的完整解决方案
Switch 开关 - 🔄 开关状态切换，适合设置页面的布尔值选择

🎯 选择器组件

Picker 选择器 - 🎡 滚轮式选择器，适合大量选项的单选或多选
Area 省市区选择 - 🗺️ 地区选择组件，支持省市区三级联动

🎨 交互组件

Button 按钮 - 🔘 各种样式的按钮组件，表单提交的好搭档
Cell 单元格 - 📱 列表展示组件，与单选框搭配使用效果更佳
ActionSheet 动作面板 - 📋 底部弹出的选择面板，移动端选择的经典方案

🛠️ 工具组件

ConfigProvider 全局配置 - ⚙️ 全局主题配置，一键定制组件样式
Toast 轻提示 - 💬 操作反馈提示，选择后的状态反馈

🔘 Radio 单选框 ​

🎯 介绍 ​

📦 引入 ​

🎯 代码演示 ​

🔧 基础用法 ​

↔️ 水平排列 ​

🚫 禁用状态 ​

🔲 自定义形状 ​

🎨 自定义颜色 ​

📏 自定义大小 ​

🖼️ 自定义图标 ​

⬅️ 左侧文本 ​

🚫 禁用文本点击 ​

📱 搭配单元格组件使用 ​

📋 API ​

Radio Props ​

RadioGroup Props ​

Radio Events ​

RadioGroup Events ​

Radio Slots ​

🔧 类型定义 ​

🎨 主题定制 ​

🎭 样式变量 ​

📚 相关文档 ​

🔗 表单组件 ​

🎯 选择器组件 ​

🎨 交互组件 ​

🛠️ 工具组件 ​

🔘 Radio 单选框

🎯 介绍

📦 引入

🎯 代码演示

🔧 基础用法

↔️ 水平排列

🚫 禁用状态

🔲 自定义形状

🎨 自定义颜色

📏 自定义大小

🖼️ 自定义图标

⬅️ 左侧文本

🚫 禁用文本点击

📱 搭配单元格组件使用

📋 API

Radio Props

RadioGroup Props

Radio Events

RadioGroup Events

Radio Slots

🔧 类型定义

🎨 主题定制

🎭 样式变量

📚 相关文档

🔗 表单组件

🎯 选择器组件

🎨 交互组件

🛠️ 工具组件