Tampermonkey 油猴脚本中文文档

文章目录

• @name
• @namespace
• @copyright
• @version
• @description
• @icon, @iconURL, @defaulticon
• @icon64, @icon64URL
• @grant
• @author
• @homepage, @homepageURL, @website, @source
• @antifeature
• @require
• @resource
• @include
• @match
• @exclude
• @run-at
• @sandbox
• @connect
• @noframes
• @updateURL
• @downloadURL
• @supportURL
• @webRequest
• @unwrap
• unsafeWindow
• Subresource Integrity
• GM_addElement(tag_name, attributes), GM_addElement(parent_node, tag_name, attributes)
• GM_addStyle(css)
• GM_download(details), GM_download(url, name)
• GM_getResourceText(name)
• GM_getResourceURL(name)
• GM_info
• GM_log(message)
• GM_notification(details, ondone), GM_notification(text, title, image, onclick)
• GM_openInTab(url, options), GM_openInTab(url, loadInBackground)
• GM_registerMenuCommand(name, callback, accessKey)
• GM_unregisterMenuCommand(menuCmdId)
• GM_setClipboard(data, info)
• GM_getTab(callback)
• GM_saveTab(tab)
• GM_getTabs(callback)
• GM_setValue(key, value)
• GM_getValue(key, defaultValue)
• GM_deleteValue(key)
• GM_listValues()
• GM_addValueChangeListener(key, (key, old_value, new_value, remote) => void)
• GM_removeValueChangeListener(listenerId)
• GM_xmlhttpRequest(details)
• GM_webRequest(rules, listener)
• 示例
• GM_cookie.list(details[, callback])
• GM_cookie.set(details[, callback])
• GM_cookie.delete(details, callback)
• window.onurlchange
• window.close
• window.focus

油猴脚本中文文档

由 ChatGPT 翻译。

用户脚本标题

@name

脚本的名称。通过添加命名区域的附录来进行国际化。

// @name    A test
// @name:de Ein Test

@namespace

脚本的命名空间。可以使用一个与网站或项目相关的标识符，如 URL、公司名等全局唯一的标识符。

@copyright

版权声明，显示在脚本编辑器标题下方的头部。

@version

脚本版本，用于更新检查，每次更新都需要增加版本号。版本号比较规则如下：

• 在该列表中，下一个条目被认为是更高的版本号，例如：Alpha-v1<Alpha-v10，16.4 == 16.04。
• 示例版本号：Alpha-v1、Alpha-v10、Alpha-v2、Beta、0.5pre3、0.5prelimiary、0.6pre4、0.6pre5、0.7pre4、0.7pre10、1.-1、1 == 1. == 1.0 == 1.0.0、1.1a、1.1aa、1.1ab、1.1b、1.1c、1.1.-1、1.1 == 1.1.0 == 1.1.00、1.1.1.1.1、1.1.1.1.2、1.1.1.1、1.10.0-alpha、1.10 == 1.10.0、1.11.0-alpha、1.11.0-alpha.1、1.11.0-alpha+1、1.11.0-0.3.7、1.12+1 == 1.12+1.0、1.12+1.1 == 1.12+1.1.0、1.12+2、1.12+2.1、1.12+3、1.12+4、1.12、2.0、16.4 == 16.04。

@description

一个简短而重要的描述，通过添加指定区域的附录来实现国际化。

// @description    This userscript does wonderful things
// @description:de Dieses Userscript tut wundervolle Dinge

@icon, @iconURL, @defaulticon

脚本的低分辨率图标。

@icon64, @icon64URL

此脚本的 64×64 像素图标。如果存在这个标签，但没有@icon，则@icon图像将在选项页面的某些位置进行缩放。

@grant

@grant用于将GM_*和GM.*函数、unsafeWindow对象以及一些强大的window函数加入白名单。

javascript

// @grant GM_setValue
// @grant GM_getValue
// @grant GM.setValue
// @grant GM.getValue
// @grant GM_setClipboard
// @grant unsafeWindow
// @grant window.close
// @grant window.focus
// @grant window.onurlchange

由于关闭和聚焦选项卡是一项强大的功能，因此也需要将其添加到@grant语句中。如果@grant后面跟着none，则禁用沙箱。在此模式下，除了GM_info属性外，将不可用GM_*函数。

// @grant none

如果没有给出@grant标签，则假定为空列表，但这与使用none是不同的。

@author

脚本的作者。

@homepage, @homepageURL, @website, @source

作者的主页，在选项页面上用于将脚本名称链接到给定页面。请注意，如果@namespace标签以http://开头，则其内容也将用作主页链接。

@antifeature

此标签允许脚本开发人员披露他们是否将其脚本商业化。例如，GreasyFork 要求此信息。
语法：<tag> <type> <description>
<type>可以有以下值：

• ads：广告
• tracking：追踪
• miner：挖矿

// @antifeature       ads         We show you ads 我们显示广告
// @antifeature:fr    ads         Nous vous montrons des publicités 我们向您展示广告
// @antifeature       tracking    We have some sort of analytics included 我们包含某种类型的分析工具
// @antifeature       miner       We use your computer's resources to mine a crypto currency 我们使用您计算机的资源来挖掘加密货币

通过添加区域附录来实现国际化。

@require

指向一个在脚本自身开始运行之前加载和执行的 JavaScript 文件。请注意：通过@require加载的脚本及其使用严格模式的声明可能会影响用户脚本的严格模式！

// @require https://code.jquery.com/jquery-2.1.4.min.js
// @require https://code.jquery.com/jquery-2.1.3.min.js#sha256=23456...
// @require https://code.jquery.com/jquery-2.1.2.min.js#md5=34567...,sha256=6789...
// @require tampermonkey://vendor/jquery.js
// @require tampermonkey://vendor/jszip/jszip.js

请参考子资源完整性部分，了解如何确保资源的完整性。允许多个标签实例。

@resource

通过脚本可以通过GM_getResourceURL和GM_getResourceText来预加载资源。

// @resource icon1       http://www.tampermonkey.net/favicon.ico
// @resource icon2       /images/icon.png
// @resource html        http://www.tampermonkey.net/index.html
// @resource xml         http://www.tampermonkey.net/crx/tampermonkey.xml
// @resource SRIsecured1 http://www.tampermonkey.net/favicon.ico#md5=123434...
// @resource SRIsecured2 http://www.tampermonkey.net/favicon.ico#md5=123434...;sha256=234234...

请查看 sub - resource integrity 部分，以获取有关如何确保完整性的更多信息。允许多个标签实例。

@include

脚本应该运行的页面。允许多个标签实例。@include 不支持 URL 哈希参数，必须匹配没有哈希参数的路径，并利用 window.onurlchange。

// @include http://www.tampermonkey.net/*
// @include http://*
// @include https://*
// @include /^https:\/\/2.zoppoz.workers.dev:443\/https\/www\.tampermonkey\.net\/.*$/
// @include *

注意：当写类似于*://tmnk.net/*的内容时，许多脚本开发者期望脚本只在tmnk.net上运行，但实际情况并非如此。它也会在https://example.com/?http://tmnk.net/上运行。因此，Tampermonkey 在@include包含://的情况下会像@match一样进行解释。://之前的每个*仅匹配除:字符之外的所有内容，以确保仅匹配 URL 方案。此外，如果这样的@include在://之后包含/，那么在这些字符串之间的所有内容都被视为主机，匹配除/字符之外的所有内容。相同的规则适用于直接跟在://后面的*。

@match

在 Tampermonkey 中，@match指令用于指定脚本应该运行的网页。@match的值应该是一个 URL 模式，与希望脚本运行的页面匹配。URL 模式格式为：// @match <protocol>://<domain><path>

• protocol：URL 的第一部分，在冒号之前，指定页面使用的协议，如http或https，*匹配所有协议。
• domain：URL 的第二部分，在协议和两个斜杠之后，指定网站的域名，如tmnk.com。可以使用通配符*.tmnk.net来匹配tmnk.net及其任何子域名，如www.tmnk.net。
• path：URL 的一部分，位于域名之后，可能包括其他子目录或文件名。可以使用通配符*来匹配路径的任何部分。
  注意：尚不支持<all_urls>声明，协议部分还接受http*://。允许多个标签实例。
  更多示例：

// @match *://*/*
// @match https://*/*
// @match http://*/foo*
// @match https://*.tampermonkey.net/foo*bar

@exclude

即使包含在@include或@match中，也要排除 URL。允许多个标签实例。

@run-at

定义脚本注入的时机。与其他脚本处理程序相反，@run-at定义了脚本希望运行的最早时刻。这意味着，如果一个使用了@require标签的脚本在文档加载完成后才执行，那是因为获取所需脚本花费了很长时间。无论如何，所有在给定注入时刻之后发生的 DOMNodeInserted 和 DOMContentLoaded 事件都会被缓存，并在脚本注入时交付给脚本。

// @run-at document-start // 脚本将尽快被注入。
// @run-at document-body // 如果body元素存在，脚本将被注入。
// @run-at document-end // 在DOMContentLoaded事件被触发时或之后，脚本将被注入。
// @run-at document-idle // 在DOMContentLoaded事件被触发后，脚本将被注入。如果没有给出@run-at标签，这是默认值。
// @run-at context-menu // 如果在浏览器的上下文菜单中点击脚本，将会被注入（仅适用于桌面版基于Chrome的浏览器）。注意：如果使用此值，所有的@include和@exclude语句将被忽略，但这可能会在将来改变。

@sandbox

@sandbox允许 Tampermonkey 决定用户脚本的注入位置：

• MAIN_WORLD：页面
• ISOLATED_WORLD：扩展的内容脚本
• USERSCRIPT_WORLD：为用户脚本创建的特殊上下文
  @sandbox支持三个可能的参数：
• raw："Raw" 访问模式意味着脚本由于兼容性原因始终需要在页面上下文中（MAIN_WORLD）运行。目前，如果省略@sandbox，则此模式是默认模式。
• JavaScript："JavaScript" 访问模式意味着脚本需要访问unsafeWindow。在 Firefox 中，会创建一个特殊的上下文，即 USERSCRIPT_WORLD，应该也会绕过所有剩余的 CSP 问题。然而，它可能会引入新问题，因为现在需要使用cloneInto和exportFunction来与页面共享对象。在其他浏览器中，将使用raw模式作为后备。
• DOM：如果脚本只需要 DOM 而不需要直接访问unsafeWindow，请使用此访问模式。如果已启用，这些脚本将在扩展上下文（ISOLATED_WORLD）中执行，或者在其他已启用的上下文中执行，因为它们都允许访问 DOM。

// @sandbox JavaScript

@connect

此标签定义了可以由 GM_xmlhttpRequest 检索的域（非顶级域），包括子域。

// @connect <value>

<value>可以是：

• 域名，如example.com（这也将允许所有子域）。
• 子域名，如subdomain.example.com。
• self，以允许脚本当前所在的域。
• localhost，以访问本地主机。
• IP 地址，如1.2.3.4。
• *。
  如果无法声明用户脚本可能连接到的所有域，建议：
• 声明所有已知或至少常见的脚本可能连接到的域，以避免对大多数用户显示确认对话框。
• 另外，在脚本中添加@connect *，允许 Tampermonkey 提供一个 “始终允许所有域” 的按钮。
  用户还可以通过将*添加到用户域白名单中来将所有请求列入白名单。
  注意：
• 会检查初始 URL 和最终 URL！
• 为了向后兼容 Scriptish，@domain标签也会被解释。
  允许多个标签实例。
  更多示例：

// @connect tmnk.net
// @connect www.tampermonkey.net
// @connect self
// @connect localhost
// @connect 8.8.8.8
// @connect *

@noframes

这个标签使脚本在主页面上运行，但不在 iframe 上运行。

@updateURL

用户脚本的更新 URL。注意：为了使更新检查起作用，需要使用@version标签。

@downloadURL

定义检测到更新时脚本将从中下载的 URL。如果使用值 none，则不会进行更新检查。

@supportURL

定义用户可以报告问题和获取个人支持的 URL。

@webRequest

@webRequest接受一个与GM_webRequest的rule参数匹配的 JSON 文档，允许规则在用户脚本加载之前应用。

@unwrap

将用户脚本注入到页面中，不带任何包装器和沙箱，这对于 Scriptlets 可能是有用的。

应用程序接口

unsafeWindow

unsafeWindow对象提供对 Tampermonkey 运行的页面的window对象的访问，而不是 Tampermonkey 扩展的window对象。这在某些情况下非常有用，例如当用户脚本需要访问在页面上定义的 JavaScript 库或变量时。

Subresource Integrity

子资源完整性（SRI）是一项安全功能，允许用户脚本开发者确保他们在用户脚本中包含的外部资源（如 JavaScript 库和 CSS 文件）没有被篡改或修改。这是通过生成资源的加密哈希并将其包含在@require和@resource标签中实现的。当用户脚本安装时，Tampermonkey 会计算资源的哈希值并将其与包含的哈希进行比较。如果两个哈希值不匹配，Tampermonkey 将拒绝加载资源，防止攻击者将恶意代码注入到用户脚本中。
@resource和@require标签的 URL 的哈希组成部分用于此目的。

// @resource SRIsecured1 http://example.com/favicon1.ico#md5=ad34bb...
// @resource SRIsecured2 http://example.com/favicon2.ico#md5=ac3434...,sha256=23fd34...
// @require              https://code.jquery.com/jquery-2.1.1.min.js#md5=45eef...
// @require              https://code.jquery.com/jquery-2.1.2.min.js#md5-ac56d...,sha256-6e789...
// @require              https://code.jquery.com/jquery-3.6.0.min.js#sha256-/xUj+3OJU...ogEvDej/m4=

Tampermonkey 原生支持SHA-256和MD5哈希，其他哈希（SHA-1，SHA-384和SHA-512）依赖于window.crypto。如果给出了多个哈希（用逗号或分号分隔），Tampermonkey 将使用最后一个当前支持的哈希。所有哈希都需要以十六进制或 Base64 格式编码。

GM_addElement(tag_name, attributes), GM_addElement(parent_node, tag_name, attributes)

GM_addElement 允许 Tampermonkey 脚本向所在页面添加新元素。当页面通过内容安全策略（CSP）限制某些标签（如script和img）时，该方法很有用。它会创建一个由"tag_name"指定的 HTML 元素，应用给定的"attributes"，然后返回注入的 HTML 元素。若指定了"parent_node"，则将新元素附加到该节点上，否则附加到文档的头部或主体中。

GM_addElement('script', {
  textContent: 'window.foo = "bar";'
});

GM_addElement('script', {
  src: 'https://example.com/script.js',
  type: 'text/javascript'
});

GM_addElement(document.getElementsByTagName('div')[0], 'img', {
  src: 'https://example.com/image.png'
});

GM_addElement(shadowDOM,'style', {
  textContent: 'div { color: black; };'
});

注意：此功能是实验性的，API 可能会更改。

GM_addStyle(css)

将给定的样式添加到文档中，并返回注入的样式元素。

GM_download(details), GM_download(url, name)

GM_download 允许用户脚本从指定的 URL 下载文件并保存到本地计算机。

• 参数说明：
  • details：包含下载相关属性的对象。
    • url：要下载的文件的 URL，必须是有效的可访问 URL。
    • name：下载时使用的文件名，需包含扩展名，且扩展名需在 Tampermonkey 选项页面进行白名单设置。
    • headers：包含下载请求中 HTTP 头的对象。
    • saveAs：布尔值，指示是使用默认下载位置还是提示用户选择其他位置，仅在浏览器 API 模式下有效。
    • conflictAction：字符串，控制同名文件已存在时的操作，仅在浏览器 API 模式下有效，取值为uniquify（生成唯一文件名）、overwrite（覆盖）和prompt（提示用户） 。
    • onload：下载成功完成时调用的函数。
    • onerror：下载失败或被取消时调用的函数。
    • onprogress：下载有进展时执行的回调函数。
    • ontimeout：下载因超时而失败时执行的回调函数。
    • onerror回调的download参数：
      • error：错误原因，如not_enabled（用户未启用下载功能）、not_whitelisted（请求的文件扩展名未在白名单中）、not_permitted（用户启用了下载功能，但未授予 downloads 权限）、not_supported（浏览器 / 版本不支持下载功能）、not_succeeded（下载未开始或失败，details属性可能提供更多信息）。
      • details：有关该错误的详细信息。
  • url：要下载的文件的 URL（GM_download(url, name)形式使用）。
  • name：下载时使用的文件名（GM_download(url, name)形式使用）。
• 返回值：返回一个具有abort属性的对象，abort是一个可调用函数，用于取消此下载。根据下载模式，GM_info提供一个名为downloadMode的属性，其值为native、disabled或browser之一。

GM_download("http://example.com/file.txt", "file.txt");

const download = GM_download({
    url: "http://example.com/file.txt",
    name: "file.txt",
    saveAs: true
});

// 5秒后取消下载
window.setTimeout(() => download.abort(), 5000);

注意：浏览器可能会修改所需的文件名，若浏览器认为在当前操作系统上下载该文件安全，可能会添加文件扩展名。

GM_getResourceText(name)

GM_getResourceText 允许用户脚本访问通过@resource包含在用户脚本中的资源（如 JavaScript 或 CSS 文件）的文本内容。该函数接受一个参数，即要检索的资源的"name"，返回资源的文本内容字符串。

const scriptText = GM_getResourceText("myscript.js");
const script = document.createElement("script");
script.textContent = scriptText;
document.body.appendChild(script);

GM_getResourceURL(name)

GM_getResourceURL 允许用户脚本访问通过@resource标签包含在用户脚本中的资源（如 CSS 或图像文件）的 URL。该函数接受一个参数，即要检索的资源的"name"，返回资源的 URL 字符串。

const imageUrl = GM_getResourceURL("myimage.png");
const image = document.createElement("img");
image.src = imageUrl;
document.body.appendChild(image);

GM_info

获取有关脚本和 Tampermonkey 的一些信息，返回的对象结构如下：

type ScriptGetInfo = {
    downloadMode: string,
    isFirstPartyIsolation?: boolean,
    isIncognito: boolean,
    sandboxMode: SandboxMode,
    scriptHandler: string,
    scriptMetaStr: string | null,
    scriptUpdateURL: string | null,
    scriptWillUpdate: boolean,
    version?: string,
    script: {
        antifeatures: { [antifeature: string]: { [locale: string]: string } },
        author: string | null,
        blockers: string[],
        connects: string[],
        copyright: string | null,
        deleted?: number | undefined,
        description_i18n: { [locale: string]: string } | null,
        description: string,
        downloadURL: string | null,
        excludes: string[],
        fileURL: string | null,
        grant: string[],
        header: string | null,
        homepage: string | null,
        icon: string | null,
        icon64: string | null,
        includes: string[],
        lastModified: number,
        matches: string[],
        name_i18n: { [locale: string]: string } | null,
        name: string,
        namespace: string | null,
        position: number,
        resources: Resource[],
        supportURL: string | null,
        system?: boolean | undefined,
        'run-at': string | null,
        unwrap: boolean | null,
        updateURL: string | null,
        version: string,
        webRequest: WebRequestRule[] | null,
        options: {
            check_for_updates: boolean,
            comment: string | null,
            compatopts_for_requires: boolean,
            compat_wrappedjsobject: boolean,
            compat_metadata: boolean,
            compat_foreach: boolean,
            compat_powerful_this: boolean | null,
            sandbox: string | null,
            noframes: boolean | null,
            unwrap: boolean | null,
            run_at: string | null,
            tab_types: string | null,
            override: {
                use_includes: string[],
                orig_includes: string[],
                merge_includes: boolean,
                use_matches: string[],
                orig_matches: string[],
                merge_matches: boolean,
                use_excludes: string[],
                orig_excludes: string[],
                merge_excludes: boolean,
                use_connects: string[],
                orig_connects: string[],
                merge_connects: boolean,
                use_blockers: string[],
                orig_run_at: string | null,
                orig_noframes: boolean | null
            }
        }
    }
};

type SandboxMode = 'js' | 'raw' | 'dom';

type Resource = {
    name: string,
    url: string,
    error?: string,
    content?: string,
    meta?: string
};

type WebRequestRule = {
    selector: { include?: string | string[], match?: string | string[], exclude?: string | string[] } | string,
    action: string | {
        cancel?: boolean,
        redirect?: {
            url: string,
            from?: string,
            to?: string
        } | string
    }
};

GM_log(message)

将消息记录到控制台。

GM_notification(details, ondone), GM_notification(text, title, image, onclick)

GM_notification 允许在屏幕上显示通知，可使用提供的消息和其他可选参数。

• 参数说明：
  • details：包含通知相关属性的对象。
    • text：通知中显示的消息字符串。
    • title：通知的标题。
    • image：通知中显示的图像的 URL。
    • highlight：布尔值，指示是否突出显示发送通知的选项卡（若未设置text，则为必需）。
    • silent：布尔值，指示是否不播放声音。
    • timeout：通知自动关闭的时间（以毫秒为单位）。
    • onclick：用户点击通知时调用的回调函数。
    • ondone：通知关闭（由超时或点击触发）或选项卡突出显示时调用的回调函数。
  • text：通知中显示的消息字符串（GM_notification(text, title, image, onclick)形式使用）。
  • title：通知的标题（GM_notification(text, title, image, onclick)形式使用）。
  • image：通知中显示的图像的 URL（GM_notification(text, title, image, onclick)形式使用）。
  • onclick：用户点击通知时调用的回调函数（GM_notification(text, title, image, onclick)形式使用）。

GM_notification({
  text: "This is the notification message.",
  title: "Notification Title",
  onclick: () => alert('I was clicked!')
});

GM_openInTab(url, options), GM_openInTab(url, loadInBackground)

GM_openInTab 允许用户脚本在浏览器中打开一个新标签页并导航到指定的 URL。

• 参数说明：
  • url：要在新标签页中打开的页面的 URL。
  • options：用于自定义新标签页行为的对象。
    • active：布尔值，指示新标签页是否应处于活动状态（选中状态），默认值为false。
    • insert：整数，指示新标签页应插入到标签栏中的位置，默认值为false，表示新标签页将添加到标签栏的末尾。
    • setParent：布尔值，指示新标签页是否应被视为当前标签页的子标签页，默认值为false。
    • incognito：布尔值，在隐身模式 / 私密模式窗口中打开标签页。
    • loadInBackground：布尔值，与active的含义相反，添加此选项是为了实现 Greasemonkey 3.x 的兼容性。
• 返回值：返回一个具有close函数、onclose监听器和一个名为closed标志的对象。

// Open a new tab and navigate to the specified URL
GM_openInTab("https://www.example.com/");

GM_registerMenuCommand(name, callback, accessKey)

GM_registerMenuCommand 允许用户脚本向浏览器的用户脚本菜单中添加一个新的条目，并指定选择菜单项时要调用的函数。

• 参数说明：
  • name：显示在菜单项中的文本字符串。
  • callback：选择菜单项时调用的函数，从 Tampermonkey 4.14 开始，会传递一个MouseEvent或KeyboardEvent作为函数参数。
  • accessKey：菜单项的可选访问键，用于创建快捷键。
• 返回值：返回一个菜单项 ID，可用于注销该命令。

const menu_command_id = GM_registerMenuCommand("Show Alert", function(event: MouseEvent | KeyboardEvent) {
  alert("Menu item selected");
}, "a");

GM_unregisterMenuCommand(menuCmdId)

GM_unregisterMenuCommand 从浏览器的用户脚本菜单中移除现有的条目。该函数接受一个参数，即要移除的菜单项的 ID，不返回任何值。

const menu_command_id = GM_registerMenuCommand(...);
GM_unregisterMenuCommand(menu_command_id);

GM_setClipboard(data, info)

GM_setClipboard 将剪贴板的文本设置为指定的值。

• 参数说明：
  • data：要设置为剪贴板文本的字符串。
  • info：可以是表示类型text或html的字符串，或者是一个对象（如{type: 'text', mimetype: 'text/plain'}）。

GM_setClipboard("This is the clipboard text.", "text");

GM_getTab(callback)

GM_getTab 函数接受一个回调函数作为参数，该回调函数将使用一个对象作为参数，该对象在此选项卡打开的整个周期内都是持久的。

GM_getTab((tab) => console.log(tab));

GM_saveTab(tab)

GM_saveTab 函数允许用户脚本保存有关选项卡的信息以供以后使用。该函数接受一个名为tab的参数，该参数是一个包含要保存的选项卡信息的对象，保存的信息可通过GM_getValue函数检索。

GM_getTab(function(tab) {
    tab.newInfo = "new!";
    GM_saveTab(tab);
});

GM_getTabs(callback)

GM_getTabs 函数接受一个回调函数作为参数，传递给回调函数的"tabs"对象包含多个对象，每个对象表示由GM_saveTab存储的保存的选项卡信息。

GM_getTabs((tabs) => {
    for (const [tabId, tab] of Object.entries(tabs)) {
        console.log(`tab ${tabId}`, tab);
    }
});

GM_setValue(key, value)

GM_setValue 允许用户脚本将特定键的值设置为用户脚本存储中的值。接受两个参数，一个是指定要设置值的键的字符串，另一个是要为键设置的值（可以是任意类型），该函数不返回任何值。

GM_setValue("someKey", "someData");
await GM.setValue("otherKey", "otherData");

GM_getValue(key, defaultValue)

GM_getValue 函数允许用户脚本从扩展程序的存储中检索特定键的值。接受两个参数，一个是指定要检索值的键的字符串，另一个是键不存在时返回的默认值（可以是任意类型），函数返回指定键的值，若键不存在则返回默认值。

const someKey = GM_getValue("someKey", null);
const otherKey = await GM.getValue("otherKey", null);

GM_deleteValue(key)

从用户脚本的存储中删除指定的"key" 。

GM_deleteValue("someKey");
await GM.deleteValue("otherKey");

GM_listValues()

GM_listValues 函数返回存储数据的所有键的列表。

const keys = GM_listValues();
const asyncKeys = await GM.listValues();

GM_addValueChangeListener(key, (key, old_value, new_value, remote) => void)

GM_addValueChangeListener 函数允许用户脚本为用户脚本存储中特定键的值更改添加监听器。接受两个参数，一个是指定要监视更改的键的字符串，另一个是键的值更改时调用的回调函数。回调函数签名为：

function(key, oldValue, newValue, remote) {
    // key是值发生更改的键
    // oldValue是键的先前值
    // newValue是键的新值
    // remote是一个布尔值，指示更改是否源自不同的用户脚本实例
}

该函数返回一个"listenerId"值，可用于稍后使用GM_removeValueChangeListener函数删除监听器。对于GM.addValueChangeListener 和GM.removeValueChangeListener，两者返回一个promise。

// 为"savedTab"键的更改添加监听器
var listenerId = GM_addValueChangeListener("savedTab", function(key, oldValue, newValue, remote) {
  // 当"savedTab"键的值更改时，将消息打印到控制台
  console.log("The value of the '" + key + "' key has changed from '" + oldValue + "' to '" + newValue + "'");
});

该函数可用于用户脚本与其他选项卡中的其他用户脚本实例进行通信。

GM_removeValueChangeListener(listenerId)

GM_removeValueChangeListener 和GM.removeValueChangeListener都接受一个名为"listenerId"的参数，并删除具有该 ID 的更改监听器。

GM_xmlhttpRequest(details)

GM_xmlhttpRequest 允许用户脚本发送 HTTP 请求并处理响应。

• 参数说明：
  • details：包含请求详细信息和回调函数的对象。
    • method：GET、HEAD、POST之一的方法。
    • url：目标 URL。
    • headers：如user - agent、referer等（某些特殊头部在 Safari 和 Android 浏览器中不受支持）。
    • data：要通过POST请求发送的一些字符串。
    • redirect：重定向检测到时的操作之一，可以是follow、error或manual（从版本 6180 开始，强制fetch模式）。

• cookie：要添加到发送的 cookie 设置中的 cookie。
• binary：以二进制模式发送数据字符串。
• nocache：不缓存资源。
• revalidate：重新验证可能缓存的内容。
• timeout：超时时间（以毫秒为单位）。
• context：将添加到响应对象中的属性。
• responseType：arraybuffer、blob、json或stream之一。
• overrideMimeType：请求的 MIME 类型。
• anonymous：不发送与请求相关的 cookie（强制fetch模式）。
• fetch：使用fetch而不是XMLHttpRequest请求（在 Chrome 中，这会导致details.timeout和xhr.onprogress不起作用，并使xhr.onreadystatechange只接收readyState DONE（== 4）事件）。
• user：用于身份验证的用户名。
• password：密码。
• onabort：如果请求被中止，则执行的回调函数。
• onerror：如果请求出错，则执行的回调函数。
• onloadstart：在加载开始时执行的回调函数，如果responseType设置为stream，可以访问流对象。
• onprogress：如果请求有进展，则执行的回调函数。
• onreadystatechange：如果请求的readyState发生更改，则执行的回调函数。
• ontimeout：如果请求由于超时而失败，则执行的回调函数。
• onload：如果请求加载完成，则执行的回调函数。
• 响应对象属性：回调函数的参数response是一个包含响应详细信息的对象，具有以下属性：
  • finalUrl：数据加载后的最终 URL，包括所有重定向。
  • readyState：请求的readyState。
  • status：请求的状态。
  • statusText：请求的状态文本。
  • responseHeaders：请求的响应头。
  • response：如果设置了details.responseType，则作为对象的响应数据。
  • responseXML：响应数据作为 XML 文档。
  • responseText：响应数据作为纯文本字符串。
• 返回值：返回一个具有abort属性的对象，abort是用于取消此请求的函数。

GM_xmlhttpRequest({
  method: "GET",
  url: "https://example.com/",
  headers: {
    "Content-Type": "application/json"
  },
  onload: function(response) {
    console.log(response.responseText);
  }
});

注意：details中的synchronous标志不受支持。重要提示：如果要使用此方法，请同时查看有关@connect的文档。

GM_webRequest(rules, listener)

注意：此 API 是实验性的，可能随时更改。在清单 v3 迁移期间，它可能会消失或更改。
GM_webRequest（重新）注册用于网页请求操作的规则和触发规则的监听器。如果只需要注册规则，最好使用@webRequest标头。注意，webRequest仅处理sub_frame、script、xhr和websocket类型的请求。

• 参数说明：
  • rules：包含规则的对象数组，每个对象包含以下属性：
    • selector：字符串或对象，指定触发规则的 URL。字符串值是{ include: [selector] }的简写形式，对象属性如下：
      • include：字符串或字符串数组，用于触发规则的 URL、模式和正则表达式。
      • match：字符串或字符串数组，用于触发规则的 URL 和模式。
      • exclude：字符串或字符串数组，不触发规则的 URL、模式和正则表达式。
    • action：字符串或对象，对请求采取的操作。字符串值"cancel"是{ cancel: true }的简写形式，对象属性如下：
      • cancel：布尔值，是否取消请求。
      • redirect：字符串或对象，重定向到某个 URL，该 URL 必须包含在任何@match或@include标头中。当为字符串时，重定向到静态 URL。如果为对象：
        • from：字符串，提取 URL 的某些部分的正则表达式，例如"([^:]+)://match.me/(.*)"。
        • to：字符串，用于替换的模式，例如"$1://redirected.to/$2"。
  • listener：当规则被触发时调用的函数，无法影响规则的操作，参数如下：
    • info：操作类型，如"cancel"、"redirect"。
    • message："ok"或"error"。
    • details：包含请求和规则信息的对象：
      • rule：触发的规则。
      • url：请求的 URL。
      • redirect_url：请求重定向的 URL。
      • description：错误描述。

GM_webRequest([
    { selector: '*cancel.me/*', action: 'cancel' },
    { selector: { include: '*', exclude: 'http://exclude.me/*' }, action: { redirect: 'http://new_static.url' } },
    { selector: { match: '*://match.me/*' }, action: { redirect: { from: '([^:]+)://match.me/(.*)',  to: '$1://redirected.to/$2' } } }
], function(info, message, details) {
    console.log(info, message, details);
});

GM_cookie.list(details[, callback])

注意：GM_cookie API 是实验性的，在某些 Tampermonkey 版本中可能会返回 “不支持” 的错误。Tampermonkey 会检查脚本是否对给定的details.url参数具有@include或@match访问权限！

• 参数说明：
  • details：包含要检索的 cookie 属性的对象。
    • url：表示要从中检索 cookie 的 URL，默认为当前文档的 URL。
    • domain：表示要检索的 cookie 的域。
    • name：表示要检索的 cookie 的名称。
    • path：表示要检索的 cookie 的路径。
  • callback：检索到 cookie 后调用的函数，传递两个参数：
    • cookies：检索到的 cookie 数组，每个 cookie 对象具有以下属性：
      • domain：cookie 的域。
      • firstPartyDomain：cookie 的第一方域。
      • hostOnly：指示是否为主机限定 cookie。
      • httpOnly：指示是否为仅限 HTTP 的 cookie。
      • name：cookie 的名称。
      • path：cookie 的路径。
      • sameSite：cookie 的 SameSite 属性。
      • secure：指示是否需要安全连接的 cookie。
      • session：指示是否为会话 cookie。
      • value：cookie 的值。
    • error：错误消息（如果发生错误），否则为null。

// 检索所有名称为 "mycookie" 的 cookie
GM_cookie.list({ name: "mycookie" }, function(cookies, error) {
  if (!error) {
    console.log(cookies);
  } else {
    console.error(error);
  }
});

// 检索当前域的所有 cookie
const cookies = await GM.cookies.list()
console.log(cookies);

GM_cookie.set(details[, callback])

使用给定的详细信息设置 cookie。

• 参数说明：
  • details：包含要设置的 cookie 详细信息的对象。
    • url：与 cookie 相关联的 URL，如果未指定，则将 cookie 关联到当前文档的 URL。
    • name：cookie 的名称。
    • value：cookie 的值。
    • domain：cookie 的域。
    • firstPartyDomain：cookie 的第一方域。
    • path：cookie 的路径。
    • secure：cookie 是否仅通过 HTTPS 发送。
    • httpOnly：cookie 是否标记为 HttpOnly。
    • expirationDate：cookie 的过期日期，以 Unix 纪元后的秒数表示，如果未指定，cookie 永不过期。
  • callback：操作完成时调用的函数，传递一个参数：
    • error：如果设置 cookie 时出现错误，包含错误消息；否则为undefined。

GM_cookie.set({
  url: 'https://example.com',
  name: 'name',
  value: 'value',
  domain: '.example.com',
  path: '/',
  secure: true,
  httpOnly: true,
  expirationDate: Math.floor(Date.now() / 1000) + (60 * 60 * 24 * 30) // Expires in 30 days
}, function(error) {
  if (error) {
    console.error(error);
  } else {
    console.log('Cookie set successfully.');
  }
});

GM.cookie.set({
  name: 'name',
  value: 'value'
})
.then(() => {
  console.log('Cookie set successfully.');
})
.catch((error) => {
  console.error(error);
});

GM_cookie.delete(details, callback)

删除一个 cookie。

• 参数说明：
  • details：对象必须至少包含以下属性之一：
    • url：与 cookie 相关联的 URL，如果未指定url，将使用当前文档的 URL。
    • name：要删除的 cookie 的名称。
    • firstPartyDomain：要删除的 cookie 的第一方域。
  • callback：可选的函数，当 cookie 被删除或出现错误时将被调用，接受一个参数：
    • error：错误消息，如果 cookie 成功删除，则为undefined。

GM_cookie.delete({ name: 'cookie_name' }, function(error) {
    if (error) {
        console.error(error);
    } else {
        console.log('Cookie deleted successfully');
    }
});

window.onurlchange

如果脚本运行在单页应用程序上，可以使用window.onurlchange监听 URL 的变化：

// ==UserScript==
...
// @grant window.onurlchange
// ==/UserScript==

if (window.onurlchange === null) {
    // 支持该功能
    window.addEventListener('urlchange', (info) => ...);
}

window.close

通常情况下，JavaScript 不允许通过window.close关闭标签页。然而，如果在@grant中请求了权限，用户脚本可以执行此操作。注意：出于安全原因，不允许关闭窗口的最后一个标签页。

// ==UserScript==
...
// @grant window.close
// ==/UserScript==

if (condition) {
    window.close();
}

window.focus

window.focus将窗口置于前台，而unsafeWindow.focus可能因用户设置而失败。

// ==UserScript==
...
// @grant window.focus
// ==/UserScript==

if (condition) {
    window.focus();
}

通过兼容性选项支持基于 CDATA 的元数据存储方式。Tampermonkey 会尝试自动检测脚本是否需要启用此选项。

var inline_src = (`
    console.log('Hello World!');
`).toString();

eval(inline_src);