油猴脚本常见API权限

xyz_xyz

一、本地数据存储权限

1. GM_setValue – 写入持久化数据

// 存储字符串
GM_setValue('username', '张三');

// 存储数字
GM_setValue('score', 100);

// 存储对象（自动序列化）
GM_setValue('userInfo', { age: 18, city: '北京' });

// 存储数组
GM_setValue('history', ['page1', 'page2']);

注意：所有值会持久保存在浏览器扩展存储中，脚本更新或页面刷新后依然存在。

---

2. GM_getValue – 读取存储数据

// 读取字符串，若不存在则返回默认值 ''
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 – 删除指定键

// 删除单个键
GM_deleteValue('username');

// 删除后再次读取将返回默认值
const name = GM_getValue('username', '未登录');
console.log(name); // '未登录'

---

4. GM_listValues – 获取所有键名列表

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 等）

第一步：在脚本元数据中声明目标域名白名单

// ==UserScript==
// @name         跨域示例
// @connect      api.example.com
// @connect      *.github.io
// @grant        GM_xmlhttpRequest
// ==/UserScript==

第二步：发起请求

// 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 – 桌面通知（右下角弹窗）

// 基础通知
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 – 调用浏览器下载资源

// 直接下载图片
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([content], { type: 'text/plain' });
const dataUrl = URL.createObjectURL(blob);

GM_download({
  url: dataUrl,
  name: 'hello.txt',
  onload: () => URL.revokeObjectURL(dataUrl) // 释放内存
});

---

3. GM_openInTab – 打开新标签页

// 在新标签页中打开指定 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 显式声明，否则将无法调用。
• 示例声明：

  // ==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