单次行程存储 $sessionStorage

当你需要“本次行程的峰值”“上一次有效读数”等临时数据时，使用 $sessionStorage。它属于当前卡片在当前记录中的存储，不是永久数据库。

接口

方法	返回值	作用
get(key)	已存数据或 null	读取一个字符串键
set(key, value)	undefined	存储普通数据快照

function main() {
  const speed = $data.current.speedMPS;
  const previous = $sessionStorage.get('peakMPS');
  const peak = speed === null ? previous : Math.max(previous ?? 0, speed);
  if (peak !== null) $sessionStorage.set('peakMPS', peak);
  return <Text color={$env.foreground}>
    {peak === null ? '—' : (peak * 3.6).toFixed(1) + ' km/h'}
  </Text>;
}

这里保存的是米/秒，避免用户切换 km/h 与 mph 后把不同单位的数字混在一起。完整版本见本次行程峰值。

什么时候保留，什么时候清空

情况	行为
同一次记录中更新读数	保留
同一次记录中导航离开、重新挂载卡片	保留在该卡片的存储中
同一次记录中重新加载代码	不应当作重新开始一段记录
记录结束、停止或进入新的记录	清空
App 进程退出后重新启动	不恢复
同一源码放入两个卡片位置	两个卡片各自独立
编辑器预览与缩略图	使用独立临时存储，不影响真实行程

没有活动记录的实时卡片读到 null，写入不会形成持续存储。

能保存什么

可以保存字符串、有限数值、布尔值、null、普通对象和数组。不能保存函数、JSX 组件描述、循环引用或特殊原型对象。

读取和写入都复制数据。修改读出的对象之后，必须再调用一次 set() 才会更新存储：

const stats = $sessionStorage.get('stats') ?? {count: 0};
stats.count += 1;
$sessionStorage.set('stats', stats);

注意这段计数表示函数被调用的次数，不是秒数或传感器采样次数；需要时间统计时请使用采样时间。

限制

每个卡片的存储最多 256 个键，估算总量约 1 MiB，数据嵌套最多 32 层，键最长 256 个 UTF-8 字节。超限会报告错误，并保留原来的数据。

set() 不主动触发界面刷新。画面仍在 CapDrive 提供新输入时更新；不能用它模拟 React 状态或浏览器定时器。