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() 應同步完成，避免持續循環或阻塞等待。