SwSegmented

SwSegmented 是單選選項組（segmented / pill-group）：一組 { value, label } 選項平鋪全可見，點擊或方向鍵選中一個。受控 v-model，選中變化 emit update:modelValue。

薄殼套 reka-ui 的 RadioGroup，方向鍵 roving tabindex 無障礙（← → / Home End 在選項間移動並選中）開箱自帶。視覺走「最小必要基礎樣式」——active 態預設主色填充、肉眼可辨，顏色 / 圓角 / 間距由 applier 覆蓋。

選型：選項少（2–5 個）、要全部可見、省一次點擊時用本元件（篩選 pills / tab / 排序）。選項多、要省橫向空間、可接受點開收合時用 SwSelect（下拉）。兩者互補。

基礎用法

基礎單選（排序切換）

加载中...
<script setup lang="ts">
const sort = ref('hot')
</script>

<template>
  <SwSegmented
    v-model="sort"
    :options="[
      { value: 'hot', label: '最热播' },
      { value: 'new', label: '最新上线' },
      { value: 'rating', label: '评分最高' },
    ]"
    aria-label="排序"
  />
</template>

禁用

支援單項 disabled（禁用列表中某一項）或整組 disabled：

單項禁用 / 整組禁用

加载中...

自訂選項視覺

#option 插槽全權控制單個選項的內容，作用域暴露 { option, selected, disabled }：

#option 插槽自訂視覺

加载中...

Props

名稱類型必填預設值說明
modelValue（v-model）string | numberundefined當前選中值（受控）。undefined 為未選
optionsSwSegmentedOption[]✓—選項列表，每項 { value, label, disabled? }
disabledbooleanfalse整組禁用

SwSegmentedOption：{ value: string \| number; label: string; disabled?: boolean }

Events

名稱攜帶說明
update:modelValuevalue: string | number選中變化，payload 為被選中項的 value

Slots

名稱作用域參數說明
option{ option, selected, disabled }自訂單個選項視覺。不傳則渲染 option.label

樣式定制 Token

視覺品牌經 --sw-segmented-* token 覆蓋（fallback 即預設視覺），無需 :deep 穿透：

Token預設值作用點
--sw-segmented-gap0.25remtrack 內選項間距
--sw-segmented-padding0.125remtrack 內邊距
--sw-segmented-bgvar(--muted)track 底色（灰槽，業界通例形態）
--sw-segmented-bordertransparenttrack 描邊色（1px 寬度常駐，設色值即得描邊 track）
--sw-segmented-radiusvar(--radius)track 圓角
--sw-segmented-min-heightvar(--control-height)track 最小高（表單控件族統一高度）
--sw-segmented-font-sizevar(--control-font-size)選項字號
--sw-segmented-option-padding0.125rem 0.875rem選項內邊距
--sw-segmented-option-radiuscalc(var(--radius) - 0.25rem)選項圓角
--sw-segmented-option-colorvar(--muted-foreground)未選中文字色
--sw-segmented-hover-colorvar(--foreground)未選中項 hover 文字色（選中項 hover 保持啟動色 + filter: brightness(0.92) 變暗）
--sw-segmented-active-colorvar(--primary-foreground)啟用文字色
--sw-segmented-active-bgvar(--primary)啟用底色
--sw-segmented-active-bordertransparent啟用描邊（inset box-shadow 實現，零 reflow）
/* 「tinted 淡底 + 描邊」啟用形態（替代 :deep 穿透） */
.filter-bar {
  --sw-segmented-active-bg: color-mix(in srgb, var(--primary) 12%, transparent);
  --sw-segmented-active-color: var(--primary);
  --sw-segmented-active-border: var(--primary);
}

高度 / 字號預設吃表單控件族語義 token --control-height（32px）/ --control-font-size（14px）——SwInput / SwSelect / SwSegmented 同行混排預設等高；覆蓋這兩個 token 全站控件同步縮放，元件級 token 優先級更高。

注意事項

  • 無內建視覺品牌：元件只給最小必要基礎樣式（active 態可辨）；顏色 / 圓角 / 間距經上表 --sw-segmented-* token 覆蓋，無需 :deep 穿透選擇器。
  • 方向鍵 a11y 自帶：← → / Home End 在選項間 roving 移動並選中，無需額外程式碼。
  • 單選專用：本元件只做單選；要下拉收合或多選請用 SwSelect。

相關