驾驶数据 $data

$data 包含当前读数与最近 30 秒的历史。读数由 CapDrive 提供；你可以格式化和组合它们，但不能通过赋值改变实际记录。

入口

字段	类型	说明
$data.current	对象	最新一份读数快照
$data.history	数组	本次记录最近 30 秒的采样，按时间从早到晚

旧写法 $data.speed、$data.heading 不再使用；请始终通过 current 或历史元素读取。

当前读数与历史采样字段

除了 recording，下表中的数字字段在不可用时可能是 null。current 与历史元素使用同样的字段名称。

字段	单位 / 类型	说明
timestamp	Unix 毫秒	采集时间，不是渲染时间
elapsed	秒或 null	自本次记录开始的时间
speed	用户选择的 km/h 或 mph	适合直接显示
speedUnit	字符串	km/h 或 mph
speedMPS	米/秒	与显示单位无关，适合统一单位的计算
longitudinalG	G	车辆纵向加速度，正为加速、负为制动
lateralG	G	车辆横向读数，配合下方方向约定使用
gForce	G	纵向与横向合成幅度
heading	度	显示方位，0° 北、90° 东、180° 南、270° 西
headingAccuracy	度	方位的不确定度
latitude	度	当前显示位置纬度
longitude	度	当前显示位置经度
locationAccuracy	米	定位精度
altitude	米	海拔
roll	度	侧倾角，取决于当前姿态参考是否可用
pitch	度	俯仰角，取决于当前姿态参考是否可用
distanceMeters	米	当前行程累计距离
movingSeconds	秒	当前行程移动时长
recording	布尔值	当前是否正在记录

不要把缺测当停车

const speed = $data.current.speed;
const display = speed === null ? '—' : speed.toFixed(1);

真实的 0 是有效读数；null 表示没有可用测量。speed || '—' 会把 0 也替换掉，因此不适合这里。speed ?? 0 虽然不会报错，但会让缺测看起来像停车，显示主读数时通常应避免。

姿态、GPS 和速度的可用性也不相同。没有经纬度不一定意味着 G 值也不可用，不应通过其中一个字段判断所有数据。

单位换算

speed 已经跟随用户的速度单位，不要再无条件乘以 3.6。

const kmh = $data.current.speedMPS === null ? null : $data.current.speedMPS * 3.6;
const mph = $data.current.speedMPS === null ? null : $data.current.speedMPS * 2.2369362921;

显示给用户的数值可使用 speed + speedUnit；需要跨单位比较的阈值，建议统一用 speedMPS 保存或比较。

G 值方向

仪表圆盘上的点可以表达惯性方向。与 CapDrive 内置圆盘保持一致时，使用下面的约定：

操作 / 读数	圆盘点方向
制动，longitudinalG < 0	向前，画面向上
加速，longitudinalG > 0	向后，画面向下
左转，lateralG > 0	向右
右转，lateralG < 0	向左

在左上角为原点、Y 向下的绘图坐标里，可以使用 x = centerX + lateralG * scale、y = centerY + longitudinalG * scale。实际作品还需要限制显示范围；完整实现见 G 值圆盘。

最近 30 秒历史

历史在仪表挂载之外收集，所以新打开的卡片可以取得本次记录已存在的前序窗口。当前限制为最多 151 个采样、最高约 5 Hz，按时间排列；它不是整段行程的所有轨迹。

• 没有历史时是 []，不是 null。
• 记录结束或切换后清空，不包含上一段记录。
• 单位改变时，历史里的 speed 同步换成新单位。
• current 保持最新输入，不受历史降采样频率限制。
• 缺测保留为 null，绘制曲线时应断开或明确标注。

const valid = $data.history.filter(p => p.speed !== null);
const average = valid.length === 0 ? null
  : valid.reduce((sum, p) => sum + p.speed, 0) / valid.length;

这是窗口采样的算术均值，不是整段行程的平均速度，也不是严格按不等时间间隔加权的平均值。

用真实时间摆放曲线点

历史点不能简单地认为每项都等间隔。优先使用两份有效 elapsed 的差值；没有时可以用 timestamp 的毫秒差除以 1000。X 轴 30 秒窗口应按实际时间映射，而不是按数组索引铺满。

完整实现见速度历史曲线和短窗口路线。