油猴脚本API中文参考

本文整理了大部分Tampermonkey 油猴脚本API的使用方法，并且附上了每个方法的代码示例。除此之外您可以安装油猴脚本API示例脚本在支持用户脚本的浏览器中进行测试。

提示文档中介绍的API支持及参数以X浏览器的内置脚本管理器为准,其他的脚本管理器可能会存在细微的差别。

元数据

元数据通常放置在整个脚本的开头，主要起到对脚本的一些描述，参数设定，声明，包括脚本名称、简介、作者、版本号、运行方式、所依赖的库文件声明等。

下面是一个脚本的元数据声明的例子。

// ==UserScript==// @name Say hello// @namespace com.example.hello// @version 0.1// @description When you open the site example.com it says "HELLO"// @author You// @match www.example.com// ==/UserScript==

元数据标记	描述
@name	脚本的名称
@namespace	脚本的的名字空间，可以是一个唯一标识或则网址
@description	脚本的简介，描述脚本的用法及功能等
@icon	为脚本定制一个图标，显示在脚本列表以及浏览器扩展菜单中的图标。可以是一个url图标资源或者Base64编码的 Data URI。
@author	脚本的作者姓名或昵称
@version	当前脚本的版本号
@match	定义脚本的作用域，只在匹配的网址或域名才执行脚本，此标记在元数据中可以有多行声明
@include	和@match类似，用来描述脚本的作用域，可以在元数据中存在多行声明。
@exclude	用于排除一些URL, 即使@match和@incluide已经指定匹配，可以在元数据中存在多行声明。
@require	该脚本执行前，需要依赖第三方的库，可以在元数据中存在多行声明
@resource	该脚本执行需要依赖的一些资源文件，如css,文本，图片资源等，可以在元数据中存在多行声明
@run-at	指定脚本的执行时机，不同的应用场景可能需要不同的执行时机 ,其中@run-at 的取值可以参见下表
@grant	在元数据中声明使用那些API函数

元数据标记@run-at 的取值如下

取值	描述
document-start	指定脚本在DOM树开始的时候执行，需要脚本尽早执行的时候添加此声明。
document-end	指定脚本在DOM数据加载完毕的时候执行
document-idle	页面加载完毕的时候执行。当元数据没有@run-at声明时，脚本默认在此时机执行
main-menu	X浏览器的扩展声明，表示此脚本不自动执行，用户通过主菜单扩展选项手动执行。
context-menu	X浏览器扩展声明,表示此脚本不自动执行，用户通过长按菜单的扩展选项执行
tool-menu	X浏览器扩展声明，表示此脚本不自动执行，用户通过页面工具菜单的扩展选项执行

油猴API

GM_addStyle

描述

为页面添加样式一段CSS样式。

语法

functionGM_addStyle(cssString)

参数

名称	类型	描述
cssString	字符串	字符串样式表

示例

GM.addStyle('#note{color: white; background: #3385ff!important;border-bottom: 1px solid #2d7');

GM_addElement

描述

增加一个页面元素，可以指定父节点，不指定父节点其节点为根元素。

语法

functionGM_addElement(tagName,attributes)

或者

functionGM_addElement(parentNode,tagName,attributes)

参数

名称	类型	描述
tagName	字符串	元素名称
attributes	对象	属性名称/数值对
parentNode	对象	新建元素的父节点

示例

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; };'});

GM_setValue

描述

通过指定的键值保存数据到浏览器本地存储中。

语法

functionGM_setValue(name,value)

参数

名称	类型	描述
name	字符串	字符串键值
value	任意类型	可以是整数、字符串、布尔类型、对象等任意数据

示例

GM_setValue("foo","bar");GM_setValue("count",100);GM_setValue("active",true);GM_setValue("data",{name: 'Andy',age: 18});

GM_getValue

描述

从浏览器的本地存储获取一个值。

语法

functionGM_getValue(name,defaultValue)

参数

名称	类型	描述
name	字符串	字符串键值
defaultValue	任意类型	可选项，如果键值从没有被设置过，返回默认值

返回值

如果键值被设置过，返回当初设置的数据类型。

示例

GM_setValue("foo","bar");GM_setValue("count",100);GM_setValue("active",true);GM_setValue("data",{name: 'Andy',age: 18});varinfo=`foo = ${GM_getValue("foo")} count = ${GM_getValue("count")} active = ${GM_getValue("active")} data.name = ${GM_getValue("data").name}`;alert(info);

GM_listValues

描述

返回使用所以GM_setValue 设置的键值列表。

语法

functionGM_listValues()

示例

GM_setValue("foo","bar");GM_setValue("count",100);GM_setValue("active",true);GM_setValue("data",{name: 'Andy',age: 18});alert(GM_listValues());

GM_deleteValue

描述

删除通过GM_setValue 方法设置的键值。

语法

functionGM_deleteValue(name)

参数

名称	类型	描述
name	字符串	字符串键值

示例

GM_deleteValue("foo");

letkeys=GM_listValues();for(letkeyofkeys){GM_deleteValue(key);}

GM_addValueChangeListener

描述

用来监听通过GM_setValue设置的键值对的改变

语法

functionGM_addValueChangeListener(name,callback);

参数

名称	类型	描述
name	字符串	字符串键值
callback	回调函数	当指定的键值改变时回调此函数

callback 参数列表

name - 字符串类型，键值名称
oldValue - 任意类型，以前的键值
newValue - 任意类型，新的键值。
remote - 布尔类型，来自当前标签的回调还是垮标签的回调（目前没有实现跨标签回调）

返回值

返回监听的回调函数的id,用于以后通过GM_removeValueChangeListener 方法删除回调函数。

示例

listener_id=GM_addValueChangeListener("foo",function(name,old_value,new_value,remote){alert("Value Changed:"+name+":"+old_value+"=>"+new_value);});

GM_removeValueChangeListener

描述

用来删除通过GM_addValueChangeListener添加的监听回调

语法

functionGM_removeValueChangeListener(listener_id);

参数

名称	类型	描述
listener_id	回调函数Id	GM_removeValueChangeListener返回的回调函数id

示例

GM_removeValueChangeListener(listener_id);

GM_notification

描述

显示一条通知消息

语法

functionGM_notification(details)

或者

functionGM_notification(text,title,image,onclick)

参数

名称	类型	描述
details	对象	一个包含text字段和ondone,onclick回调函数字段的对象
text	字符串	文本内容
title	字符串	参数为了兼容，手机端目前未实现
Image	对象	参数为了兼容，手机端目前未实现
onclick	回调函数	当用户点击了确定按钮的回调函数

示例

GM_notification("Hello!");GM.notification({text: 'This is a message with callback',onclick: function(){alert("you click message ok button");},ondone: function(){alert("message bar closed");}});GM_notification("Hello","","",function(){alert("you click message ok button");})

GM_setClipboard

描述

写入字符串数据到剪贴板

语法

function GM_setClipboard(data)

参数

名称	类型	描述
data	字符串	字符串内容

示例

GM_setClipboard('this is test data');

GM_registerMenuCommand

描述

注册一个菜单选项，菜单选项会显示在X浏览器的页面工具菜单中。

语法

functionGM_registerMenuCommand(title,callback)

参数

名称	类型	描述
title	字符串	菜单名称
callback	回调函数	点击菜单项执行的回调函数

返回值

返回菜单项的命令ID, 注销菜单的时候会用到

示例

GM_registerMenuCommand("click me",function(){alert("You click menu item");});

GM_unregisterMenuCommand

描述

注销之前注册的菜单项

语法

functionGM_unregisterMenuCommand(commandId)

参数

名称	类型	描述
commandId	字符串	菜单项的命令id

示例

GM_unregisterMenuCommand(commandId);

GM_openInTab

描述

在新标签中打开一个页面

语法

functionGM_openInTab(url,background)

参数

名称	类型	描述
url	字符串	新标签页面的网址
background	布尔类型	是否在后台打开标签,默认为false

示例

GM_openInTab("https://www.example.com");GM_openInTab("https://www.example.com",true);

GM_download

描述

调用浏览器的默认下载器进行下载

语法

functionGM_download(url,name)

或者

functionGM_download(detail)

参数

名称	类型	描述
url	字符串	要下载资源的网址
name	字符串	下载文件保存的名称
detail	对象	通过对象配置下载参数

detail 参数属性列表

url - 字符串类型，表示要下载的网址
name - 字符串类型，下载文件保存的名称
hedaers - 对象类型，HTTP请求头
onload - 回调函数，下载完成.
onerror - 回调函数，下载出错
tag - 字符串 ,下载文件打上标签，X浏览器的实现是相同tag的资源保存在以标签命名的目录。

示例

GM_download("https://www.xbext.com/download/xbrowser-release.apk")

//指定下载保存文件名称GM_download("https://www.xbext.com/download/xbrowser-release.apk,"xbrowser.apk")

leturls=["https://www.dundeecity.gov.uk/sites/default/files/publications/civic_renewal_forms.zip","https://www.dundeecity.gov.uk/sites/default/files/publications/civic_renewal_forms.zip","https://www.dundeecity.gov.uk/sites/default/files/publications/civic_renewal_forms.zip",];vari=0;for(leturlofurls){GM_download({url: `${url}`,name: `test-file${++i}.zip`,headers:{Referer:"https://www.example.com/"},onload: function(){console.log("download completed !");},tag: "test-file"/* 此属性为 x的扩展，在下载目录中创建名字为tag的子目录中统一保存 */});}

GM_getResourceText

描述

获取元数据标记@resource指向资源的文本内容。

语法

functionGM_getResourceText(name)

参数

名称	类型	描述
name	字符串	标记@resource 定义的用于引用资源的键值名称

示例

// @resource main-content https://www.example.com/res/main-content.txtvartext=GM_getResourceText("main-content");

返回值

返回资源URL的文本内容。

GM_getResourceURL

描述

获取元数据标记@resource 指向资源的内容，内容以Base64编码，格式为Data URI格式。

语法

functionGM_getResourceURL(name)

参数

名称	类型	描述
name	字符串	标记@resource 定义的用于引用资源的键值名称

示例

varimg=document.querySelector("#avatar")//@resource avatar01 https://api.multiavatar.com/avatar01.svgimg.src=GM_getResourceURL("avatar01");

返回值

返回以Base64编码的Data URI。

GM_xmlhttpRequest

描述

这个方法类似于XMLHttpRequest 对象, 不同的是此方法支持跨域请求，突破了对象同源访问策略,使用起来更加灵活。

语法

functionGM_xmlhttpRequest(details)

参数

这个方法只有对象类型的参数details ，对象的属性列表和含义如下：

名称	类型	描述
details	对象	包含一系列属性作为控制参数

details 属性说明

method - Http请求方法，GET、POST、HEAD等。
url - 字符串，目标请求URL。
headers - 可选项，字符串，HTTP协议头，User-Agent，Referer等。
data - 可选项，字符串，通过POST方法发送的数据
responseType - 可选项，字符串，设置响应类型，可以为arraybuffer, blob, json 和 stream 之一。
onabort- 可选项，回调函数，当HTTP请求被终止时调用。
onerror- 可选项，回调函数，HTTP请求出现异常时被调用
onloadstart - 可选项，回调函数，HTTP请求开始被调用
onreadystatechange - 可选项，回调函数，HTTP请求状态变化被调用
onload - 可选项，回调函数，当HTTP请求完成时被调用，回调函数参数携带的几个属性如下
- finalUrl - HTTP 最终请求的URL地址，比如最后重定向的网址。
- readyState - 数据状态
- status - HTTP请求状态
- statusText - HTTP请求状态文本
- responseHeaders - HTTP响应头
- response - HTTP响应返回的对象类型数据，当 details.responseType 被设置返回相应类型的对象。
- responseText - 返回文本类型的数据

示例

//发起一个get请求GM_xmlhttpRequest({method: "GET",url: "http://www.example.com/",onload: function(response){alert(response.responseText);}});

//发起一个post请求GM.xmlHttpRequest({method: "POST",url: "https://www.example.net/login",data: "username=johndoe&password=xyz123",headers: {"Content-Type": "application/x-www-form-urlencoded"},onload: function(response){if(response.responseText.indexOf("Logged in as")>-1){location.href="http://www.example.net/dashboard";}}});

urlchange

这是扩展的一个事件函数，常用于单页面应用监听浏览器url变化。

示例

window.addEventListener('urlchange',()=>{alert("urlchange");});//当页面跳转到一个新的锚点会触发urlchange事件window.location="#test"

GM_cookie

描述

该方法可以突破浏览器对Cookie的跨域限制，对某个网站下的Cookie进行操作，包括获取、设置、删除Cookie。此方法存在安全隐患，可能会导致用户隐私信息泄露。目前主要为了兼容一些脚本，暂时支持这个方法，后续可能会限制这个方法的使用。

语法

functionGM_cookie(action,details,callback)

参数

名称	类型	描述
action	字符串	对Cookie的操作方式 [list,set,delete]
details	对象	包含一系列属性作为参数
callback	回调函数	返回对Cookie操作的结果

action 可选项

list - 获取某个域名下的Cookies 列表
set - 设置某个域名下的Cookie
delete - 删除某个域名下的Cookie

details 属性说明

url - 页面网址
domain - Cookie域名。
name - 字符串，Cookie键值
value -字符串，Cookie内容。

示例

获取某个域名下的Cookies 列表

GM_cookie('list',{url: "https://www.example.com",},function(result){console.log(result);});

删除某个域名下的Cookie

GM_cookie('delete',{url: "https://www.example.com",name: "test"},function(result){console.log(result);});

设置某个域名下的Cookie

GM_cookie('set',{url: "https://www.example.com",name: "test",value: "test",},function(result){console.log(result);});

为了兼容一些其它脚本GM_cookie函数同时也支持下面的调用方式

//获取某个域名下的cookiesGM_cookie.list({url: "https://www.example.com",},function(result){console.log(result);});//设置某个域名下的CookieGM_cookie.set({url: "https://www.example.com",name: "test",value: "test",},function(result){console.log(result);});//删除某个域名下的CookieGM_cookie.delete({url: "https://www.example.com",name: "test"},function(result){console.log(result);});

GM_info

这是一个对象，用来保存每个脚本的相关环境变量，比如脚本的版本、作者、介绍等，对象属性列表如下：

script - 对象类型，包含下面一些属性。
- author - 脚本作者
- name - 脚本名称
- description - 脚本介绍
- version - 版本
- copyright - 版权信息
- includes - 数组类型，包含匹配页面的列表
- matches - 数组类型，和includes类似，包含匹配页面的列表
- excludes -数组类型，排除匹配网址列表
- resources - 数组类型，所有资源列表
version - 脚本管理器的版本
scriptHandler - 脚本管理器的名称
scriptMetaStr - 脚本管理器元数据字符串

示例

varinfo="Script Name: "+GM_info.script.name+"\nVersion: "+GM_info.script.version+"\nVersion: "+GM_info.script.version+"\nScriptHandler: "+GM_info.scriptHandler+"\nScript Handler Version : "+GM_info.version;alert(info);

Name		Name	Last commit message	Last commit date
Latest commit History 5 Commits
README-en.md		README-en.md
README.md		README.md

Folders and files

Latest commit

History

Repository files navigation