TamperMonkey编写脚本常用api中文版（附文档原地址和各种api案例）

TamperMonkey脚本api文档用户脚本头部@name@namespace@version@author@description@homepage, @homepageURL, @website and @source@icon, @iconURL and @defaulticon@icon64 and @icon64URL@updateURL@downloadURL@supportURL@

good_good_xiu

45388人浏览 · 2021-07-08 16:17:13

good_good_xiu · 2021-07-08 16:17:13 发布

用户脚本头部

@name

描述脚本的名称

// ==UserScript==
// @name         autowritebycomplanywork
// ==/UserScript==

@namespace

描述脚本的命名空间，默认是http://tampermonkey.net/
@namespace 及 @name 这两个属性将帮助用户脚本管理器判断是否已安装该脚本

// ==UserScript==
// @namespace    http://tampermonkey.net/
// ==/UserScript==

@version

描述脚本版本，默认0.1
这用于更新检查，以防脚本未从 userscript.org 安装或在检索脚本元数据时出现问题。

// ==UserScript==
// @version      0.1
// ==/UserScript==

@author

描述编写脚本的作者信息

// ==UserScript==
// @author       tj
// ==/UserScript==

@description

关于脚本的简述，脚本发布时，必须修改其内容，不能使用默认的。

// ==UserScript==
// @description  try to take over the world!
// ==/UserScript==

@homepage, @homepageURL, @website and @source

描述该脚本的作者首页地址

在脚本管理的界面中，点击主页则跳转到脚本名称链接到给定页面。请注意，如果 @namespace 标记以“http://”开头，则使用@homepage或使用其他三个标签编辑作者首页链接时都需要以http://开头。

// ==UserScript==
// @homepage     http://wwww.baidu.com/
// ==/UserScript==

在这里插入图片描述
点击后，则跳转到百度。

@icon, @iconURL and @defaulticon

配置低分辨率的脚本图标。链接地址可以为http://或者https://

// ==UserScript==
// @icon         https://gimg2.baidu.com/image_search/src=http%3A%2F%2Fpic.ruiwen.com%2Fallimg%2F1808%2F5b80650664c8b96375.jpg%3Fx-oss-process%3Dstyle%2Fqr.sundxs&refer=http%3A%2F%2Fpic.ruiwen.com&app=2002&size=f9999,10000&q=a80&n=0&g=0n&fmt=jpeg?sec=1627451179&t=6529ca9c90b6bc0f2101d5e1c8af7061
// ==/UserScript==

在这里插入图片描述

@icon64 and @icon64URL

此脚本图标为 64x64 像素。如果这个标签，但被赋予了 @icon 图像将在选项页面的某些地方被缩放

// ==UserScript==
// @icon64       https://gimg2.baidu.com/image_search/src=http%3A%2F%2Fpic.ruiwen.com%2Fallimg%2F1808%2F5b80650664c8b96375.jpg%3Fx-oss-process%3Dstyle%2Fqr.sundxs&refer=http%3A%2F%2Fpic.ruiwen.com&app=2002&size=f9999,10000&q=a80&n=0&g=0n&fmt=jpeg?sec=1627451179&t=6529ca9c90b6bc0f2101d5e1c8af7061
// ==/UserScript==

@updateURL

Greasy Fork上传脚本后，使用该地址作为更新
用户脚本的更新 URL。
注意：需要一个@version 标签才能使更新检查工作。

// ==UserScript==
// @updateURL https://xxxx.com/xx/xx
// ==/UserScript==

@downloadURL

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

这里可以先将脚本另存为至桌面后，将脚本发布到自己的gitbub仓库中，然后保持tamperMonkey插件启动状态，点击脚本，点击raw就可以加载到tamperMonkey的管理面板了

在这里插入图片描述

// ==UserScript==
// @downloadURL https://xxxx.com/xx/xx
// ==/UserScript==

@supportURL

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

// ==UserScript==
// @supportURL https://xxxx.com/xx/xx
// ==/UserScript==

@include

脚本应该运行的页面。允许多个标签实例。
下面例子代表在搜狗搜索、百度搜索的页面，脚本会执行

// ==UserScript==
// @include      https://www.baidu.com/
// @include      https://www.sogou.com/
// ==/UserScript==

@match

或多或少等于 @include 标签，允许多个标签实例。

// ==UserScript==
// @match        https://www.baidu.com/
// @match        https://www.sogou.com/
// ==/UserScript==

@exclude

排除 URL，即使它们被 @include 或 @match包含。
被@exclude标签标记的url，脚本不会在此url运行，即使被@include和@match标签标记

// ==UserScript==
// @include      https://www.baidu.com/
// @include      https://www.sogou.com/
// @exclude      https://www.sogou.com/
// ==/UserScript==

@require

指向在脚本本身开始运行之前加载和执行的 JavaScript 文件。一般用于请求外部js文件。
注意：通过@require加载的脚本及其“use strict”语句可能会影响用户脚本的严格模式！

// ==UserScript==
// @require      https://cdn.bootcss.com/jquery/3.4.1/jquery.min.js
// ==/UserScript==

@resource

预加载资源，可由脚本通过 GM_getResourceURL 和 GM_getResourceText 访问的资源。

// ==UserScript==
// @resource icon1 http://www.tampermonkey.net/favicon.ico
// @resource icon2 /images/icon.png
// @resource html http://www.tampermonkey.net/index.html
// ==/UserScript==

@connect

允许多个标签实例。

// ==UserScript==
// @connect <value>
// ==/UserScript==

value可以具有以下值：

tampermonkey.net 之类的域（这也将允许所有子域）
子域，即safari.tampermonkey.net
self将脚本当前运行的域列入白名单
localhost访问本地主机
1.2.3.4连接IP地址
*
如果无法声明用户脚本可能连接到的所有域，那么执行以下操作是一个很好的做法：
声明所有已知或至少所有可能由脚本连接的公共域。通过这种方式，大多数用户可以避免确认对话框。

另外将@connect *添加到脚本中。通过这样做，Tampermonkey 仍会询问用户是否允许下一次连接到未提及的域，但还会提供“始终允许所有域”按钮。如果用户单击此按钮，则将自动允许所有未来的请求。

用户还可以通过在脚本设置选项卡中将“*”添加到用户域白名单中来将所有请求列入白名单。

笔记：
初始URL和最终 URL 都将被检查！
为了向后兼容 Scriptish @domain标签也被解释。

@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语句都将被忽略，但将来可能会更改。

// ==UserScript==
// @run-at document-start
// @run-at document-body
// @run-at document-end
// @run-at document-idle
// @run-at context-menu
// ==/UserScript==

@grant

@grant 用于将油猴提供的接口列入白名单，使脚本可以使用。例如： GM_* 函数、unsafeWindow 对象和一些强大的窗口函数列入白名单。

// ==UserScript==
// @grant        unsafeWindow
// @grant        GM_setValue
// @grant        GM_getValue
// @grant        GM_log
// ==/UserScript==

@antifeature

此标签允许脚本开发人员披露他们是否通过脚本获利。例如，GreasyFork需要它。
语法：<tag> <type> <description>
type可以有以下值:

ads
tracking
miner

// ==UserScript==
// @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
// ==/UserScript==

@noframes

此标记使脚本在主页上运行，但不在 iframe 上运行。

// ==UserScript==
// @noframes
// ==/UserScript==

@unwrap

该标签被忽略，因为 Google Chrome/Chromium 不需要它。

// ==UserScript==
// @unwrap
// ==/UserScript==

@nocompat

目前油猴试图通过查找 @match 标签来检测脚本是否是基于 Google Chrome/Chromium 的知识编写的，但并非每个脚本都使用它。这就是为什么油猴支持此标签以禁用运行为 Firefox/Greasemonkey 编写的脚本可能需要的所有优化。为了保持这个标签的可扩展性，您可以添加可由脚本处理的浏览器名称。

// ==UserScript==
// @nocompat Chrome
// ==/UserScript==

油猴提供接口

引用语法

// ==UserScript==
// @grant xxxx
// ==/UserScript==

unsafeWindow

unsafeWindow 对象提供对页面 javascript 函数和变量的完全访问。

Subresource Integrity

子资源完整性

GM_addStyle(css)

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

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

创建一个由“tag_name”指定的 HTML 元素并应用所有给定的“属性”并返回注入的 HTML 元素。如果给出了“parent_node”，则将其附加到它或以其他方式附加到文档头或体。

有关合适的“属性”，请查阅相应的文档。例如：
script tag
img tag
style tag
示例：

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_deleteValue(name)

从存储中删除“名称”。

GM_listValues()

列出存储的所有名称。

GM_addValueChangeListener(name, function(name, old_value, new_value, remote) {})

将更改侦听器添加到存储并返回侦听器 ID。
‘name’ 是观察变量的名称。
回调函数的 ‘remote’ 参数显示该值是从另一个选项卡的实例 (true) 还是在此脚本实例 (false) 中修改的。
因此，不同浏览器选项卡的脚本可以使用此功能相互通信。

GM_removeValueChangeListener(listener_id)

按 ID 删除更改侦听器。

GM_setValue(name, value)

将 ‘name’ 的值设置为存储。

GM_getValue(name, defaultValue)

从存储中获取 ‘name’ 的值。

GM_log(message)

将消息记录到控制台。

GM_getResourceText(name)

获取脚本头中预定义的@resource 标记的内容。

GM_getResourceURL(name)

获取脚本标头处预定义 @resource 标记的 base64 编码 URI。

GM_registerMenuCommand(name, fn, accessKey)

在运行此脚本的页面的 Tampermonkey 菜单中注册要显示的菜单，并返回菜单命令 ID。

GM_unregisterMenuCommand(menuCmdId)

使用给定的菜单命令 ID 取消注册先前由 GM_registerMenuCommand 注册的菜单命令。

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

使用此 url 打开一个新选项卡。选项对象可以具有以下属性：

active决定是否应该关注新选项卡
insert在当前标签之后插入新标签
setParent使浏览器在关闭和关闭时重新聚焦当前选项卡
incognito使选项卡在隐身模式/私人模式窗口中打开。

否则只是附加新选项卡。loadInBackground与active 的含义相反，添加它是为了实现 Greasemonkey 3.x 兼容性。如果既没有给定active也没有给定loadInBackground，则该选项卡将不会被聚焦。此函数返回一个对象，该对象具有函数close、侦听器onclose和一个名为closed的标志。

GM_xmlhttpRequest(details)

创建一个 xmlHttpRequest。

属性细节：

method：GET, HEAD, POST方法之一
url：目标网址
headers：user-agent, referer, … （Safari 和 Android 浏览器不支持一些特殊的标头）
data：通过POST请求发送的一些字符串
cookie：要修补到发送的 cookie 集中的 cookie
binary：以二进制方式发送数据串
nocache：不缓存资源
revalidate：重新验证可能缓存的内容
timeout：以毫秒超时
context：将添加到响应对象的属性
responseType：arraybuffer、blob、json 之一
overrideMimeType：请求的 MIME 类型
anonymous：不要随请求发送 cookie （请参阅获取说明）
fetch (beta)：使用 fetch 而不是 xhr 请求（在 Chrome 中这会导致 xhr.abort、details.timeout 和 xhr.onprogress 不起作用并使 xhr.onreadystatechange 只接收 readyState 4 个事件）
user：用于身份验证的用户名
password：用于身份验证的密码
onabort：如果请求被中止，则执行onabort回调
onerror：如果请求以错误结束，则执行onerror回调
onloadstart：如果请求开始加载则执行onloadstart回调
onprogress：如果请求取得了一些进展，则执行onprogress回调
onreadystatechange：如果请求的就绪状态发生变化，则执行onreadystatechange回调
ontimeout：如果请求因超时而失败，则执行ontimeout回调
onload：如果请求已加载，则执行onload回调。
它获得一个具有以下属性的参数：

finalUrl - 从加载数据的位置进行所有重定向后的最终 URL
readyState - 就绪状态
status - 请求状态
statusText - 请求状态文本
responseHeaders - 请求响应头
response - 如果设置了details.responseType，则响应数据作为对象
responseXML - 作为 XML 文档的响应数据
responseText - 作为纯字符串的响应数据

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

abort - 要调用的函数以取消此请求

注意：不支持详细信息处的同步标志重要提示：如果您想使用此方法，请同时查看有关@connect的文档。

GM_download(details), GM_download(url, name)

将给定的 URL 下载到本地磁盘。

详细信息可以具有以下属性：

url - 数据下载地址（必填）
name - 文件名 - 出于安全原因，文件扩展名需要在 Tampermonkey 的选项页面上列入白名单（必需）标头- 有关更多详细信息，请参阅 GM_xmlhttpRequest
saveAs - 布尔值，显示另存为对话框
onerror - 如果此下载以错误结束，则执行onerror回调
onload - 如果此下载完成，则执行onload回调
onprogress - 如果此下载取得了一些进展，则执行onprogress回调
ontimeout - 如果此下载由于超时而失败，则执行ontimeout回调

onerror回调的下载参数可以具有以下属性：
error - 错误原因

not_enabled - 用户未启用下载功能
not_whitelisted - 请求的文件扩展名未列入白名单
not_permitted - 用户启用了下载功能，但没有授予下载权限
not_supported - 浏览器/版本不支持下载功能
not_succeeded - 下载未开始或失败，详细信息属性可能提供更多信息

details - 有关该错误的详细信息

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

abort - 要调用的函数以取消此下载

根据下载模式 GM_info 提供一个名为downloadMode的属性，该属性设置为以下值之一：native、disabled或browser。

GM_getTab(callback)

只要此选项卡处于打开状态，就获取一个持久对象。

GM_saveTab(tab)

保存选项卡对象以在页面卸载后重新打开它。

GM_getTabs(callback)

获取所有选项卡对象作为散列以与其他脚本实例通信。

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

显示 HTML5 桌面通知和/或突出显示当前选项卡。

详细信息可以具有以下属性：

text - 通知的文本（除非设置了突出显示，否则为必需）
title - 通知标题
image - 图像
highlight - 一个布尔标志是否突出显示发送通知的选项卡（除非设置了文本，否则需要）
silent - 一个布尔标志是否不播放声音
timeout - 隐藏通知之后的时间（0 = 禁用）
ondone - 在通知关闭时调用（无论这是由超时还是点击触发）或选项卡突出显示
onclick - 在用户点击通知时调用

所有参数都与它们相应的详细信息属性挂件完全相同。

GM_setClipboard(data, info)

将数据复制到剪贴板。参数 ‘info’ 可以是像“{ type: ‘text’, mimetype: ‘text/plain’}”这样的对象，或者只是一个表示类型的字符串（“text”或“html”）。

GM_info

获取有关脚本和油猴的一些信息。该对象可能如下所示：

Object+
---> script: Object+
------> author: ""
------>copyright: "2012+, You"
------>description: "enter something useful"
------>excludes: Array[0]
------>homepage: null
------>icon: null
------>icon64: null
------>includes: Array[2]
------>lastUpdated: 1338465932430
------>matches: Array[2]
------>downloadMode: 'browser'
------>name: "Local File Test"
------>namespace: "http://your.homepage/"
------>options: Object+
--------->awareOfChrome: true
--------->compat_arrayleft: false
--------->compat_foreach: false
--------->compat_forvarin: false
--------->compat_metadata: false
--------->compat_prototypes: false
--------->compat_uW_gmonkey: false
--------->noframes: false
--------->override: Object+
------------>excludes: false
------------>includes: false
------------>orig_excludes: Array[0]
------------>orig_includes: Array[2]
------------>use_excludes: Array[0]
------------>use_includes: Array[0]
--------->run_at: "document-end"
------>position: 1
------>resources: Array[0]
------>run-at: "document-end"
------>system: false
------>unwrap: false
------>version: "0.1"
---> scriptMetaStr: undefined
---> scriptSource: "// ==UserScript==\n// @name       Local File Test\n ...."
---> scriptUpdateURL: undefined
---> scriptWillUpdate: false
---> scriptHandler: "Tampermonkey"
---> isIncognito: false
---> isFirstPartyIsolation: false
---> version: "4.0.25"