# SegmentedControl

> SegmentedControl 是用于互斥选项的 React 分段控件，比如在颜色选择器的滑块模式中切换 RGB、HSL 或 HSB。

Source: https://chroma-panel.jscrate.dev/zh/react/components/segmented-control
Last updated: 2026-09-21

`SegmentedControl` 显示一排选项，其中一项处于选中状态。React 颜色选择器用它来切换 RGB、HSL 和 HSB，模式标签页也是用它做的。

把选中项的 id 传给 `value`，并在 `onChange` 中更新它。每一项都有一个 `id`、一个可访问的 `label`，以及放在 `content` 里的文字或图标。用 `ariaLabel` 给整个控件命名。如果某个选项会显示另一个元素，就使用 `controls`。

## 结构

```tsx
import { useState } from "react";
import { SegmentedControl } from "chroma-panel";

function ModelSwitch() {
  const [model, setModel] = useState("rgb");

  return (
    <SegmentedControl
      size="sm"
      ariaLabel="Color model"
      items={[
        { id: "rgb", label: "RGB", content: "RGB" },
        { id: "hsl", label: "HSL", content: "HSL" },
        { id: "hsb", label: "HSB", content: "HSB" },
      ]}
      value={model}
      onChange={setModel}
    />
  );
}
```

> **随处可用**
>
> `SegmentedControl` 不读取面板的颜色。它完全通过 `value` 和 `onChange`
> 受控，所以外面不需要包一层 `ChromaPanel`。

## API 参考

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` (required) | `SegmentedItem[]` | — | The segments, in order. `content` is what each tab renders. |
| `value` (required) | `string` | — | Id of the selected segment. |
| `onChange` (required) | `(id: string) => void` | — | Fires with the id chosen. |
| `size` | `"md" \| "sm"` | `'md'` | `'sm'` is the compact height, for toolbars inside a panel. |
| `ariaLabel` (required) | `string` | — | Accessible name for the tablist. |
| `controls` | `(id: string) => string` | — | Maps a segment id to the id of the panel it controls, for `aria-controls`. |
| `segmentId` | `(id: string) => string` | — | Maps a segment id to the DOM id given to that tab. |
| `disabled` | `boolean` | `false` | Makes every segment unselectable. |
| `className` | `string` | — | Class on the tablist. |
| `tabClassName` | `string` | — | Class on each tab. |

## 相关内容

- [ModeToolbar](https://chroma-panel.jscrate.dev/zh/react/components/mode-toolbar)：基于它构建的模式标签页
- [滑块模式](https://chroma-panel.jscrate.dev/zh/react/modes/sliders)：RGB、HSL 和 HSB 切换的实际用法
- [无障碍功能](https://chroma-panel.jscrate.dev/zh/react/overview/accessibility)：整个选择器的键盘支持