Tampermonkey中GM_getValues和GM_setValues API的使用指南

概述

Tampermonkey作为最流行的用户脚本管理器之一，提供了丰富的API来增强脚本功能。其中GM_getValues和GM_setValues是两个重要的存储操作API，允许开发者批量读取和设置多个键值对。本文将详细介绍这两个API的使用方法、适用场景以及版本兼容性注意事项。

API功能介绍

GM_getValues和GM_setValues是Tampermonkey提供的批量存储操作接口，它们是对GM_getValue和GM_setValue的批量操作扩展。

GM_getValues

此API允许一次性获取多个存储值，其语法为：

const values = GM_getValues(keysArray);

其中keysArray可以是一个包含多个键名的数组，或者一个键名与默认值的映射对象。

GM_setValues

此API用于批量设置多个键值对：

GM_setValues(valuesObject);

valuesObject是一个键值对对象，包含所有需要设置的键及其对应值。

版本兼容性

这两个API是Tampermonkey 5.3版本新增的功能。在使用前需要注意：

1. 确保Tampermonkey版本≥5.3
2. 在脚本元数据中声明所需的权限：

// @grant GM_getValues
// @grant GM_setValues

使用示例

以下是一个完整的使用示例，展示了如何批量读取和设置多个配置项：

// 批量获取配置值，带有默认值
const config = GM_getValues({
  theme: 'dark',
  fontSize: 14,
  notifications: true
});

// 修改配置
config.theme = 'light';
config.fontSize = 16;

// 批量保存修改
GM_setValues(config);

性能优势

相比单次操作的GM_getValue/GM_setValue，批量API具有以下优势：

1. 减少存储操作的次数
2. 降低脚本与存储系统间的通信开销
3. 提高复杂配置操作的原子性

最佳实践

1. 对于需要同时读取或设置多个相关配置的场景，优先使用批量API
2. 合理设置默认值，避免未定义值导致的错误
3. 注意数据大小限制，避免一次操作过多数据
4. 考虑错误处理机制，确保部分操作失败时的数据一致性

总结

GM_getValues和GM_setValues为Tampermonkey脚本提供了更高效的批量存储操作能力。开发者应当了解其版本要求，并在适当的场景下使用这些API来优化脚本性能。随着Tampermonkey的持续更新，建议开发者保持对API文档的关注，及时了解新特性和改进。