UserScript

January 29, 2023

metadata

https://violentmonkey.github.io/api/gm/
https://www.tampermonkey.net/documentation.php?locale=zh
https://wiki.greasespot.net/Greasemonkey_Manual:API
https://docs.scriptcat.org/docs/dev/api/
https://www.chromium.org/developers/design-documents/user-scripts/

项目相关

// ==UserScript==
// @name          Violentmonkey Script
// @name:zh-CN    暴力猴脚本
// @namespace https://violentmonkey.github.io #此字段一般填写项目主页，非必须
// @version 1.0
// @description         This script rocks.
// @description:zh-CN   这个脚本很棒！
// @icon https://my.cdn.com/icon.png #也可以使用 data:image/jpeg;base64,xxx
// ==/UserScript==

运行相关

// @require https://my.cdn.com/jquery.js
// @run-at #考虑到兼容性此字段可以不填，一般默认运行在DOMContentLoaded事件发送后
// @noframes #不需要值，出现此字段则脚本不在frame中执行
// @resource logo https://my.cdn.com/logo.png  #此字段声明了允许通过GM_getResourceText()和GM_getResourceURL()函数拿到的资源
// @resource text https://my.cdn.com/some-text.txt
// @connect tampermonkey.net #此字段声明了允许通过GM_xmlhttpRequest()函数访问的域名，指定顶级域名会同时允许其子域名
// @grant none #默认值，允许脚本直接获取真实的DOM，相当于直接在页面中载入了一个脚本（但可以获取GM_info对象，@require同理）
// @grant unsafeWindow #隔离浏览器上下文，unsafeWindow指向真实页面的window对象（@require虽然也隔离上下文，但可以直接访问DOM）
// @grant GM_setValue
// @grant GM_getValue
// @grant GM_setClipboard
// @grant window.close
// @grant window.focus
// @grant window.onurlchange

小技巧，绕过 unsafeWindow

console.log(GM_setValue); // OK

function main() {
    console.log(window);
    // console.log(GM_setValue); // Uncaught ReferenceError: GM_setValue is not defined
}
const script = document.createElement("script");
script.textContent = "(" + main.toString() + ")();";
document.body.appendChild(script);

网址匹配

https://developer.chrome.com/docs/extensions/mv3/match_patterns/

// @match *://*.google.com/foo*bar #不匹配锚点
// @include /\.com\.hk\// #不建议使用，使用@match即可
// @exclude 与include相反

更新相关

// @downloadURL #此字段用于检测更新
// @supportURL #此字段指定了“反馈”按钮指向的地址
// @homepageURL #主页

GM functions

持久化存储

键名为字符串，值是通过 JSON 序列化

let value = GM_getValue(key, defaultValue);

GM_setValue(key, value); // GM_setValue(String(key), value)

GM_deleteValue(key);

let arrayOfKeys = GM_listValues();

let listenerId = GM_addValueChangeListener(key, (key, oldValue, newValue, remote) => void);

GM_removeValueChangeListener(listenerId)

获取资源

// @resource logo https://my.cdn.com/logo.png
// @resource text https://my.cdn.com/some-text.txt

let text = GM_getResourceText("text");

let blobUrl = GM_getResourceURL("logo");
let blobOrDataUrl = GM_getResourceURL("logo", isBlobUrl);

DOM

let element1 = GM_addElement(tagName, attributes);
let element2 = GM_addElement(parentNode, tagName, attributes);

let styleElement = GM_addStyle(css);

let tabControl = GM_openInTab(url, openInBackground);
let tabControl = GM_openInTab(url);
tabControl.onclose = () => console.log(tabControl.closed === true);
tabControl.close();

杂项

const id = GM_registerMenuCommand(caption, onClick);
GM_unregisterMenuCommand(caption);

GM_setClipboard(data, type ?? "text/plain");

GM_notification({ text, title, image, onclick, ondone });
GM_notification(text, title, image, onclick);

// 不受限制的 xmlhttpRequest
let control = GM_xmlhttpRequest({
    url: "https://example.net/",
    method: "POST",
    data: "string | ArrayBuffer | Blob | DataView | FormData | ReadableStream | TypedArray | URLSearchParams",
    headers: {
        Referer: "https://example.com/",
        "User-Agent": "GM",
    },
    responseType: "text", // or "json" or "blob" or "arraybuffer"
    timeout: 3000,
});
control.onabort = (res) => {};
control.onerror = (res) => {};
control.onload = (res) => {};
control.onloadend = (res) => {};
control.onloadstart = (res) => {};
control.onprogress = (res) => {};
control.onreadystatechange = (res) => {};
control.ontimeout = (res) => {};
// const { status, statusText, readyState, responseHeaders, response, finalUrl } = res;

GM_download({ url, name /* 选项同 GM_xmlhttpRequest */ });
GM_download(url, name);

通过 GM_xmlhttpRequest 实现 GM_fetch，参见
https://github.com/Trim21/gm-fetch
https://github.com/AlttiRi/gm_fetch
https://github.com/mitchellmebane/GM_fetch

/* 例如 */

// ==UserScript==
// @name        GM_fetch
// @match       *://*/*
// @connect     *
// @grant       unsafeWindow
// @grant       GM_xmlhttpRequest
// @require     https://raw.githubusercontents.com/mitchellmebane/GM_fetch/master/GM_fetch.min.js
// ==/UserScript==

GM_fetch("http://ip.42.pl/raw")
    .then((res) => res.text())
    .then(console.log);

`GM.*` async

https://violentmonkey.github.io/api/gm/#gm

←Back to home