Segmented

segmented

在紧凑的分段控件里选一项，滑块跟着移动

用法

基础用法

传入 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="计费周期"
/>

语义色档（tone）

tone 与 TabsList 同名同取值，选中段的文字带上语义色，滑块仍是白药丸。默认 neutral 保持库既有的中性选中态，不传就不变。

tsx

<Segmented
  items={[
    { value: "day", label: "日" },
    { value: "week", label: "周" },
    { value: "month", label: "月" },
  ]}
  defaultValue="week"
  tone="brand"
  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"`	-
tone	`"brand"｜"success"｜"warning"｜"danger"｜"neutral"`	`"neutral"`	选中段的语义色档：只染选中段文字，滑块仍是白药丸。默认 `neutral` 逐字保持库既有的中性选中态（`text-foreground`），不是「把品牌色换成灰」；与 Tabs 的 `TabsList` 同名同取值
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`	段内容（文字或图标）

禁忌 / 坑

装不下时段会压缩并省略，不会消失。段是 min-w-0 flex-1 truncate：任何宽度下每一段都仍然可见、可点。0.27.0 前缺 min-w-0，flex item 的 min-width:auto 配上 whitespace-nowrap 完全不可压缩，root 宽度被撑到「所有段文字之和」，超出部分被上游容器裁掉——选项存在但不可达（#114）。
但「能压缩」不等于「好用」：4 段中文塞进 150px 只会全变省略号。窄容器请改用 Select，或像 InspectorPanel 那样按容器宽度自动降级。

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

Playground

sizetonedisabled

<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="计费周期"
/>

语义色档（tone）

tone 与 TabsList 同名同取值，选中段的文字带上语义色，滑块仍是白药丸。默认 neutral 保持库既有的中性选中态，不传就不变。

tsx

<Segmented
  items={[
    { value: "day", label: "日" },
    { value: "week", label: "周" },
    { value: "month", label: "月" },
  ]}
  defaultValue="week"
  tone="brand"
  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"`	-
tone	`"brand"｜"success"｜"warning"｜"danger"｜"neutral"`	`"neutral"`	选中段的语义色档：只染选中段文字，滑块仍是白药丸。默认 `neutral` 逐字保持库既有的中性选中态（`text-foreground`），不是「把品牌色换成灰」；与 Tabs 的 `TabsList` 同名同取值
className	`string`	-	-
aria-label	`string`	-	无可见标题时提供

SegmentedItem

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

事件

类型

说明

onValueChange

(value: string) => void

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

插槽

类型

说明

label *

ReactNode

段内容（文字或图标）

禁忌 / 坑

装不下时段会压缩并省略，不会消失。段是 min-w-0 flex-1 truncate：任何宽度下每一段都仍然可见、可点。0.27.0 前缺 min-w-0，flex item 的 min-width:auto 配上 whitespace-nowrap 完全不可压缩，root 宽度被撑到「所有段文字之和」，超出部分被上游容器裁掉——选项存在但不可达（#114）。

但「能压缩」不等于「好用」：4 段中文塞进 150px 只会全变省略号。窄容器请改用 Select，或像 InspectorPanel 那样按容器宽度自动降级。

段 label 是图标/徽标等富节点时必须给该段 ariaLabel，否则读屏会读英文 value（念读不友好）。

用 value/onValueChange 即受控，须自管 state；非受控只给 defaultValue。

选中是单值互斥，没有多选——多选共存改用 ToggleGroup。

Segmented

用法

基础用法

图标段

段内徽标

语义色档（tone）

尺寸

禁用

何时用

导入

Props

Events

Slots

禁忌 / 坑

相关

Playground

Segmented

用法

基础用法

图标段

段内徽标

语义色档（tone）

尺寸

禁用

何时用

导入

Props

Events

Slots

禁忌 / 坑

相关

Playground