写入参数。options.key 必须符合 SetStoragePayload.key 的字符和
长度约束;options.data 必须符合 SetStoragePayload.data 的 clone、JSON 与配额约束。
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 写入失败会保留对应错误码。
该 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)
将 JSON 数据持久化到当前小程序隔离 Storage 的一个 key。