☰

wait-for-element

Provides utility functions to get and wait for elements asyncronously that are not yet loaded or available on the page.

目前为 2024-02-24 提交的版本。查看 最新版本。

此脚本不应直接安装，它是一个供其他脚本使用的外部库。如果您需要使用该库，请在脚本元属性加入：// @require https://update.cn-greasyfork.org/scripts/488161/1332704/wait-for-element.js 

  1. // ==UserScript==
  2. // @name         wait-for-element
  3. // @description  Provides utility functions to get and wait for elements asyncronously that are not yet loaded or available on the page.
  4. // @version      0.0.1
  5. // @namespace    owowed.moe
  6. // @author       owowed <island@owowed.moe>
  7. // @require      https://update.greasyfork.org/scripts/488160/1332703/make-mutation-observer.js
  8. // @license      LGPL-3.0
  9. // ==/UserScript==
  10.  
  11. /**
  12.  * @typedef WaitForElementOptions
  13.  * @prop {string} [id] - when used, it will select element by ID, and it will use the `document` as the selector parent.
  14.  * @prop {string | string[]} selector - the selector for the element. If `selector` is `string[]`, then `multiple` option is automatically enabled. Setting `multiple` option to `false` will not have effect at all.
  15.  * @prop {ParentNode} [parent] - when used, it will instead use `parent` parent element as the selector parent. This option will specify/limit the scope of query selector from `parent` parent element. This may be useful for optimizing selecting element.
  16.  * @prop {AbortSignal} [abortSignal] - when used, user may able to abort waiting for element by using `AbortSignal#abort()`.
  17.  * @prop {boolean} [multiple] - when used, `waitForElement*` will act as `ParentNode#querySelectorAll()`.
  18.  * @prop {number} [timeout] - will set wait for element timeout. Default timeout is 5 seconds.
  19.  * @prop {boolean} [enableTimeout] - if timeout set by `timeout` reached, `waitForElement*` will throw `WaitForElementTimeoutError`.
  20.  * @prop {number} [maxTries] - will set how many attempt `waitForElement*` will query select, and if it reached, it will throw `WaitForElementMaximumTriesError`.
  21.  * @prop {boolean} [ensureDomContentLoaded] - ensure DOM content loaded by listening to `DOMContentLoad` event, and then execute by that, or checking by using `document.readyState`.
  22.  * @prop {MutationObserverInit} [observerOptions] - set options for `MutationObserver` used in `waitForElement*`.
  23.  * @prop {(elem: HTMLElement) => boolean} [filter] - filter multiple or single element before being returned.
  24.  * @prop {(elem: HTMLElement) => HTMLElement} [transform] - transform or modify multiple or single element before being returned.
  25.  */
  26.  
  27. /**
  28.  * @typedef {Element[] | Element | null} WaitForElementReturnValue
  29.  */
  30.  
  31. class WaitForElementError extends Error {
  32.     name = this.constructor.name;
  33. }
  34. class WaitForElementTimeoutError extends WaitForElementError {}
  35. class WaitForElementMaximumTriesError extends WaitForElementError {}
  36.  
  37. /**
  38.  * Wait for element asyncronously until the element is available on the page. This function immediately accept `parent` as its first parameter. `parent` parameter will specify/limit the scope of query selector. This may be useful for optimizing selecting element.
  39.  * @param {NonNullable<WaitForElementOptions["parent"]>} parent 
  40.  * @param {WaitForElementOptions["selector"]} selector 
  41.  * @param {WaitForElementOptions} options 
  42.  * @returns {WaitForElementReturnValue}
  43.  */
  44. function waitForElementByParent(parent, selector, options) {
  45.     return waitForElementOptions({ selector, parent, ...options });
  46. }
  47.  
  48. /**
  49.  * Wait for element asyncronously until the element is available on the page. This function immediately accept `selector` as its first parameter.
  50.  * @param {WaitForElementOptions["selector"]} selector 
  51.  * @param {WaitForElementOptions} options 
  52.  * @returns {WaitForElementReturnValue}
  53.  */
  54. function waitForElement(selector, options) {
  55.     return waitForElementOptions({ selector, ...options });
  56. }
  57.  
  58. /**
  59.  * Wait for element asyncronously until the element is available on the page.
  60.  * @param {WaitForElementOptions} options 
  61.  * @returns {WaitForElementReturnValue}
  62.  */
  63. function waitForElementOptions(
  64.     { id,
  65.         selector,
  66.         parent = document.documentElement,
  67.         abortSignal, // abort controller signal
  68.         multiple = false,
  69.         timeout = 5000,
  70.         enableTimeout = true,
  71.         maxTries = Number.MAX_SAFE_INTEGER,
  72.         ensureDomContentLoaded = true,
  73.         observerOptions = {},
  74.         filter,
  75.         transform,
  76.         throwError } = {}) {
  77.     return new Promise((resolve, reject) => {
  78.         let result, tries = 0;
  79.         
  80.         function* applyFilterTransform(result) {
  81.             if (filter != undefined) {
  82.                 for (let elem of result) {
  83.                     if (filter(elem)) {
  84.                         if (transform) elem = transform(elem);
  85.                         yield elem;
  86.                     }
  87.                 }
  88.             }
  89.             else if (transform != undefined) {
  90.                 for (const elem of result) {
  91.                     yield transform(elem);
  92.                 }
  93.             }
  94.         }
  95.  
  96.         function tryQueryElement(observer) {
  97.             abortSignal?.throwIfAborted();
  98.  
  99.             if (multiple && id == undefined) {
  100.                 if (Array.isArray(selector)) {
  101.                     result = [];
  102.                     for (const sel of selector) {
  103.                         result = result.concat(Array.from(parent.querySelectorAll(sel)));
  104.                     }
  105.                 }
  106.                 else {
  107.                     result = Array.from(parent.querySelectorAll(selector));
  108.                 }
  109.                 result = Array.from(applyFilterTransform(result));
  110.             }
  111.             else {
  112.                 if (id) {
  113.                     result = document.getElementById(id);
  114.                 }
  115.                 else if (Array.isArray(selector)) {
  116.                     result = [];
  117.  
  118.                     function* querySelectorIterator() {
  119.                         for (const sel of selector) {
  120.                             yield parent.querySelector(sel);
  121.                         }
  122.                     }
  123.  
  124.                     result = Array.from(applyFilterTransform(querySelectorIterator()));
  125.                 }
  126.                 else {
  127.                     result = parent.querySelector(selector);
  128.                 }
  129.                 if (transform) result = transform(result);
  130.                 if (filter != undefined && !filter(result)) {
  131.                     return false;
  132.                 }
  133.             }
  134.  
  135.             if (multiple ? result?.length > 0 : result) {
  136.                 observer?.disconnect();
  137.                 resolve(result);
  138.                 return result;
  139.             }
  140.  
  141.             tries++;
  142.  
  143.             if (tries >= maxTries) {
  144.                 observer?.disconnect();
  145.                 if (throwError) {
  146.                     reject(new WaitForElementMaximumTriesError(`maximum number of tries (${maxTries}) reached waiting for element "${selector}"`));
  147.                 }
  148.                 else {
  149.                     resolve(null);
  150.                 }
  151.                 return false;
  152.             }
  153.         }
  154.  
  155.         function startWaitForElement() {
  156.             const firstResult = tryQueryElement();
  157.  
  158.             if (firstResult) return;
  159.             
  160.             let observer = makeMutationObserver(
  161.                 { target: parent,
  162.                     childList: true,
  163.                     subtree: true,
  164.                     abortSignal,
  165.                     ...observerOptions },
  166.                 () => tryQueryElement(observer));
  167.     
  168.             let timeoutId = null;
  169.     
  170.             if (enableTimeout) {
  171.                 timeoutId = setTimeout(() => {
  172.                     observer.disconnect();
  173.                     if (throwError) {
  174.                         reject(new WaitForElementTimeoutError(`timeout waiting for element "${selector}"`));
  175.                     }
  176.                     else {
  177.                         resolve(null);
  178.                     }
  179.                 }, timeout);
  180.             }
  181.     
  182.             abortSignal?.addEventListener("abort", () => {
  183.                 clearTimeout(timeoutId);
  184.                 observer.disconnect();
  185.                 if (throwError) {
  186.                     reject(new DOMException(abortSignal.reason, "AbortError"));
  187.                 }
  188.                 else {
  189.                     resolve(null);
  190.                 }
  191.             });
  192.     
  193.             tryQueryElement();
  194.         }
  195.  
  196.         if (ensureDomContentLoaded && document.readyState == "loading") {
  197.             document.addEventListener("DOMContentLoaded", () => {
  198.                 startWaitForElement();
  199.             });
  200.         }
  201.         else {
  202.             startWaitForElement();
  203.         }
  204.     });
  205. }