共享存储 sharedStorage

sharedStorage 是插件级的跨层共享 KV 存储：同一插件在逻辑层、渲染层、面板层读写的是同一份数据，由宿主持久化到 plugins/<id>/store/shared.json（明文 JSON）。挂在三个全局变量上（wadLogicLayer.sharedStorage / wadRenderLayer.sharedStorage / wadPanelLayer.sharedStorage），三层 API 完全一致。

两个作用域：

• sharedStorage.app —— 绑定当前小程序（换 app 看不到）
• sharedStorage.global —— 全局（跨小程序可见）

所有方法返回 Promise。

本页你将学到

• app / global 两个作用域怎么选；
• get / set / remove / keys / clear 的用法；
• watch 的 change 对象字段；
• 面板与逻辑层共享登录态的实战。

get(key)

取值，不存在返回 null（三层一致）。

(async () => {
  const v = await wadPanelLayer.sharedStorage.app.get('token');
  // 不存在返回 null
})();

set(key, value)

写值，返回本次变更对象。

(async () => {
  const change = await wadPanelLayer.sharedStorage.app.set('token', { access: 'xxx', at: Date.now() });
  // change = { key:'token', op:'set', scope:'app', value:{...}, rev: 7, at: 1699..., plugin:'my-plugin', from:'panel', instanceId:'c12' }
})();

写入成功后宿主会向三层广播变更（见下文 watch）。value 支持 JSON 可序列化的任意结构。

remove(key) / keys() / clear()

(async () => {
  await wadPanelLayer.sharedStorage.app.remove('token');

  const ks = await wadPanelLayer.sharedStorage.app.keys();   // 本插件 app 作用域的全部 key
  const gks = await wadPanelLayer.sharedStorage.global.keys();

  await wadPanelLayer.sharedStorage.app.clear();    // 只清 app 作用域
  await wadPanelLayer.sharedStorage.global.clear(); // 只清 global 作用域
})();

watch(key, fn)

监听变更。key 传具体 key 或 '*'（全部）。回调签名 fn(value, change)，返回解绑函数。

const un = wadPanelLayer.sharedStorage.app.watch('token', function (value, change) {
  console.log('token 变了:', value, '来自', change.from, change.instanceId);
});

// 通配：任何 key 的变化都会进来
const unAll = wadPanelLayer.sharedStorage.global.watch('*', function (value, change) { /* ... */ });

// 用完解绑
un();
unAll();

change 对象字段：

字段	说明
key / op('set'|'remove'|'clear') / scope('app'|'global') / value / rev / at	变更本体
plugin	写入方插件 id
from	'logic' | 'render' | 'panel'
instanceId	写入方实例（面板是总线 clientId）
appid	仅 app 作用域携带

限制

项	值
单值大小	≤ 64KB
单作用域总量	≤ 1MB
key 长度	≤ 256 字符
持久化	明文 JSON 文件（与插件数据同级）

超限写入会 reject（value_too_large / scope_too_large / bad_key）。

实战：面板与逻辑层共享登录态

(async () => {
  // —— 逻辑层：拦截 mmtls/ilink 响应，提取 token 存入 app 作用域 ——
  wadLogicLayer.native.intercept.response(function (resp) {
    const data = resp.data;
    if (data && data.token) {
      wadLogicLayer.sharedStorage.app.set('token', data.token);   // 面板立刻可见
    }
    return undefined; // 不改写
  });

  // —— 面板：watch 到 token 就刷新 UI ——
  wadPanelLayer.sharedStorage.app.watch('token', function (v) {
    render(v);
  });

  // —— 渲染层：读当前 token ——
  const token = await wadRenderLayer.sharedStorage.app.get('token');
})();

实战：多标签面板状态同步

PC 和手机同时开着同一插件的面板时，一个面板写、另一个面板 watch 到变化即时刷新 —— 不需要自己搭同步。

(async () => {
  // 两个面板都执行：
  let state = await wadPanelLayer.sharedStorage.app.get('ui-state') || { tab: 0 };
  watchAndRender();

  function watchAndRender() {
    wadPanelLayer.sharedStorage.app.watch('ui-state', function (v) { state = v; render(); });
  }
  function setTab(i) {
    state = { tab: i };
    wadPanelLayer.sharedStorage.app.set('ui-state', state);   // 对端面板自动收到 watch
    render();
  }
})();

选型

插件私有小数据用 wadPanelLayer.storage（面板）/ wadLogicLayer.storage（逻辑层 wx storage）；需要跨层共享或跨面板同步时用 sharedStorage。全景对比见 存储。

下一步

• messaging：一次性事件广播（存储适合"状态"，消息适合"事件"）
• 跨层调用实例集