Selectboxes 选择框

选择框（Selectboxes）以卡片/按钮式布局展示选项，支持单选（Radio）和多选（Checkbox）模式，样式简洁直观。

基础用法（单选）

通过 v-model 实现双向绑定，默认单次只能选中一项。

<TSelectboxes v-model="selected">
  <TSelectboxItem value="apple" label="苹果" />
  <TSelectboxItem value="banana" label="香蕉" />
  <TSelectboxItem value="orange" label="橙子" />
</TSelectboxes>

多选模式

设置 multiple 切换为多选（Checkbox）模式，可同时选中多项，值类型为数组。

<TSelectboxes v-model="selectedMulti" multiple>
  <TSelectboxItem value="vue" label="Vue" />
  <TSelectboxItem value="react" label="React" />
  <TSelectboxItem value="svelte" label="Svelte" />
  <TSelectboxItem value="angular" label="Angular" />
</TSelectboxes>

Pill 胶囊样式

设置 pill 属性切换为胶囊样式，选项更紧凑圆润。

<TSelectboxes v-model="selectedTag" pill>
  <TSelectboxItem value="design" label="设计" />
  <TSelectboxItem value="frontend" label="前端" />
  <TSelectboxItem value="backend" label="后端" />
  <TSelectboxItem value="devops" label="运维" />
</TSelectboxes>

图标自定义（插槽）

通过 default 插槽自定义每个选项的内容，支持图标、富文本等。

<TSelectboxes v-model="selectedPlatform">
  <TSelectboxItem value="ios">
    <span class="d-inline-flex align-items-center gap-2">
      <IconBrandApple :size="16" />
      <span>iOS</span>
    </span>
  </TSelectboxItem>
  <!-- ... -->
</TSelectboxes>

Options 数组生成

通过 options 属性传入字符串或对象数组，自动生成 TSelectboxItem 子组件，无需手动编写。

<TSelectboxes v-model="selected" :options="[
  { label: 'A', value: 'a' },
]" />

网格列布局

通过 cols 属性控制每行列数，选项自动等分排列。

<TSelectboxes v-model="selected" :options="options" :cols="4" />

选项图标 & 描述

options 对象支持 icon（图标组件）、description（描述文字）、image（图片）、color（颜色类）字段。

<TSelectboxes v-model="selected" :options="[
  { label: '免费版', value: 'free', description: '基础功能', icon: IconStar },
]" />

Boxes 垂直卡片（支付方式）

设置 boxes 属性切换为垂直卡片布局，每个选项独立成行，适合展示支付方式等富内容。

查看代码

<TSelectboxes v-model="selected" boxes>
  <TSelectboxItem value="visa">
    <div>
      <span class="fw-bold">Visa</span>
      <br />
      <span class="text-secondary">ending in <strong>7998</strong></span>
    </div>
  </TSelectboxItem>
  <TSelectboxItem value="mastercard">
    <div>
      <span class="fw-bold">Mastercard</span>
      <br />
      <span class="text-secondary">ending in <strong>2807</strong></span>
    </div>
  </TSelectboxItem>
  <TSelectboxItem value="paypal">
    <span class="fw-bold">PayPal</span>
  </TSelectboxItem>
</TSelectboxes>

API

TSelectboxes 属性 (Props)

属性名	说明	类型	默认值
v-model	绑定值（单选时为任意类型，多选时为数组）	any | any[]	undefined
multiple	多选模式（Checkbox）	boolean	false
pill	Pill 胶囊样式	boolean	false
boxes	垂直卡片样式	boolean	false
disabled	全部禁用	boolean	false
name	原生 name 属性	string	undefined
cols	每行显示列数（非 boxes 模式）	number	undefined
options	选项数组（字符串或对象），自动生成子项	(string | SelectOption)[]	undefined

SelectOption

字段	类型	说明
label	string	标签文本
value	any	选项值（默认同 label）
disabled	boolean	禁用该项
description	string	描述文字（灰色小字）
icon	Component | object	图标组件
image	string	图片 URL
color	string	颜色类名（如 'red'、'green'）

TSelectboxes 事件 (Emits)

事件名	说明	回调参数
update:modelValue	v-model 值变化时触发	(value: any | any[]) => void
change	选中值变化时触发	(value: any | any[]) => void

TSelectboxItem 属性 (Props)

属性名	说明	类型	默认值
value	选项值	any	—
label	标签文本	string	undefined
disabled	禁用该项	boolean	false
description	描述文字	string	undefined
icon	图标组件	Component | object	undefined
image	图片 URL	string	undefined
color	颜色类名	string	undefined

TSelectboxes 插槽 (Slots)

插槽名	说明	作用域参数
default	自定义子项（当未设置 options 时）	—
option	自定义选项标签（当设置了 options 时）	{ option: SelectOption, checked: boolean }

TSelectboxItem 插槽 (Slots)

插槽名	说明
default	自定义选项内容（替代 label 属性）