切换按钮 · ToggleButton

表示可以开启或关闭的操作状态。

安装与前置条件

npm install @astryxdesign/core@0.7.1 @astryxdesign/theme-neutral@0.7.1 @stylexjs/stylex@0.19.0

需要 React 19+，按顺序导入基础 CSS 和主题，并设置 Theme Provider。参见开始使用。

示例与使用方式

切换按钮 · 综合展示 / 分组 1：首先体验这个示例，再查看代码理解组件的组合方式。
切换按钮 · 综合展示 2：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
切换按钮 · 交互示例 3：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
切换按钮 · 分组 4：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
切换按钮 · 分组 5：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
切换按钮 · 交互示例 6：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
切换按钮 · 交互示例 7：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。
切换按钮 · 多种状态 8：可交互查看这一用法的行为，复制代码时保留它实际使用的属性与导入。

API 与上游详细参考

优先使用 0.7.1 官方中文说明；上游尚未提供中文的条目保留英文。属性名、类型及默认值保持原生 API，不把示例状态名称当成组件属性。

Toggle Button

ToggleButton switches between selected and unselected states to represent a persistent on/off choice. Use it standalone for binary actions like bold, mute, or favorite, or inside a ToggleButtonGroup for single-select or multi-select toolbar controls.

属性	类型	默认值	说明
label *	string		Accessible label for the button. Used as visible text, or as aria-label for icon-only buttons.
isPressed	boolean		Whether the button is currently pressed. Ignored for a ToggleButtonGroup member with a value.
onPressedChange	(isPressed: boolean, event: MouseEvent) => void		Called synchronously when pressed state should change. Receives the next state and the click event; call event.preventDefault() to skip pressedChangeAction. Without an Action, the callback produces no Action-pending feedback. Ignored for a ToggleButtonGroup member with a value.
pressedChangeAction	(isPressed: boolean) => void \| Promise<void>		Action handler for API- or navigation-backed toggles, run in a transition after the synchronous onPressedChange callback unless that callback calls event.preventDefault(). Works without onPressedChange. Shows an optimistic pressed state and a spinner while pending, and remains interruptible by re-clicks. Omit it for callback-only toggles with no Action-pending feedback. Ignored for a ToggleButtonGroup member with a value.
size	'sm' \| 'md' \| 'lg'	'md'	Button size. Defaults to group size when inside a group.
elevation	'none' \| 'low' \| 'med' \| 'high'	'none'	Resting shadow depth for floating (FAB-style) toggle buttons, mirroring Button. `none` is the default flat button; `low`/`med`/`high` map to the shadow token scale. Applies inside a ToggleButtonGroup as well — grouped children retain their own elevation.
isDisabled	boolean	false	Whether the button is disabled.
isLoading	boolean	false	Whether the button shows a loading spinner.
icon	ReactNode		Icon element. When provided without children, button becomes icon-only with tooltip from label.
isIconOnly	boolean	false	When true, renders as a square icon-only button with `label` as the aria-label and an automatic tooltip from the label.
pressedIcon	ReactNode		Icon shown when pressed. Falls back to icon if not provided.
children	ReactNode		Visible content. If omitted with icon, button becomes icon-only.
tooltip	string		Tooltip text shown on hover.
value	string		Value identifier when used inside ToggleButtonGroup. Required in groups.
data-testid	string		Test selector for automated testing frameworks.

使用建议

Use a filled or colored icon for the pressed state so users can see the current state at a glance: an outline star vs a solid star, for example.
Keep the label identical between pressed and unpressed states. Let the visual treatment (icon, weight, background) communicate the change.
Wrap related toggles in a ToggleButtonGroup with an accessible label so screen readers announce them as a connected set.
避免：Don't use a ToggleButton for one-time actions like "Submit" or "Delete"; those are regular Buttons, not toggles.
避免：Don't mix ToggleButtons with regular Buttons inside the same group; use only ToggleButtons in a ToggleButtonGroup.
避免：Don't use a ToggleButton for on/off settings that persist across sessions; use a Switch instead, which better communicates "setting" semantics.

主题 API

{
  "targets": [
    {
      "className": "astryx-toggle-button-group"
    },
    {
      "className": "astryx-toggle-button",
      "states": [
        "isPressed"
      ],
      "visualProps": [
        "elevation"
      ]
    }
  ]
}

ToggleButtonGroup

无障碍

Text label: The label must have at least 4.5:1 contrast with the button background when selected and unselected. For Hover and Pointer down, measure the final background after the overlay is applied. — 4.5:1
Essential icon or spinner arc: An icon-only ToggleButton must have at least 3:1 contrast between its icon and button background. The moving spinner arc must also meet 3:1. An icon beside a visible label does not need its own check. — 3:1
Selected state indicator: The selected background must reach 3:1 only when users need it to tell selected from unselected. Label weight or a changed icon can also show selection. — 3:1 if relied upon
Visible control boundary: The button edge needs 3:1 contrast only when users need it to see the control. A visible label or icon can show the control instead. — 3:1 if needed
Keyboard focus indicator: The focus outline must have at least 3:1 contrast with the area around the button. Check both selected and unselected states. — 3:1
Disabled appearance: Disabled controls do not need to meet these contrast ratios. — Not required

组件结构

Icon: A leading icon that represents the toggle action, like a star for favorite or bold "B" for formatting.
Pressed icon: An alternate icon shown when pressed: typically a filled version of the default icon to reinforce the active state.
Label: The visible text or accessible name. For icon-only toggles, used as the aria-label and auto-tooltip.
Spinner: Replaces the icon during async operations triggered by pressedChangeAction.

Toggle Button Group

将切换按钮分组，支持单选或多选行为。通过 type 判别联合类型实现类型安全。

属性	类型	默认值	说明
children *	ReactNode		ToggleButton 子元素；每个成员都需要 value。分组控制按下状态，并忽略成员的 isPressed、onPressedChange 和 pressedChangeAction。激活成员只调用分组的 onChange，不启动成员的 Action 过渡。
label *	string		分组的无障碍标签 (aria-label)。
type	'single' \| 'multiple'	'single'	选择模式。single 允许单个激活，multiple 允许多个。
value *	string \| null \| string[]		当前选中的值。类型取决于选择模式。
onChange *	(value: string \| null \| string[]) => void		选择变更时的回调。
orientation	'horizontal' \| 'vertical'	'horizontal'	按钮组的布局方向。
size	'sm' \| 'md' \| 'lg'	'md'	分组内按钮的默认尺寸。单个按钮可覆盖。
isDisabled	boolean	false	分组内所有按钮是否禁用。
xstyle	StyleXStyles		StyleX 样式，用于布局自定义。必须是 stylex.create() 的值。
data-testid	string		自动化测试的选择器。

完整示例的额外依赖

部分示例使用独立图标包。示例清单中的每条安装命令包含该示例实际需要的依赖；若要运行本页全部示例，还需安装：

npm install @heroicons/react@2.2.0