NPP API 使用指南
本文将介绍 NPP 系统中 API 的使用方法。
数据存储
NPP 提供了一套异步的数据存储 API，允许插件进行基础的读写删改操作，一些复杂的操作建议使用浏览器原生 API 实现。 Cookie 不要用（浏览器扩展环境下不可用，见NPP API）
必须从插件脚本自身的同步执行期调用
npp.set / npp.get / npp.remove 不带插件 ID 参数，它们通过 document.currentScript 定位当前正在执行的插件脚本。在 setTimeout后、事件回调内、Promise 回调内，document.currentScript = null，API 会返回 { ok: false, error }
做法：npp.dbGet / npp.dbSet / npp.dbRemove，或者只在 API 的同步调用链里使用
javascript
// 在 API 的同步调用链里使用
const { ok, value } = await npp.get('theme');
// 在事件回调内失效
document.getElementById('btn').addEventListener('click', async () => {
const { ok, value } = await npp.get('theme'); // ok === false
});1. 初始化存储空间
javascript
/**
* 初始化插件存储库
* @param {string} pluginId - 插件唯一标识符
* @returns {Promise<void>} - 初始化完成的Promise
*/
await npp.init(pluginId);示例
javascript
// 初始化当前插件的存储
try {
await npp.init(metadata.id);
console.log('存储初始化成功');
} catch (error) {
console.error('存储初始化失败:', error);
}2. 存储
javascript
/**
* 存储数据到当前插件的存储空间
* @param {string} key - 存储键名
* @param {any} value - 存储值 (可用可序列化的 JS 对象)
* @returns {Promise<{ok: boolean, value: any, error: any}>} - 统一返回对象
*/
const { ok, error } = await npp.set(key, value);示例
javascript
// 存储用户配置
async function saveUserConfig(config) {
const { ok, error } = await npp.set('userConfig', config);
if (ok) {
console.log('配置保存成功');
} else {
console.error('配置保存失败:', error);
}
}
// 使用示例
const userPreferences = {
theme: 'dark',
fontSize: 16
};
saveUserConfig(userPreferences);3. 读取
javascript
/**
* 从当前插件的存储空间获取数据
* @param {string} key - 存储键名
* @returns {Promise<{ok: boolean, value: any, error: any}>} - 统一返回对象，value 为 undefined 则 key 不存在
*/
const { ok, value, error } = await npp.get(key);示例
javascript
// 读取用户配置
async function loadUserConfig() {
const { ok, value: config, error } = await npp.get('userConfig');
if (!ok) {
console.error('配置读取失败:', error);
return { theme: 'light', fontSize: 14 };
}
if (config) {
console.log('配置加载成功:', config);
return config;
}
console.log('没有找到配置，使用默认值');
return { // 加载基础配置
theme: 'light',
fontSize: 14
};
}4. 删除
javascript
/**
* 从当前插件的存储空间删除数据
* @param {string} key - 存储键名
* @returns {Promise<{ok: boolean, value: any, error: any}>} - 统一返回对象
*/
const { ok, error } = await npp.remove(key);示例
javascript
// 清除用户配置
async function clearUserConfig() {
const { ok, error } = await npp.remove('userConfig');
if (ok) {
console.log('配置已清除');
} else {
console.error('配置清除失败:', error);
}
}5. 返回值
三个方法都统一返回 { ok, value, error }：
| 字段 | 成功 | 失败 |
|---|---|---|
ok | true | false |
value | get 读到的值；set / remove 为 undefined | undefined |
error | null | Error 对象 |
get 读不到 key 不算失败：返回 { ok: true, value: undefined }。
6. 指定插件 ID 的读写（v3.1.3 起）
npp.set / npp.get / npp.remove 靠 document.currentScript 定位插件，事件回调里会失效。这三套在任何异步上下文里都能调用
javascript
/**
* @param {string} pluginId - 插件唯一标识符
* @param {string} key - 存储键名
* @param {any} value - 存储值（可序列化的 JS 对象）
* @returns {Promise<{ok: boolean, value: any, error: any}>} - 统一返回对象
*/
const { ok, value, error } = await npp.dbGet(pluginId, key);
const saved = await npp.dbSet(pluginId, key, value);
const removed = await npp.dbRemove(pluginId, key);示例
javascript
// 事件回调里也能用
document.getElementById('btn').addEventListener('click', async () => {
const { ok, value } = await npp.dbGet(NID, 'theme');
await npp.dbSet(NID, 'theme', 'dark');
});- 等价于
npp.get(key, 1, pluginId)/npp.set(key, value, 1, pluginId)/npp.remove(key, 1, pluginId) - 内部自动调用
npp.init，不需要手动初始化 pluginId为空：返回{ ok: false, error }
数据存储机制说明
- Npplication API 使用 IndexedDB 进行数据存储，为每个插件创建独立的存储空间
- 所有数据存储操作都是异步的，返回 Promise，统一解析为
{ ok, value, error } npp.set/npp.get/npp.remove内部会自动调用npp.init，无需手动初始化- 存储在
nppDB，存储名就是插件 ID，如{ key, value } - 虽然插件可以访问其它插件的数据，但不建议这样做
- 存储的数据会持久化保存，只能手动清除 —— 卸载插件不会删除已有数据
- 存储的数据大小受浏览器 IndexedDB 限制
- 不要存储过大的数据，可能会影响性能
- 优先用 NPP API 的
npp.set/npp.get/npp.remove—— 数据永久保存，卸载插件也不会丢失【将来用户可以一键清理已卸载插件的残留数据】localStorage也可以用，但不建议（卸载后残留、用户无法清理）；Cookie 不要用（浏览器扩展环境下不可用，见NPP API）