$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 裝置