Tampermonkey 油猴脚本中文文档

油猴脚本中文文档，由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函数加入白名单。

// @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要求此信息。

语法：

可以有以下值：

• 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://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 – 这是URL的第一部分，在冒号之前。它指定页面使用的协议，如http或https。*匹配所有协议。
• domain – 这是URL的第二部分，在协议和两个斜杠之后。它指定网站的域名，如tmnk.com。您可以使用通配符 *.tmnk.net 来匹配 tmnk.net 和其任何子域名，如 www.tmnk.net。
• path – 这是URL的一部分，位于域名之后，可能包括其他子目录或文件名。您可以使用通配符 * 来匹配路径的任何部分。

请查看此文档以获取有关匹配模式的更多信息。注意：尚不支持 声明，协议部分还接受 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 

可以是：

• 域名，如 example.com（这也将允许所有子域）。
• 子域名，如 subdomain.example.com。
• self，以允许脚本当前所在的域。
• localhost，以访问本地主机。
• IP地址，如 1.2.3.4。
• *。

如果无法声明用户脚本可能连接到的所有域，则建议按照以下做法进行：

1. 声明所有已知或至少常见的脚本可能连接到的域，以避免对大多数用户显示确认对话框。
2. 另外，在脚本中添加@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脚本向Tampermonkey所在的页面添加新元素。这对于各种用途非常有用，例如在页面通过内容安全策略（CSP）限制script和img标签时，可以添加这些元素。

它创建一个由"tag_name"指定的HTML元素，并应用所有给定的"attributes"，然后返回注入的HTML元素。如果给定了"parent_node"，则将其附加到该节点上，否则将附加到文档的头部或主体中。

请参考适当的文档了解适合的"attributes"。例如：

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下载文件并将其保存到用户的本地计算机中。

GM_download函数接受以下参数：

details可以具有以下属性：

• url：要下载的文件的URL。这必须是一个有效的URL，并且必须指向用户可以访问的文件。
• name：用于下载的文件名。这应该包括文件的扩展名，例如.txt或.pdf。出于安全原因，文件扩展名需要在Tampermonkey的选项页面上进行白名单设置。
• headers：一个包含要包含在下载请求中的HTTP头的对象。有关详细信息，请参见GM_xmlhttpRequest。
• 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：有关该错误的详细信息

返回一个具有以下属性的对象：

• 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对象或多个直接参数。

details对象可以具有以下属性，其中某些属性也可以作为直接参数使用。

可用选项包括：

• text：要在通知中显示的消息的字符串。
• title：通知的标题。
• image：要在通知中显示的图像的URL。
• highlight：一个布尔值标志，指示是否突出显示发送通知的选项卡（如果没有设置text，则为必需）。
• silent：一个布尔值标志，指示是否不播放声音。
• timeout：通知自动关闭的时间（以毫秒为单位）。
• onclick：当用户点击通知时将调用的回调函数。
• ondone：当通知关闭（无论是由超时还是点击触发）或选项卡突出显示时将调用的回调函数。

该函数没有返回值。

以下是该函数的使用示例：

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：菜单项的可选访问键。这可以用于为菜单项创建快捷键。例如，如果访问键是“s”，当打开Tampermonkey的弹出菜单时，用户可以按下“s”来选择菜单项。

该函数返回一个菜单项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”的参数。

“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_saveTab函数保存所提供的选项卡信息，以便稍后可以使用GM_getValue函数检索。

以下是在用户脚本中使用GM_saveTab函数的示例：

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

在此示例中，GM_saveTab函数使用由GM_getTab函数返回的选项卡对象和一个名为”newInfo”的新键。

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函数接受两个参数：

• 一个字符串，指定要设置值的键。
• 要为键设置的值。该值可以是任意类型（字符串、数字、对象等）。

GM_setValue函数不返回任何值。相反，它在用户脚本的存储中为指定的键设置提供的值。

以下是在用户脚本中使用GM_setValue及其异步变体GM.setValue的示例：

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

GM_getValue(key, defaultValue)

GM_getValue函数允许用户脚本从扩展程序的存储中检索特定键的值。它接受两个参数：

• 一个字符串，指定要检索值的键。
• 一个默认值，在键不存在于扩展程序的存储中时返回该默认值。该默认值可以是任意类型（字符串、数字、对象等）。

GM_getValue函数从扩展程序的存储中返回指定键的值，如果键不存在，则返回默认值。

以下是GM_getValue函数在用户脚本中的使用示例：

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

在此示例中，GM_getValue函数使用键”someKey”和默认值null调用。如果扩展程序的存储中存在”someKey”键，将返回其值并存储在someKey变量中。如果键不存在，将返回默认值null并存储在savedTab变量中。

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是一个布尔值，指示更改是否源自不同的用户脚本实例
  }

GM_addValueChangeListener函数返回一个“listenerId”值，可用于稍后使用GM_removeValueChangeListener函数删除监听器。对于GM.addValueChangeListener和GM.removeValueChangeListener也是如此，只是两者返回一个promise。

以下是在用户脚本中使用GM_addValueChangeListener函数的示例：

// 为"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_addValueChangeListener可用于用户脚本与其他选项卡中的其他用户脚本实例进行通信。

GM_removeValueChangeListener(listenerId)

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

GM_xmlhttpRequest(details)

GM_xmlhttpRequest允许用户脚本发送HTTP请求并处理响应。该函数接受一个参数：一个包含要发送的请求的详细信息和在接收到响应时要调用的回调函数的对象。

该对象可以具有以下属性：

• 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：响应数据作为纯文本字符串。

GM_xmlhttpRequest返回一个具有以下属性的对象：

• abort：用于取消此请求的函数。

以下是在用户脚本中使用GM_xmlhttpRequest函数的示例：

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 – object[]对象数组，包含以下属性的规则数组：

• 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 string?，表示要从中检索 cookie 的 URL（默认为当前文档的 URL）
• domain string?，表示要检索的 cookie 的域
• name string?，表示要检索的 cookie 的名称
• path string?，表示要检索的 cookie 的路径
• callback function?，在检索到 cookie 后将调用此函数。该函数将传递两个参数：
  • cookies object[]，表示检索到的 cookie
  • error string，表示错误消息（如果发生错误），否则为 null。

cookie 对象具有以下属性：

• domain string，表示 cookie 的域
• firstPartyDomain string?：cookie 的第一方域。
• hostOnly boolean，指示是否为主机限定 cookie
• httpOnly boolean，指示是否为仅限 HTTP 的 cookie
• name string，表示 cookie 的名称
• path string，表示 cookie 的路径
• sameSite string，表示 cookie 的 SameSite 属性
• secure boolean，指示是否需要安全连接的 cookie
• session boolean，指示是否为会话 cookie
• value string，表示 cookie 的值

示例用法：

// 检索所有名称为 "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 string?，与 cookie 相关联的 URL。如果未指定，则将 cookie 关联到当前文档的 URL。
• name string，cookie 的名称。
• value string，cookie 的值。
• domain string?，cookie 的域。
• firstPartyDomain string?：cookie 的第一方域。
• path string?，cookie 的路径。
• secure boolean?，cookie 是否仅通过 HTTPS 发送。
• httpOnly boolean?，cookie 是否标记为 HttpOnly。
• expirationDate number?，cookie 的过期日期，以 Unix 纪元后的秒数表示。如果未指定，cookie 永不过期。
• callback function?，操作完成时要调用的函数。该函数传递一个参数：
  • error string?，如果设置 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 string?，与 cookie 相关联的 URL。如果未指定 url，将使用当前文档的 URL。
• name string?，要删除的 cookie 的名称。
• firstPartyDomain string?：要删除的 cookie 的第一方域。

callback 函数是可选的，当 cookie 被删除或出现错误时将被调用。它接受一个参数：

• error string?，错误消息，如果 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 = (<>).toString();

eval(inline_src);