# @data-slot/toggle 中文文档

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

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

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

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

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

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

## 中文简介

用于香草JavaScript的无头切换按钮组件. 无障碍而无作相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相.

## 安装

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

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

## README

# @ data- slot/ 切换

用于香草JavaScript的无头切换按钮组件. 无障碍而无作相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相.

## 安装

```bash
npm install @data-slot/toggle
```

## 快速启动

```html
<button data-slot="toggle">Bold</button>
<button data-slot="toggle" data-default-pressed>Italic</button>

<script type="module">
  import { create } from "@data-slot/toggle";

  const controllers = create();
</script>
```

## API 密码

### 初始化

#### `create(scope?)`

自动发现并约束范围中的所有切换例(默认为 `document`) (中文(简体) ).

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

const controllers = create(); // Returns ToggleController[]
```

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

为特定元素创建控制器.

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

const toggle = createToggle(element, {
  defaultPressed: false,
  disabled: false,
  onPressedChange: (pressed) => console.log(pressed),
});
```

### 槽数

#### 运行时间槽

-   `toggle` - 按钮本身。 切换其受压状态并曝光 `aria-pressed` 财务报告和审定财务报表 `data-state` - 不需要儿童插槽.

#### 标记

```html
<button data-slot="toggle">Label</button>
```

切换是一个简单的单元素组件. 总是使用本地 `<button>` 元素键盘支持( Enter/ Space) 和焦点处理只保证 `<button>`非按钮元素(例如, `<div>`, (中文(简体) ), `<span>`不建议这样做,需要手工操作键盘.

### 数据属性

也可以通过根元素上的数据属性来设定选项. 联合来文的选择优先.

| 属性 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `data-default-pressed` | 布尔 | `false` | 初始按下状态 |
| `data-disabled` | 布尔 | `false` | 状态 |

```html
<!-- Initially pressed toggle -->
<button data-slot="toggle" data-default-pressed>Bold</button>
```

### 选项

| 选项 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `defaultPressed` | `boolean` | `false` | 初始按下状态 |
| `disabled` | `boolean` | `false` | 状态 |
| `onPressedChange` | `(pressed: boolean) => void` | `undefined` | 状态改变时召回 |

### 主计长

| 方法/财产 | 说明 |
| --- | --- |
| `toggle()` | 切换按下状态( 已禁用 ) |
| `press()` | 设定为真( 已禁用 ) |
| `release()` | 套接字为假( 已禁用 ) |
| `pressed` | 当前按下状态( 只读) `boolean`(中文(简体) ) |
| `destroy()` | 清理所有事件听众 |

**说明:** 控制器的方法总是有效的,即使残疾。 这样不管用户交互状态如何,都可以进行程序控制. 如果您在调用控制器方法前需要检查已禁用状态, 请亲自检查元素的属性 .

### 活动

#### 境外事件

通过自定义事件聆听更改 :

```javascript
element.addEventListener("toggle:change", (e) => {
  console.log("Pressed:", e.detail.pressed);
});
```

#### 入境事件

通过事件控制切换( 禁用时被忽略 ) :

| 活动 | 细节 | 说明 |
| --- | --- | --- |
| `toggle:set` | `{ value: boolean }` | 按程序设置状态 |

```javascript
// Set to specific state
element.dispatchEvent(
  new CustomEvent("toggle:set", { detail: { value: true } })
);
```

#### 折旧形状

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

```javascript
// Deprecated: boolean detail
element.dispatchEvent(
  new CustomEvent("toggle:set", { detail: true })
);

// Deprecated: { pressed } shape
element.dispatchEvent(
  new CustomEvent("toggle:set", { detail: { pressed: true } })
);
```

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

### 样式

#### 状态属性

组件设置这些属性用于样式:

-   `aria-pressed="true|false"` - 阿里亚州
-   `data-state="on|off"` - CSS型钩子

#### 基本结构

```css
/* Unpressed state */
[data-slot="toggle"] {
  background: #e5e7eb;
  border: none;
  padding: 0.5rem 1rem;
  cursor: pointer;
}

/* Pressed state */
[data-slot="toggle"][data-state="on"] {
  background: #3b82f6;
  color: white;
}

/* Or use aria-pressed */
[data-slot="toggle"][aria-pressed="true"] {
  background: #3b82f6;
  color: white;
}

/* Disabled state */
[data-slot="toggle"][aria-disabled="true"] {
  opacity: 0.5;
  cursor: not-allowed;
}
```

#### 尾风示例

```html
<button
  data-slot="toggle"
  class="px-4 py-2 bg-gray-200 data-[state=on]:bg-blue-500 data-[state=on]:text-white aria-disabled:opacity-50"
>
  Bold
</button>
```

### 键盘导航

切换使用本地 `<button>` 元素,所以键盘支持是自动的 :

| 密钥 | 行动 |
| --- | --- |
| `Enter` | 切换状态 |
| `Space` | 切换状态 |

### 无障碍

该组件自动处理 :

-   `aria-pressed` 状态在按钮上
-   土著 `disabled` 财务报告和审定财务报表 `aria-disabled` 禁用时( 对于按钮)
-   `type="button"` 防止提交表格

### 行为

#### 残疾行为

残疾时(通过 `disabled` 选项, `data-disabled` 属性, 本地 `disabled` 属性,或 `aria-disabled="true"`:

| 投入 | 封锁? |
| --- | --- |
| 单击/ 输入/ 空格 | 对 |
| `toggle:set` 事件 | 对 |
| 主计长方法`toggle()`, (中文(简体) ), `press()`, (中文(简体) ), `release()`(中文(简体) ) | 没有 |

对于 `<button>` 要素 `disabled` 选项同时设置本地 `disabled` 属性和 `aria-disabled="true"`。仅针对其他要素 `aria-disabled` 已经设定.

## 许可证

麻省理工学院

## 常见问题

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

用于香草JavaScript的无头切换按钮组件\. 无障碍而无作相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相\.

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

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

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

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

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

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

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

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

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

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

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

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