用户脚本API文档

本文档详细介绍了扩展中支持的用户脚本API（GM_*方法）。

GM_info

获取用户脚本的元数据信息。

参数

无

返回值

any // 返回脚本的元数据对象

示例

// 获取脚本元数据
const metadata = GM_info();
console.log('脚本名称:', metadata.script.name);
console.log('脚本版本:', metadata.script.version);

TIP

可以通过GM_info获取脚本的名称、版本、描述等元数据信息。

GM_getValue

获取存储的值。

参数

• key: string - 键名
• defaultValue?: any - 默认值（可选）

返回值

Promise<any> // 返回存储的值，如果不存在则返回默认值

示例

// 获取值，不设置默认值
const value1 = await GM_getValue('myKey');

// 获取值，设置默认值
const value2 = await GM_getValue('myKey', 'defaultValue');

WARNING

存储的值会在不同页面间共享，注意键名冲突。

GM_setValue

设置存储值。

参数

• key: string - 键名
• value: any - 要存储的值

返回值

Promise<void>

示例

// 存储字符串
await GM_setValue('name', 'John');

// 存储对象
await GM_setValue('user', { id: 1, name: 'John' });

INFO

可以存储任何可序列化的JavaScript值。

GM_deleteValue

删除存储的值。

参数

• key: string - 要删除的键名

返回值

Promise<void>

示例

await GM_deleteValue('myKey');

GM_listValues

获取所有存储的键名列表。

参数

无

返回值

Promise<string[]> // 返回所有键名数组

示例

const keys = await GM_listValues();
console.log('所有存储的键：', keys);

GM_deleteValues

批量删除存储的值。

参数

• keys: string[] - 要删除的键名数组

返回值

Promise<void>

示例

await GM_deleteValues(['key1', 'key2', 'key3']);

GM_setValues

批量设置存储值。

参数

• values: Record<string, any> - 键值对对象

返回值

Promise<void>

示例

await GM_setValues({
  key1: 'value1',
  key2: 'value2',
  key3: { id: 3, name: 'test' }
});

GM_getValues

批量获取存储值。

参数

• keys: string[] - 要获取的键名数组

返回值

Promise<Record<string, any>> // 返回键值对对象

示例

const values = await GM_getValues(['key1', 'key2', 'key3']);
console.log('key1的值:', values.key1);

GM_addElement

向页面添加新元素。

参数

• parentNodeOrTagName: Node | Element | ShadowRoot | string - 父节点或标签名
• tagNameOrAttributes?: string | object - 标签名或属性对象
• attributes?: object - 属性对象（可选）

返回值

Element // 返回创建的元素

示例

// 简单用法
const div = GM_addElement('div', { class: 'my-class' });

// 指定父节点
const span = GM_addElement(document.body, 'span', { textContent: 'Hello' });

GM_addStyle

添加CSS样式。

参数

• css: string - CSS样式文本

返回值

HTMLStyleElement // 返回创建的style元素

示例

GM_addStyle('.my-class { color: red; }');

GM_setClipboard

设置剪贴板内容。

参数

• text: string - 要复制的文本
• type?: string - 内容类型，支持 'text/plain'、'text/html'、'text/rich'，默认为 'text/plain'

返回值

Promise<void>

示例

// 复制普通文本
await GM_setClipboard('Hello World');

// 复制HTML内容
await GM_setClipboard('<b>Hello World</b>', 'text/html');

GM_xmlhttpRequest

跨域网络请求方法。

参数

• details: object - 请求配置对象
  • url: string - 请求URL（必需）
  • method?: string - 请求方法，默认为 'GET'
  • headers?: object - 请求头
  • data?: any - 请求数据
  • mode?: string - 请求模式，默认为 'cors'
  • credentials?: string - 凭证模式，默认为 'same-origin'
  • redirect?: string - 重定向模式，默认为 'follow'
  • referrer?: string - 请求来源
  • referrerPolicy?: string - 请求来源策略，默认为 'no-referrer-when-downgrade'
  • responseType?: string - 响应类型，支持 'text'、'json'、'blob'、'arraybuffer'
  • encoding?: string - 响应编码，默认为 'utf-8'

返回值

Promise<{
  status: number; // HTTP状态码
  statusText: string; // HTTP状态文本
  response: any; // 响应数据
  responseHeaders: Headers; // 响应头
  finalUrl: string; // 最终URL（考虑重定向）
}>

示例

// GET请求
await GM_xmlhttpRequest({
  url: 'https://api.example.com/data',
  method: 'GET'
});

// POST请求
await GM_xmlhttpRequest({
  url: 'https://api.example.com/data',
  method: 'POST',
  headers: {
    'content-type': 'application/json'
  },
  data: { name: 'test' }
});

WARNING

注意跨域请求的安全性，不要发送敏感信息。

GM_notification

显示桌面通知。

参数

• textOrOptions: string | object - 通知文本或配置对象
  • 当为string时：通知文本
  • 当为object时：
    • text: string - 通知文本
    • title?: string - 通知标题
    • image?: string - 通知图标URL
    • silent?: boolean - 是否静音，默认为false
    • tag?: string - 通知标识，相同tag的通知会替换之前的通知
    • zombieTimeout?: number - 自动关闭时间（毫秒）

返回值

Promise<void>

示例

// 简单通知
await GM_notification('Hello World');

// 完整配置
await GM_notification({
  text: 'Hello World',
  title: '通知标题',
  image: 'icon.png',
  silent: false,
  tag: 'my-notification',
  zombieTimeout: 5000
});

TIP

合理使用通知可以提升用户体验，但不要过度打扰用户。