☰

Greasy Fork is available in English.

UserscriptAPI

My API for userscripts.

As of 10.12.2022. See ბოლო ვერსია.

ეს სკრიპტი არ უნდა იყოს პირდაპირ დაინსტალირებული. ეს ბიბლიოთეკაა, სხვა სკრიპტებისთვის უნდა ჩართეთ მეტა-დირექტივაში // @require https://update.greatest.deepsurf.us/scripts/409641/1126983/UserscriptAPI.js. 

  1. /* exported UserscriptAPI */
  2. /**
  3.  * UserscriptAPI
  4.  *
  5.  * 需要引入模块方可工作，详见 `README.md`。
  6.  * @version 2.2.0.20210925
  7.  * @author Laster2800
  8.  * @see {@link https://gitee.com/liangjiancang/userscript/tree/master/lib/UserscriptAPI UserscriptAPI}
  9.  */
  10. class UserscriptAPI {
  11.   /** @type {{[name: string]: Function}} 可访问模块 */
  12.   static #modules = {}
  13.   /** @type {string[]} 待添加模块样式队列 */
  14.   #moduleCssQueue = []
  15.  
  16.   /**
  17.    * @param {Object} [options] 选项
  18.    * @param {string} [options.id='default'] 标识符
  19.    * @param {string} [options.label] 日志标签，为空时不设置标签
  20.    * @param {Object} [options.wait] `wait` API 默认选项（默认值见构造器代码）
  21.    * @param {Object} [options.wait.condition] `wait` 条件 API 默认选项
  22.    * @param {Object} [options.wait.element] `wait` 元素 API 默认选项
  23.    * @param {number} [options.fadeTime=400] UI 渐变时间
  24.    */
  25.   constructor(options) {
  26.     this.options = {
  27.       id: 'default',
  28.       label: null,
  29.       fadeTime: 400,
  30.       ...options,
  31.       wait: {
  32.         condition: {
  33.           callback: result => this.logger.info(result),
  34.           interval: 100,
  35.           timeout: 10000,
  36.           onTimeout: options => this.logger[options.stopOnTimeout ? 'error' : 'warn']('executeAfterConditionPassed: TIMEOUT', options),
  37.           stopOnTimeout: true,
  38.           stopCondition: null,
  39.           onStop: options => this.logger.error('executeAfterConditionPassed: STOP', options),
  40.           stopInterval: 50,
  41.           stopTimeout: 0,
  42.           onError: (options, e) => this.logger.error('executeAfterConditionPassed: ERROR', options, e),
  43.           stopOnError: true,
  44.           timePadding: 0,
  45.           ...options?.wait?.condition,
  46.         },
  47.         element: {
  48.           base: document,
  49.           exclude: null,
  50.           callback: el => this.logger.info(el),
  51.           subtree: true,
  52.           multiple: false,
  53.           repeat: false,
  54.           throttleWait: 100,
  55.           timeout: 10000,
  56.           onTimeout: options => this.logger[options.stopOnTimeout ? 'error' : 'warn']('executeAfterElementLoaded: TIMEOUT', options),
  57.           stopOnTimeout: false,
  58.           stopCondition: null,
  59.           onStop: options => this.logger.error('executeAfterElementLoaded: STOP', options),
  60.           onError: (options, e) => this.logger.error('executeAfterElementLoaded: ERROR', options, e),
  61.           stopOnError: true,
  62.           timePadding: 0,
  63.           ...options?.wait?.element,
  64.         },
  65.       },
  66.     }
  67.  
  68.     /** @type {UserscriptAPIDom} */
  69.     this.dom = this.#getModuleInstance('dom')
  70.     /** @type {UserscriptAPIMessage} */
  71.     this.message = this.#getModuleInstance('message')
  72.     /** @type {UserscriptAPIWait} */
  73.     this.wait = this.#getModuleInstance('wait')
  74.     /** @type {UserscriptAPIWeb} */
  75.     this.web = this.#getModuleInstance('web')
  76.  
  77.     if (!this.message) {
  78.       this.message = {
  79.         api: this,
  80.         alert: this.base.alert,
  81.         confirm: this.base.confirm,
  82.         prompt: this.base.prompt,
  83.       }
  84.     }
  85.  
  86.     for (const css of this.#moduleCssQueue) {
  87.       this.base.addStyle(css)
  88.     }
  89.   }
  90.  
  91.   /**
  92.    * 注册模块
  93.    * @param {string} name 模块名称
  94.    * @param {Object} module 模块类
  95.    */
  96.   static registerModule(name, module) {
  97.     this.#modules[name] = module
  98.   }
  99.   /**
  100.    * 获取模块实例
  101.    * @param {string} name 模块名称
  102.    * @returns {Object} 模块实例，无对应模块时返回 `null`
  103.    */
  104.   #getModuleInstance(name) {
  105.     const module = UserscriptAPI.#modules[name]
  106.     return module ? new module(this) : null
  107.   }
  108.  
  109.   /**
  110.    * 初始化模块样式（仅应在模块构造器中使用）
  111.    * @param {string} css 样式
  112.    */
  113.   initModuleStyle(css) {
  114.     this.#moduleCssQueue.push(css)
  115.   }
  116.  
  117.   /**
  118.    * UserscriptAPIBase
  119.    * @version 1.2.1.20210813
  120.    */
  121.   base = new class UserscriptAPIBase {
  122.     /**
  123.      * @param {UserscriptAPI} api `UserscriptAPI`
  124.      */
  125.     constructor(api) {
  126.       this.api = api
  127.     }
  128.  
  129.     /**
  130.      * 添加样式
  131.      * @param {string} css 样式
  132.      * @param {Document} [doc=document] 文档
  133.      * @returns {HTMLStyleElement} `<style>`
  134.      */
  135.     addStyle(css, doc = document) {
  136.       const { api } = this
  137.       const style = doc.createElement('style')
  138.       style.className = `${api.options.id}-style`
  139.       style.textContent = css
  140.       const parent = doc.head || doc.documentElement
  141.       if (parent) {
  142.         parent.append(style)
  143.       } else { // 极端情况下会出现，DevTools 网络+CPU 双限制可模拟
  144.         api.wait?.waitForConditionPassed({
  145.           condition: () => doc.head || doc.documentElement,
  146.           timeout: 0,
  147.         }).then(parent => parent.append(style))
  148.       }
  149.       return style
  150.     }
  151.  
  152.     /**
  153.      * 判断给定 URL 是否匹配
  154.      * @param {RegExp | RegExp[]} regex 用于判断是否匹配的正则表达式，或正则表达式数组
  155.      * @param {'OR' | 'AND'} [mode='OR'] 匹配模式
  156.      * @returns {boolean} 是否匹配
  157.      */
  158.     urlMatch(regex, mode = 'OR') {
  159.       let result = false
  160.       const { href } = location
  161.       if (Array.isArray(regex)) {
  162.         if (regex.length > 0) {
  163.           if (mode === 'AND') {
  164.             result = true
  165.             for (const ex of regex) {
  166.               if (!ex.test(href)) {
  167.                 result = false
  168.                 break
  169.               }
  170.             }
  171.           } else if (mode === 'OR') {
  172.             for (const ex of regex) {
  173.               if (ex.test(href)) {
  174.                 result = true
  175.                 break
  176.               }
  177.             }
  178.           }
  179.         }
  180.       } else {
  181.         result = regex.test(href)
  182.       }
  183.       return result
  184.     }
  185.  
  186.     /**
  187.      * 初始化 `urlchange` 事件
  188.      * @example
  189.      *  window.addEventListener('urlchange', e => { ... })
  190.      *  window.addEventListener('urlchange', e => e.stopPropagation(), true)
  191.      *  window.onurlchange = function(e) { ... }
  192.      * @see {@link https://stackoverflow.com/a/52809105 How to detect if URL has changed after hash in JavaScript}
  193.      * @see {@link https://stackoverflow.com/a/69342637 Event bubbles before captured on `window`}
  194.      */
  195.     initUrlchangeEvent() {
  196.       const win = typeof unsafeWindow === 'object' ? unsafeWindow : window
  197.       if (win[Symbol.for('onurlchange')] === undefined) {
  198.         let url = new URL(location.href)
  199.         const dispatchEvent = () => {
  200.           const event = new CustomEvent('urlchange', {
  201.             detail: { prev: url, curr: new URL(location.href) },
  202.             bubbles: true,
  203.           })
  204.           url = event.detail.curr
  205.           if (typeof window.onurlchange === 'function') { // 若直接调用则 eventPhase 不对，且会有一些其他问题
  206.             // 这一方案只能让事件处理器属性在最后被激活，但正确的顺序是：https://stackoverflow.com/a/49806959
  207.             // 要实现正确的顺序，需用 defineProperty 定义 onurlchange，但 Tampermonkey 已经定义了该属性
  208.             // 尽管目前 Tampermonkey 定义的属性是可写的，但为了向前兼容性及简化代码考虑，决定采用当前方案
  209.             window.addEventListener('urlchange', window.onurlchange, { once: true })
  210.           }
  211.           document.dispatchEvent(event) // 在 window 上 dispatch 不能确保在冒泡前捕获，至少目前是这样
  212.         }
  213.  
  214.         history.pushState = (f => (...args) => {
  215.           const ret = Reflect.apply(f, history, args)
  216.           dispatchEvent()
  217.           return ret
  218.         })(history.pushState)
  219.         history.replaceState = (f => (...args) => {
  220.           const ret = Reflect.apply(f, history, args)
  221.           dispatchEvent()
  222.           return ret
  223.         })(history.replaceState)
  224.         window.addEventListener('popstate', () => {
  225.           dispatchEvent()
  226.         })
  227.         win[Symbol.for('onurlchange')] = true
  228.       }
  229.     }
  230.  
  231.     /**
  232.      * 生成消抖函数
  233.      * @param {Function} fn 目标函数
  234.      * @param {number} [wait=0] 消抖延迟
  235.      * @param {Object} [options] 选项
  236.      * @param {boolean} [options.leading] 是否在延迟开始前调用目标函数
  237.      * @param {boolean} [options.trailing=true] 是否在延迟结束后调用目标函数
  238.      * @param {number} [options.maxWait=0] 最大延迟时间（非准确），`0` 表示禁用
  239.      * @returns {Function} 消抖函数 `debounced`，可调用 `debounced.cancel()` 取消执行
  240.      */
  241.     debounce(fn, wait = 0, options = {}) {
  242.       options = {
  243.         leading: false,
  244.         trailing: true,
  245.         maxWait: 0,
  246.         ...options,
  247.       }
  248.  
  249.       let tid = null
  250.       let start = null
  251.       let execute = null
  252.       let callback = null
  253.  
  254.       /** @this {*} thisArg */
  255.       function debounced(...args) {
  256.         execute = () => {
  257.           Reflect.apply(fn, this, args)
  258.           execute = null
  259.         }
  260.         callback = () => {
  261.           if (options.trailing) {
  262.             execute?.()
  263.           }
  264.           tid = null
  265.           start = null
  266.         }
  267.  
  268.         if (tid) {
  269.           clearTimeout(tid)
  270.           if (options.maxWait > 0 && Date.now() - start > options.maxWait) {
  271.             callback()
  272.           }
  273.         }
  274.  
  275.         if (!tid && options.leading) {
  276.           execute?.()
  277.         }
  278.  
  279.         if (!start) {
  280.           start = Date.now()
  281.         }
  282.  
  283.         tid = setTimeout(callback, wait)
  284.       }
  285.  
  286.       debounced.cancel = function() {
  287.         if (tid) {
  288.           clearTimeout(tid)
  289.           tid = null
  290.           start = null
  291.         }
  292.       }
  293.  
  294.       return debounced
  295.     }
  296.  
  297.     /**
  298.      * 生成节流函数
  299.      * @param {Function} fn 目标函数
  300.      * @param {number} [wait=0] 节流延迟（非准确）
  301.      * @returns {Function} 节流函数 `throttled`，可调用 `throttled.cancel()` 取消执行
  302.      */
  303.     throttle(fn, wait = 0) {
  304.       return this.debounce(fn, wait, {
  305.         leading: true,
  306.         trailing: true,
  307.         maxWait: wait,
  308.       })
  309.     }
  310.  
  311.     /**
  312.      * 创建基础提醒对话框（异步）
  313.      *
  314.      * 若没有引入 `message` 模块，可使用 `api.message.alert()` 引用该方法。
  315.      * @param {string} msg 信息
  316.      */
  317.     alert(msg) {
  318.       const { label } = this.api.options
  319.       return new Promise(resolve => {
  320.         resolve(alert(`${label ? `${label}\n\n` : ''}${msg}`))
  321.       })
  322.     }
  323.  
  324.     /**
  325.      * 创建基础确认对话框（异步）
  326.      *
  327.      * 若没有引入 `message` 模块，可使用 `api.message.confirm()` 引用该方法。
  328.      * @param {string} msg 信息
  329.      * @returns {Promise<boolean>} 用户输入
  330.      */
  331.     confirm(msg) {
  332.       const { label } = this.api.options
  333.       return new Promise(resolve => {
  334.         resolve(confirm(`${label ? `${label}\n\n` : ''}${msg}`))
  335.       })
  336.     }
  337.  
  338.     /**
  339.      * 创建基础输入对话框（异步）
  340.      *
  341.      * 若没有引入 `message` 模块，可使用 `api.message.prompt()` 引用该方法。
  342.      * @param {string} msg 信息
  343.      * @param {string} [val] 默认值
  344.      * @returns {Promise<string>} 用户输入
  345.      */
  346.     prompt(msg, val) {
  347.       const { label } = this.api.options
  348.       return new Promise(resolve => {
  349.         resolve(prompt(`${label ? `${label}\n\n` : ''}${msg}`, val))
  350.       })
  351.     }
  352.   }(this)
  353.  
  354.   /**
  355.    * UserscriptAPILogger
  356.    * @version 1.2.0.20210925
  357.    */
  358.   logger = new class UserscriptAPILogger {
  359.     #logCss = `
  360.       background-color: black;
  361.       color: white;
  362.       border-radius: 2px;
  363.       padding: 2px;
  364.       margin-right: 4px;
  365.     `
  366.  
  367.     /**
  368.      * @param {UserscriptAPI} api `UserscriptAPI`
  369.      */
  370.     constructor(api) {
  371.       this.api = api
  372.     }
  373.  
  374.     /**
  375.      * 打印格式化日志
  376.      * @param {'info' | 'warn' | 'error'} fn 日志函数名
  377.      * @param {*[]} message 日志信息
  378.      */
  379.     #log(fn, ...message) {
  380.       const output = console[fn]
  381.       const label = this.api.options.label ?? ''
  382.       const causes = []
  383.       let template = null
  384.       if (message.length > 0) {
  385.         const types = []
  386.         for (const [idx, m] of message.entries()) {
  387.           if (m) {
  388.             types.push(typeof m === 'string' ? '%s' : '%o')
  389.             if (m instanceof Error && m.cause !== undefined) {
  390.               causes.push(m.cause)
  391.             }
  392.           } else {
  393.             if (m === undefined) {
  394.               message[idx] = '[undefined]'
  395.             } else if (m === null) {
  396.               message[idx] = '[null]'
  397.             } else if (m === '') {
  398.               message[idx] = '[empty string]'
  399.             }
  400.             types.push(typeof message[idx] === 'string' ? '%s' : '%o')
  401.           }
  402.         }
  403.         template = types.join(', ')
  404.       } else {
  405.         template = '[undefined]'
  406.       }
  407.       output(`%c${label}%c${template}`, this.#logCss, null, ...message)
  408.       for (const [idx, cause] of causes.entries()) {
  409.         output(`%c${label}%c${idx + 1}-th error is caused by %o`, this.#logCss, null, cause)
  410.       }
  411.     }
  412.  
  413.     /**
  414.      * 打印日志
  415.      * @param {*[]} message 日志信息
  416.      */
  417.     info(...message) {
  418.       this.#log('info', ...message)
  419.     }
  420.  
  421.     /**
  422.      * 打印警告日志
  423.      * @param {*[]} message 警告日志信息
  424.      */
  425.     warn(...message) {
  426.       this.#log('warn', ...message)
  427.     }
  428.  
  429.     /**
  430.      * 打印错误日志
  431.      * @param {*[]} message 错误日志信息
  432.      */
  433.     error(...message) {
  434.       this.#log('error', ...message)
  435.     }
  436.   }(this)
  437. }