TechUI Docs

简中

EN

简中

EN

主题

单选框 ​

TuiRadio 用于在多个备选项中选中单个状态。 它提供了极高的定制自由度，支持常规单选、按钮组、卡片列表等多种形态，并支持水平或垂直布局。

基础用法 ​

数据驱动渲染 (Options) ​

最简单的用法是通过 options 属性传入配置数组。

  • options: 数组项需包含 label (显示文本) 和 value (绑定值)。
html
<script setup>
import { ref } from 'vue';

const value = ref(0);
const options = [
  { label: '备选项 1', value: 0 },
  { label: '备选项 2', value: 1 },
  { label: '禁用项', value: 2, disabled: true }
];
</script>

<template>
  <TuiRadio v-model="value" :options="options" />
</template>

插槽自定义渲染 (Slot) ​

使用 <TuiRadioItem> 子组件可以实现更复杂的布局。例如，在单选框中嵌入颜色块、图标或复杂的 HTML 结构。

html
<template>
  <TuiRadio v-model="color">
    <TuiRadioItem value="blue">
      <div style="width: 20px; height: 20px; background: blue;"></div>
    </TuiRadioItem>
    <TuiRadioItem value="red">
      <div style="width: 20px; height: 20px; background: red;"></div>
    </TuiRadioItem>
  </TuiRadio>
</template>

自定义内容 (Color Picker 示例) ​

通过设置 defaultIcon 为 false 隐藏默认的单选圆圈，并在 <TuiRadioItem> 内部通过插槽自定义渲染逻辑。 利用 CSS 的 .is-active 状态（组件自动添加），可以轻松实现“选中出现对勾”的交互效果。

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

const activeTheme = ref(0);

const themes = [
  { label: "LightBlue", colors: ['#409eff', '#ecf5ff'] },
  { label: "DarkMix", colors: ['#303133', '#909399'] },
  { label: "Forest", colors: ['#67c23a', '#e1f3d8'] },
];
</script>

<template>
  <TuiRadio v-model="activeTheme" :defaultIcon="false" class="theme-selector">
    <TuiRadioItem 
      v-for="(item, index) in themes" 
      :key="index" 
      :value="index" 
      class="theme-item"
    >
      <div class="color-view">
        <i class="tui-icon ti-check check-mark"></i>
        <div class="color-half" :style="{ backgroundColor: item.colors[0] }"></div>
        <div class="color-half" :style="{ backgroundColor: item.colors[1] }"></div>
      </div>
    </TuiRadioItem>
  </TuiRadio>
</template>

<style lang="less" scoped>
.theme-selector {
  .theme-item {
    margin-right: 12px;
    
    // TuiRadioItem 选中时会自动添加 .is-active 类名
    &.is-active {
      .check-mark { opacity: 1; transform: translate(-50%, -50%) scale(1); }
    }

    .color-view {
      position: relative;
      width: 40px;
      height: 40px;
      border-radius: 6px;
      overflow: hidden;
      cursor: pointer;
      box-shadow: 0 2px 4px rgba(0,0,0,0.1);
      
      .color-half {
        width: 100%;
        height: 50%;
      }

      .check-mark {
        position: absolute;
        left: 50%;
        top: 50%;
        transform: translate(-50%, -50%) scale(0.5);
        color: #fff;
        font-size: 20px;
        opacity: 0;
        transition: all 0.2s;
        text-shadow: 0 1px 2px rgba(0,0,0,0.2);
      }
    }
  }
}
</style>

外观风格 ​

通过 appearance 属性可以切换三种主流风格。

简约风格 (Simple) - 默认 ​

标准的单选框样式，带有圆形选中指示器。

html
<TuiRadio appearance="simple" :options="options" />

按钮风格 (Button) ​

实心按钮样式。选中时背景色填充，常用于工具栏或模式切换。 配合 separable 属性可控制按钮之间是否分离。

html
<template>
  <TuiRadio appearance="button" :options="options" />
  
  <TuiRadio appearance="button" separable :options="options" />
</template>

卡片风格 (ButtonPlain) ​

描边卡片样式。选中时边框高亮并带有浅色背景，适合选项较少但内容较长的场景。

html
<TuiRadio appearance="buttonPlain" :options="options" />

布局与方向 ​

垂直排列 ​

设置 direction="v" 可将选项垂直堆叠。

html
<TuiRadio direction="v" :options="options" />

文字方向 (TextDirection) ​

设置 textDirection="v" 可以让选项内的文字垂直排列（从上到下）。这在某些特殊的侧边栏设计中非常有用。

html
<TuiRadio direction="v" textDirection="v" :options="options" />

图标与装饰 ​

自定义图标 ​

TuiRadio 支持灵活的图标配置：

  • defaultIcon: 是否显示默认的圆形/对勾指示器（默认为 true）。
  • icon: 在选项数据或组件中传入图标。支持传入数组 ['未选中图标', '选中图标'] 来实现状态切换效果。
html
<script setup>
const iconOptions = [
  // 传入数组实现图标切换：[未选中, 选中]
  { label: '收藏', value: 1, icon: ['tui-icon ti-star', 'tui-icon tis-star'] },
  { label: '文件', value: 2, icon: 'tui-icon ti-file' }
];
</script>

<template>
  <TuiRadio 
    :defaultIcon="false" 
    appearance="buttonPlain" 
    :options="iconOptions" 
  />
</template>

尺寸 (Size) ​

支持 large, default, small 三种尺寸。

html
<TuiRadio size="small" :options="options" />
<TuiRadio size="default" :options="options" />
<TuiRadio size="large" :options="options" />

API 参考 ​

TuiRadio Props ​

属性名类型默认值说明
modelValueString/Number/Boolean-绑定值。
optionsArray[]数据源。
appearanceString'simple'外观风格。可选：simple, button, buttonPlain。
directionString'h'排列方向。可选：h (水平), v (垂直)。
sizeString'default'尺寸。可选：large, default, small。
defaultIconBooleantrue是否显示默认的单选指示图标（圆圈/对勾）。
separableBooleanfalse是否分离按钮（仅在 button/buttonPlain 模式下有效）。
alignStringnull内部内容对齐方式。可选：start, center, end。
textDirectionStringnull文本排列方向。可选：h, v。
itemMaxWidthNumber/String-单个选项的最大宽度。
disabledBooleanfalse是否禁用整个组件。
classNameString-自定义类名。

TuiRadio Events ​

事件名说明回调参数
update:modelValue绑定值变化时触发。(value)
change选中值变化时触发。(value)

TuiRadioItem Props ​

属性名类型默认值说明
valueString/Number/BooleanRequired选项的值。
iconString/Arraynull图标。可传字符串或 [inactive, active] 数组。
disabledBooleanfalse是否禁用该选项。