---
title: "切换按钮"
description: "Toggle 是带按下状态的按钮：单独用于收藏、置顶，或组成共享值、方向键导航的切换按钮组。"
---
> Documentation Index
> Fetch the complete documentation index at: https://ui-sdk.ndjp.net/llms.txt
> Use this file to discover all available pages before exploring further.
# 切换按钮
`Toggle`（切换按钮）渲染一个原生按钮，用 `aria-pressed` 报告按下状态：按一下保持按下，再按一下弹起，适合收藏文档、开启加粗这类操作。把多个按钮放进 `ToggleGroup` 可以共享一个值、用方向键在按钮间移动焦点，例如编辑器的格式栏或视图切换器。需要「方向键移动即选中」的单选时用[单选框](https://ui-sdk.ndjp.net/docs/components/radio)。
## 演示
点击切换按钮，或聚焦后按空格、回车，下方的状态文字随之更新：
## 组合
部件都从 `@ui-sdk/react/toggle` 导入。单独使用时就是 `Toggle` 加可选的 `ToggleIcon`；分组时：
```text
ToggleGroup
├── Toggle
│ └── ToggleIcon
└── Toggle
└── ToggleIcon
```
`ToggleIcon` 可选，承载图标并对屏幕阅读器隐藏。组内每个 `Toggle` 都要给 `value`，组的值就是被按下按钮的 `value` 组成的数组。
## 用法
```tsx
import { Toggle, ToggleIcon } from "@ui-sdk/react/toggle";
function Example() {
return (
★
收藏
);
}
```
两种状态下文字保持一致：屏幕阅读器会读出按钮是否按下，不必把标签改成「已收藏」。只有图标没有文字时必须给 `aria-label`。按钮始终是 `type="button"`，在表单里按下它不会触发提交。
## 分组与单选
`multiple` 允许多个按钮同时按下，方向键只移动焦点、不改变按下状态：
```tsx
import { Toggle, ToggleGroup } from "@ui-sdk/react/toggle";
加粗
斜体
下划线
;
```
不传 `multiple` 时同一时刻只有一个按下：按新按钮会弹起其他按钮，再按当前按下的按钮会清空选择。设 `deselectable={false}` 让选择始终保留一项，并搭配 `defaultValue` 指定初始项，例如视图切换器用 `defaultValue={["list"]}` 保证总有一种视图被选中。
组的值**始终是数组**，按按钮在文档里的顺序排列；组内按钮自己的 `pressed` / `defaultPressed` 不生效。有方向含义的图标（箭头、对齐）给 `ToggleIcon` 加 `mirror`，在从右到左的文本里水平翻转；时钟、对勾这类描绘事物的图标不用翻。
## 禁用与可聚焦
`disabled` 可以设在按钮或整个组上，禁用的按钮仍能以按下状态开始（``），外层禁用的 `