# @data-slot/core 中文文档

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

版本：1\.1\.3
npm 元数据更新时间：2026-11-05T11:53:03.108Z
中文译文更新时间：2026-11-11T12:54:16.563Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：110 kB，6 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2026-01-09T14:57:26.490Z
- 最新版本发布：2026-11-05T11:53:02.724Z
- 近 30 天下载量：27414（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：165（近 12 个月 165 个）

## 中文简介

共享数据槽无头UI组件的公用设施.

## 安装

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

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

## README

# 数据位/ 核心

共享数据槽无头UI组件的公用设施.

## 安装

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

## API 密码

### DOM 公用事业

#### `getPart(root, slot)`

查询组件根内的单个部分/槽.

```typescript
const trigger = getPart<HTMLButtonElement>(root, "dialog-trigger");
```

#### `getParts(root, slot)`

查询组件根内的所有部件/槽.

```typescript
const items = getParts<HTMLElement>(root, "accordion-item");
```

#### `getRoots(scope, slot)`

通过数据槽值在一个范围内查找所有组件根.

```typescript
const dialogs = getRoots(document, "dialog");
```

### 重点公用事业

`isFocusable(element)` 检查单个元素能否收到 方案重点,使用与后裔发现相同的资格规则.

`getFocusable(container)` 返回DOM中可方案重点的后代 顺序,包括负数元素 `tabindex`。 。 。 . `getTabbables(container)` 返回符合 Tab 导航条件的子集,核算已检查的收音机 组合。 返回 DOM 命令, 而不是排序为正 `tabindex` 数值.

`getAutofocusOrFirstFocusable(container)` 选择符合条件的 `[autofocus]` 后人,否则第一个可关注后人,或 `undefined` 如果不存在的话.

每次通话都读取当前DOM状态. 隐藏、惰性和本地禁用控制 除外. `aria-disabled` 财务报告和审定财务报表 `data-disabled` 仅此而已,不能取消本地焦点 资格。 查询将容器本身排除在外,不会穿入巢中 阴影根;直接通过阴影根来查询其后人.

### ARIA 公用事业

#### `ensureId(element, prefix)`

确保元素具有识别码,必要时生成识别码.

```typescript
const id = ensureId(content, "dialog-content");
// Returns existing id or generates "dialog-content-1"
```

#### `setAria(element, name, value)`

设置或删除 ARIA 属性 。 布尔值转换为字符串 .

```typescript
setAria(trigger, "expanded", true);  // aria-expanded="true"
setAria(trigger, "expanded", null);  // removes aria-expanded
```

#### `linkLabelledBy(content, title, description)`

通过ARIA将内容元素与其标签和描述联系起来.

```typescript
linkLabelledBy(dialogContent, titleElement, descriptionElement);
// Sets aria-labelledby and aria-describedby
```

### 水电费

#### `on(element, type, handler, options?)`

添加事件倾听器并返回清理功能 .

```typescript
const cleanup = on(button, "click", () => console.log("clicked"));
// Later: cleanup() to remove listener
```

#### `onRoot(root, type, handler)`

直接发送到元件根上的事件听好了 。 突发事件 后代被这个处理者所忽视,并继续被宣传. 回返a 清理功能, 如 `on`。 。 。 .

用于输入组件命令, 因此嵌入实例无法更改 父状态 :

```typescript
const cleanup = onRoot(root, "tabs:set", handleSet);
```

#### `emit(element, name, detail?)`

以可选的细节发送自定义自定义事件 。 外出活动 可在祖先身上观察到;检查 `event.target` 以识别源根.

```typescript
emit(root, "tabs:change", { value: "tab-2" });
```

#### `composeHandlers(...handlers)`

将多个事件处理器组成一个. 停止,如果 `event.defaultPrevented`。 。 。 .

```typescript
const handler = composeHandlers(onClickProp, internalHandler);
```

### 模块和解雇公用事业

#### `createModalStackItem(options)`

用文档的模式堆栈登记表面 。 控制器提供 `open()`, (中文(简体) ), `close()`, (中文(简体) ), `destroy()`,并只读 `isTopmost` 属性。 使用 `isTopmost` 用于交互所有,而不是读取样式属性.

设定 `isolateOutside: true` 来保持背景内容惰性和隐藏 打开时的辅助技术 。 最上面的隔离 堆栈项目,包括抽屉上方打开的对话框,并允许其拥有 门户. 关闭或销毁项目恢复先前的隔离并写入 属性。 不要求隔离的项目保留其现有行为 当没有隔离项目打开时.

#### `createDismissLayer(options)`

坐标外按,出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出入出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出入出出出出出出出出出入出出出出出出出出出出出入出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出入出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出出. `onDismiss(details)` 收到触发器 `originalEvent` 联 合 国 `reason`数字 : `"outside-press"`, (中文(简体) ), `"escape-key"`,或 `"focus-out"`触摸解雇报告 启动点击; Iframe difference 报告窗口模糊事件 。 回电 不需要这些细节,也无需继续争论.

### 手势

#### `createSwipeGesture(options)`

一次从媒体上跟踪一个指针或切换 `element`无 报告到行动通过为止 `lockThreshold` (默认 8px ) 允许 `axes`; 以另一个轴为主的拖动,或 `lock` 回调 拒绝(例如当滚动容器拥有它时),则留到页面上. `start(event, target)` 确定媒体会刷取或返回什么 `null` 改为 别管它 一旦锁定, 指针被捕获到元素上 `capture` 返回时, `move` 接受生的三角洲,和 `release` 增加新闻时间 速度。 速度. `reset` 当锁定的手势结束而不释放时运行。 点击 随即释放出一丝被吞下 控制器提供 `cancel()`, (中文(简体) ), 可选择针对一个目标,以及 `destroy()`。 。 。 .

## 组件使用量

此软件包被全部内部使用 `@data-slot/*` 组件包。 您通常不需要直接导入, 除非构建自定义组件 .

```typescript
import { getPart, setAria, on } from "@data-slot/core";

function createCustomComponent(root: Element) {
  const trigger = getPart(root, "custom-trigger");
  const content = getPart(root, "custom-content");
  
  const cleanup = on(trigger, "click", () => {
    const isOpen = content.hidden;
    content.hidden = !isOpen;
    setAria(trigger, "expanded", isOpen);
  });
  
  return { destroy: cleanup };
}
```

## 终端生命周期

`createTerminalLifecycle()` 管理必须在 控制器被摧毁 。 它返回一个 `TerminalLifecycleController`数字 :

| 成员 | 行为 |
| --- | --- |
| `isDestroyed` | 成为 `true` 在销毁前的钩子和清理资源之前. |
| `trackRaf(callback)` | 调度动画框架;返回其控件或 `null` 一旦破坏开始. |
| `trackTimeout(callback, delay)` | 计划超时;返回其控件或 `null` 一旦破坏开始. |
| `cancelRaf(handle)` 编号 : `cancelTimeout(handle)` | 取消跟踪工作并立即放出手柄. 被忽略的有: Null, finished, 或已切换的手柄. 使用这些方法代替本地取消的履带工作. |
| `onBeforeDestroy(callback)` | 普通待办工作取消后, 资源清理前, 登记同步准备 . |
| `trackFinalRaf(callback)` | 仅从已毁的钩子上排出一个最终框架。 这个框架是故意在被破坏后幸存下来的,例如完成一个已经待决的重点修复. 回返 `null` 在那个阶段之外. |
| `onDestroy(callback)` | 注册同步资源清理, 如果已销毁, 则立即运行 . |
| `destroy()` | 取消待定的工作并运行一次钩子. 回返 `true` 为第一次毁灭, `false` 重复或重复通话. |

```typescript
import { createTerminalLifecycle } from "@data-slot/core";

const lifecycle = createTerminalLifecycle();
const frame = lifecycle.trackRaf(() => updatePosition());
lifecycle.cancelRaf(frame);
lifecycle.onDestroy(() => observer.disconnect());
lifecycle.destroy();
```

`registerFloatingTerminalResources(lifecycle, resources)` 登记册清理 `positionSync`, (中文(简体) ), `presence`, (中文(简体) ), `portal`页:1 `cleanups` 数组,和一个 `unbind` 召回电话, 依此顺序。 资源使用导出 `FloatingTerminalResources` 类型. 该部门仍对其封闭状态和重点政策负责.

`registerModalTerminalResources(lifecycle, resources)` 可选择登记 a `beforeDestroy` 钩子,然后处理 `modalStack`中,每个条目 `presence` 数组, 调用 `reset`, (中文(简体) ), `releaseScrollLock`,以及 `cleanup`,清理无效 `portal`,排水管收听器 `cleanups`和电话 `unbind`顺序. `ModalTerminalResources` 描述这些召回和资源。 重点政策 互动活动仍然是组成部分的责任.

`drainCleanups(cleanups)` 从数组中删除当前调用,并引用 他们的顺序。 重复空出数组的调用毫无作用 。 清理 调用应同步完成而不丢出.

## 许可证

麻省理工学院

## 保留已关闭的重叠内容

`createContentMount({ root, target, strategy: "lazy" })` 保留同一作者 连接文档外的节点。 通过外部作者的门户/定位器 作为 `target` 当在现相. `strategy: "eager"` 保留内容连接.

-   打电话 `mount()` 在门户安装、定位、ARIA参考或焦点之前.
-   打电话 `unmount()` 存在退出完成后,门户恢复.
-   打电话 `cleanup()` 在清理后恢复作者的放置并删除 占位符。 清净是终端和一能.

帮助者只拥有安置. 组件自己的能见度,动画,焦点, ARIA,和开放状态. `getRoots(scope, slot)` 包括嵌入于 保留的内容属于该范围内的根属;正常的DOM查询没有. 分遣队在初始化后会减少活的DOM,而不是服务器所交付的HTML字节.

## 常见问题

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

共享数据槽无头UI组件的公用设施\.

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

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

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

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

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

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

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

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

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

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

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

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