心向自由

CUBERWR/BLOG

油猴中文文档

2023.07.24

Tampermonkey文档

用户脚本头

@name

脚本的名称，可通过添加语言代码来实现国际化

// @name    一个测试脚本 
// @name:zh-CN 一个测试脚本

@namespace

脚本的命名空间

脚本版权声明，在编辑器的头部显示

@version

脚本版本号，用于更新检查，每次更新时需要递增

版本号排序规则如下，后面的视为较新版本：

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 这个用户脚本可以做一些很棒的事情  
// @description:zh-CN 这个用户脚本可以做一些很棒的事情

@icon、@iconURL、@defaulticon

脚本的图标，低分辨率

@icon64、@icon64URL

脚本的 64x64 像素图标，如果只有 @icon64 但没有 @icon,@icon 图像在某些地方也会被缩放

@grant

@grant 用于白名单 GM_\* 和 GM.* 函数、unsafeWindow 对象和一些强大的窗口函数

// @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_\* 函数不可用，但 GM_info 属性可用

// @grant none

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

@author

脚本作者

@homepage、@homepageURL、@website、@source

作者主页，在脚本设置页面用来从脚本名称链接到该页面，注意如果 @namespace 以 http:// 开头，其内容也会用于此目的

@antifeature

此标记允许脚本开发者披露他们是否正在从脚本中获利，例如 GreasyFork 要求这一点

语法：<标记名> <类型> <描述>

类型 可以是以下值：

  • ads： 表示有广告
  • tracking： 表示有某种分析
  • miner： 表示使用计算资源挖矿
// @antifeature ads 我们会展示一些广告
// @antifeature:zh-CN ads 我们会展示一些广告
// @antifeature tracking 我们集成了某种分析
// @antifeature miner 我们使用您的计算资源进行挖矿

也可以用语言代码实现国际化

@require

指定在脚本本身开始运行前需要加载并执行的 JavaScript 文件

注意：@require 加载的脚本中的 "use strict" 语句可能会影响用户脚本的严格模式!

// @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...

请查看子资源完整性部分以获取更多信息以确保完整性

允许多个标记实例

@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 会像 @match 一样稍微特殊解释包含 :// 的 @include，在 :// 之前的 * 只匹配非 : 字符，以确保只匹配协议

如果这样的 @include 在 :// 后面包含 /，那么这两个字符串之间的所有内容都将被视为主机，匹配任何非 / 字符，同样适用于紧随 :// 之后的 *

@match

@match 指令用于指定用户脚本应该运行的网页

@match 的值应该是一个 URL 模式，匹配你希望脚本运行的页面，这里是你需要设置的 URL 模式的部分：

// @match <协议>://<域名><路径>

  • 协议 - URL 的第一部分，冒号之前，它指定页面使用的协议，如 http 或 https，* 匹配两者

  • 域名 - URL 的第二部分，在协议和两个斜杠之后，它指定网站的域名，如 tmnk.com，你可以像这样使用通配符 *.tmnk.net 来匹配 tmnk.net 和它的任意子域，如 www.tmnk.net

  • 路径 - 域名后的 URL 部分，可能包含其他子目录或文件名，你可以使用通配符 * 来匹配路径的任意部分

请查看文档 ↗以获取更多关于匹配模式的信息，注意：<all_urls> 语句尚未支持，scheme 部分也接受 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：“原始”访问意味着某些脚本出于兼容性原因总是需要在页面上下文中运行，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
  • *.

如果无法声明用户脚本可能连接的所有域，那么最好遵循以下做法：

  • 声明脚本可能连接的所有已知或至少所有常用域，以避免对大多数用户显示确认对话框

  • 另外添加 @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 库或变量时

子资源完整性

子资源完整性（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”，则将其附加到其上或者附加到文档头或主体

适合的 “attributes” 请参考相关文档，例如：

  • script 标签
  • img 标签
  • style 标签
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 - 用户启用了下载功能，但未授予下载权限

  • 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)

允许用户脚本访问通过 @resource 加载到用户脚本中的资源（如 JavaScript 或 CSS 文件）的文本

该函数需要一个参数，即要检索的资源的“名称”，它返回资源文本作为字符串

下面是一个函数用法示例：

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

该函数需要一个参数，即要检索的资源的“名称”，它返回资源的 URL 作为字符串

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

GM_info

获取关于脚本和 TM 的一些信息，对象可能如下所示：

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：一个布尔标志，指示是否突出显示发送通知的选项卡（除非设置了文本）

  • 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 标志的对象

下面是一个函数用法示例：

// 打开新选项卡并导航到指定的 URL
GM_openInTab("https://www.example.com/");

GM_registerMenuCommand(name, callback, accessKey)

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

该函数需要三个参数：

  • name：包含要为菜单项显示的文本的字符串

  • callback：选择菜单项时调用的函数，该函数将传递一个参数，即当前活动选项卡

  • accessKey：菜单项的可选快捷键，例如，如果快捷键为 s，则用户可以在打开 Tampermonkey 弹出菜单时按 s 来选择该菜单项

该函数返回一个菜单项 ID，可用于取消注册命令

下面是一个函数用法示例：

const menu_command_id = GM_registerMenuCommand("Show Alert", function(event) {
  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 函数返回的 tab 对象，以及一个名为 "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);

在此示例中，使用键 "someKey" 和默认值 null 调用了 GM_getValue 函数

如果 "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：请求加载完成时执行的回调，函数签名为：
  function(response) {
    // response 是一个包含响应详细信息的对象
  }

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 为实验性的，可能会随时更改或消失，可能还会在 manifest v3 迁移期间消失或改变

GM_webRequest （重新）注册网络请求操作规则及触发规则的监听器

如果你只需要注册规则，最好使用 @webRequest 头

注意，webRequest 仅处理具有 sub_frame、script、xhr 和 websocket 类型的请求

参数：

  • rules - object[]，规则数组，具有以下属性：

    • selector - string|object，用于触发规则的 URL，字符串值是 { include: [selector] } 的缩写，对象属性：

      • include - string|string[]，用于触发规则的 URL、模式和正则表达式
      • match - string|string[]，用于触发规则的 URL 和模式;
      • exclude - string|string[]，不触发规则的 URL、模式和正则表达式

    • action - string|object，对请求进行的操作，字符串值 "cancel" 是 { cancel: true } 的缩写，对象属性：

      • cancel - boolean，是否取消请求
      • redirect - string|object，重定向到 @match 或 @include 头中包含的某个 URL，字符串时重定向到静态 URL，如果是对象：
        • from - string，一个正则表达式来提取 URL 的某些部分，例如 "([^:]+)://match.me/(.*)"
        • to - string，替换模式，例如 "$1://redirected.to/$2"

  • listener - function，规则被触发时调用，无法影响规则动作，参数：

    • info - string，操作类型："cancel"、"redirect"
    • message - string，"ok" 或 "error"
    • details - object，关于请求和规则的信息
      • rule - object，被触发的规则
      • url - string，请求的 URL
      • redirect_url - string，请求被重定向到的位置;
      • description - string，错误描述

示例：

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会检查脚本是否有@include或@match访问给定details.url参数的权限!

参数：

  • details - object，包含要检索的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 - bool，指示cookie是否为主机仅cookie
  • httpOnly - bool，指示cookie是否为HTTP仅cookie
  • name - string，表示cookie的名称
  • path - string，表示cookie的路径
  • sameSite - string，表示cookie的SameSite属性
  • secure - bool，指示cookie是否需要安全连接
  • session - bool，指示cookie是否为会话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 - object： 包含要设置的cookie详细信息的对象，对象可以具有以下属性：

    • url - string?，与cookie相关联的URL，如果未指定，则cookie与当前文档的URL相关联
    • name - string，cookie的名称
    • value - string，cookie的值
    • domain - string?，cookie的域
    • firstPartyDomain - string?： cookie的首方域
    • path - string?，cookie的路径
    • secure - bool?，是否仅通过HTTPS发送cookie
    • httpOnly - bool?，是否将cookie标记为HttpOnly
    • expirationDate - number?，cookie的过期日期，以Unix纪元以来的秒数，如果未指定，则cookie永不过期

  • callback - function?，操作完成时要调用的函数，该函数传递一个参数：

    • error - string?，如果设置cookie时出错，则包含错误消息，否则未定义

示例：

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) // 30天后过期
}, function(error) {
  if (error) {
    console.error(error);
  } else {
    console.log('Cookie设置成功，');
  }
});

GM.cookie.set({
  name: 'name',
  value: 'value'
})
.then(() => {
  console.log('Cookie设置成功，'); 
})
.catch((error) => {
  console.error(error);
});

GM_cookie.delete(details, callback)

删除cookie

参数：

详情对象必须包含以下至少一个属性：

  • url - string?，与cookie相关联的URL，如果未指定url，则使用当前文档的URL
  • name - string?，要删除的cookie的名称，
  • firstPartyDomain - string?：要删除的cookie的首方域

回调函数是可选的，它将在cookie被删除或发生错误时调用，它接受一个参数：

  • error - string?，错误消息，或在成功删除cookie时未定义

示例：

GM_cookie.delete({ name: 'cookie_name' }, function(error) {
  if (error) {
    console.error(error);

  } else {
    console.log('Cookie删除成功');
  }
});

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[...]]></>

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

var inline_src = (<><![CDATA[
  console.log('Hello World!'); 
]]></>).toString();

eval(inline_src);