$env · 显示环境

$env 提供当前这块仪表的尺寸、主题、显示模式、单位及语言,用于让同一份代码适应手机和 HUD 等显示场景。

尺寸与布局

width、height 是当前仪表可用区域的宽高,单位为屏幕点,随卡片尺寸和显示环境变化。它们不是整台手机的分辨率,也不是图像像素数。

需要随尺寸调整的字体、图形半径和端点坐标,应在 main() 中用本次宽高计算。固定的 120 点圆形始终使用固定尺寸;要让它随卡片变化,可以使用可用宽高的较小值计算直径。

主题、模式与单位

foreground 是适合当前背景的文字色,accent 是强调色,dark 表示当前深色外观。mode 的值为 instruments 或 hud,表示普通仪表或 HUD 显示。

speedUnit 表示当前速度显示单位,language 是 App 语言,reduceMotion 表示系统减弱动态效果设置。obdDevice 提供当前已连接设备的 id 和 name,没有已就绪设备时为空。单位标签应与数值一起使用,改变标签本身不会换算数值。

示例:适应显示模式

下例在 HUD 模式中使用更大字号,并使用当前主题文字色与速度单位。

function main() {
  return (
    <Text fontSize={$env.mode === 'hud' ? 72 : 48} color={$env.foreground}>
      {$env.speedUnit}
    </Text>
  );
}

环境更新

尺寸、主题或其他环境变化时,CapDrive 会提供新的输入。把依赖 $env 的计算放在 main() 内,确保下一次绘制使用新值。重复动效应根据 reduceMotion 调整,避免忽略用户的系统偏好。

字段

widthnumber

宽度

heightnumber

高度

darkboolean

深色外观

foregroundstring

文字颜色

mode"instruments" | "hud"

显示模式

speedUnit"km/h" | "mph"

速度单位

languagestring

App 语言

reduceMotionboolean

减少动态效果

accentstring

强调色

obdDevice{ id: string; name: string } | null

OBD 设备