切换按钮

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

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

使用场景与业务边界

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

原生组成与范围

ToggleButton, ToggleButtonGroup

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

原生安装与初始化

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 结构、可空值与泛型仍按固定源码保留。

可运行原生示例

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

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

真实使用示例

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

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

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

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

ToggleButtonGroup

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

原生源码声明

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

vendor/src/ToggleButton/ToggleButton.d.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

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，不标为全文中文化。