Skip to content
Lenso UI

ToggleButtonGroup 切换按钮组

将多个 ToggleButton 组合为统一控件，允许用户选择单个或多个选项。

用法

import { ToggleButtonGroup, ToggleButton } from '@lenso/ui';

此预览复用英文版适配，不代表中文源示例已完成本地实现。

"use client";
import { Bold, Italic, Strikethrough, Underline } from "@gravity-ui/icons";import { ToggleButton, ToggleButtonGroup } from "@lenso/ui";
export function Basic() {  return (    <ToggleButtonGroup multiple aria-label="Text formatting">      <ToggleButton isIconOnly aria-label="Bold" value="bold">        <ToggleButton.Icon>          <Bold />        </ToggleButton.Icon>      </ToggleButton>      <ToggleButton isIconOnly aria-label="Italic" value="italic">        <ToggleButtonGroup.Separator />        <ToggleButton.Icon>          <Italic />        </ToggleButton.Icon>      </ToggleButton>      <ToggleButton isIconOnly aria-label="Underline" value="underline">        <ToggleButtonGroup.Separator />        <ToggleButton.Icon>          <Underline />        </ToggleButton.Icon>      </ToggleButton>      <ToggleButton isIconOnly aria-label="Strikethrough" value="strikethrough">        <ToggleButtonGroup.Separator />        <ToggleButton.Icon>          <Strikethrough />        </ToggleButton.Icon>      </ToggleButton>    </ToggleButtonGroup>  );}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

组件结构

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

import { ToggleButtonGroup, ToggleButton } from '@lenso/ui';
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>);

示例

尺寸

此预览复用英文版适配，不代表中文源示例已完成本地实现。

"use client";export { Sizes } from "./source";

Local adaptation source above. Derived from HeroUI v3.2.6 source.

方向

此预览复用英文版适配，不代表中文源示例已完成本地实现。

"use client";export { Orientation } from "./source";

Local adaptation source above. Derived from HeroUI v3.2.6 source.

宽度充满

此预览复用英文版适配，不代表中文源示例已完成本地实现。

"use client";export { FullWidth } from "./source";

Local adaptation source above. Derived from HeroUI v3.2.6 source.

禁用

此预览复用英文版适配，不代表中文源示例已完成本地实现。

"use client";export { Disabled } from "./source";

Local adaptation source above. Derived from HeroUI v3.2.6 source.

无分隔线

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

此预览复用英文版适配，不代表中文源示例已完成本地实现。

"use client";export { WithoutSeparator } from "./source";

Local adaptation source above. Derived from HeroUI v3.2.6 source.

分离模式

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

此预览复用英文版适配，不代表中文源示例已完成本地实现。

"use client";export { Attached } from "./source";

Local adaptation source above. Derived from HeroUI v3.2.6 source.

选择模式

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

此预览复用英文版适配，不代表中文源示例已完成本地实现。

"use client";export { SelectionMode } from "./source";

Local adaptation source above. Derived from HeroUI v3.2.6 source.

受控组件

此预览复用英文版适配，不代表中文源示例已完成本地实现。

"use client";export { Controlled } from "./source";

Local adaptation source above. Derived from HeroUI v3.2.6 source.

自定义样式

Tailwind CSS

此预览复用英文版适配，不代表中文源示例已完成本地实现。

"use client";export { CustomStyles } from "./source";

Local adaptation source above. Derived from HeroUI v3.2.6 source.

全局 CSS

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

@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"是否允许选中一个或多个按钮
selectedKeysIterable<Key>-受控的选中状态
defaultSelectedKeysIterable<Key>-默认选中 key（非受控）
onSelectionChange(keys: Set<Key>) => void-选中变化时调用
disallowEmptySelectionbooleanfalse是否禁止清空所有选中
orientation"horizontal" | "vertical""horizontal"布局方向
size"sm" | "md" | "lg""md"传递给子 ToggleButton 的尺寸
isDetachedbooleanfalse按钮是否以间隔分离显示
fullWidthbooleanfalse按钮组是否占满可用宽度
isDisabledbooleanfalse是否禁用组内全部按钮
classNamestring-额外的 CSS 类

ToggleButtonGroup.Separator

Prop类型默认值描述
classNamestring-额外的 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" 一起使用，可确保始终有一个选项被选中

相关组件

ToggleButton 切换按钮

用于在开启/关闭或已选中/未选中状态之间切换的交互式切换控件。

ButtonGroup 按钮组

将相关按钮组合在一起，保持一致的样式与间距

Button 按钮

可点击的按钮组件，支持多种变体与状态