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 会直接返回 false / undefined

做法：使用 NID 用原生 IndexedDB 自行读写，或者只在 API 的同步调用链里使用

// 在 API 的同步调用链里使用
const saved = await npp.get('theme');

// 在事件回调内失效
document.getElementById('btn').addEventListener('click', async () => {
    const saved = await npp.get('theme'); // undefined
});

1. 初始化存储空间

/**
 * 初始化插件存储库
 * @param {string} pluginId - 插件唯一标识符
 * @returns {Promise<void>} - 初始化完成的Promise
 */
await npp.init(pluginId);

示例

// 初始化当前插件的存储
try {
  await npp.init(metadata.id);
  console.log('存储初始化成功');
} catch (error) {
  console.error('存储初始化失败:', error);
}

2. 存储

/**
 * 存储数据到当前插件的存储空间
 * @param {string} key - 存储键名
 * @param {any} value - 存储值 (可用可序列化的 JS 对象)
 * @returns {Promise<boolean>} - 存储状态 (是否存储成功)
 */
const success = await npp.set(key, value);

示例

// 存储用户配置
async function saveUserConfig(config) {
  const result = await npp.set('userConfig', config);
  if (result) {
    console.log('配置保存成功');
  } else {
    console.error('配置保存失败');
  }
}

// 使用示例
const userPreferences = {
  theme: 'dark',
  fontSize: 16
};
saveUserConfig(userPreferences);

3. 读取

/**
 * 从当前插件的存储空间获取数据
 * @param {string} key - 存储键名
 * @returns {Promise<any>} - Value / Undefined
 */
const value = await npp.get(key);

示例

// 读取用户配置
async function loadUserConfig() {
  const config = await npp.get('userConfig');
  if (config) {
    console.log('配置加载成功:', config);
    return config;
  } else {
    console.log('没有找到配置，使用默认值');
    return { // 加载基础配置
      theme: 'light',
      fontSize: 14
    };
  }
}

4. 删除

/**
 * 从当前插件的存储空间删除数据
 * @param {string} key - 存储键名
 * @returns {Promise<boolean>} - 是否删除成功
 */
const success = await npp.remove(key);

示例

// 清除用户配置
async function clearUserConfig() {
  const result = await npp.remove('userConfig');
  if (result) {
    console.log('配置已清除');
  } else {
    console.error('配置清除失败');
  }
}

数据存储机制说明

1. Npplication API 使用 IndexedDB 进行数据存储，为每个插件创建独立的存储空间
2. 所有数据存储操作都是异步的，返回 Promise
3. npp.set / npp.get / npp.remove 内部会自动调用 npp.init，无需手动初始化
4. 存储在 nppDB，存储名就是插件 ID，如 { key, value }
5. 虽然插件可以访问其它插件的数据，但不建议这样做
6. 存储的数据会持久化保存，只能手动清除 —— 卸载插件不会删除已有数据
7. 存储的数据大小受浏览器 IndexedDB 限制
8. 不要存储过大的数据，可能会影响性能
9. 优先用 NPP API 的 npp.set / npp.get / npp.remove —— 数据永久保存，卸载插件也不会丢失【将来用户可以一键清理已卸载插件的残留数据】localStorage 也可以用，但不建议（卸载后残留、用户无法清理）；Cookie 不要用（浏览器扩展环境下不可用，见NPP API）