# @data-slot/dialog 中文文档

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

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

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

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

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

- 包体积（解压后）：22.5 kB，6 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2026-01-09T14:58:16.466Z
- 最新版本发布：2026-11-05T12:08:44.068Z
- 近 30 天下载量：12930（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：164（近 12 个月 164 个）

## 中文简介

香草JavaScript的无头模式对话框组件. 无障碍而无作相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相.

## 安装

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

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

## README

# @ data- slot/ 对话框

香草JavaScript的无头模式对话框组件. 无障碍而无作相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相.

## 安装

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

## 快速启动

```html
<div data-slot="dialog">
  <button data-slot="dialog-trigger">Open Dialog</button>
  <div data-slot="dialog-overlay" hidden></div>
  <div data-slot="dialog-content" hidden>
    <h2 data-slot="dialog-title">Dialog Title</h2>
    <p data-slot="dialog-description">Dialog description text.</p>
    <button data-slot="dialog-close">Close</button>
  </div>
</div>

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

## API 密码

### 初始化

#### `create(scope?)`

自动发现并绑定范围中的所有对话框实例(默认为 `document`) (中文(简体) ).

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

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

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

为特定元素创建控制器.

```typescript
import { createDialog } from "@data-slot/dialog";

const dialog = createDialog(element, {
  defaultOpen: false,
  closeOnClickOutside: true,
  closeOnEscape: true,
  lockScroll: true,
  onOpenChange: (open) => console.log(open),
});
```

### 槽数

#### 运行时间槽

-   `dialog` - 管理开放状态并接收对话框事件的根元素.
-   `dialog-trigger` - 切换对话框的可选按钮.
-   `dialog-portal` - 可选包装器搬到了 `document.body` 当对话框打开时.
-   `dialog-overlay` - 需要的背景;在启用外部点击解禁时点击它删除对话框.
-   `dialog-content` - 配有对话框语义和焦点管理的必要模式面板.
-   `dialog-title` - 用于面板的可选标题 `aria-labelledby`。 。 。 .
-   `dialog-description` - 用于面板的可选描述 `aria-describedby`。 。 。 .
-   `dialog-close` - 关闭对话框的可选按钮;支持多个关闭按钮.

#### 标记

```html
<div data-slot="dialog">
  <button data-slot="dialog-trigger">Open</button>
  <div data-slot="dialog-overlay" hidden></div>
  <div data-slot="dialog-content" role="dialog">
    <h2 data-slot="dialog-title">Title</h2>
    <p data-slot="dialog-description">Description</p>
    <button data-slot="dialog-close">Close</button>
  </div>
</div>
```

### 数据属性

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

| 属性 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `data-default-open` | 布尔 | `false` | 初始打开状态 |
| `data-close-on-click-outside` | 布尔 | `true` | 点击外部内容时关闭 |
| `data-close-on-escape` | 布尔 | `true` | 按下 Escape 键时关闭 |
| `data-lock-scroll` | 布尔 | `true` | 打开后锁定正文滚动 |
| `data-alert-dialog` | 布尔 | `false` | 使用提醒对话框确认 |

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

```html
<!-- Disable close on Escape -->
<div data-slot="dialog" data-close-on-escape="false">
  ...
</div>

<!-- Alert dialog that stays open when clicking outside -->
<div data-slot="dialog" data-alert-dialog data-close-on-click-outside="false">
  ...
</div>
```

### 选项

| 选项 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `defaultOpen` | `boolean` | `false` | 初始打开状态 |
| `closeOnClickOutside` | `boolean` | `true` | 点击外部内容时关闭 |
| `closeOnEscape` | `boolean` | `true` | 按下 Escape 键时关闭 |
| `lockScroll` | `boolean` | `true` | 打开后锁定正文滚动 |
| `alertDialog` | `boolean` | `false` | 使用提醒对话框确认 |
| `onOpenChange` | `(open: boolean) => void` | `undefined` | 打开状态更改时召回 |

### 主计长

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

#### 主计长销毁

`destroy()` 永久处理控制器并隐藏任何打开的表面,而不包含 产生额外的变化事件。 重复销毁是安全的 旧控制器变成无操作器。 在同一根上创建新控制器以重新组合 .

破坏恢复了先前的焦点,如果先前的,则会回到存活的触发器 目标被移除。 摧毁未打开的模式不会移动焦点.

### 活动

#### 境外事件

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

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

#### 入境事件

通过事件控制对话框 :

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

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

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

##### 折旧形状

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

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

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

### 样式

对话框都显示 `data-state="open|closed"` 和弹出式动画钩:

-   `data-open` 编号 : `data-closed` 打开 `dialog`, (中文(简体) ), `dialog-portal`, (中文(简体) ), `dialog-overlay`,以及 `dialog-content`
-   `data-starting-style` 打开时
-   `data-ending-style` 关闭时

使用 `data-open` 编号 : `data-closed` 与 `data-starting-style` 编号 : `data-ending-style` 动画:

```css
/* Backdrop */
[data-slot="dialog-overlay"] {
  position: fixed;
  inset: 0;
  background: rgba(0, 0, 0, 0.5);
  opacity: 0;
  transition: opacity 0.2s ease;
}

[data-slot="dialog-overlay"][data-open] {
  opacity: 1;
}

[data-slot="dialog-content"] {
  opacity: 0;
  transform: translate(-50%, -50%) scale(0.95);
  transition:
    opacity 0.2s ease,
    transform 0.2s ease;
}

[data-slot="dialog-content"][data-open] {
  opacity: 1;
  transform: translate(-50%, -50%) scale(1);
}

[data-slot="dialog-overlay"][data-starting-style],
[data-slot="dialog-overlay"][data-ending-style] {
  opacity: 0;
}

[data-slot="dialog-content"][data-starting-style],
[data-slot="dialog-content"][data-ending-style] {
  opacity: 0;
  transform: translate(-50%, -50%) scale(0.95);
}
```

堆叠在JavaScript中是故意不硬编码的. 配置 `z-index` 在你的CSS中.  
当多个对话框打开时, `data-stack-index` 并打开 CSS 变量 `dialog-overlay` 财务报告和审定财务报表 `dialog-content`数字 :

-   `data-stack-index`
-   `--dialog-stack-index`
-   `--dialog-overlay-stack-index` (重叠)
-   `--dialog-content-stack-index` (内容)

以尾风:

```html
<div
  data-slot="dialog-overlay"
  class="fixed inset-0 bg-black/50 opacity-0 transition-opacity duration-200 data-[open]:opacity-100 data-[starting-style]:opacity-0 data-[ending-style]:opacity-0"
></div>
<div
  data-slot="dialog-content"
  class="fixed top-1/2 left-1/2 -translate-x-1/2 -translate-y-1/2 bg-white p-6 opacity-0 scale-95 transition-all duration-200 data-[open]:opacity-100 data-[open]:scale-100 data-[starting-style]:opacity-0 data-[starting-style]:scale-95 data-[ending-style]:opacity-0 data-[ending-style]:scale-95"
>
  <!-- Dialog content -->
</div>
```

### 键盘导航

| 密钥 | 行动 |
| --- | --- |
| `Escape` | 关闭对话框 |
| `Tab` | 对话框中的循环焦点 |
| `Shift+Tab` | 向后循环焦点 |

### 无障碍

该组件自动处理 :

-   `role="dialog"` 关于内容
-   `aria-modal="true"` 关于内容
-   `aria-labelledby` 链接到标题
-   `aria-describedby` 与描述相链接
-   `aria-haspopup="dialog"` 触发
-   `aria-expanded` 启动状态
-   对话框中的焦点陷阱
-   重点恢复到关闭

## 许可证

麻省理工学院

## 常见问题

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

香草JavaScript的无头模式对话框组件\. 无障碍而无作相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相\.

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

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

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

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

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

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

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

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

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

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

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

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