Tuff
|Docs
组件/FlatRadio 平铺选择器

FlatRadio 平铺选择器

在 2–5 个选项间平铺选择的分段控件

已验证自 0.3.4

用法

基础

示例加载中...

禁用

disabled 可设在整组或单项上。

示例加载中...

尺寸

size 可选 sm、md（默认）、lg、xl。

示例加载中...

图标

icon 接收图标 class，例如 UnoCSS 图标。

示例加载中...

边框

示例加载中...

多选

multiple 时值为数组，各项像复选框一样切换，不显示滑块。

示例加载中...

键盘导航

容器获得焦点后响应下表按键。

示例加载中...
按键行为
→ / ↓下一个非禁用项（循环）
← / ↑上一个非禁用项（循环）
Home第一个非禁用项
End最后一个非禁用项
Enter / Space多选时切换当前项

最佳实践

  • 用于 2–5 个需要直接比较的短选项（标签不换行）；更多选项用 TxSelect。
  • 页面上的主选择用 xl；行内与工具栏保持默认 md。
  • 自定义插槽内容不要只在选中时加粗：每一项本就带选中字重，再加粗会引起重排。
  • 只有各值相互独立时才用 multiple；否则用开关或复选框。
  • value 在渲染间保持稳定：父级按 value 注册项，用于滑块定位与键盘顺序。

API 参考

TxFlatRadio

属性

属性名类型默认值说明
modelValue / v-modelstring | number | (string | number)[]必填单选为单值，多选为数组。
multiplebooleanfalse多选：各项像复选框一样切换，不显示滑块。
disabledbooleanfalse禁用整组，移出 Tab 序列并阻止变更。
size'sm' | 'md' | 'lg' | 'xl''md'尺寸。
borderedbooleanfalse添加外边框。

事件

事件名参数说明
update:modelValue(value: string | number | (string | number)[]) => void选择变化后触发，参数为新值。
change(value: string | number | (string | number)[]) => void与 update:modelValue 同时触发。

插槽

插槽名说明
defaultTxFlatRadioItem 子项。

TxFlatRadioItem

属性

属性名类型默认值说明
valuestring | number必填项的值，注册到父级。
labelstring-无默认插槽时显示的文本。
iconstring-无 icon 插槽时使用的图标 class。
disabledbooleanfalse禁用该项，键盘导航时跳过。

插槽

插槽名说明
default自定义内容，替代 label。
icon自定义图标，替代 icon。

概述

  • 单选时容器为 role="radiogroup"、项为 role="radio"；多选时为 role="group" 与 role="checkbox"。
  • 只有容器进入 Tab 序列，项保持 tabindex="-1"；用相邻字段文案或外部 label 为整组命名。
  • 单选时方向键直接选中；多选时方向键只移动焦点，Enter / Space 切换。
  • 滑块从不缩放：挂载、尺寸变化与注册新项时直接落位，选中新项时滑过去，两端不越出轨道。
  • 按压只缩放文字与图标，不缩放项本身。
  • 减少动态效果时，滑块直接落位并去掉按压缩放，保留淡入。

技术实现

  • 滑块由共享的 useJellyIndicator 滑行材质驱动（与 TxTabs、TxTabBar、TxSidebarNav 相同），每帧直接写 transform、width、opacity，不触发重渲染。
  • 源码：packages/tuffex/packages/components/src/flat-radio/。
查看源码
packages/tuffex/packages/components/src/flat-radio/index.ts

自定义

CSS 变量用途
--tx-flat-radio-track-bg轨道底色，默认 --tx-fill-color。
--tx-flat-radio-indicator-bg滑块与多选项底色，默认 --tx-surface-raised。
--tx-flat-radio-indicator-shadow滑块投影。