# 切换按钮

- 页面: https://jiguang132.com/zh/resources/material-ui/docs/toggle-button
- 资源: Material UI (https://jiguang132.com/zh/resources/material-ui.md)
- 全部指南: https://jiguang132.com/zh/resources/material-ui/docs.md

在原生 ToggleButtonGroup 中选择单个或多个按下的操作。

本指南覆盖默认 Emotion 环境的 Material UI Core；扩展包与额外示例按清单单独标注。

## 使用场景与业务边界

互斥选择取消后可能返回 null；拒绝空选择属于宿主策略，不是内置 required 属性。

## 原生组成与范围

`ToggleButton`, `ToggleButtonGroup`

保持 Material UI 原生组合与类型，不替换为 JGuang／Base UI／Radix 同名 API。示例条目不是额外组件。

## 原生安装与初始化

```bash
npm install @mui/material@9.4.0 @emotion/react@11.14.0 @emotion/styled@11.14.1
```

采用原生 npm 包与 Emotion，不提供虚构的 JGuang UI Registry 地址。将示例放在原生 ThemeProvider 内，按项目选择 CssBaseline 或 ScopedCssBaseline。先检查 React、现有 Provider、锁文件与 SSR 配置；不要覆盖用户文件或忽略 peer 冲突。本批实际验收 React 19.2.8；React 18 及以下须匹配 react-is。完整初始化规则见随附的双语 setup 文档。

## 关键原生参数

仅解释本指南选出的关键参数，不是平铺的通用 API。原生继承来源、slot 结构、可空值与泛型仍按固定源码保留。

| 所属组件.属性 | 用途说明 | 声明来源 |
| --- | --- | --- |
| `ToggleButtonGroup.value` | 受控原生值，其单值／数组／可空类型取决于所属组件。 | `ToggleButtonGroup` |
| `ToggleButtonGroup.exclusive` | 使用 ToggleButtonGroup 单选，取消选择可能返回 null。 | `ToggleButtonGroup` |
| `ToggleButtonGroup.onChange` | 所属控件的原生回调，保留其准确事件／数值／可空签名。 | `ToggleButtonGroup` |
| `ToggleButton.selected` | 原生选中／按下展示，选中值由宿主管理。 | `ToggleButton` |

## 可运行原生示例

下列机器键只选择示例入口，不会作为通用 variant 属性传入每个组件。原生示例 JSX 与数据保持上游原文；JGuang 编写的验收示例明确标注。

- 互斥选择 · `ToggleButtons` · 上游原生示例
- 多项选择 · `ToggleButtonsMultiple` · 上游原生示例
- 尺寸 · `ToggleButtonSizes` · 上游原生示例
- 颜色 · `ColorToggleButton` · 上游原生示例
- 纵向按钮 · `VerticalToggleButtons` · 上游原生示例
- 保持非空选择 · `ToggleButtonNotEmpty` · 上游原生示例
- 独立切换按钮 · `StandaloneToggleButton` · 上游原生示例
- 定制样式 · `CustomizedDividers` · 上游原生示例
- 横向间距 · `HorizontalSpacingToggleButton` · 上游原生示例
- 纵向间距 · `VerticalSpacingToggleButton` · 上游原生示例

## 真实使用示例

固定版本的未修改原生示例；复制时同时保留所需的局部辅助文件。

```tsx
import * as React from 'react';
import FormatAlignLeftIcon from '@mui/icons-material/FormatAlignLeft';
import FormatAlignCenterIcon from '@mui/icons-material/FormatAlignCenter';
import FormatAlignRightIcon from '@mui/icons-material/FormatAlignRight';
import FormatAlignJustifyIcon from '@mui/icons-material/FormatAlignJustify';
import ToggleButton from '@mui/material/ToggleButton';
import ToggleButtonGroup from '@mui/material/ToggleButtonGroup';

export default function ToggleButtons() {
  const [alignment, setAlignment] = React.useState<string | null>('left');

  const handleAlignment = (
    event: React.MouseEvent<HTMLElement>,
    newAlignment: string | null,
  ) => {
    setAlignment(newAlignment);
  };

  return (
    <ToggleButtonGroup
      value={alignment}
      exclusive
      onChange={handleAlignment}
      aria-label="text alignment"
    >
      <ToggleButton value="left" aria-label="left aligned">
        <FormatAlignLeftIcon />
      </ToggleButton>
      <ToggleButton value="center" aria-label="centered">
        <FormatAlignCenterIcon />
      </ToggleButton>
      <ToggleButton value="right" aria-label="right aligned">
        <FormatAlignRightIcon />
      </ToggleButton>
      <ToggleButton value="justify" aria-label="justified" disabled>
        <FormatAlignJustifyIcon />
      </ToggleButton>
    </ToggleButtonGroup>
  );
}

```

## 示例依赖边界

`react`, `@mui/icons-material/FormatAlignLeft`, `@mui/icons-material/FormatAlignCenter`, `@mui/icons-material/FormatAlignRight`, `@mui/icons-material/FormatAlignJustify`, `@mui/material/ToggleButton`, `@mui/material/ToggleButtonGroup`, `@mui/icons-material/FormatBold`, `@mui/icons-material/FormatItalic`, `@mui/icons-material/FormatUnderlined`, `@mui/icons-material/FormatColorFill`, `@mui/icons-material/ArrowDropDown`, `@mui/material/Stack`, `@mui/icons-material/ViewList`, `@mui/icons-material/ViewModule`, `@mui/icons-material/ViewQuilt`, `@mui/icons-material/Laptop`, `@mui/icons-material/Tv`, `@mui/icons-material/PhoneAndroid`, `@mui/icons-material/Check`, `@mui/material/styles`, `@mui/material/Divider`, `@mui/material/Paper`

直接导入 Icons／System／Utils 的示例需要匹配 9.4.0 包。局部数据与辅助文件属于示例闭包，不是额外组件。远程图片和模拟操作不提供后端。

## 固定上游 API 元数据参考

以下表格保留上游元数据，不是重新推断的通用类型体系。条件泛型、继承属性与回调细节以以下源码声明为准。主题默认配置可能覆盖元数据默认值。

### ToggleButton

```tsx
import ToggleButton from '@mui/material/ToggleButton';
import { ToggleButton } from '@mui/material';
```

原生继承: `ButtonBase`. 父级与 DOM 属性未被伪造为本组件新属性。

| 属性 | 必需 | 上游元数据类型／约束 | 元数据默认值 |
| --- | --- | --- | --- |
| `value` | 是 | `any` | — |
| `children` | 否 | `node` | — |
| `classes` | 否 | `object` | — |
| `color` | 否 | `'standard' \| 'primary' \| 'secondary' \| 'error' \| 'info' \| 'success' \| 'warning' \| string` | `'standard'` |
| `disabled` | 否 | `bool` | `false` |
| `disableFocusRipple` | 否 | `bool` | `false` |
| `disableRipple` | 否 | `bool` | `false` |
| `fullWidth` | 否 | `bool` | `false` |
| `onChange` | 否 | `func` | — |
| `onClick` | 否 | `func` | — |
| `selected` | 否 | `bool` | — |
| `size` | 否 | `'small' \| 'medium' \| 'large' \| string` | `'medium'` |
| `sx` | 否 | `Array<func \| object \| bool> \| func \| object` | — |



### ToggleButtonGroup

```tsx
import ToggleButtonGroup from '@mui/material/ToggleButtonGroup';
import { ToggleButtonGroup } from '@mui/material';
```

| 属性 | 必需 | 上游元数据类型／约束 | 元数据默认值 |
| --- | --- | --- | --- |
| `children` | 否 | `node` | — |
| `classes` | 否 | `object` | — |
| `color` | 否 | `'standard' \| 'primary' \| 'secondary' \| 'error' \| 'info' \| 'success' \| 'warning' \| string` | `'standard'` |
| `disabled` | 否 | `bool` | `false` |
| `exclusive` | 否 | `bool` | `false` |
| `fullWidth` | 否 | `bool` | `false` |
| `onChange` | 否 | `func` | — |
| `orientation` | 否 | `'horizontal' \| 'vertical'` | `'horizontal'` |
| `size` | 否 | `'small' \| 'medium' \| 'large' \| string` | `'medium'` |
| `sx` | 否 | `Array<func \| object \| bool> \| func \| object` | — |
| `value` | 否 | `any` | — |


## 原生源码声明

声明与 import 从固定源码提取，不平铺联合类型或外部继承。英文注释／类型属于原始源码参考，不代表上游正文已全文翻译。共享类型仍位于原生包中。

### vendor/src/ToggleButton/ToggleButton.d.ts

```ts
import { SxProps } from '@mui/system';

import { OverridableStringUnion } from '@mui/types';

import * as React from 'react';

import { Theme } from '../styles';

import { ExtendButtonBase, ExtendButtonBaseTypeMap } from '../ButtonBase';

import { OverrideProps } from '../OverridableComponent';

import { ToggleButtonClasses } from './toggleButtonClasses';

export interface ToggleButtonPropsSizeOverrides {}

export interface ToggleButtonPropsColorOverrides {}

export interface ToggleButtonOwnProps {
  /**
   * The content of the component.
   */
  children?: React.ReactNode;
  /**
   * Override or extend the styles applied to the component.
   */
  classes?: Partial<ToggleButtonClasses> | undefined;
  /**
   * The color of the button when it is in an active state.
   * It supports both default and custom theme colors, which can be added as shown in the
   * [palette customization guide](https://mui.com/material-ui/customization/palette/#custom-colors).
   * @default 'standard'
   */
  color?:
    | OverridableStringUnion<
        'standard' | 'primary' | 'secondary' | 'error' | 'info' | 'success' | 'warning',
        ToggleButtonPropsColorOverrides
      >
    | undefined;
  /**
   * If `true`, the component is disabled.
   * @default false
   */
  disabled?: boolean | undefined;
  /**
   * If `true`, the  keyboard focus ripple is disabled.
   * @default false
   */
  disableFocusRipple?: boolean | undefined;
  /**
   * If `true`, the button will take up the full width of its container.
   * @default false
   */
  fullWidth?: boolean | undefined;
  /**
   * Callback fired when the state changes.
   *
   * @param {React.MouseEvent<HTMLElement>} event The event source of the callback.
   * @param {any} value of the selected button.
   */
  onChange?: ((event: React.MouseEvent<HTMLElement>, value: any) => void) | undefined;
  /**
   * Callback fired when the button is clicked.
   *
   * @param {React.MouseEvent<HTMLElement>} event The event source of the callback.
   * @param {any} value of the selected button.
   */
  onClick?: ((event: React.MouseEvent<HTMLElement>, value: any) => void) | undefined;
  /**
   * If `true`, the button is rendered in an active state.
   */
  selected?: boolean | undefined;
  /**
   * The size of the component.
   * The prop defaults to the value inherited from the parent ToggleButtonGroup component.
   * @default 'medium'
   */
  size?:
    | OverridableStringUnion<'small' | 'medium' | 'large', ToggleButtonPropsSizeOverrides>
    | undefined;
  /**
   * The system prop that allows defining system overrides as well as additional CSS styles.
   */
  sx?: SxProps<Theme> | undefined;
  /**
   * The value to associate with the button when selected in a
   * ToggleButtonGroup.
   */
  value: NonNullable<unknown>;
}

export type ToggleButtonTypeMap<
  AdditionalProps = {},
  RootComponent extends React.ElementType = 'button',
> = ExtendButtonBaseTypeMap<{
  props: AdditionalProps & ToggleButtonOwnProps;
  defaultComponent: RootComponent;
}>;

declare const ToggleButton: ExtendButtonBase<ToggleButtonTypeMap>;

export type ToggleButtonProps<
  RootComponent extends React.ElementType = ToggleButtonTypeMap['defaultComponent'],
  AdditionalProps = {},
> = OverrideProps<ToggleButtonTypeMap<AdditionalProps, RootComponent>, RootComponent> & {
  component?: React.ElementType | undefined;
};
```

### vendor/src/ToggleButtonGroup/ToggleButtonGroup.d.ts

```ts
import * as React from 'react';

import { SxProps } from '@mui/system';

import { OverridableStringUnion } from '@mui/types';

import { Theme } from '../styles';

import { InternalStandardProps as StandardProps } from '../internal';

import { ToggleButtonGroupClasses } from './toggleButtonGroupClasses';

export interface ToggleButtonGroupPropsSizeOverrides {}

export interface ToggleButtonGroupPropsColorOverrides {}

export interface ToggleButtonGroupProps extends StandardProps<
  React.HTMLAttributes<HTMLDivElement>,
  'onChange' | 'children'
> {
  /**
   * The content of the component.
   */
  children?: React.ReactNode;
  /**
   * Override or extend the styles applied to the component.
   */
  classes?: Partial<ToggleButtonGroupClasses> | undefined;
  /**
   * The color of the button when it is selected.
   * It supports both default and custom theme colors, which can be added as shown in the
   * [palette customization guide](https://mui.com/material-ui/customization/palette/#custom-colors).
   * @default 'standard'
   */
  color?:
    | OverridableStringUnion<
        'standard' | 'primary' | 'secondary' | 'error' | 'info' | 'success' | 'warning',
        ToggleButtonGroupPropsColorOverrides
      >
    | undefined;
  /**
   * If `true`, only allow one of the child ToggleButton values to be selected.
   * @default false
   */
  exclusive?: boolean | undefined;
  /**
   * If `true`, the component is disabled. This implies that all ToggleButton children will be disabled.
   * @default false
   */
  disabled?: boolean | undefined;
  /**
   * If `true`, the button group will take up the full width of its container.
   * @default false
   */
  fullWidth?: boolean | undefined;
  /**
   * Callback fired when the value changes.
   *
   * @param {React.MouseEvent<HTMLElement>} event The event source of the callback.
   * @param {any} value of the selected buttons. When `exclusive` is true
   * this is a single value; when false an array of selected values. If no value
   * is selected and `exclusive` is true the value is null; when false an empty array.
   */
  onChange?: ((event: React.MouseEvent<HTMLElement>, value: any) => void) | undefined;
  /**
   * The component orientation (layout flow direction).
   * @default 'horizontal'
   */
  orientation?: 'horizontal' | 'vertical' | undefined;
  /**
   * The size of the component.
   * @default 'medium'
   */
  size?:
    | OverridableStringUnion<'small' | 'medium' | 'large', ToggleButtonGroupPropsSizeOverrides>
    | undefined;
  /**
   * The system prop that allows defining system overrides as well as additional CSS styles.
   */
  sx?: SxProps<Theme> | undefined;
  /**
   * The currently selected value within the group or an array of selected
   * values when `exclusive` is false.
   *
   * The value must have reference equality with the option in order to be selected.
   */
  value?: any;
}

export default function ToggleButtonGroup(props: ToggleButtonGroupProps): React.JSX.Element;
```

## 安装后验收

执行严格类型检查、生产构建和实际交互。检查键盘标签／焦点、原生支持的禁用／错误／只读语义、深浅色、窄屏和减少动画。按真实宿主数据检查回调，不把复制提示词当作安装完成。初始化工具还需检查服务端 HTML 与无告警水合。

## 来源与许可

https://github.com/mui/material-ui/tree/809a7717b4c050ba3f69b75300689f07c050a16e

MIT · @mui/material@9.4.0. 保留上游原始内容与许可证。上游完整原文保留于 vendor/docs，不标为全文中文化。

---

JGuang 全部资源索引: https://jiguang132.com/llms.txt