油猴子(Tampermonkey )API userscliptAPI 中文翻译

由官网翻译为https://www.tampermonkey.net/documentation.php?ext=dhdg#_name

以下标签使用样例：// 这个双反斜杠是必须有的，必须写在 // UserScript @标签 //
/UserScript内部 // UserScript // @name New Userscript // @namespace http://tampermonkey.net/ // @version 0.1 //
@description try to take over the world! // @author You //
@match https://www.tampermonkey.net/documentation.php?ext=dhdg
// @grant none // /UserScript

@name 脚本名称 用法 // @name A test // @name:de Ein Test

@namespace 脚本的命名空间

@version 脚本版本，这用于更新检查，以防脚本未从 userscript.org 安装，或者 TM 在检索脚本元数据时遇到问题。

@author 脚本作者

@description 简短的重要描述。国际化是通过添加一个附录来命名本地。
// @description This userscript does wonderful things
// @description:de Dieses Userscript tut wundervolle Dinge

@homepage、@homepageURL、@website和@source
作者主页用于选项页面，以便从脚本名称链接到给定页面。请注意，如果@namespace标签以"http://"开头，其内容也将用于此。

@icon、@iconURL和@defaulticon 低重的脚本图标。

@icon64和@icon64URL 此脚本图标为 64x64
像素。如果此标记，但给@icon，则在选项页面的某些位置将缩放@icon图像。

@updateURL 用户脚本的更新网址。 注意：需要一个@version标签才能使更新检查工作

@downloadURL 定义检测到更新时将下载脚本的网址。如果未使用任何值，则不会进行更新检查。

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

@include 该脚本上的页面应该运行。允许多个标签实例。
请注意，@include不支持URL哈希参数。你必须匹配路径没有哈希参数，并利用窗口。 // @include
http://www.tampermonkey.net/* // @include http://* // @include
https://* // @include /^https://www.tampermonkey.net/.*$/ //
@include *

@match 或多或少等于@include标签。你可以在这里得到更多的信息。
注：“lt;all_urls"声明尚未得到支持，计划部分也接受"http*：//”。 允许多个标签实 例。

@exclude 排除网址，即使它包括在@include或@match。允许多个标签实例。

@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

有关如何确保完整性的更多信息，请查看子资源完整性部分。允许多个标签实例

@connect此标记定义域（无顶级域），包括允许通过GM_xmlhttpRequest检索的子域
用法：// @connect
像tampermonkey.net这样的域（这也将允许所有子域）
子域，即safari.tampermonkey.net
自我将脚本当前运行的域列入白名单
本地托家访问本地托家
1.2.3.4连接到 IP 地址
如果无法声明用户脚本可能连接到的所有域，则这样做是一个很好的做法：
声明可能由脚本连接的所有已知域或至少是所有常见域。这样可以避免大多数用户的确认对话。
此外，在脚本中添加"@connect*"。
通过这样做，Tampermonkey仍然会问用户是否允许下一个连接到未提及的域，但也提供一个"始终允许所有域"按钮。如果用户单击此按钮，则将自动允许所有未来的请求。用户还可以通过在脚本设置选项卡中将"*"添加到用户域白名单来将所有请求列入白
名单。
同时，将检查初始和最终URL！
对于脚本@domain标签的向后兼容性也进行了解释。
允许多个标签实例。

@run
定义注入脚本的瞬间。与其他脚本处理程序相反，@run定义脚本想要运行的第一个可能时刻。这意味着它可能发生，使用@require标签的脚本可能会在文档加载后执行，导致提取所需的脚本需要那么长时间。无论如何，在给定注射时刻之后发生的所有
DOMNodeInsered 和 DOM 提交加载事件在注射时缓存并交付到脚本中。
用法： // @run-at document-start
脚本将尽快注入。
用法：
// @run-at document-body
如果存在主体元素，将注入脚本。
用法：
// @run-at document-end
脚本将在 DOM 会议加载事件发出时或之后注入。
用法：
// @run-at document-idle
脚本将在 DOM 已加载事件发送后注入。如果没有给出@run标签，则这是默认值。
用法：
// @run-at context-menu
如果在浏览器上下文菜单上单击脚本，将注入脚本（仅基于桌面Chrome浏览器）。
注意：如果使用此值，所有@include和@exclude语句都将被忽略，但将来可能会发生变化。

@grant @grant用于将GM_*功能、不安全的窗口对象和一些强大的窗口功能列入白名单。如果没有@grant标签被给予TM猜测脚本需要
// @grant GM_setValue
// @grant GM_getValue
// @grant GM_setClipboard
// @grant unsafeWindow
// @grant window.close
// @grant window.focus
// @grant window.onurlchange
由于关闭和对焦选项卡是一个强大的功能，因此还需要添加到@grant语句中。
如果脚本在单页应用程序上运行，则可以使用
窗口。
// UserScript
…
// @grant window.onurlchange
// /UserScript

if (window.onurlchange === null) {
    // feature is supported
    window.addEventListener('urlchange', (info) => ...);
}
如果@grant后面是"无"，则沙盒将被禁用，脚本将直接在页面上下文中运行。在此模式下，没有GM_*功能，但GM_info属性将可用。
法典：
// @grant none

@antifeature
这个标签允许脚本开发者公开他们的脚本是否盈利。例如，GreasyFork《https://greasyfork.org/zh-CN》就需要它。
语法: 可以有以下值: 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 国际化是通过添加一个附录来命名本地。

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

@unwrap 这个标签被忽略，因为，它是不需要在谷歌。

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

应用程序编程界面： 不安全的窗口：不安全的窗口对象可完全访问页面抓取脚本函数和变量。

子资源完整性：@resource和@require标签 URL 的哈希组件可用于此目的。 // @resource SRIsecured1
http://www.tampermonkey.net/favicon1.ico#md5=ad34bb… // @resource
SRIsecured2
http://www.tampermonkey.net/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…
TM 支持 MD5 原生回退，所有其他（SHA-1、SHA-256、SHA-384 和
SHA-512）都依赖于窗口。如果给定了多个哈希（按逗号或分号分离），TM
将使用当前支持的最后一个。如果外部资源的内容与选定的哈希不匹配，则资源不会交付给用户脚本。所有哈希都需要以十六进制或 Base64
格式编码。

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

GM_addElement（tag_name属性）、GM_addElement（parent_node、tag_name、属性）
创建由"tag_name"指定的 HTML 元素，并应用所有给定的"属性"并返回注入的 HTML
元素。如果给出了"parent_node"，则将其连接到它或以其他方式记录头部或身体。 有关合适的"属性"，请查阅相应的文 档。例如：
script
tag《https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script》
img tag
《https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img》 style
tag《https://developer.mozilla.org/en-US/docs/Web/HTML/Element/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_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)：将"名称"值设置为存储。

GM_getValue(name, defaultValue)：从存储中获取"名称"值。

GM_log（message）将消息记录到控制台。

GM_getResourceText(name) 在脚本标题上获取预先定义的@resource标签的内容。

GM_getResourceURL(name) 在脚本标题上获取预先定义的@resource标签的基数 64 编码 URI。

GM_registerMenuCommand(name, fn, accessKey) 在脚本运行的页面上注册要显示在
Tampermonkey 菜单上的菜单，并返回菜单命令 ID。

GM_unregisterMenuCommand(menuCmdId)
取消注册以前由GM_registerMenuCommand用给定的菜单命令 ID 注册的菜单命令。

GM_openInTab(url, options), GM_openInTab(url, loadInBackground)
用这个url打开一个新标签。options对象可以有以下属性:
active 决定新标签是否应该聚焦，
insert 将新标签插入到当前标签之后，
setParent 使浏览器重新聚焦当前标签关闭和
incognito 使标签被打开在一个隐身模式/私人模式窗口。 否则，新选项卡将被附加。loadInBackground与active的含义相反，是为了实现Greasemonkey
3而添加的。x兼容性。如果active和loadInBackground都没有给出，那么标签将不会被聚焦。这个函数返回一个带有函数close、监听器onclose和一个名为closed的标志的对象。
GM_xmlhttpRequest（details） Make an xmlHttpRequest.

Property of details: method one of GET, HEAD, POST url 目的地网址 headers
ie. user-agent, referer, … (some special headers are not supported
by Safari and Android browsers) data 一些字符串通过post请求发送 cookie a cookie
to be patched into the sent cookie set binary 以二进制模式发送数据字符串 nocache
不缓存资源 revalidate 重新验证缓存的内容 timeout 超时-毫秒 context 将添加到响应对象的属性
responseType 响应类型： arraybuffer, blob, json overrideMimeType 请求的MIME类型
anonymous 不要发送带有请求的cookie（请参阅取件说明） fetch （测试版）使用fetch而不是xhr请求 (at
Chrome this causes xhr.abort, details.timeout and xhr.onprogress to
not work and makes xhr.onreadystatechange receive only readyState 4
events) user 身份验证的用户名 password 密码 如果请求被中止，将执行回调 如果请求最终出现错误，则将执行单调回
如果请求开始加载，将执行卸载启动回调 如果请求取得了一些进展，将执行进度回调 如果请求的就绪状态发生变化，将执行已准备好的状态调用
如果请求因超时而失败，将执行超时回调 如果加载请求，将执行加载回调 它得到一个参数与以下属性： finalUrl -
最终URL毕竟从加载数据的位置重定向 readyState - 就绪状态 status - 请求状态 statusText - 请求状态文本
responseHeaders --请求响应标题 response - 如果设置详细信息，则响应数据作为对象。 responseXML -
响应数据为XML对象 responseText - 响应数据为纯字符串 返回具有以下属性的对象： abort - 功能将被调用以取消此请求

注意：在细节同步标志不支持
重要：如果你想使用这种方法，那么也请检查有关@connect《https://www.tampermonkey.net/documentation.php?ext=dhdg#_connect》文档。

GM_download(details), GM_download(url, name)
将给定的URL下载到本地磁盘。详细信息可以具有以下属性： url - 应从该数据下载位置下载的URL（需要） name -
-文件名称-出于安全原因，文件扩展需要在Tampermonkey’s的选项页面（需要）列入白名单 headers - 有关详细信息，请参阅GM_xmlhttpRequest saveAs - 布尔值，显示保存作为对话框 如果此下载最终出现错误，则将执行单调用
加载回调要执行，如果此下载完成 如果此下载取得了一些进展，将执行进度回调 如果此下载因超时而失败，则将执行超时回拨

onerror回调的下载参数可以具有以下属性： 错误-错误原因 not_enabled - 下载功能不由用户启用
not_whitelisted - 请求的文件扩展未列入白名单 not_permitted - 用户启用了下载功能，但没有授予下载权限
not_supported - 下载功能不受浏览器/版本的支持 not_succeeded -
下载未开始或失败，详细信息属性可能会提供更多信息 details - -有关该错误的细节 返回具有以下属性的对象： abort -
功能被调用取消此下载

根据下载模式，GM_info提供名为"下载模式"的属性，该属性设置为以下值之一：原生、禁用或浏览器。
GM_getTab(callback) 只要此选项卡处于打开状态，就获取持久性的对象。

GM_saveTab(tab) 保存选项卡对象，以便在页面卸载后重新打开它。

GM_getTabs(callback) 将所有选项卡对象作为哈希，以便与其他脚本实例进行通信。

GM_notification(details, ondone), GM_notification(text, title, image,
onclick) 显示HTML5桌面通知和/或突出显示当前选项卡。 details can have the following
attributes: text - the text of the notification (required unless
highlight is set) title - the notificaton title image - the image
highlight - a boolean flag whether to highlight the tab that sends the
notfication (required unless text is set) silent - a boolean flag
whether to not play a sound timeout - the time after that the
notification will be hidden (0 = disabled) ondone - called when the
notification is closed (no matter if this was triggered by a timeout
or a click) or the tab was highlighted onclick - called in case the
user clicks the notification 所有参数都与相应的细节属性完全相同。

GM_setClipboard(data, info)
将数据复制到剪贴板中。参数"信息"可以是一个对象，如"{类型：“文本”，哑剧类型：“文本/平原”}"或只是一个字符串表示类型（“文本"或"html”）。
GM_info 获取有关脚本和TM的一些信息。对象可能看起来像这样：

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”

<><![CDATA[your_text_here]]></> Tampermonkey 支持这种存储元数据的方式。TM
尝试自动检测脚本是否需要启用此兼容性选项。