本地键值存储

通过 storage.setStorage() 和 storage.getStorage() 保存设置、草稿等少量 JSON 数据。数据按小程序隔离，存储在当前 Host 本地，不随账号或设备同步；同一小程序升级版本后仍使用原有数据。

声明与使用

先在项目 package.json 中声明权限：

json

{
  "heybox": {
    "permissions": {
      "storage": { "enabled": true }
    }
  }
}

声明完整后，在 SDK 就绪时读写：

import hbSDK from '@heybox/hb-sdk'

await hbSDK.ready()
await hbSDK.storage.setStorage({
  key: 'settings',
  data: { theme: 'dark' },
})

const { data } = await hbSDK.storage.getStorage<{ theme: string }>({
  key: 'settings',
})
// 泛型不会校验历史数据；读取后仍需检查业务结构。
const theme = data?.theme === 'dark' ? 'dark' : 'light'

不需要平台批准、用户授权或用户手势；当前 Host 仍须支持该能力。公开模块只有读取和整值写入，没有枚举、单键删除或清空 API。

数据与容量边界

key 默认仅接受 1–128 位 ASCII 字母、数字、下划线和连字符，Host 可配置不同的长度上限。
0.9.1 配套 Runtime 为每个小程序记录最多 1000 个不同 key；达到上限后写入新 key 返回 STORAGE_QUOTA_EXCEEDED，已记录 key 可继续覆盖。不要用时间戳持续创建新 key；写入 null 或空字符串也不会释放 key 配额。
data 必须可通过 structured clone 和 JSON 序列化。顶层 undefined、BigInt、循环引用等不受支持；同一 key 每次整值替换，没有局部合并或多 key 事务。
Host 可另设单值 UTF-8 字节配额，超限同样返回 STORAGE_QUOTA_EXCEEDED；精确序列化和错误规则见 setStorage() Reference。

读取与历史数据

key 不存在时返回 { data: undefined }；0.9.1 配套 Runtime 也将历史原始空串视为未设置。正常通过 setStorage({ key, data: '' }) 保存的字符串仍读作 ''，JSON null 仍读作 null。升级前遗留的非 JSON 原始值按原字符串返回。

重要数据应自行校验结构和处理版本迁移；本地数据可能由用户清理，不应作为唯一备份。

用户清理本地数据

支持该功能的宿主简介页提供本地数据大小与清理入口。清理范围为当前小程序的本地 K-V 和宿主可访问的隔离 sandbox 文件，不包含开发者服务端数据或用户选择的外部文件。宿主执行清理时会停止运行实例，完成后重新加载小程序；业务应能从空数据重新初始化。

清理能力取决于宿主，升级 SDK 不代表所有平台立即提供入口。旧宿主若不能枚举存储，只能处理已记录到索引的 K-V；既无索引也不能枚举时可能显示 0MB 并禁用清理，不能据此断定没有历史数据。原生 K-V 清理可能采用空串覆盖，使 SDK 不再读到旧值，不保证物理磁盘空间立即回收。

完成检查

声明 storage 权限，在目标 Host 验证实际读写。
key 数量有界，处理配额错误与历史数据结构变化。
清理数据或缺少本地值后，页面可以恢复默认状态。

本地键值存储 ​

声明与使用 ​

数据与容量边界 ​

读取与历史数据 ​

用户清理本地数据 ​

相关文档 ​

完成检查 ​