@heybox/hb-sdk API Reference - v0.9.5
    正在准备搜索索引...
    • 将 JSON 数据持久化到当前小程序隔离 Storage 的一个 key。

      参数

      返回 Promise<void>

      Host 完成该 key 的整值替换后 resolve undefined;该 API 没有业务返回值。

      HbMiniProgramSDKError INVALID_PARAMS:options、key 或 JSON 数据非法, 包括顶层 undefined、BigInt、循环引用或序列化过程抛错。

      HbMiniProgramSDKError STORAGE_QUOTA_EXCEEDED:完整 JSON 字符串的 UTF-8 字节数超过当前 Host 配额,或写入新 key 后当前小程序的不同 key 数量将超过 1000 个。

      HbMiniProgramSDKError PERMISSION_NOT_IN_SNAPSHOT / PERMISSION_DENIED:当前运行快照 缺少或未启用 storage;INVALID_STATE:canonical 小程序身份尚未就绪。

      HbMiniProgramSDKError METHOD_NOT_FOUND / METHOD_FORBIDDEN:当前 Host 不支持或禁用了该能力。其他握手、bridge、超时与 Host 写入失败会保留对应错误码。

      DOMException 数据含函数、Symbol、自定义 toJSON 方法等不可 structured-clone 内容时,浏览器可能在请求发送前抛出 DataCloneError。

      该 API 需要在 package.json#heybox.permissions 声明并启用 storage,不需要平台批准、 用户授权或可信用户手势。

      Storage 作用域由平台确认的 canonical 小程序 ID 决定,并在当前 Runtime 首次使用时 固定;版本号、当前登录账号、页面 URL 和 key 都不能改变作用域。不同小程序不能互相 读取数据,同一小程序的版本升级仍使用相同作用域;本地匿名调试只使用 Runtime 显式 分配的临时 scope。该能力是 Host 本地持久化,不是账号级或跨设备云同步。

      Runtime 会先完成 JSON 序列化和 UTF-8 配额校验,再向 Host 提交一个完整字符串;这些 前置校验失败时不会覆盖旧值。Host 以单次操作整值替换同一个 key,不暴露局部写入、 merge、append 或多 key 事务。Promise resolve 表示 Host 已完成本次持久化;随后可用 storage.getStorage 读取反序列化后的值。

      import hbSDK from '@heybox/hb-sdk'

      type Settings = { theme: 'light' | 'dark'; updatedAt: string }

      await hbSDK.storage.setStorage({
      key: 'settings',
      data: { theme: 'dark', updatedAt: new Date().toISOString() },
      })

      const { data } = await hbSDK.storage.getStorage<Settings>({ key: 'settings' })
      if (data) console.log(data.theme)

      0.3.1

      android

      ios

      ohos

      windows

      macos

      android none

      ios none

      ohos none

      windows none

      macos none