Segmented

segmented

分段控制器 · 自研 radio 语义(方向键漫游) + active-tab CSS 变量滑块(零依赖)

用法

基础用法

传入 items 数组，defaultValue 设初始选中段，滑块平滑过渡。

tsx

<Segmented
  items={[
    { value: "day", label: "日" },
    { value: "week", label: "周" },
    { value: "month", label: "月" },
  ]}
  defaultValue="week"
  aria-label="周期"
/>

图标段

label 用图标时，ariaLabel 提供无障碍名称。

tsx

<Segmented
  items={[
    { value: "grid", ariaLabel: "网格视图", label: <LayoutGrid className="size-4" /> },
    { value: "list", ariaLabel: "列表视图", label: <List className="size-4" /> },
    { value: "map", ariaLabel: "地图视图", label: <Map className="size-4" /> },
  ]}
  defaultValue="grid"
  aria-label="视图"
/>

段内徽标

label 可放富节点，如计费周期里嵌一枚优惠 Tag。

tsx

<Segmented
  items={[
    { value: "monthly", label: "按月付费" },
    {
      value: "yearly",
      ariaLabel: "按年付费，立省 2 个月",
      label: (
        <>
          按年付费
          <Tag variant="soft" tone="success" size="sm">省 2 个月</Tag>
        </>
      ),
    },
  ]}
  defaultValue="monthly"
  aria-label="计费周期"
/>

尺寸

size="sm" 用于工具栏等紧凑场景。

tsx

<>
  <Segmented size="sm" items={periodItems} defaultValue="day" aria-label="周期-小" />
  <Segmented items={periodItems} defaultValue="day" aria-label="周期-中" />
</>

禁用

单段 disabled 跳过该项；整体 disabled 禁用全部。

tsx

<>
  <Segmented
    items={[
      { value: "a", label: "甲" },
      { value: "b", label: "乙", disabled: true },
      { value: "c", label: "丙" },
    ]}
    defaultValue="a"
    aria-label="示例"
  />
  <Segmented items={periodItems} defaultValue="week" disabled aria-label="周期" />
</>

何时用

横向一排互斥选项（约 2–5 段，如「日/周/月」「网格/列表/地图」「按月/按年付费」）需滑块高亮当前段时用，items 数组驱动、单值互斥。选项纵向排列或语义偏表单单选用 Radio；切换页面级视图区块用 Tabs；选项多需收起用 Select。

导入

import { Segmented } from "@hulianui/ui"

Props

Segmented

名称	类型	默认	说明
items *	`SegmentedItem[]`	—	段定义数组
value	`string`	—	受控选中值
defaultValue	`string`	首个未禁用段	非受控初始选中值
disabled	`boolean`	`false`	整体禁用
size	`"sm"｜"md"`	`"md"`	—
className	`string`	—	—
aria-label	`string`	—	无可见标题时提供

SegmentedItem

名称	类型	默认	说明
value *	`string`	—	该段唯一值（也是选中标识）
ariaLabel	`string`	—	label 为富节点（图标/徽标）时必填，否则降级取 value
disabled	`boolean`	`false`	单段禁用

Events

Segmented

事件	类型	说明
onValueChange	`(value: string) => void`	选中变化（单值，radio 语义互斥）

Slots

SegmentedItem

插槽	类型	说明
label *	`ReactNode`	段内容（文字或图标）

禁忌 / 坑

段 label 是图标/徽标等富节点时必须给该段 ariaLabel，否则读屏会读英文 value（念读不友好）。
用 value/onValueChange 即受控，须自管 state；非受控只给 defaultValue。
选中是单值互斥，没有多选——多选共存改用 ToggleGroup。

Playground

sizedisabled

<Segmented
  items={[{ value: "day", label: "日" }, { value: "week", label: "周" }, { value: "month", label: "月" }]}
  defaultValue="week"
/>

用法

基础用法

传入 items 数组，defaultValue 设初始选中段，滑块平滑过渡。

tsx

<Segmented
  items={[
    { value: "day", label: "日" },
    { value: "week", label: "周" },
    { value: "month", label: "月" },
  ]}
  defaultValue="week"
  aria-label="周期"
/>

图标段

label 用图标时，ariaLabel 提供无障碍名称。

tsx

<Segmented
  items={[
    { value: "grid", ariaLabel: "网格视图", label: <LayoutGrid className="size-4" /> },
    { value: "list", ariaLabel: "列表视图", label: <List className="size-4" /> },
    { value: "map", ariaLabel: "地图视图", label: <Map className="size-4" /> },
  ]}
  defaultValue="grid"
  aria-label="视图"
/>

段内徽标

label 可放富节点，如计费周期里嵌一枚优惠 Tag。

tsx

<Segmented
  items={[
    { value: "monthly", label: "按月付费" },
    {
      value: "yearly",
      ariaLabel: "按年付费，立省 2 个月",
      label: (
        <>
          按年付费
          <Tag variant="soft" tone="success" size="sm">省 2 个月</Tag>
        </>
      ),
    },
  ]}
  defaultValue="monthly"
  aria-label="计费周期"
/>

尺寸

size="sm" 用于工具栏等紧凑场景。

tsx

<>
  <Segmented size="sm" items={periodItems} defaultValue="day" aria-label="周期-小" />
  <Segmented items={periodItems} defaultValue="day" aria-label="周期-中" />
</>

禁用

单段 disabled 跳过该项；整体 disabled 禁用全部。

tsx

<>
  <Segmented
    items={[
      { value: "a", label: "甲" },
      { value: "b", label: "乙", disabled: true },
      { value: "c", label: "丙" },
    ]}
    defaultValue="a"
    aria-label="示例"
  />
  <Segmented items={periodItems} defaultValue="week" disabled aria-label="周期" />
</>

何时用

Props

Segmented

名称	类型	默认	说明
items *	`SegmentedItem[]`	—	段定义数组
value	`string`	—	受控选中值
defaultValue	`string`	首个未禁用段	非受控初始选中值
disabled	`boolean`	`false`	整体禁用
size	`"sm"｜"md"`	`"md"`	—
className	`string`	—	—
aria-label	`string`	—	无可见标题时提供

SegmentedItem

名称	类型	默认	说明
value *	`string`	—	该段唯一值（也是选中标识）
ariaLabel	`string`	—	label 为富节点（图标/徽标）时必填，否则降级取 value
disabled	`boolean`	`false`	单段禁用

事件

类型

说明

onValueChange

(value: string) => void

选中变化（单值，radio 语义互斥）

插槽

类型

说明

label *

ReactNode

段内容（文字或图标）

Segmented

用法

基础用法

图标段

段内徽标

尺寸

禁用

何时用

导入

Props

Events

Slots

禁忌 / 坑

相关

Playground

Segmented

用法

基础用法

图标段

段内徽标

尺寸

禁用

何时用

导入

Props

Events

Slots

禁忌 / 坑

相关

Playground