切换按钮组

一组互斥的按钮。

简介

切换按钮组提供了一种通过共享公共容器将互斥操作更紧密地结合在一起的方法。当给定自身的 value 属性时，它会控制其子按钮的选中状态。

基础

import ToggleButtonGroup from '@mui/joy/ToggleButtonGroup';

请注意，Joy UI 不提供切换按钮组件，而是提供切换按钮组容器组件。原因是根据 WAI ARIA 模式，最好在按钮或图标按钮组件上使用 aria-pressed。

也就是说，当使用切换按钮组组件时，请将值作为数组传递。当组内的按钮被按下时，切换按钮组组件会触发它的 onChange 属性，并将更新后的数组作为参数传递。

切换按钮组组件使用与按钮组组件相同的样式，以确保所有 Joy UI 按钮之间视觉连接的一致性。

独占选择

当提供给切换按钮组组件的值不是数组时，它将在独占选择模式下运行，这意味着在组内一次只能选择一个按钮。

自定义

变体

切换按钮组组件支持 Joy UI 的四个全局变体：outlined（默认）、plain、soft 和 solid。

<ToggleButtonGroup
  variant={value || undefined}
  value={value}
  onChange={(event, newValue) => {
    setValue(newValue);
  }}
>
  <Button value="plain">plain</Button>
  <Button value="outlined">outlined</Button>
  <Button value="soft">soft</Button>
  <Button value="solid">solid</Button>
</ToggleButtonGroup>

<ToggleButtonGroup
  variant={value || undefined}
  value={value}
  onChange={(event, newValue) => {
    setValue(newValue);
  }}
>
  <Button value="plain">plain</Button>
  <Button value="outlined">outlined</Button>
  <Button value="soft">soft</Button>
  <Button value="solid">solid</Button>
</ToggleButtonGroup>

按 Enter 开始编辑

尺寸

切换按钮组组件提供三种尺寸：sm、md（默认）和 lg。

<ToggleButtonGroup
  size={value || undefined}
  value={value}
  onChange={(event, newValue) => {
    setValue(newValue);
  }}
>
  <Button value="sm">Small</Button>
  <Button value="md">Medium</Button>
  <Button value="lg">Large</Button>
</ToggleButtonGroup>

<ToggleButtonGroup
  size={value || undefined}
  value={value}
  onChange={(event, newValue) => {
    setValue(newValue);
  }}
>
  <Button value="sm">Small</Button>
  <Button value="md">Medium</Button>
  <Button value="lg">Large</Button>
</ToggleButtonGroup>

按 Enter 开始编辑

颜色

主题中包含的每个调色板都可通过 color 属性使用。

间距

默认情况下，切换按钮组内的按钮之间没有间距。使用 spacing 属性且值大于 0 可分隔每个按钮。

间距是使用 gap CSS 属性应用的，其值由主题 theme.spacing(<value>) 确定。

要创建响应式间距比例，<value> 可以是对象或数组。

<ToggleButtonGroup spacing={{ xs: 0, md: 2, lg: 3 }}>…</ToggleButtonGroup>

常见示例

类似 Figma 的切换按钮组

使用 CSS 变量 --ButtonGroup-connected 来控制何时应删除中间按钮的边框半径。

要创建一个类似 Figma 的按钮组，其中按钮在用户悬停在任何按钮上时连接，请将 --ButtonGroup-connected 设置为 0，并在悬停时更改为 1。

可访问性

ARIA

切换按钮组组件具有 role="group"。请确保使用 aria-label="label"、aria-labelledby="id" 或 <label> 提供可访问的标签。
对于切换按钮，请根据按钮状态设置 aria-pressed="<bool>"。请确保使用 aria-label 标记图标按钮。

键盘

切换按钮组组件中的按钮顺序与 DOM 中的顺序相同。使用 Tab 键导航它们。

无样式

使用 Base UI 切换按钮组以完全拥有组件的设计，而无需覆盖 Material UI 或 Joy UI 样式。此无样式版本的组件是进行重度自定义和减小包大小的理想选择。

API

请参阅下面的文档，以获取此处提及的组件的所有属性和类的完整参考。

切换按钮组

Playground