FxSegmented 分段控制器

展示多个选项并允许用户选择其一。不依赖任何 UI 框架，选中项带滑动高亮指示，颜色走 @fx/styles 的 --color-* token，亮暗自动跟随。

基础用法

用 v-model 绑定当前选中项的值，options 为选项数组（基础类型或对象）。

<template>
  <div>
    <FxSegmented v-model="value" :options="options" />
    <div class="value">当前值：{{ value }}</div>
  </div>
</template>

<script setup lang="ts">
import { ref } from "vue"

const value = ref("周一")
const options = ["周一", "周二", "周三", "周四", "周五", "周六", "周日"]
</script>

<style scoped>
.value {
  margin-top: 16px;
  font-size: 14px;
  color: var(--fx-text-color-secondary);
}
</style>

尺寸

通过 size 属性设置 large / default / small 三种尺寸。

<template>
  <div class="demo-size">
    <FxSegmented v-model="v1" :options="options" size="large" />
    <FxSegmented v-model="v2" :options="options" />
    <FxSegmented v-model="v3" :options="options" size="small" />
  </div>
</template>

<script setup lang="ts">
import { ref } from "vue"

const v1 = ref("周一")
const v2 = ref("周一")
const v3 = ref("周一")
const options = ["周一", "周二", "周三", "周四", "周五"]
</script>

<style scoped>
.demo-size {
  display: flex;
  flex-direction: column;
  align-items: flex-start;
  gap: 16px;
}
</style>

排列方向

通过 direction 设置 horizontal（水平，默认）或 vertical（垂直）。

<template>
  <div class="demo-direction">
    <div class="control">
      <FxSegmented v-model="size" :options="sizeOptions" />
      <FxSegmented v-model="direction" :options="directionOptions" />
    </div>
    <FxSegmented
      v-model="value"
      :options="options"
      :direction="direction"
      :size="size"
    >
      <template #default="{ item }: { item: OptionItem }">
        <div
          :class="[
            'custom-item',
            direction === 'horizontal' && 'is-horizontal',
          ]"
        >
          <FxIcon :name="item.icon" :size="20" />
          <span>{{ item.label }}</span>
        </div>
      </template>
    </FxSegmented>
  </div>
</template>

<script setup lang="ts">
import { ref } from "vue"

interface OptionItem {
  label: string
  value: string
  icon: string
  disabled?: boolean
}

const value = ref("desktop")
const direction = ref<"horizontal" | "vertical">("horizontal")
const size = ref<"large" | "default" | "small">("default")

const directionOptions = [
  { label: "水平", value: "horizontal" },
  { label: "垂直", value: "vertical" },
]
const sizeOptions = ["large", "default", "small"]

const options: OptionItem[] = [
  { label: "桌面", value: "desktop", icon: "ep:monitor" },
  { label: "应用", value: "app", icon: "ep:grid" },
  { label: "文档", value: "doc", icon: "ep:document" },
  { label: "通知", value: "notify", icon: "ep:bell" },
  { label: "日程", value: "calendar", icon: "ep:calendar" },
  { label: "设置aaaaa", value: "setting", icon: "ep:setting", disabled: true },
]
</script>

<style scoped>
.demo-direction {
  display: flex;
  flex-direction: column;
  align-items: flex-start;
  gap: 16px;
}
.control {
  display: flex;
  gap: 16px;
  align-items: center;
}
.custom-item {
  display: flex;
  flex-direction: column;
  align-items: center;
  gap: 8px;
}
.custom-item.is-horizontal {
  padding: 8px;
}
</style>

禁用

将分段控制器整体 disabled，或单独设置某个选项的 disabled 为 true。

<template>
  <div class="demo-disabled">
    <FxSegmented v-model="value" :options="options" disabled />
    <FxSegmented v-model="value" :options="options" />
  </div>
</template>

<script setup lang="ts">
import { ref } from "vue"

const value = ref("周二")
const options = [
  { label: "周一", value: "周一", disabled: true },
  { label: "周二", value: "周二" },
  { label: "周三", value: "周三", disabled: true },
  { label: "周四", value: "周四" },
  { label: "周五", value: "周五", disabled: true },
  { label: "周六", value: "周六" },
  { label: "周日", value: "周日" },
]
</script>

<style scoped>
.demo-disabled {
  display: flex;
  flex-direction: column;
  gap: 16px;
  align-items: flex-start;
}
</style>

自定义别名

当 options 的字段名与默认（value / label / disabled）不同时，可通过 props 属性配置别名。

<template>
  <FxSegmented v-model="value" :options="options" :props="aliasProps" />
</template>

<script setup lang="ts">
import { ref } from "vue"

const value = ref("周一")

// 当 options 的字段名与默认（value / label / disabled）不同时，
// 通过 props 配置别名
const aliasProps = {
  label: "myLabel",
  value: "myValue",
  disabled: "myDisabled",
}

const options = [
  { myLabel: "周一", myValue: "周一", myDisabled: true },
  { myLabel: "周二", myValue: "周二" },
  { myLabel: "周三", myValue: "周三", myDisabled: true },
  { myLabel: "周四", myValue: "周四" },
  { myLabel: "周五", myValue: "周五", myDisabled: true },
  { myLabel: "周六", myValue: "周六" },
  { myLabel: "周日", myValue: "周日" },
]
</script>

撑满父容器

设置 block 为 true 时，分段控制器宽度撑满父元素，各项均分宽度。

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

<script setup lang="ts">
import { ref } from "vue"

const value = ref("周一")
const options = [
  "周一",
  "周二",
  "周三",
  "周四",
  "周五",
  "周六",
  "周日（演示超长文本被省略号截断的 block 撑满模式）",
]
</script>

自定义内容

通过默认插槽自定义选项渲染，插槽作用域提供当前选项对象 item。

<template>
  <FxSegmented v-model="value" :options="options">
    <template #default="{ item }: { item: OptionItem }">
      <div class="custom-item">
        <FxIcon :name="item.icon" :size="20" />
        <span>{{ item.label }}</span>
      </div>
    </template>
  </FxSegmented>
</template>

<script setup lang="ts">
import { ref } from "vue"

interface OptionItem {
  label: string
  value: string
  icon: string
}

const value = ref("desktop")
const options: OptionItem[] = [
  { label: "桌面", value: "desktop", icon: "ep:monitor" },
  { label: "应用", value: "app", icon: "ep:grid" },
  { label: "文档", value: "doc", icon: "ep:document" },
  { label: "通知", value: "notify", icon: "ep:bell" },
  { label: "日程", value: "calendar", icon: "ep:calendar" },
  { label: "设置", value: "setting", icon: "ep:setting" },
]
</script>

<style scoped>
.custom-item {
  display: flex;
  flex-direction: column;
  align-items: center;
  gap: 8px;
  padding: 8px;
}
</style>

自定义样式

通过覆盖组件暴露的 CSS 变量自定义样式（如选中项颜色、圆角等）。

<template>
  <div class="custom-style">
    <FxSegmented v-model="value" :options="options" />
  </div>
</template>

<script setup lang="ts">
import { ref } from "vue"

const value = ref("美食")
const options = ["美食", "甜品饮品", "生鲜果蔬", "超市便利"]
</script>

<style scoped>
/* 通过覆盖 FxSegmented 的 CSS 变量自定义样式 */
.custom-style :deep(.fx-segmented) {
  --fx-segmented-item-selected-color: var(--fx-color-white);
  --fx-segmented-item-selected-bg-color: var(--fx-color-warning);
  --fx-segmented-border-radius: var(--fx-border-radius-2xl);
}
</style>

API

Attributes

属性	说明	类型	默认值
model-value (v-model)	绑定值	string / number / boolean	—
options	选项数据	Option[]	[]
props	别名配置，见下表	object	见下表
size	尺寸	'large' | 'default' | 'small'	—
block	是否撑满父容器宽度	boolean	false
disabled	是否禁用	boolean	false
validate-event	是否在值变化时触发表单项校验	boolean	true
name	原生 name（radio 分组名，未传则自动生成）	string	—
id	原生 id	string	—
aria-label	原生 aria-label	string	—
direction	排列方向	'horizontal' | 'vertical'	horizontal

自定义别名

props 属性的配置项，用于指定对象选项中取值 / 标签 / 禁用标记对应的字段名。

属性	说明	类型	默认值
value	用作选项值的字段名	string	value
label	用作选项标签的字段名	string	label
disabled	用作禁用标记的字段名	string	disabled

Events

事件名	说明	类型
update:model-value	值更新时触发	(value: string | number | boolean) => void
change	选中值变化时触发，参数为当前值	(value: string | number | boolean) => void

Slots

插槽名	说明	类型
default	自定义选项内容	{ item: Option }

类型声明

展开查看

type Option = Record<string, any> | string | number | boolean