# @data-slot/collapsible 中文文档

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

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

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

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

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

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

## 中文简介

香草JavaScript的无头相撞(show/hide)组件. 无障碍而无作相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相.

## 安装

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

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

## README

# @ data- slot/ 可缩写

香草JavaScript的无头相撞(show/hide)组件. 无障碍而无作相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相.

## 安装

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

## 快速启动

```html
<div data-slot="collapsible">
  <button data-slot="collapsible-trigger">Toggle Content</button>
  <div data-slot="collapsible-content" hidden>
    Hidden content revealed on click.
  </div>
</div>

<script type="module">
  import { create } from "@data-slot/collapsible";
  
  const controllers = create();
</script>
```

## API 密码

### 初始化

#### `create(scope?)`

自动发现并绑定一个范围内的所有相撞事件(默认为 `document`) (中文(简体) ).

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

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

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

为特定元素创建控制器.

```typescript
import { createCollapsible } from "@data-slot/collapsible";

const collapsible = createCollapsible(element, {
  defaultOpen: false,
  hiddenUntilFound: false,
  closeOnEscape: false,
  closeOnClickOutside: false,
  onOpenChange: (open) => console.log(open),
});
```

### 槽数

#### 运行时间槽

-   `collapsible` - 管理开放状态的根元素.
-   `collapsible-trigger` - 需要切换内容并接收的按钮 `aria-expanded`。 。 。 .
-   `collapsible-content` - 需要显示或隐藏在打开状态下的面板.

#### 标记

```html
<div data-slot="collapsible">
  <button data-slot="collapsible-trigger">Toggle</button>
  <div data-slot="collapsible-content">Content</div>
</div>
```

### 数据属性

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

| 属性 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `data-default-open` | 布尔 | `false` | 初始打开状态 |
| `data-hidden-until-found` | 布尔 | `false` | 使用 `hidden="until-found"` 关闭时 |
| `data-close-on-escape` | 布尔 | `false` | 按下 Escape 键时关闭 |
| `data-close-on-click-outside` | 布尔 | `false` | 在相撞器外的指针上关闭 |

布尔属性: 存在或 `"true"` 没错, `"false"` =虚假,缺席=默认.

```html
<!-- Start expanded -->
<div data-slot="collapsible" data-default-open>
  ...
</div>
```

### 选项

| 选项 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `defaultOpen` | `boolean` | `false` | 初始打开状态 |
| `hiddenUntilFound` | `boolean` | `false` | 使用 `hidden="until-found"` 关闭时 |
| `closeOnEscape` | `boolean` | `false` | 按下 Escape 键时关闭 |
| `closeOnClickOutside` | `boolean` | `false` | 在相撞器外的指针上关闭 |
| `onOpenChange` | `(open: boolean) => void` | `undefined` | 打开状态更改时调用( 未调用 init) |

### 主计长

| 方法/财产 | 说明 |
| --- | --- |
| `open()` | 打开可折叠的 |
| `close()` | 关闭相撞 |
| `toggle()` | 切换相撞 |
| `isOpen` | 当前打开状态( 只读) `boolean`(中文(简体) ) |
| `destroy()` | 清理所有事件听众 |

### 活动

#### 境外事件

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

```javascript
element.addEventListener("collapsible:change", (e) => {
  console.log("Collapsible open:", e.detail.open);
});
```

#### 入境事件

通过事件控制相撞:

| 活动 | 细节 | 说明 |
| --- | --- | --- |
| `collapsible:set` | `{ open: boolean }` | 方案设置开放状态 |

```javascript
// Open the collapsible
element.dispatchEvent(
  new CustomEvent("collapsible:set", { detail: { open: true } })
);

// Close the collapsible
element.dispatchEvent(
  new CustomEvent("collapsible:set", { detail: { open: false } })
);
```

**说明:** 已禁用触发时被屏蔽( has `disabled` 属性或 `aria-disabled="true"`) (中文(简体) ).

##### 折旧形状

下列形状已贬值并会在v1.0中去除:

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

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

### 样式

使用 `data-state` 用于 CSS 样式的属性(在根和内容上都有):

```css
/* Hidden state */
[data-slot="collapsible-content"][hidden] {
  display: none;
}

/* Or use data-state */
[data-slot="collapsible"][data-state="closed"] [data-slot="collapsible-content"] {
  display: none;
}

/* Animate using data-state on content */
[data-slot="collapsible-content"] {
  overflow: hidden;
  transition: max-height 0.3s;
  max-height: 0;
}

[data-slot="collapsible-content"][data-state="open"] {
  max-height: 500px;
}

/* Presence lifecycle markers */
[data-slot="collapsible-content"][data-starting-style] {
  opacity: 0;
}

[data-slot="collapsible-content"][data-ending-style] {
  opacity: 0;
}
```

#### CSS 变量

内容元素会暴露大小变量, 用于维度动画 :

| 变量 | 说明 |
| --- | --- |
| `--collapsible-panel-height` | 面板高度( E)`auto` 在开放休息时,在过渡期间测量px, `0px` 当关闭时) |
| `--collapsible-panel-width` | 面板宽度( O)`auto` 在开放休息时,在过渡期间测量px, `0px` 当关闭时) |

示例

```css
[data-slot="collapsible-content"] {
  overflow: hidden;
  height: var(--collapsible-panel-height);
  width: var(--collapsible-panel-width);
  transition: height 0.25s ease, width 0.25s ease, opacity 0.2s ease;
}

[data-slot="collapsible-content"][data-starting-style],
[data-slot="collapsible-content"][data-ending-style] {
  height: 0;
  opacity: 0;
}
```

### 无障碍

该组件自动处理 :

-   `aria-expanded` 启动状态
-   `aria-controls` 连接触发到内容
-   `role="region"` 关于内容
-   `aria-labelledby` 链接内容返回触发
-   唯一用于触发和内容的ID生成
-   禁用触发支持( 尊重) `disabled` 属性和 `aria-disabled="true"`(中文(简体) )
-   当逃生关闭相撞时, 焦点返回触发器, 而焦点就在其中

### 行为

#### 开除

折叠器会一直打开直到默认切换. 启用 `closeOnEscape` 财务报告和审定财务报表 `closeOnClickOutside` (或 `data-close-on-escape` 财务报告和审定财务报表 `data-close-on-click-outside`(中文(简体) ) 如移动导航板.

```html
<div data-slot="collapsible" data-close-on-escape data-close-on-click-outside>
  <button data-slot="collapsible-trigger">Menu</button>
  <nav data-slot="collapsible-content" aria-label="Main">...</nav>
</div>
```

Dismissal 使用与 popover , 对话框和菜单相同的层叠 :

-   逃逸只关闭了最近打开的地层,所以面板内部的弹出会先关闭.
-   被传送的后人内部按压,如从面板上打开的弹出器,算在内.
-   在触摸装置上,外部媒体关闭了面板 `click`,所以滚动页面并不否定它.
-   触发器被禁用时, 解职被屏蔽 .

#### 查找页面支持

启用 `hiddenUntilFound` (或 `data-hidden-until-found`关闭面板 `hidden="until-found"`。这允许浏览器在页面中查找显示匹配的文本.

以尾风:

```html
<div data-slot="collapsible" class="group">
  <button data-slot="collapsible-trigger" class="flex items-center gap-2">
    <span>Show more</span>
    <svg class="group-data-[state=open]:rotate-180 transition-transform">...</svg>
  </button>
  <div data-slot="collapsible-content" class="hidden group-data-[state=open]:block">
    Content here
  </div>
</div>
```

## 许可证

麻省理工学院

## 常见问题

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

香草JavaScript的无头相撞\(show/hide\)组件\. 无障碍而无作相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相\.

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

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

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

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

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

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

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

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

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

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

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

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