油猴常用API使用示例
# Tampermonkey中文文档介绍如何使用 Tampermonkey API
## 用户脚本标头(部分)
| 名称 | 描述 | 参数 |
| :------------ | :--------------- | :----------------------------------------------------------- |
| `name` | 脚本名称 | - |
| `namespace` | 脚本命名空间 | - |
| `version` | 脚本版本 | [语义化版本规则](https://semver.org/lang/zh-CN/) |
| `author` | 脚本作者 | - |
| `description` | 脚本描述 | - |
| `include` | 脚本匹配地址 | 允许正则匹配 |
| `match` | 脚本匹配地址 | 使用*表示通配，使用更严格 |
| `exclude` | 排除脚本匹配地址 | - |
| `require` | 引入外部JS文件 | 指向脚本开始运行之前加载并执行的 JavaScript 文件 |
| `resource` | 预加载资源 | 预加载的资源由GM_getResourceURL/Text访问 |
| `connect` | 获取网站访问权限 | 允许由GM_xmlhttpRequest检索的子域 |
| `run-at` | 脚本的运行时机 | document-start/body/end/idle/menu [详细](https://docs.scriptcat.org/dev/meta.html#run-at) |
| `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~~
```javascript
// @grant unsafeWindow
```
#### GM_addStyle & GM_getResourceText
```javascript
// @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
```javascript
// @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
```javascript
// @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
```javascript
// @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
```javascript
// @grant GM_registerMenuCommand
// @grant GM_unregisterMenuCommand
let menu = GM_registerMenuCommand('hello world', function () {
alert('hello world')
GM_unregisterMenuCommand(menu) // 按id删除一个菜单
}, 'H') // 快捷键
```
#### GM_xmlhttpRequest
```javascript
// @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
```javascript
// @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
```javascript
// @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() {} // 在通知关闭（无论这是由超时还是单击触发）或突出显示选项卡时调用
})
```
补充几个我遇到过的问题：
GM_addStyle在部分油猴版本中不可用。
注册多个同名菜单时（第一个参数相同），只有一个生效。
overrideMimeType是响应的mime类型，请求的写在headers里。
GM_download支持的文件类型有限，且在某些情况下会强制修改后缀。另外还有GM_download(url, filename)这种同步写法，错误信息将被忽略。
GM_setClipboard通过监听copy事件实现，如果copy事件被其他插件或脚本阻止，将会影响这个函数的执行。 ggnb 辛苦整理
GM_notification
本帖最后由 dahua1 于 2022-3-17 15:12 编辑这个我怎么用不了呢
ggnb 辛苦整理 哥哥辛苦了，都老是记不住，得随时查
祝哥哥早中晚各一发 dahua1 发表于 2022-3-17 15:00
这个我怎么用不了呢
建议直接发代码。看看是不是@grant没声明 王一之 发表于 2022-3-18 10:47
建议直接发代码。看看是不是@grant没声明
现在可以了{:4_110:} 还有一个，overrideMimeType如果在本地请求里我印象里是不会生效的
页:
[1]