# @drivy/dom-query 中文文档
规范地址：https://npmcn.com/package/%40drivy/dom-query/
版本：1\.0\.6
npm 元数据更新时间：2026-10-21T13:48:52.347Z
中文译文更新时间：2026-11-12T23:15:33.330Z
软件包许可：MIT
本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。
原始 npm 页面：https://www.npmjs.com/package/%40drivy/dom-query
原文对照：https://npmcn.com/package/%40drivy/dom-query/?lang=original
项目主页：https://github.com/drivy/dom-query#readme
源码仓库：https://github.com/drivy/dom-query
## 关键信息（来自 npm 元数据）
- 包体积（解压后）：36.7 kB，12 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2019-06-26T13:40:40.603Z
- 最新版本发布：2022-01-12T09:23:14.230Z
- 近 30 天下载量：3199（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：6（近 12 个月 0 个）
## 中文简介
用于选择 dom 元素和处理事件的工具
## 安装
```sh
npm install @drivy/dom-query
```
也可以使用：`pnpm add @drivy/dom-query`、`yarn add @drivy/dom-query`、`bun add @drivy/dom-query`
## README
# 用查询/活动方法增强的 HTML 元素
方便进行 DOM 元素操作的功能 :
- 基于 Css 查询选择器的元素选择 。 可连锁. 节点列表自动转换为矩阵
- 帮助附加/挖掘事件。 支持的活动
这个库作为ES模块提供,并附有打字声明.
## 安装
用 npm 安装 :
```ts
$ npm install @drivy/dom-query
```
用纱线安装 :
```ts
$ yarn add @drivy/dom-query
```
## 使用量
```ts
import { query, queryAll } from "@drivy/dom-query";
queryAll(".home-header").map(header => console.log(header));
// =>
// =>
query(".confirm-button").on("click", e => {
confirm(e.target);
});
```
## API 密码
### 从DOM中获取元素
`query`
- 从 DOM 中选择带有 css 查询选择器的元素.
- 返回时 `null` 如果没有元素匹配选择器.
- 可连锁. 链条方法将基于最后选定的元素上下文
`queryStrict`
- 喜欢 `query` 方法,但如果没有元素与选择器相匹配,则将例外提出.
`queryAll`
- 从 DOM 中选择一个带有 cs 查询选择器的元素列表。 节点列表结果将被转换为阵列, 这样您就可以直接访问阵列方法( 对于每个阵列, 映射, 减少, 过滤...)
实例:
```ts
import { query, queryStrict, queryAll } from "@drivy/dom-query"
...
const myElement = query(".js_my-element")
const mySubElement = myElement.query(".js_my-sub-element")
const mySubElements = myElement.queryAll(".js_my-sub-elements")
queryAll(".js_my-container .js_my-children-to-select").map(enhancedElement => {
doSomething(enhancedElement)
})
const myElement2 = queryStrict(".js_my-existing-element")
//code below won't be reached if the previous element was not found
doSomething(myElement2)
```
### 将已有的javascript 元素转换为增强HTMLEments
您可以用以下方法将现有的javascript Element/List 转换为增强HTMLElement/增强HTMLElementList :
- `toEnhancedHTMLElement`
- `toEnhancedHTMLElementList`
当输入元素超出你的范围时,您必须使用这些方法(函数参数,事件.目标.)
```ts
import { toEnhancedHTMLElement, toEnhancedHTMLElementList } from "@drivy/dom-query"
...
const myElement = toEnhancedHTMLElement(myHTMLElement);
const myElements = toEnhancedHTMLElementList(myHTMLElements);
```
### 处理事件
您可以以下列方法附加/分离事件:
增强式HTMLELED(增强式)`.on`
- 附加类似本地事件 `target.addEventListener`。 。 。 .
- 返回“调试”函数。 当调用时, 将会像删除事件听众 `target.removeEventListener`。 。 。 .
增强HTMLelement列表`.on`
- 与增强HTMLElement 相同的参数和行为`.on` 但该活动将附在清单中的每个要素上.
- 返回“ 解析” 函数, 当调用时, 将解析列表中每个元素所附带的事件
增强式HTMLELED(增强式)`.onDelegate`
- 执行活动任务. [这里的模式描述](https://davidwalsh.name/event-delegate)。 。 。 .
- 喜欢 `.on` 方法,但将一个额外的参数(第一个)作为 css 查询选择器,指定作为事件目标的孩子们
- 返回“调试”函数。 当被调用时,会移除附在容器上的事件收听器.
增强HTMLelement列表`.onDelegate`
- 与增强HTMLElement 相同的参数和行为`.onDelegate` 但活动代表团将按清单的每一项进行.
- 返回“ 解析” 函数, 当调用时, 将解析列表中每个元素所附带的事件
实例:
```ts
// EnhancedHTMLElement
const detach = myElement.on("click", e => {
doSomething(e.target)
})
...
detach() //same behavior than native target.removeEventListener
const detachDelegation = myContainer.onDelegate(".js_sub-elements", "click", e => {
doSomething(e.target)
});
// clicking on a child having the "js_sub-elements" class will trigger the event
...
detachDelegation() // remove event listener used to delegate
// EnhancedHTMLElementList
const detach = queryAll(".js_my-elements").on("click", e => {
doSomething(e.target)
})
...
detach()
const detachDelegations = queryAll(".js_my-elements").onDelegate(
".js_my-sub-elements",
"click",
e => {
doSomething(e.target)
}
)
...
detachDelegations()
```
### 高级特性
#### 事件配置
附加事件时 `.on` 或者说 `.onDelegate` 您可以将可选事件配置对象指定为最后一个参数. 此配置对象有一个 `once` 布尔属性, 当 `true` 在拨打一次电话后, 将自动解析事件 .
```ts
myElement2.on(
"click",
e => {
doSomething(e.target);
// event listener will be detached
},
{
once: true
}
);
```
#### 专门化 HTML 元素( 如: HTML 输入元素)
因为 `EnhancedHTMLElement` 增强 `HTMLElement` 默认情况下,从带有 Typescript(例如: `myEnhancedInput.value`),在调用查询/转换方法时必须声明目标类型
```ts
import { query, queryAll, toEnhancedHTMLElement } from "@drivy/dom-query"
...
const myEnhancedInput = query(".js_my-target-input");
doSomething(myEnhancedInput.value)
const myEnhancedInput2 = toEnhancedHTMLElement(myExistingInput);
doSomething(myEnhancedInput2.value)
const myEnhancedInputs = queryAll(".js_my-target-inputs");
myEnhancedInputs.forEach(myInput => {
doSomething(myInput.value);
})
```
## 常见问题
### @drivy/dom-query 是什么？
用于选择 dom 元素和处理事件的工具
### 如何安装 @drivy/dom-query？
在项目目录运行 npm install @drivy/dom-query，或使用 pnpm add / yarn add / bun add。
### @drivy/dom-query 支持 TypeScript 吗？
支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。
### @drivy/dom-query 支持 ESM 还是 CommonJS？
同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。
### @drivy/dom-query 可以商用吗？
@drivy/dom-query 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。
### @drivy/dom-query 的下载量有多少？
根据 npm 官方下载统计，@drivy/dom-query 在 2026/10/13 – 2026/11/11 这 30 天内被下载 3,199 次，日均约 107 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。
### @drivy/dom-query 还在维护吗？
最新版本 1\.0\.6 发布于 2022/01/12（4 年前）；至今共发布 6 个版本，其中过去 12 个月发布了 0 个；首次发布于 2019/06/26。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。