Segmented 分段控制器

Segmented 分段控制器

分段控制器是一种用于在多个选项之间进行单选的控件，选中项会有滑块动画效果，类似 iOS 的分段选择器。

何时使用

  • 需要在少量选项之间快速切换时。
  • 选项数量固定且较少（通常 2-5 个）时。
  • 用于视图切换、数据筛选等场景。

导入

import { Segmented } from "@reglow/reui";
import type { SegmentedOption } from "@reglow/reui";

代码演示

基础用法

<script setup lang="ts">
import { ref } from "vue";
import { Segmented } from "@reglow/reui";

const value = ref("每日");
</script>

<template>
  <Segmented v-model="value" :options="['每日', '每周', '每月']" />
</template>

对象选项

使用 SegmentedOption 对象配置每个选项，可设置 label、disabled 等属性。

<script setup lang="ts">
import { ref } from "vue";
import { Segmented } from "@reglow/reui";
import type { SegmentedOption } from "@reglow/reui";

const value = ref("list");
const options: SegmentedOption[] = [
  { value: "list", label: "列表" },
  { value: "card", label: "卡片" },
  { value: "table", label: "表格", disabled: true },
];
</script>

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

数值选项

options 也支持数值类型。

<script setup lang="ts">
import { ref } from "vue";
import { Segmented } from "@reglow/reui";

const value = ref(1);
</script>

<template>
  <Segmented v-model="value" :options="[1, 2, 3]" />
</template>

带图标

通过 icon 属性为选项添加图标。

<script setup lang="ts">
import { ref, h } from "vue";
import { Segmented } from "@reglow/reui";
import { List, Grid, Table } from "lucide-vue-next";

const value = ref("list");
const options = [
  { value: "list", label: "列表", icon: h(List) },
  { value: "grid", label: "网格", icon: h(Grid) },
  { value: "table", label: "表格", icon: h(Table) },
];
</script>

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

尺寸

三种尺寸：small、default、large。

<template>
  <Segmented :options="['A', 'B', 'C']" size="small" />
  <Segmented :options="['A', 'B', 'C']" size="default" />
  <Segmented :options="['A', 'B', 'C']" size="large" />
</template>

圆角形状

设置 shape 为 round 显示为胶囊形。

<template>
  <Segmented :options="['每日', '每周', '每月']" shape="round" />
</template>

撑满父容器

设置 block 为 true 使组件宽度撑满父容器，选项均分宽度。

<template>
  <Segmented :options="['每日', '每周', '每月']" block />
</template>

禁用

disabled 禁用整个组件，也可在选项级别设置 disabled。

<script setup lang="ts">
import { ref } from "vue";
import { Segmented } from "@reglow/reui";

const value = ref("a");
</script>

<template>
  <!-- 禁用整个组件 -->
  <Segmented v-model="value" :options="['a', 'b', 'c']" disabled />

  <!-- 禁用单个选项 -->
  <Segmented
    v-model="value"
    :options="[
      { value: 'a', label: '选项A' },
      { value: 'b', label: '选项B（禁用）', disabled: true },
      { value: 'c', label: '选项C' },
    ]"
  />
</template>

受控用法

通过 v-model 双向绑定，监听 change 事件。

<script setup lang="ts">
import { ref } from "vue";
import { Segmented } from "@reglow/reui";

const value = ref("daily");

function handleChange(val: string) {
  console.log("切换到:", val);
}
</script>

<template>
  <Segmented
    v-model="value"
    :options="[
      { value: 'daily', label: '日' },
      { value: 'weekly', label: '周' },
      { value: 'monthly', label: '月' },
    ]"
    @change="handleChange"
  />
</template>

自定义渲染

通过 default 插槽自定义选项内容，或通过 label 插槽自定义标签渲染。

<script setup lang="ts">
import { ref } from "vue";
import { Segmented } from "@reglow/reui";

const value = ref("a");
</script>

<template>
  <!-- 使用 default 插槽完全自定义渲染 -->
  <Segmented v-model="value" :options="['a', 'b', 'c']">
    <template #default="{ option, index }">
      <span class="font-bold">{{ index + 1 }}. {{ option.label }}</span>
    </template>
  </Segmented>

  <!-- 使用 label 插槽自定义标签 -->
  <Segmented v-model="value" :options="['a', 'b', 'c']">
    <template #label="{ option }">
      <span class="uppercase">{{ option.label }}</span>
    </template>
  </Segmented>
</template>

API

Segmented Props

参数说明类型默认值
modelValue (v-model)当前选中值string | number-
defaultValue默认选中值（非受控）string | number第一项
options选项列表(SegmentedOption | string | number)[][]
disabled是否禁用整个组件booleanfalse
size尺寸'small' | 'default' | 'large''default'
block是否撑满父容器宽度booleanfalse
shape形状'default' | 'round''default'
class附加类名string-

Segmented Events

事件名说明回调参数
change选中值变化回调(value: string | number)
update:modelValue选中值变化（v-model）(value: string | number)

Segmented Slots

插槽名说明参数
default自定义选项内容（完全自定义）{ option: SegmentedOption, index: number }
label自定义标签渲染{ option: SegmentedOption }

SegmentedOption

参数说明类型默认值
value选项值（必填）string | number-
label选项文本string | VNode-
disabled是否禁用booleanfalse
icon图标VNode-
payload附加数据any-

键盘操作

按键说明
ArrowRight / ArrowDown切换到下一个选项
ArrowLeft / ArrowUp切换到上一个选项
Home切换到第一个选项
End切换到最后一个选项
Rate 评分
对事物进行评级的星形组件
Select 选择器
基于 reka-ui 的组合式选择器。选项较少时也可用 [Radio](/components-library/reui/components/data-entry/radio)。