Tampermonkey中文文档(部分)

内容

Userscript Header

@name

@namespace

@version

@author

@description

@homepage, @homepageURL, @website and @source

@icon, @iconURL and @defaulticon

@icon64 and @icon64URL

@updateURL

@downloadURL

@supportURL

@include

@match

@exclude

@require

@resource

@connect

@run-at

@grant

@noframes

@unwrap

@nocompat

Application Programming Interface

unsafeWindow

Subresource Integrity

GM_addStyle(css)(TM4.0+弃用)

GM_deleteValue(name)

GM_listValues()

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

GM_removeValueChangeListener(listener_id)

GM_setValue(name, value)

GM_getValue(name, defaultValue)

GM_log(message)

GM_getResourceText(name)

GM_getResourceURL(name)

GM_registerMenuCommand(name, fn, accessKey)

GM_unregisterMenuCommand(menuCmdId)

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

GM_xmlhttpRequest(details)

GM_download(details), GM_download(url, name)

GM_getTab(cb)

GM_saveTab(tab)

GM_getTabs(cb)

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

GM_setClipboard(data, info)

GM_info

<><![CDATA[your_text_here]]></>

 

 

Userscript Header

@name

脚本的名称

@namespace

该脚本的命名空间

@version

版本号。当脚本未从 userscript.org安装时或 Tampermonkey 检索脚本元数据有问题时,用于更新检查。

@author

作者

@description

简介

@homepage, @homepageURL, @website and @source

作者主页,用于在Tampermonkey选项页面上从脚本名称点击跳转。请注意,如果`@namespace`标记以"http://"开头,此处也要一样。

@icon, @iconURL and @defaulticon

低分辨率图标

@icon64 and @icon64URL

64x64的图标。如果同时定义`@icon`和`@icon64`,Tampermonkey仍可能优先使用`@icon`定义的图标。

@updateURL

检查更新的网址。注意:需要定义@version

@downloadURL

更新下载脚本的网址,如果定义成`none`就不会检查更新。

@supportURL

报告问题的网址

@include

脚本生效地址,每行一个。不支持URL hash(即网址中的#),详情点击https://forum.tampermonkey.net/viewtopic.php?p=3094

示例:

// @include http://tampermonkey.net/*
// @include http://*
// @include https://*
// @include *

@match

约等于@include标签,详情点击http://code.google.com/chrome/extensions/match_patterns.html。

注意:"<all_urls>"语句尚不支持,scheme部分也接受"http*://"。

@exclude

不生效页面,每行一个。优先于`@include`和`@match`

@require

脚本本身开始运行之前加载并执行的JavaScript文件,每行一个。通过@require加载的脚本如果是严格模式("use strict")的,可能会影响本脚本的严格模式!

Code:

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

有关如何确保完整性的内容可以阅读`sub-resource integrity`

@resource

预加载资源,可通过GM_getResourceURL和GM_getResourceText读取

Code:

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

有关如何确保完整性的内容可以阅读`sub-resource integrity`

@connect

允许被GM_xmlhttpRequest访问的域名,不能是顶级域(`.com`、`.net`之类)。每行一个。

Code:

// @connect <value>

<value> 可以具有以下值

  • 域名,例如tampermonkey.net(这也将允许所有子域)

  • 子域名,即safari.tampermonkey.net

  • self,即脚本运行的网址

  • localhost

  • IP地址,例如1.2.3.4

  • *

如果无法全部声明脚本可能连接到的所有域,那么这是下面是推荐做法:

声明所有已知的域名,大多数用户可以避免请求链接外部域名的确认框。

另外添加`// @connect *`,对于没有显式标明的域名,Tampermonkey仍然会询问用户是否允许建立连接。如果用户点击`始终允许所有域(Always allow all domains)`,则将自动允许未来的所有请求。

用户还可以通过在脚本设置选项卡中将`*`添加到白名单。

Notes:

- both, the initial and the final URL will be checked!

- Scriptish的`@domain`会视为`@connect`。

@run-at

定义脚本注入的时刻。与其他脚本处理程序不同,`@run-at`定义了脚本可以运行的最初时刻。这意味着,通过`@require`引入的脚本如果在获取时耗费过多时间,那么脚本可能在网页加载后执行。无论如何,在给定注入时刻后且脚本注入成功的情况下,发生的所有`DOMNodeInserted`和`DOMContentLoaded`事件都会传递到用户脚本。

Code:

// @run-at document-start

脚本将尽可能快地注入。

Code:

// @run-at document-body

如果body元素存在,则脚本将被注入。

Code:

// @run-at document-end

该脚本将在发生DOMContentLoaded事件时或之后注入。

Code:

// @run-at document-idle

在发生DOMContentLoaded事件后注入脚本。

Code:

// @run-at context-menu

如果在浏览器上下文菜单(仅限桌面Chrome浏览器)中点击该脚本,则会注入该脚本。注意:如果使用此值,则将忽略所有@include和@exclude语句,但这可能会在将来更改。

@grant

用于添加GM_ 函数到白名单,例如unsafeWindow对象和一些强大的window函数。如果没有给出@grant标签Tampermonkey会猜测脚本需要。

Code:

// @grant GM_setValue
// @grant GM_getValue
// @grant GM_setClipboard
// @grant unsafeWindow
// @grant window.close
// @grant window.focus

另外window.close和window.focus必须显式声明。

如果使用// @grant none,沙箱将被禁用,脚本将直接在页面上下文中运行。在此模式下,没有GM_ 函数,但GM_info属性仍然可用。

Code:

// @grant none

@noframes

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

@unwrap

此标记会被忽略,因为Google Chrome / Chromium不需要此标记。

@nocompat

由于部分代码可能是专门为专门的浏览器所写,通过此标记,Tampermonkey会知道脚本可以运行的浏览器。

Code:

// @nocompat支持的浏览器
// @nocompat Chrome

 

APPLICATION PROGRAMMING INTERFACE

unsafeWindow

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

Subresource Integrity

`@resource`和`@require`标记的URL的hash(#)部分可用于此检查完整性。

Code:

// @resource SRIsecured1 http://tampermonkey.net/favicon1.ico#md5=ad34bb...
// @resource SRIsecured2 http://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...

Tampermonkey自身支持MD5校验,其他(SHA-1,SHA-256,SHA-384和SHA-512)依赖于window.crypto。在多个hash(由逗号或分号分隔)的情况下,TM使用最后一个支持的hash。如果外部资源的内容不匹配所选的hash,则资源不会传递给userscript。所有校验码必须是hex或者base64格式。

GM_addStyle(css)(TM4.0+弃用)

将给定的CSS添加到document。

例子GM_addStyle('#uiSideNav uiSideNavSection uiFutureSideNavSection{ background-color:#ffffff; }');

GM_deleteValue(name)

从storage中删除"name"。

GM_listValues()

列出storage的所有key。

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

向storage添加一个change listener,并返回此监听器ID。

'name'是被观察变量的名称。

回调函数的'remote'参数表明此值的修改者是另一个网页(browser tabs)的实例(true),或是在此脚本实例(false)。

因此脚本可以通过`function`在不同的网页(browser tabs)互相通信。

GM_removeValueChangeListener(listener_id)

通过ID删除change listener。

GM_setValue(name, value)

在storage中存储值。

GM_getValue(name, defaultValue)

在storage中取得name的值,取不到则使用defaultValue。

GM_log(message)

将消息记录到控制台。

GM_getResourceText(name)

获取`@resource`标记定义的内容。

GM_getResourceURL(name)

获取`@resource`标记定义的base64编码的URI。

GM_registerMenuCommand(name, fn, accessKey)

在要运行脚本的网页上,在Tampermonkey中注册一个menu,并返回menu的命令 id。

GM_unregisterMenuCommand(menuCmdId)

通过menu id反注册由GM_registerMenuCommand注册menu。

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

根据url打开新tab。options对象有以下属性:

- `active`决定新的选项卡是否在前台打开

- `insert`决定是否在当前标签之后打开新标签页

- `setParent`关闭新选项卡后是否返回当前选项卡

其他情况都是仅仅添加新选项卡。`loadInBackground`与`active`相反,用于实现Greasemonkey 3.x的兼容性。如果既没有`active`也没有`loadInBackground`,那么选项卡不会在前台打开。这个函数返回一个对象,该对象具有close方法,onclosed监听器,closed标志。

GM_xmlhttpRequest(details)

创建一个xmlHttpRequest。

详细属性:

  • method - GET,HEAD,POST之一

  • url - 目标网址

  • headers - 即user-agent, referer, ... (Safari和Android浏览器不支持某些特殊headers

  • data - 通过 POST 请求发送的字符串

  • binary - 以二进制模式发送数据

  • timeout - 超时时间(单位ms)

  • context - 将添加到response对象的属性

  • responseType - arraybuffer,blob,json之一

  • overrideMimeType - request的MIME类型

  • anonymous - request将不发送cookies,参见fetch

  • fetch - (beta) 使用fetch而不是xhr,在Chrome这会导致xhr.abort,details.timeout和xhr.onprogress失效,并使xhr.onreadystatechange只接收readyState4事件。

  • username 用于认证的用户名

  • password 密码

  • `onabort` callback to be executed if the request was aborted

  • `onerror` callback to be executed if the request ended up with an error

  • - `onloadstart` callback to be executed if the request started to load

  • - `onprogress` callback to be executed if the request made some progress

  • - `onreadystatechange` callback to be executed if the request's ready state changed

  • - `ontimeout` callback to be executed if the request failed due to a timeout

  • - `onload` 成功请求时触发的callback。这个callback有一个参数包含以下属性:

  • >- `finalUrl` - 重定向后最终的URL

  • >- `readyState` - the ready state

  • >- `status` - the request status

  • >- `statusText` - the request status text

  • >- `responseHeaders` - response headers

  • >- `response` - 如果设置了`details.responseType`,那么response data会被视为一个对象

  • >- `responseXML` - the response data as XML document

  • >- `responseText` - the response data as plain string

 

返回值:一个包含以下属性的`object`:

- `abort` - function to be called to cancel this request

 

Note: 不支持`details`对象的`synchronous` 属性

Note: 如果想使用`GM_xmlhttpRequest`,请参阅`@connect`。

GM_download(details), GM_download(url, name)

从给定的 URL 下载。

details可以具有下列属性:

  • url - 下载数据的 url 路径

  • name - 文件名,因为安全原因,文件扩展名必须显式声明于Tampermonkey 白名单。

  • headers - 参见GM_xmlhttpRequest。

  • saveAs - 布尔值,是否显示保存对话框.

  • onload - function() {} - 下载完成后调用的函数

  • onerror - function(download) {} - 当出现错误时调用的函数

onerror参数可以具有以下属性:

  • error -错误原因

    • not_enabled -用户未启用下载功能
    • not_whitelisted -所请求的文件扩展名没有列入白名单
    • not_permitted - 用户启用了下载功能,但没有给予下载权限
    • not_supported - 浏览器不支持下载功能
    • not_succeeded -下载启动失败,details属性提供更多信息
  • details -关于该错误的详细信息

根据下载模式,GM_info提供了一个名为downloadMode的属性,该属性设置为以下值之一:native,,disabledbrowser.

Advertisement

GM_getTab(cb)

获取一个tab的持久化对象,只要此选项卡是打开的。

GM_saveTab(tab)

保存tab对象以在页面unload后重新打开。

GM_getTabs(cb)

获取所有tab对象的hash,以便与其他脚本实例进行通信。

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

显示一个 HTML5 桌面通知(Desktop notification)或高亮当前tab。

details可以具有以下属性:

  • text - 通知的文本,如果设置了highlight

  • title - 通知标题(可选)

  • image - 图像(可选)

  • highlight - 布尔值,发送通知时是否要高亮tab(可选)

  • timeout - 多久后通知将会隐藏 (可选,0 = 禁用)

  • ondone - 当关闭通知时调用(无论是由于超时或鼠标单击),或选项卡已经是高亮状态(可选)

  • onclick - 用户单击通知时调用(可选)

All parameters do exactly the same like their corresponding details property pendant.

GM_setClipboard(data, info)

将数据复制到剪贴板。参数 ' info ' 可以是对象,例如"{ type: 'text', mimetype: 'text/plain'}"或仅仅是一个字符串表达式(text或者html类型)。

GM_info

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

Code:

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://use.i.E.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
---> version: "4.0.25"

<><![CDATA[your_text_here]]></>

Tampermonkey支持这种写法,会尝试自动检测脚本是否需要启用此兼容性选项。

已标记关键词 清除标记
©️2020 CSDN 皮肤主题: 大白 设计师:CSDN官方博客 返回首页