API 参考

自定义仪表使用 main() 返回 View 树。这里介绍脚本结构、运行接口和绘制组件，并提供各项 API 的入口。

全局对象

CapDrive 在仪表脚本中直接提供以下全局对象，无需导入或自行创建。可以在 main() 中读取它们，用于取得数据、适应显示环境、保存临时状态和输出日志。

对象	用途与常用访问方式
$data	驾驶数据。通过 `$data.current` 读取当前采样，通过 `$data.history` 读取本次行程最近 30 秒的采样。
$env	当前仪表的显示环境，包括可用尺寸、主题颜色、单位、语言和显示模式，例如 `$env.width`、`$env.foreground`。
$sessionStorage	当前行程内、当前仪表实例的临时状态。用 `get(key)` 读取、`set(key, value)` 保存；结束行程或重新加载仪表时清空。
console	脚本日志。用 `console.log(...)`、`console.warn(...)` 等方法输出数据和诊断信息。

$data 和 $env 由 App 更新，是只读输入。每次调用 main() 时读取本次值；修改读取到的数据副本不会改变实际驾驶数据。$ 是对象名称的一部分，直接使用 $env.width，不需要写成函数调用。

定义绘制内容

仪表脚本中的 main() 返回由 JSX 描述的画面。每个 JSX 节点都是一个内置 View，属性控制尺寸、颜色和其他绘制行为，嵌套关系构成最终画面。

下面的完整脚本绘制一个数字和一行单位。VStack 将两个 Text 上下排列，spacing 设置间距，fontSize 设置字号，颜色由当前显示环境提供。

function main() {
  return (
    <VStack spacing={6}>
      <Text fontSize={48} color={$env.foreground}>
        78
      </Text>
      <Text fontSize={14} color={$env.accent}>
        km/h
      </Text>
    </VStack>
  );
}

在 JSX 的 {} 中可以使用 JavaScript 表达式。将固定的 78 换成计算结果，即可让文字随输入变化；同样可以把计算结果传给颜色、尺寸或圆弧角度等属性。

$data：驾驶数据

$data.current 的字段来自本仪表的输入标识符。在 仪表设置 → 输入绑定 填写本机值或选择 OBD 参数，齿轮进入 参数配置 管理定义。以下均以对应标识符已经定义为前提。

示例访问方式	输入定义与返回内容
`$data.current.speed`	基础速度输入，返回 `{ value, unit }`。
`$data.current.gForce`	基础 G 值输入，包含 `longitudinal`、`lateral`、`combined` 与单位。
`$data.current.location`	基础位置输入，包含经纬度与单位。
`$data.current.elapsed`	基础已记录时长输入，单位为秒。
`$data.current.recording`	基础记录状态输入，返回布尔值。
`$data.current.coolant`	OBD 输入，绑定车辆参数后返回 `{ value, unit }` 或 `null`。
`$data.current.limit`	数值输入，直接返回数字。
`$data.current.label`	文本输入，直接返回字符串。
`$data.current.showUnit`	开关输入，直接返回布尔值。
`$data.current.style`	选择项输入，返回已选字符串。

$data.history 覆盖当前行程最近 30 秒，按从旧到新排列，采样字段与 current 一致；固定输入使用当前配置。窗口可能为空或包含缺测。OBD 的数值可能是映射文字，应先检查类型。零与 null 含义不同。完整输入、单位和历史规则。

$env：显示环境

$env 描述当前这块仪表所在的显示区域。调整卡片尺寸、切换主题或进入 HUD 后，App 会提供更新后的环境。依赖这些值的计算应放在 main() 中。

字段	含义与用法
`$env.width`、`$env.height`	当前仪表可用宽高，单位为屏幕点。可用于计算字号、直径或端点坐标。
`$env.foreground`、`$env.accent`	当前主题的文字色和强调色，可直接传给 `color`、`stroke`、`background` 等颜色属性。
`$env.dark`	是否为深色外观，类型为布尔值。
`$env.mode`	显示模式，值为 `'instruments'` 或 `'hud'`。
`$env.speedUnit`	当前速度显示单位，值为 `'km/h'` 或 `'mph'`。读数自带单位时优先使用读数的 `unit`。
`$env.language`	App 当前语言标识，例如 `'zh-Hans'`。
`$env.reduceMotion`	系统是否启用了减弱动态效果，可据此调整重复动画。
`$env.obdDevice`	当前已连接设备的 `{ id, name }`，没有已就绪设备时为 `null`。

例如，使用 Math.min($env.width, $env.height) 可以取得适合放置正圆的最大直径，使用 $env.foreground 可以让文字跟随主题。完整显示环境定义。

示例：使用数据与显示环境

在仪表设置中选择速度。下面的脚本读取当前速度，按卡片宽高计算字号，使用主题颜色，并显示读数提供的单位。缺少速度时显示横线；有效的零显示为 0。

function main() {
  const speed = $data.current.speed;
  const fontSize = Math.min(64, $env.width * 0.25, $env.height * 0.5);

  return (
    <VStack spacing={6}>
      <Text fontSize={fontSize} color={$env.foreground}>
        {speed?.value == null ? '—' : Math.round(speed.value)}
      </Text>
      <Text fontSize={14} color={$env.accent}>
        {speed?.unit ?? $env.speedUnit}
      </Text>
    </VStack>
  );
}

数据更新时，下一次调用会使用新的速度；卡片尺寸或主题改变时，字号与颜色使用新的环境值。需要在同一行程中累计峰值等状态，可继续使用 $sessionStorage；需要检查实际输入，可在调试时用 console.log('speed', speed) 输出日志。

画面更新

当前输入、输入定义或显示环境变化时，CapDrive 提供最新的 $data 和 $env，在新的局部作用域执行整个文件，再调用本次定义的 main()。顶层计算也会重新执行，普通变量不会跨次保留。完全相同的输入会跳过；处理中只保留最新的待处理输入。历史窗口维护和内部采样时间变化不会单独触发执行；显式定义的时间输入变化则会。

脚本没有统一固定的频率，实际更新取决于输入和处理耗时。跨次状态使用 $sessionStorage；属性过渡使用 animations，由绘制端独立执行。main() 应同步完成，避免持续循环或阻塞等待。