ToggleButtonGroup 切换按钮组

用法

tsx

import { ToggleButtonGroup, ToggleButton } from '@heroui/react';

组件结构

导入 ToggleButtonGroup 组件，并通过点语法访问所有子部分。

tsx

import { ToggleButtonGroup, ToggleButton } from '@heroui/react';

export default () => (
  <ToggleButtonGroup selectionMode="multiple">
    <ToggleButton id="first">First</ToggleButton>
    <ToggleButton id="second">
      <ToggleButtonGroup.Separator />
      Second
    </ToggleButton>
    <ToggleButton id="third">
      <ToggleButtonGroup.Separator />
      Third
    </ToggleButton>
  </ToggleButtonGroup>
);

示例

尺寸

方向

宽度充满

禁用

无分隔线

省略按钮中的 <ToggleButtonGroup.Separator /> 组件即可。

分离模式

使用 isDetached 让按钮之间留出间隔，而不是彼此连接。

选择模式

使用 selectionMode="single" 实现互斥选择，或使用 selectionMode="multiple" 实现独立切换。

受控组件

自定义样式

Tailwind CSS

全局 CSS

若要自定义组件类，可使用 @layer components 指令。了解更多。

css

@layer components {
  .toggle-button-group {
    @apply rounded-lg;
  }

  .toggle-button-group__separator {
    @apply opacity-25;
  }

  .toggle-button-group--full-width {
    @apply w-full;
  }
}

样式参考

HeroUI 遵循 BEM 方法论，确保组件变体与状态可复用且易于自定义。

CSS 类

ToggleButtonGroup 组件使用以下 CSS 类（查看源码样式）：

基础与布局类 [!toc]

.toggle-button-group - 容器基础样式
.toggle-button-group--horizontal - 水平方向
.toggle-button-group--vertical - 垂直方向
.toggle-button-group--full-width - 全宽修饰符
.toggle-button-group__separator - 按钮之间的分隔线元素

修饰符类 [!toc]

.toggle-button-group--detached - 分离模式（按钮间有间隔）

API 参考

ToggleButtonGroup

继承自 React Aria ToggleButtonGroup。

Prop	类型	默认值	描述
`selectionMode`	`"single" \| "multiple"`	`"single"`	是否允许选中一个或多个按钮
`selectedKeys`	`Iterable<Key>`	-	受控的选中状态
`defaultSelectedKeys`	`Iterable<Key>`	-	默认选中 key（非受控）
`onSelectionChange`	`(keys: Set<Key>) => void`	-	选中变化时调用
`disallowEmptySelection`	`boolean`	`false`	是否禁止清空所有选中
`orientation`	`"horizontal" \| "vertical"`	`"horizontal"`	布局方向
`size`	`"sm" \| "md" \| "lg"`	`"md"`	传递给子 ToggleButton 的尺寸
`isDetached`	`boolean`	`false`	按钮是否以间隔分离显示
`fullWidth`	`boolean`	`false`	按钮组是否占满可用宽度
`isDisabled`	`boolean`	`false`	是否禁用组内全部按钮
`className`	`string`	-	额外的 CSS 类

ToggleButtonGroup.Separator

Prop	类型	默认值	描述
`className`	`string`	-	额外的 CSS 类

说明

ToggleButtonGroup 使用 React Context 将 size 传递给所有子 ToggleButton 组件
每个 ToggleButton 都必须有唯一 id prop，并与 selectedKeys / defaultSelectedKeys 中使用的 key 对应
isDisabled prop 由 React Aria 原生处理，会禁用所有子 ToggleButton；单个按钮可通过设置 isDisabled={false} 覆盖
组件会自动处理按钮之间的圆角
在每个 ToggleButton（第一个除外）内添加 <ToggleButtonGroup.Separator />，可在按钮之间显示分隔线
将 disallowEmptySelection 与 selectionMode="single" 一起使用，可确保始终有一个选项被选中

用法