English | 中文

dom-deep-search

一个高性能、高精度的原生 DOM 深度搜索工具库。专为处理复杂的现代网页结构设计，支持 Shadow DOM 穿透、碎片化节点自动规范化 以及 基于 RegExp d 标志位 的绝对物理定位。

核心特性

• 穿透 Shadow DOM：能够递归检索并进入 Web Components 内部的 shadow-root 提取文本节点。
• 碎片化节点合并 (Normalization)：自动识别并虚拟合并由 <span>、<b>、<i> 等行内标签切碎的文本内容。
• 规范化触发逻辑：仅针对无嵌套结构、包含特定行内标签且不含换行符的节点执行合并。
• 高精度 Range 定位：基于正则表达式的 indices 索引返回原生 Range 对象。
• 偏移量映射算法：通过双循环累加器，确保在跨标签合并后，Range 仍能精准落位到原始 DOM 节点中。
• 正则安全检测：内置 isDangerousReg 函数，有效拦截宽泛匹配或导致 ReDoS 的高风险正则表达式。
• 极致轻量：纯 TypeScript 编写，无任何外部运行时依赖。

安装

npm install dom-deep-search

快速上手

import { deepSearch } from 'dom-deep-search';

// 基础搜索示例，更多选项见下方 API 说明
const results = await deepSearch('搜索词', {
  root: document.getElementById('app')
});

results.forEach(res => {
  console.log('匹配文本:', res.matchText);
  console.log('匹配文本所在父元素:', res.parent);
  console.log('匹配文本所在 range（便于高亮）:', res.range);
});

API 说明

query（搜索词）

纯文本。注意如果 SearchOptions 中 isReg 为 true 时，这里的文本要自带转义，就像自己 new Regexp() 一样。
如：

const results = await deepSearch('搜索词');
const resultsWithReg = await deepSearch('\\d{4}'); // 要带上转义

SearchOptions (配置项)

通过 deepSearch 的第二个参数传入，用于微调搜索行为。可选。

| 属性 | 类型 | 默认值 | 注释 | | :--- |:-----------| :--- |:----------------------------------------------------------------------------| | root | Node | document.body | 指定搜索的起始根节点。 | | isReg | boolean | false | 是否开启正则表达式搜索。 | | isWord | boolean | false | 是否启用单词边界匹配（基于 Unicode 属性判断）。 | | isMatchCase | boolean | false | 是否区分大小写。true 时不带 i 标志，false 时带 i 标志。 | | exclude | string[] | ['STYLE', 'SCRIPT', 'NOSCRIPT', 'META', 'LINK'] | 排除指定的标签名称。 | | pick | string[] | undefined | 性能优化：按需选择返回 matchText, parent, range 字段。例如我只需要一个文本，就传入['matchText'] |

SearchResult (返回结果)

函数返回一个 Promise，解析为结果对象数组。

| 属性 | 类型 | 注释 | | :--- | :--- | :--- | | matchText | string | 本次成功匹配的确切文字内容。 | | parent | HTMLElement \| null | 匹配点所属的真实父节点。若是规范化节点，则返回原始源节点；若是 Shadow DOM 节点，则返回 host。 | | range | Range | 标准浏览器 Range 对象，支持各种 DOM 高亮操作。 |

技术规范

• 支持规范化的标签：STRONG, WBR, EM, ABBR, A, SPAN, ADDRESS, B, BDI, BDO, CITE, I, KBD, MARK, Q, S, DEL, INS, SAMP, SMALL, SUB, SUP, TIME, U, VAR。
• 安全性：搜索前会通过 isDangerousReg 在预设的高风险字符集上进行模拟执行，确保正则不会导致浏览器挂起。

许可证

MIT