油猴脚本常见API权限
## 一、本地数据存储权限### 1. `GM_setValue` – 写入持久化数据
```javascript
// 存储字符串
GM_setValue('username', '张三');
// 存储数字
GM_setValue('score', 100);
// 存储对象（自动序列化）
GM_setValue('userInfo', { age: 18, city: '北京' });
// 存储数组
GM_setValue('history', ['page1', 'page2']);
```
> **注意**：所有值会持久保存在浏览器扩展存储中，脚本更新或页面刷新后依然存在。
---
### 2. `GM_getValue` – 读取存储数据
```javascript
// 读取字符串，若不存在则返回默认值 ''
const name = GM_getValue('username', '');
// 读取数字，设置默认值为 0
const score = GM_getValue('score', 0);
// 读取对象，默认空对象
const info = GM_getValue('userInfo', {});
// 读取数组，默认空数组
const list = GM_getValue('history', []);
```
> **建议**：始终提供默认值，避免读取未定义键时返回 `undefined` 导致后续逻辑报错。
---
### 3. `GM_deleteValue` – 删除指定键
```javascript
// 删除单个键
GM_deleteValue('username');
// 删除后再次读取将返回默认值
const name = GM_getValue('username', '未登录');
console.log(name); // '未登录'
```
---
### 4. `GM_listValues` – 获取所有键名列表
```javascript
const keys = GM_listValues();
console.log('当前存储的所有键名：', keys);
// 常用于遍历清理或导出数据
keys.forEach(key => {
const val = GM_getValue(key);
console.log(`${key}: ${val}`);
});
```
---
## 二、跨域网络请求权限（需搭配 `@connect` 声明）
### `GM_xmlhttpRequest` – 跨域请求（支持 GET/POST/PUT/DELETE 等）
**第一步**：在脚本元数据中声明目标域名白名单
```javascript
// ==UserScript==
// @name 跨域示例
// @connect api.example.com
// @connect *.github.io
// @grant GM_xmlhttpRequest
// ==/UserScript==
```
**第二步**：发起请求
```javascript
// GET 请求
GM_xmlhttpRequest({
method: 'GET',
url: 'https://api.example.com/users',
onload: function(response) {
console.log('响应状态:', response.status);
console.log('响应内容:', response.responseText);
},
onerror: function(err) {
console.error('请求失败:', err);
}
});
// POST 请求（带 JSON 数据）
GM_xmlhttpRequest({
method: 'POST',
url: 'https://api.example.com/submit',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer your-token'
},
data: JSON.stringify({ name: '李四', age: 25 }),
timeout: 10000, // 10秒超时
onload: function(res) {
const data = JSON.parse(res.responseText);
console.log('提交成功:', data);
},
ontimeout: function() {
alert('请求超时，请检查网络');
},
onprogress: function(evt) {
// 上传进度监听 (若为上传)
if (evt.lengthComputable) {
const percent = (evt.loaded / evt.total) * 100;
console.log(`上传进度: ${percent.toFixed(2)}%`);
}
}
});
// 下载文件示例（获取二进制流）
GM_xmlhttpRequest({
method: 'GET',
url: 'https://example.com/image.png',
responseType: 'blob',
onload: function(res) {
// res.response 为 Blob 对象
const url = URL.createObjectURL(res.response);
// 可创建下载链接等
}
});
```
---
## 三、其它权限
### 1. `GM_notification` – 桌面通知（右下角弹窗）
```javascript
// 基础通知
GM_notification({
title: '提醒',
text: '您有一条新消息',
timeout: 5000, // 5秒后自动关闭
onclick: function() {
console.log('用户点击了通知');
// 可在此执行跳转或操作
}
});
// 带图标的通知
GM_notification({
title: '更新完成',
text: '脚本已自动更新到 v2.0',
image: 'https://example.com/icon.png',
onclick: function() {
window.focus(); // 聚焦当前页面
}
});
```
> **注意**：部分浏览器需用户授予通知权限，首次调用会弹出权限请求。
---
### 2. `GM_download` – 调用浏览器下载资源
```javascript
// 直接下载图片
GM_download({
url: 'https://example.com/photo.jpg',
name: 'my_photo.jpg', // 保存的文件名
onload: function() {
console.log('下载完成');
},
onerror: function(err) {
console.error('下载失败:', err);
}
});
// 下载文本内容（通过 Blob URL）
const content = 'Hello, world!';
const blob = new Blob(, { type: 'text/plain' });
const dataUrl = URL.createObjectURL(blob);
GM_download({
url: dataUrl,
name: 'hello.txt',
onload: () => URL.revokeObjectURL(dataUrl) // 释放内存
});
```
---
### 3. `GM_openInTab` – 打开新标签页
```javascript
// 在新标签页中打开指定 URL
GM_openInTab('https://www.google.com');
// 控制新标签页是否获得焦点（默认 true）
GM_openInTab('https://example.com', { active: true });
// 在后台打开（不切换焦点）
GM_openInTab('https://example.com', { active: false });
// 返回的 tab 对象可用来关闭该标签页（部分浏览器支持）
const tab = GM_openInTab('https://example.com');
// 若需关闭：tab.close();
```
---
## 权限组合使用提示
- 所有 API 都需在脚本元数据中通过 `@grant` 显式声明，否则将无法调用。
- 示例声明：
```javascript
// ==UserScript==
// @grant GM_setValue
// @grant GM_getValue
// @grant GM_deleteValue
// @grant GM_listValues
// @grant GM_xmlhttpRequest
// @grant GM_notification
// @grant GM_download
// @grant GM_openInTab
// ==/UserScript==
```
> 我的:主页[https://scriptcat.org/zh-CN/users/176579](https://scriptcat.org/zh-CN/users/176579)
页:
[1]