油猴 API

介绍如何使用 Tampermonkey API

用户脚本标头(部分)

名称	描述	参数
name	脚本名称	-
namespace	脚本命名空间	-
version	脚本版本	语义化版本规则
author	脚本作者	-
description	脚本描述	-
include	脚本匹配地址	允许正则匹配
match	脚本匹配地址	使用*表示通配，使用更严格
exclude	排除脚本匹配地址	-
require	引入外部JS文件	指向脚本开始运行之前加载并执行的 JavaScript 文件
resource	预加载资源	预加载的资源由GM_getResourceURL/Text访问
connect	获取网站访问权限	允许由GM_xmlhttpRequest检索的子域
run-at	脚本的运行时机	document-start/body/end/idle/menu 详细
grant	申请API权限	none表示页面环境 unsafeWindow表示沙盒环境
noframes	脚本标记	标记使脚本在主页上运行，但不在 iframe 上运行

API 说明

名称	描述
GM_addStyle	将给定样式添加到文档中并返回注入的样式元素
GM_addElement	创建指定的 HTML 元素，应用所有给定的"属性"并返回注入的 HTML 元素，此功能是实验性的，API 可能会更改
GM_setValue	将"名称"的值设置为存储
GM_getValue	从 GM_setValue 存储的"名称"中获取值
GM_deleteValue	将 GM_setValue 存储的"名称"删除
GM_listValues	列出GM_setValue 存储的所有"名称"
GM_addValueChangeListener	侦听 GM_setValue 储存"名称"的值的更改并返回更改前和后的值
GM_removeValueChangeListener	删除由 GM_addValueChangeListener 添加的侦听器
GM_log	向控制台记录消息
GM_getResourceText	获取由 resource 预加载的资源
GM_getResourceURL	获取由 resource 预加载的 base64 编码 URI
GM_registerMenuCommand	注册一个菜单，在运行此脚本的页面中显示
GM_registerMenuCommand	取消由 GM_registerMenuCommand 注册的菜单
GM_openInTab	通过给定的 URL 打开一个新标签页
GM_xmlhttpRequest	通过脚本发送的XHR请求
GM_download	通过给定的 URL 下载文件到本地
GM_saveTab	保存选项卡对象，生命周期为选项卡的打开->关闭
GM_getTab	获取选项卡对象，生命周期为选项卡的打开->关闭
GM_getTabs	获取所有选项卡对象，生命周期为选项卡的打开->关闭
GM_notification	显示 HTML5 桌面通知
GM_setClipboard	将数据复制到剪贴板

使用方法/示例

使用油猴GM_*函数必须声明在沙盒环境中运行 @grant none

// @grant        unsafeWindow

GM_addStyle & GM_getResourceText

// @grant        GM_addStyle
// @grant        GM_getResourceText
// @resource css https://cdn.jsdelivr.net/npm/index.css

GM_addStyle(GM_getResourceText(css))

GM_addStyle(`
    body{
        background-color: orange;
    }
`)

GM_addElement

// @grant        GM_addElement

GM_addElement('script', {
    src: 'https://cdn.jsdelivr.net/npm/index.js',
    type: 'text/javascript'
})

GM_addElement('link', {
    href: 'https://cdn.jsdelivr.net/npm/index.css',
    rel: 'stylesheet'
})

GM_set/get/deleteValue & GM_listValues

// @grant        GM_setValue
// @grant        GM_getValue
// @grant        GM_listValues
// @grant        GM_deleteValue

let value = "hello world"

GM_setValue("value", value)        // 将"名称"的值设置为存储

console.log(GM_getValue("value"))  // 从存储中获取"名称"的值 => hello world

console.log(GM_listValues())       // 列出存储的所有名称 => ['value']

GM_deleteValue("value")            // 从存储中删除"名称"

console.log(GM_listValues())       // => []

GM_add/removeValueChangeListener

// @grant        GM_setValue
// @grant        GM_addValueChangeListener
// @grant        GM_removeValueChangeListener

GM_addValueChangeListener('value', function (name, old_value, new_value, remote) {
    
    console.log(name, old_value, new_value, remote)

    // 3秒后输出 =>value old_value new_value false

})

setTimeout(() => {

    GM_setValue('value', 'new_value')

}, 3000)

setTimeout(() => {

    GM_removeValueChangeListener(add)  // 按 ID 删除侦听器

    console.log('已删除');

    GM_setValue('value', 'new_value1') // 这里改变'value'的值后侦听器不会再执行

}, 6000)

GM_reg/unregisterMenuCommand

// @grant        GM_registerMenuCommand
// @grant        GM_unregisterMenuCommand

let menu = GM_registerMenuCommand('hello world', function () {

    alert('hello world')

    GM_unregisterMenuCommand(menu) // 按id删除一个菜单

}, 'H') // 快捷键

GM_xmlhttpRequest

// @grant        GM_xmlhttpRequest

let ajax = GM_xmlhttpRequest({

    method: "GET",                        // 请求方法 GET POST

    // headers: {},                       // 消息头

    // data: '',                          // 通过 POST 请求发送的字符串

    // timeout: 10000,                    // 超时（毫秒）

    responseType: "json",                 // 响应的数据类型 text arraybuffer blob document json

    // overrideMimeType: "text/xml",      // 请求的 MIME 类型

    url: 'url',                           // 请求的 URL

    onabort: function () {},              // 如果请求中止，则要执行的回调

    onerror: function () {},              // 如果请求最终出现错误，则要执行的回调

    onloadstart: function () {},          // 在请求开始时执行的回调

    onprogress: function () {},           // 如果请求取得了一些进展，则要执行的回调

    onreadystatechange: function () {},   // 在请求的就绪状态发生更改时要执行的回调

    ontimeout: function () {},            // 如果请求由于超时而失败，则要执行的回调

    onload: function (xhr) {              // 如果加载了请求，则要执行的回调

        console.log(xhr);
      
    }
})

abort(ajax)                               // 调用以取消此请求

GM_download

// @grant        GM_download

let download = GM_download({
  
    url: 'url',                           // 下载文件的 URL 地址

    name: "文件名.后缀",                   // 不填则自动获取文件名

    saveAs: true,                         // 布尔值，显示"保存为"对话框

    onerror: function (error) {           // 如果下载最终出现错误，则要执行的回调

        console.log(error)

    },

    onprogress: (pro) => {                // 如果此下载取得了一些进展，则要执行的回调

        console.log(pro.loaded)           // 文件加载量

        console.log(pro.totalSize)        // 文件总大小

    },

    ontimeout: () => {},                  // 如果此下载由于超时而失败，则要执行的回调
    
    onload: () => {}                      // 如果此下载完成，则要执行的回调
})

abort(download)                           // 调用以取消此下载

GM_notification & GM_openInTab & GM_setClipboard

// @grant        GM_openInTab
// @grant        GM_notification
// @grant        GM_setClipboard

GM_notification({

    title: "标题",

    image: "图像链接",

    text: "通知内容",
    
    highlight: true,                   // 布尔值，是否突出显示发送通知的选项卡

    silent: false,                     // 布尔值，是否播放声音

    timeout: 10000,                    // 设置通知隐藏时间

    onclick: function () {             // 在单击通知时调用

        GM_openInTab("url", true)      // 使用此 URL打开一个新标签页
        
        //or

        GM_setClipboard("text")        // 将数据复制到剪贴板

    },

    ondone() {}                        // 在通知关闭（无论这是由超时还是单击触发）或突出显示选项卡时调用
})