# @1natsu/wait-element 中文文档

规范地址：https://npmcn.com/package/%401natsu/wait-element/

版本：5\.0\.0
npm 元数据更新时间：2026-10-02T12:37:45.653Z
中文译文更新时间：2026-11-05T16:57:57.465Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%401natsu/wait-element
原文对照：https://npmcn.com/package/%401natsu/wait-element/?lang=original
项目主页：https://github.com/1natsu172/wait-element
源码仓库：https://github.com/1natsu172/wait-element

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

- 包体积（解压后）：17.8 kB，11 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：2 个
- 首次发布：2018-03-07T13:44:50.477Z
- 最新版本发布：2026-10-02T12:37:45.401Z
- 近 30 天下载量：2954043（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：17（近 12 个月 3 个）

## 中文简介

检测浏览器 DOM 中元素的外观

## 安装

```sh
npm install @1natsu/wait-element
```

也可以使用：`pnpm add @1natsu/wait-element`、`yarn add @1natsu/wait-element`、`bun add @1natsu/wait-element`

## README

# 等号元素

[![npm](https://img.shields.io/npm/v/@1natsu/wait-element.svg?style=for-the-badge)](https://www.npmjs.com/package/@1natsu/wait-element) ![npm bundle size (minified)](https://img.shields.io/bundlephobia/min/@1natsu/wait-element.svg?style=for-the-badge) ![npm bundle size (minified + gzip)](https://img.shields.io/bundlephobia/minzip/@1natsu/wait-element.svg?style=for-the-badge)

> 检测浏览器 DOM 中元素的外观

## a.k.a 承诺 -- -- 选择者

-   保证API
-   开车经过 `MutationObserver`
-   探测到的 `querySelecrtor`
-   可用 `AbortSignal`

如果目标元素在执行"等待元素"时已经存在,则立即 `resolve` 并返回元素.

## 安装

```bash
npm install @1natsu/wait-element
```

```bash
yarn add @1natsu/wait-element
```

```bash
pnpm add @1natsu/wait-element
```

```bash
bun add @1natsu/wait-element
```

## 使用量

### 模块规格

```js
import { waitElement } from "@1natsu/wait-element";
```

#### 总之

```js
const el = await waitElement(".late-comming");
console.log(el);
//=> example: "<div class="late-comming">I'm late</div>"
```

#### 指定母目标元素( 请指定突变目标)

```js
const parent = await waitElement("#parent");
const el = await waitElement(".late-comming", { target: parent });
console.log(el);
//=> example: "<div class="late-comming">I'm late</div>"
```

#### 设置超时

```js
const el = await waitElement(".late-comming", { signal: AbortSignal.timeout(1000) }).catch(err => console.log(err));
console.log(el);
//=> If detected element: "<div class="late-comming">I'm late</div>"
//=> If timeouted: DOMException: TimeoutError
```

#### 终止等待

```js
try {
    const waitAbortable = new AbortController();

    const checkElement = waitElement(".late-comming", { signal: waitAbortable.signal });

    waitAbortable.abort("abort this time!");

} catch(error) {
    // After abort handling...
}
```

#### 自定义检测条件

```js
const el = await waitElement("#animal", {
  detector: (element) =>
        element?.textContent === "Tiger"
            ? { isDetected: true, result: element }
            : { isDetected: false },
});
console.log(el.textContent);
//=> example: Tiger
```

```js
import { isNotExist } from "@1natsu/wait-element/detectors";

// when resolve if “not exist” or “disappear” at the time of call
const result = await waitElement(".hero", { detector: isNotExist });
//=> result: null
```

#### 统一等待程序

统一查找元素的过程。 如果设定 `true`,提高效率。 将相同的参数(包括选项)相互统一.

```js
const A = waitElement(".late-comming", {
    unifyProcess: true,
});

const B = waitElement(".late-comming", {
    unifyProcess: true,
});

const C = waitElement(".late-comming", {
    unifyProcess: true,
    signal: AbortSignal.timeout(1000)
});

const D = waitElement(".late-comming", {
    unifyProcess: false,
});

// Unified:
// A === B
// B !== C
// B !== D
```

## API 密码

### 等待元素( 选择器, \[选项\])

#### 选择器

类型 : `string`

格式为 [CSS 选择器](https://developer.mozilla.org/en-US/docs/Learn/CSS/Introduction_to_CSS/Selectors)

#### 选项

通过的选项与默认配置合并.

[详情见TS定义](https://github.com/1natsu172/wait-element/blob/master/src/options.ts)

### 创建waitElement( 最小选项)

自定义等离子函数可以创建 .

## 类似

类似图书馆.

-   [元素准备](https://github.com/sindresorhus/element-ready)
    -   执行方法与这个库不同.

## 许可证

麻省理工学院 [1纳通172](https://github.com/1natsu172)

## 常见问题

### @1natsu/wait-element 是什么？

检测浏览器 DOM 中元素的外观

### 如何安装 @1natsu/wait-element？

在项目目录运行 npm install @1natsu/wait-element，或使用 pnpm add / yarn add / bun add。

### @1natsu/wait-element 支持 TypeScript 吗？

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

### @1natsu/wait-element 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @1natsu/wait-element 可以商用吗？

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

### @1natsu/wait-element 的下载量有多少？

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

### @1natsu/wait-element 还在维护吗？

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