tencent.jquery.pix.devtool

通用调试工具与缓存管理 npm 包，适用于 Gamelet / PixUI 项目。

特性

• 🛠 悬浮调试面板：可拖拽、可最小化，支持控制台日志拦截、JS 代码执行
• 📦 缓存管理：查看 / 删除 / 清空由 setNoteCacheInfo 注册的所有缓存

安装

npm install tencent.jquery.pix.devtool

peerDependencies：项目中需自行安装 gamelet-pixui-frame 和 tencent.jquery.pix

快速上手

// 1. 引入样式（在项目入口）
import 'tencent.jquery.pix.devtool/src/devtool.scss';

// 2. 初始化（可选配置）
import { initDevTool, addTestBtn, log } from 'tencent.jquery.pix.devtool';
await initDevTool({
  proxyConsole: false,  // 是否默认拦截 console（默认 true）
  scale: 1,            // 面板初始缩放倍数（默认 1，范围 0.3 ~ 10）
});

// 端内打印日志
log('dev:',{aa:1})

// initDevTool 是异步函数，await 后面板已完全就绪，可安全调用 addTestBtn
addTestBtn('测试登录', () => { /* 你的逻辑 */ });
addTestBtn('清除数据', () => { localStorage.clear(); });

// 隐藏「执行 JavaScript」模块（适合不需要代码执行功能的场景）
await initDevTool({
  showExecuteCode: false,
});

面板 API

| 函数 | 说明 | |------|------| | initDevTool(options?) | 异步初始化面板，接受可选配置项，返回 Promise，await 后面板完全就绪 | | show(visible?) | 显示或隐藏面板，默认 true | | toggle() | 切换面板显示状态 | | enableShortcut() | 注册 Ctrl+Shift+D 快捷键切换面板 | | addTestBtn(btnName, callback) | 在「动作」tab 下添加自定义调试按钮，callback(inputVal, $btn)：inputVal 为自定义参数输入框的值（string），$btn 为当前按钮的 jQuery 对象 | | log(message) | 向面板控制台输出日志（面板未显示时自动打开） |

initDevTool 配置项

| 参数 | 类型 | 默认值 | 说明 | |------|------|--------|------| | proxyConsole | boolean | true | 是否拦截 console.log/warn/error 并显示在面板中 | | scale | number | 1 | 面板初始缩放倍数，范围 0.3 ~ 10，也可在面板控制台底部通过「扩大 / 缩小」按钮动态调整，调整后的值会自动缓存 | | appId | string | "" | app 环境下剪贴板写入所需的 appId | | appName | string | "" | app 环境下剪贴板写入所需的 appName | | showExecuteCode | boolean | true | 是否显示「执行 JavaScript」模块，设为 false 可隐藏该模块（适合生产环境或不需要代码执行功能的场景） |

缓存 API

基础读写

import { setNoteCacheInfo, getNoteCacheInfo, clearNoteCacheInfo } from 'tencent.jquery.pix.devtool';

// 写入
setNoteCacheInfo('myKey', { foo: 'bar' });

// 读取
const val = await getNoteCacheInfo('myKey');

// 删除
await clearNoteCacheInfo('myKey');

批量操作

import { clearAllNoteCacheInfo, clearMultipleNoteCacheInfo } from 'tencent.jquery.pix.devtool';

// 清空所有已注册的缓存
const count = await clearAllNoteCacheInfo();

// 清空指定前缀的缓存
await clearAllNoteCacheInfo('user_');

// 批量删除指定 key
const result = await clearMultipleNoteCacheInfo(['key1', 'key2']);
// result: { success: 2, failed: 0 }

带过期时间的读写

import {
  setNoteCacheInfoWithHours,
  setNoteCacheInfoWithDays,
  getNoteCacheInfoWithExpire,
  clearExpiredNoteCacheInfo,
} from 'tencent.jquery.pix.devtool';

// 写入 2 小时后过期
setNoteCacheInfoWithHours('myKey', data, 2);

// 写入 3 天后过期（支持 0.5 表示半天）
setNoteCacheInfoWithDays('myKey', data, 3);

// 读取（自动处理过期，过期返回 null）
const val = await getNoteCacheInfoWithExpire('myKey');

// 清除一批 key 中已过期的缓存
const cleared = await clearExpiredNoteCacheInfo(['key1', 'key2']);

Key 注册表

import { registerCacheKeys, getAllRegisteredCacheKeys, removeCacheKeys } from 'tencent.jquery.pix.devtool';

// 手动注册历史遗留的 key（使其出现在面板缓存列表中）
registerCacheKeys(['legacyKey1', 'legacyKey2']);

// 获取所有已注册的 key
const keys = getAllRegisteredCacheKeys();

// 从注册表中移除（不删除实际缓存数据）
removeCacheKeys(['legacyKey1']);

通过 setNoteCacheInfo 写入的 key 会自动注册，无需手动调用 registerCacheKeys。

缓存白名单

白名单中的缓存 key 在执行清除操作（clearNoteCacheInfo / clearAllNoteCacheInfo / clearMultipleNoteCacheInfo）时会被自动跳过，适用于需要长期保留、不希望被误删的关键缓存。

import { addCacheWhitelist, removeCacheWhitelist, getCacheWhitelist, isCacheWhitelisted } from 'tencent.jquery.pix.devtool';

// 添加 key 到白名单（支持字符串或数组）
addCacheWhitelist('importantKey');
addCacheWhitelist(['userToken', 'gameProgress']);

// 从白名单中移除
removeCacheWhitelist('userToken');

// 获取当前白名单列表
const list = getCacheWhitelist(); // ['importantKey', 'gameProgress']

// 判断某个 key 是否在白名单中
isCacheWhitelisted('importantKey'); // true

白名单中的 key 仍可通过 force 参数强制删除：clearNoteCacheInfo('importantKey', true)。

环境说明

| 环境 | 缓存底层 | |------|---------| | app（jssdk-appwindow / preprocessor） | GameletAPI.readCookie / writeCookie | | 浏览器 / 模拟器 | sessionStorage |

开发技术细节请参阅 DEVELOPMENT.md