$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"速度单位
languagestringApp 语言
reduceMotionboolean减少动态效果
accentstring强调色
obdDevice{ id: string; name: string } | nullOBD 设备