> Leaf UI 0.6.0 · Package: @ifhover/leaf-ui · Source: b30c3d3a8fa9c5e15d0d0522cebfbd33f60c6b06
> Browser documentation: https://ifhover.github.io/leaf-ui/v/0.6.0/components/segmented.html

> For AI agents: the complete documentation index is available at https://ifhover.github.io/leaf-ui/v/0.6.0/llms.txt, the full documentation bundle is available at https://ifhover.github.io/leaf-ui/v/0.6.0/llms-full.txt.

# Segmented 分段控制器

快速切换一组相关选项。

## 基本用法


按日按周按月

当前视图: 按周

basic.tsx

复制代码

```tsx lineNumbers file="../../src/examples/segmented/basic.tsx"
import { Segmented, Space, Text } from '@ifhover/leaf-ui';

import { useState } from 'react';

export function SegmentedBasic() {
  const [value, setValue] = useState('按周');
  return (
    <Space direction="vertical" align="stretch">
      <Segmented options={['按日', '按周', '按月']} value={value} onChange={setValue} />
      <output>
        <Text tone="muted">当前视图: {value}</Text>
      </output>
    </Space>
  );
}
```

展开代码

## 更多用法


填满容器

列表栅格归档（不可用）

小尺寸

ABC

advanced.tsx

复制代码

```tsx lineNumbers file="../../src/examples/segmented/advanced.tsx"
import { Segmented, Space, Text } from '@ifhover/leaf-ui';

export function SegmentedOptions() {
  return (
    <Space direction="vertical" align="stretch">
      <Text tone="muted">填满容器</Text>
      <Segmented
        block
        options={[
          { value: 'list', label: '列表' },
          { value: 'grid', label: '栅格' },
          { value: 'archived', label: '归档（不可用）', disabled: true },
        ]}
      />
      <Text tone="muted">小尺寸</Text>
      <Segmented size="sm" options={['A', 'B', 'C']} />
    </Space>
  );
}
```

展开代码

## 使用说明

默认宽度由内容决定，block 可填满容器。options 可使用字符串或带图标的选项。value / onChange 控制选中值，方向键切换选项；name 让选中值参与原生表单提交。

## 类型

组装数据、定义回调和使用 ref 时，可以导入这些类型。

```ts
import type { SegmentedOption, SegmentedProps } from '@ifhover/leaf-ui';
```

## SegmentedOption API

| 属性         | 类型          | 默认值 | 说明    |
| ---------- | ----------- | --- | ----- |
| `value`    | `string`    | 必填  | 受控值   |
| `label`    | `ReactNode` | 必填  | 显示内容  |
| `icon`     | `ReactNode` | —   | 自定义图标 |
| `disabled` | `boolean`   | —   | 禁止交互  |

## SegmentedProps API

| 属性             | 类型                                                               | 默认值     | 说明                  |
| -------------- | ---------------------------------------------------------------- | ------- | ------------------- |
| `options`      | [`readonly (string \| SegmentedOption)[]`](#segmentedoption-api) | 必填      | 可用选项                |
| `value`        | `string`                                                         | —       | 受控值                 |
| `defaultValue` | `string`                                                         | —       | 初始值；非受控表单 reset 时恢复 |
| `onChange`     | `(value: string) => void`                                        | —       | 值变化回调               |
| `disabled`     | `boolean`                                                        | —       | 禁止交互                |
| `size`         | `'sm' \| 'md' \| 'lg'`                                           | `'md'`  | 尺寸或间距预设             |
| `block`        | `boolean`                                                        | `false` | 填满容器宽度              |
| `name`         | `string`                                                         | —       | 表单字段名称              |
| `form`         | `string`                                                         | —       | 关联表单 ID             |