原版的地址: https://bbs.tampermonkey.net.cn/thread-2726-1-1.html
感谢 cxxjackie 大佬的开源, cxxjackie 大佬的代码未明确开源协议，我实在是太欣赏这段代码，没忍住先 fork 了，在此诚挚地向 cxxjackie 大佬道个歉。如果涉及任何侵权问题，我一定第一时间下架，绝不含糊。
如果我魔改后的库能合并到主分支，将会是最棒的。
elmGetter原有的部分代码设计用起来不太顺手，所以我决定对它进行魔改，添加自己需要的功能。
我希望给 elmGetter 添加三个功能：一是增加超时错误处理回调参数，在未找到元素时打印日志，便于调试；二是通过 bool 参数控制超时时，让 promise 保持 pending 或者 resolve (null)；三是支持自定义超时时 resolve 的值，比如 resolve 一个无法删除的 div。
我不仅把这些参数保留为函数参数，还将其设为 elmGetter 成员变量，便于统一设置。为传参方便，我重构了几乎所有函数的传参方式，支持对象传参，无需记参数顺序。
和原版相比，elmGetter水果玉米魔改版主要在优化开发体验上做了提升和改善。
✅ 新增超时回调，方便日志输出，便于调试代码；
✅ 新增统一设置超时时间功能，方便在脚本发布时去掉超时时间；
✅ 还新增了超时后的行为控制，能通过参数或成员变量设置超时回调、超时后promise的状态，以及超时后resolve降级元素。
✅ 我会持续维护这个库，一旦原版有更新，将及时进行合并。
✅ 接口参数进行了重构，使用option方式传参，增加代码的可读性，和方便了接口调用
❎ 由于进行了接口重构，这个库将不兼容原版库
原版的代码:
// ==UserScript==
// @name New Userscript
// @namespace http://tampermonkey.net/
// @version 2025-02-21
// @description try to take over the world!
// @author You
// @match http://127.0.0.1:5500/playground.html
// @icon https://www.google.com/s2/favicons?sz=64&domain=0.1
// @grant unsafeWindow
// @require https://scriptcat.org/lib/513/2.0.1/ElementGetter.js#sha256=V0EUYIfbOrr63nT8+W7BP1xEmWcumTLWu2PXFJHh5dg=
// ==/UserScript==
(async function () {
'use strict';
// TODO: 发布脚本时, 请去掉延时, 延时会导致 elmGetter 启动 setTimeout, 降低脚本性能, 这里设置延时, 仅仅是方便日志打印和调试bug
const timeout = 300;
const childSelector = ".child";
let el1 = await elmGetter.get(childSelector, timeout);
if (el1 === null) {
console.warn(`[elmGetter] [get失败] ${childSelector} 没有找到`);
}
const errorSelector = ".error";
// TODO: 发布脚本时, 请去掉延时, 延时会导致 elmGetter 启动 setTimeout, 降低脚本性能, 这里设置延时, 仅仅是方便日志打印和调试bug
let el2 = await elmGetter.get(errorSelector, timeout);
if (el2 === null) {
console.warn(`[elmGetter] [get失败] ${errorSelector} 没有找到`);
}
})();
魔改版:
// ==UserScript==
// @name New Userscript
// @namespace http://tampermonkey.net/
// @version 2025-02-21
// @description try to take over the world!
// @author You
// @match http://127.0.0.1:5500/playground.html
// @icon https://www.google.com/s2/favicons?sz=64&domain=0.1
// @grant unsafeWindow
// @require [库地址]
// ==/UserScript==
// 没有中间层
initGlobalVar();
(async function () {
'use strict';
// TODO: 发布脚本时, 请去掉延时, 延时会导致 elmGetter 启动 setTimeout, 降低脚本性能, 这里设置延时, 仅仅是方便日志打印和调试bug
elmGetter.timeout = 300;
let el1 = await elmGetter.get(".comments");
let el2 = await elmGetter.get(".error");
})();
使用说明: 基本上和原版一致, 看cxxjackie的原文就好了, https://bbs.tampermonkey.net.cn/thread-2726-1-1.html, 这里主要的是接口参数有变化, 变成了options 传参
/**
* 异步的 querySelector
* @param selectorOrSelectors 选择器, 可以为数组
* @param options 一个对象
* - parent 父元素, 默认值是 document
* - timeout 设置 get 的超时时间, 默认值是 elmGetter.timeout, 其值默认为 0
* - 如果该值为 0, 表示永不超时, 如果 selector 有误, 返回的 Promise 将永远 pending
* - 如果该值不为 0, 表示等待多少毫秒, 和 setTimeout 单位一致
* - onError 超时后的失败回调, 参数为 selector, 默认值为 elmGetter.onError, 其默认行为是 console.warn 打印 selector
* - isPending 超时后 Promise 是否仍然保持 pending, 默认值为 elmGetter.isPending, 其值默认为 true
* - errEl 超时后 Promise 返回的值, 需要 isPending 为 false 才能有效, 默认值为 elmGetter.errorEl,
* 其值默认为一个 "class 为 no-found" "remove 为 () => {}" 的元素
* @return 根据参数决定返回值
* isPending 为 true
* 如果 selector 为 字符串数组, 则返回 Promise<Element[]>
* 如果 selector 为 字符串, 则返回 Promise<Element>
*
* isPending 为 false
* 如果 selector 为 字符串数组, 则返回 Promise<Element[] | typeof errEl>
* 如果 selector 为 字符串, 则返回 Promise<Element | typeof errEl>
*/
get(selectorOrSelectors, options = {}) {
let {
parent = doc,
timeout = this.timeout,
onError = this.onError,
isPending = this.isPending,
errEl = this.errEl,
} = options;
/**
* 设置监听，所有符合选择器的元素（包括页面已有的和新插入的）都将被传给回调函数处理，
* each方法适用于各种 滚动加载的列表（如评论区），或者发生 非刷新跳转的页面 (SPA)等
*
* @param selector 选择器
* @param callback 回调函数, 在每个目标元素上触发一次。
* 回调函数接收 2 个参数
* 第一个是符合选择器的元素
* 第二个表明该元素是否为新插入的（已有为 false，插入为 true）
* 已有的为 querySelectorAll 搜索出来的
* 插入的为 MutationObserver 监听到的
*
* callback 类型为 (el: Element, isNew: boolean) => boolean
* 如果 callback 返回值 === false, 则停止监听
*
* @param options 一个对象
* - parent 父元素, 默认值是 document
*
* @return void
*/
each(selector, callback, options = {}) {
let {
parent = doc,
} = options;
/**
* 渲染器, 将 html 字符串渲染为元素
* 渲染也就是 解析 并 挂载 元素
* 解析为: innerHTML = domString
* 挂载为: appendChild
*
* @param domString html 字符串
* @param options 一个对象
* - parent 父节点，将创建的元素添加到父节点末尾处, 如果不指定, 解析后的元素将 remove, 而不会被挂载
* 默认值为 doc.body
*
* - returnList 布尔值，是否返回以 id 作为索引的元素列表, 默认值为 false
* 如 create('<div id="myId"></div>`)
* 返回 { myId: <div id="myId"></div> (HTMLElement) }
*
* @returns {Element|{[id:string]: Element}|null} 元素或对象，取决于 returnList 参数
*/
create(domString, options = {}) {
let {
returnList = false,
parent = doc.body
} = options;
let errEl = document.createElement('div');
errEl.classList.add('no-found');
errEl.remove = () => {};
return {
timeout: 0,
onError: (selector) => {console.warn(`[elmGetter] [get失败] selector为: ${selector} 的查询超时`)},
isPending: true,
errEl,
我为elmGetter打造了一整套原版源码分析指南，旨在帮大家掌握源码修改技巧，让elmGetter成为你的如意兵器。
指南内容涵盖MutationObserve快速上手、源码分析思路与知识点补充，还将经典的WaitForKeyElememt异步库设计作为附录。
目前已近万字，我仍在精简润色，后续会拆分成多篇文章，整理目录后发布于脚本猫论坛，敬请期待！ (◦˙▽˙◦)
文档链接: https://bbs.tampermonkey.net.cn/thread-8196-1-1.html
原版存在的问题: 当一个脚本有40，50个异步查询的时候，开发的过程中不小心填错了某个选择器，或某个选择器失效了，由于elmGetter的默认策略就是无限等待pending，也不会控制台输出，所以排查问题变得比较棘手 唯一的解决方案是设置timeout参数，elmGetter超时后，判断其resolve的值是否为null 这里存在三个问题，
使用了魔改库后，解决了这三个问题
摘要: elmGetter 魔改版的主要改进，增加了错误处理回调，方便找不到元素的时候打印日志，排查错误 在elmGetter 魔改版找不到元素的时候，默认错误处理是console.warn 而且支持全局统一设置超时时间，等发布脚本的时候直接把那行注释掉就可以了
感谢 cxxjackie 大佬的开源，正是有了他的贡献，我才能站在巨人的肩膀上；感谢脚本猫脚本站的站长和管理员，正是有了这个平台，脚本分享和交流才变得如此便捷。最后，衷心感谢每一位用户的支持！祝你们用得开心!
✿✿ヽ(°▽°)ノ✿完结撒花！