# @data-slot/toggle-group 中文文档

规范地址：https://npmcn.com/package/%40data-slot/toggle-group/

版本：1\.1\.3
npm 元数据更新时间：2026-11-05T12:34:15.129Z
中文译文更新时间：2026-11-11T13:47:02.065Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40data-slot/toggle-group
原文对照：https://npmcn.com/package/%40data-slot/toggle-group/?lang=original
项目主页：https://github.com/bejamas/data-slot#readme
源码仓库：https://github.com/bejamas/data-slot

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：20.1 kB，6 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2026-02-02T09:04:10.426Z
- 最新版本发布：2026-11-05T12:34:14.715Z
- 近 30 天下载量：4145（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：149（近 12 个月 149 个）

## 中文简介

一组具有共享状态的切换按钮,支持单个或多个选择.

## 安装

```sh
npm install @data-slot/toggle-group
```

也可以使用：`pnpm add @data-slot/toggle-group`、`yarn add @data-slot/toggle-group`、`bun add @data-slot/toggle-group`

## README

# @ data- slot/ 切换组

一组具有共享状态的切换按钮,支持单个或多个选择.

## 安装

```bash
bun add @data-slot/toggle-group
```

## 使用量

### 基本标记

```html
<!-- Single selection (default) -->
<div data-slot="toggle-group" data-default-value="center">
  <button data-slot="toggle-group-item" data-value="left">Left</button>
  <button data-slot="toggle-group-item" data-value="center">Center</button>
  <button data-slot="toggle-group-item" data-value="right">Right</button>
</div>

<!-- Multiple selection -->
<div data-slot="toggle-group" data-multiple data-default-value="bold italic">
  <button data-slot="toggle-group-item" data-value="bold">B</button>
  <button data-slot="toggle-group-item" data-value="italic">I</button>
  <button data-slot="toggle-group-item" data-value="underline">U</button>
</div>
```

### Java 脚本

```javascript
import { create, createToggleGroup } from "@data-slot/toggle-group";

// Auto-discover and bind all toggle-group elements
const controllers = create();

// Or target a specific element
const group = createToggleGroup(element, {
  defaultValue: "center",
  multiple: false,
  orientation: "horizontal",
  loop: true,
  onValueChange: (value) => console.log(value),
});

// Programmatic control
group.setValue("left");
group.toggle("bold");
console.log(group.value); // ["left"]

// Cleanup
group.destroy();
```

## API 密码

### 初始化

#### `create(scope?)`

寻找和约束未初始化 `[data-slot="toggle-group"]` 后裔 `scope` (违约) `document`) (中文(简体) ). 回返 `ToggleGroupController[]` 新绑起的根。 初始化范围元素本身,使用 `createToggleGroup`。 。 。 .

```typescript
import { create } from "@data-slot/toggle-group";

const controllers = create();
```

#### `createToggleGroup(root, options?)`

创建一个 `ToggleGroupController` 用于一个根元素。 JavaScript 选项优先于相应的数据属性. 再次调用此选项为绑定根返回其已存在的控制器; 在重新绑定新选项前将其销毁 .

```typescript
import { createToggleGroup } from "@data-slot/toggle-group";

const controller = createToggleGroup(element, {});
```

### 槽数

#### 运行时间槽

-   `toggle-group` - 管理单项或多项选择和键盘导航的根元素.
-   `toggle-group-item` - 在组内切换按钮,由独特的 `data-value`; 获得 `aria-pressed` 财务报告和审定财务报表 `data-state` 作为其选择的变化.

### 数据属性

#### 根元素

| 属性 | 说明 |
| --- | --- |
| `data-slot="toggle-group"` | 要求。 识别根元素. |
| `data-default-value` | 初始选定值 。 多个值的空格分隔. |
| `data-multiple` | 启用多个选择模式 . |
| `data-orientation` | `"horizontal"` 或者说 `"vertical"` 键盘导航. |
| `data-loop` | 结尾的键盘焦点( 默认) `true`; 使用情况 `"false"` 停止在结尾. |
| `data-disabled` | 禁用整个组 . |

#### 项目要点

| 属性 | 说明 |
| --- | --- |
| `data-slot="toggle-group-item"` | 要求。 确定一个项目. |
| `data-value` | 要求。 与本项目相关的值 . |
| `data-disabled` | 禁用此特定项目 . |

#### 状态属性(按构成部分设置)

| 属性 | 数值 | 说明 |
| --- | --- | --- |
| `aria-pressed` | `"true"` | `"false"` | 是否按下项目 . |
| `data-state` | `"on"` | `"off"` | 造型的视觉状态. |
| `data-value` (在根头上) | 空格分隔值 | 当前所选. |

### 选项

| 选项 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `defaultValue` | `string | string[]` | `[]` | 初始选定值 。 对于多值,使用数组或空格分隔的字符串. |
| `multiple` | `boolean` | `false` | 允许多个选择 . |
| `orientation` | `"horizontal" | "vertical"` | `"horizontal"` | 键盘导航方向 . |
| `loop` | `boolean` | `true` | 将键盘焦点置于尾端 . |
| `disabled` | `boolean` | `false` | 禁用整个组 . |
| `onValueChange` | `(value: string[]) => void` | \- 说吧 | 选择更改时召回 . |

### 主计长

| 方法/财产 | 说明 |
| --- | --- |
| `setValue(value: string | string[])` | 替换选择。 字符串是空格分隔的;未知值被忽略,单模式保留了第一个匹配值. |
| `toggle(value: string)` | 切换一个值;单模式清除上一个选择. |
| `value` | 当前选择( 只读) `string[]`,包括单模式). |
| `destroy()` | 删除听众并释放根绑定 . |

控制器在小组停用时使用方法。 用户互动和 `toggle-group:set` 禁用时被屏蔽.

### 活动

#### 境外事件

```javascript
// Listen for changes
root.addEventListener("toggle-group:change", (e) => {
  console.log(e.detail.value); // string[]
});
```

#### 入境事件

| 活动 | 细节 | 说明 |
| --- | --- | --- |
| `toggle-group:set` | `{ value: string | string[] }` | 程序设定选择 |

```javascript
// Set selection from outside
root.dispatchEvent(new CustomEvent("toggle-group:set", {
  detail: { value: "bold" }
}));

// Set multiple values
root.dispatchEvent(new CustomEvent("toggle-group:set", {
  detail: { value: ["bold", "italic"] }
}));
```

**说明:** 组禁用时被屏蔽 .

#### 折旧形状

下列形状被去化并会在v1.0中去除:

```javascript
// Deprecated: bare string
root.dispatchEvent(new CustomEvent("toggle-group:set", {
  detail: "bold"
}));

// Deprecated: bare array
root.dispatchEvent(new CustomEvent("toggle-group:set", {
  detail: ["bold", "italic"]
}));
```

使用 `{ value: ... }` 换句话说.

### 样式

```css
/* Style pressed items */
[data-slot="toggle-group-item"][data-state="on"] {
  background: #333;
  color: white;
}

/* Style disabled items */
[data-slot="toggle-group-item"][aria-disabled="true"] {
  opacity: 0.5;
  cursor: not-allowed;
}
```

### 键盘导航

| 密钥 | 行动 |
| --- | --- |
| `ArrowRight` 编号 : `ArrowDown` | 移动到下一个项目( 基于方向) |
| `ArrowLeft` 编号 : `ArrowUp` | 移动到上一个项目( 根据方向) |
| `Home` | 移动到第一个项目 |
| `End` | 移动到上一个项目 |
| `Enter` 编号 : `Space` | 切换当前项目 |

### 无障碍

-   根已经 `role="group"`
-   项目有: `aria-pressed` 属性
-   已禁用的项目有: `aria-disabled="true"` 和本土 `disabled`
-   支持运行键盘导航的标签索引
-   添加 `aria-label` 或者说 `aria-labelledby` 转到上下文的根

## 常见问题

### @data-slot/toggle-group 是什么？

一组具有共享状态的切换按钮,支持单个或多个选择\.

### 如何安装 @data-slot/toggle-group？

在项目目录运行 npm install @data-slot/toggle-group，或使用 pnpm add / yarn add / bun add。

### @data-slot/toggle-group 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @data-slot/toggle-group 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @data-slot/toggle-group 可以商用吗？

@data-slot/toggle-group 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @data-slot/toggle-group 的下载量有多少？

根据 npm 官方下载统计，@data-slot/toggle-group 在 2026/10/12 – 2026/11/10 这 30 天内被下载 4,145 次，日均约 138 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @data-slot/toggle-group 还在维护吗？

最新版本 1\.1\.3 发布于 2026/11/05（6 天前）；至今共发布 149 个版本，其中过去 12 个月发布了 149 个；首次发布于 2026/02/02。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。