儀表資料

儀表通過 $data 使用已定義的輸入。$data.current 提供當前輸入，$data.history 提供當前行程最近 30 秒的採樣序列。欄位名稱來自本儀表的輸入標識符；例如，把基礎速度輸入命名為 speed，通過 $data.current.speed 讀取；把 OBD 輸入命名為 coolant，通過 $data.current.coolant 讀取。

速度、距離、時間和 OBD 等量值包含 value 與 unit。例如 { value: 42.3, unit: 'km/h' } 包含數值與單位；位置、G 值等欄位提供各自分量。數值、文本、開關與選擇項則直接回傳數字、字串或布爾值，不再包一層 value。完整規則見 $data API。

點擊編輯器頂部的儀表名稱，打開 儀表設定 → 輸入綁定。齒輪進入 參數設定，用於定義輸入的名稱、標識符和類型；回傳輸入綁定後填寫本機數值，或為 OBD 輸入選擇自己的車輛參數。基礎資料由 App 自動提供。

輸入標識符為 1–100 個英文字母和數字，以字母開頭，同一儀表內不得重復；每塊儀表最多 256 項輸入。名稱用於介面顯示，標識符用於程式碼。修改顯示名稱不改變訪問路徑，修改標識符則需要同步修改程式碼。

例如，用 coolant 表示冷卻液溫度後，綁定不同設備的相應參數，程式碼仍讀取 $data.current.coolant。編輯器按輸入定義提供表達式與類型提示。數值預設值必須落在上下限內，選擇項必須有互不重復的非空選項及有效預設項；儲存提示錯誤時先修正對應欄位。

新建儀表已包含標識符為 speed、來源為 速度 的基礎資料輸入；已有作品可在 參數設定 中檢查該定義。在 main() 中取得 $data.current.speed，即可使用本次速度的數值和單位。下例將數值四捨五入後顯示在上方，單位顯示在下方；沒有可用速度時顯示 —。

配置正確的基礎速度輸入始終保留物件，缺測時 value 為 null，unit 仍為設定中的 km/h 或 mph。== null 檢查數值是否缺測，速度為零時仍顯示 0。欄位名由輸入標識符決定；若改為 vehicleSpeed，程式碼也應改為 $data.current.vehicleSpeed。

function main() {
  const speed = $data.current.speed;
  return (
    <VStack spacing={8}>
      <Text fontSize={64} color={$env.foreground}>
        {speed?.value == null ? '—' : Math.round(speed.value)}
      </Text>
      <Text fontSize={16} color={$env.accent}>
        {speed?.unit ?? $env.speedUnit}
      </Text>
    </VStack>
  );
}

先連線 OBD 設備並確認目標參數能產生有效讀數。進入 參數設定 添加 OBD 資料 輸入，例如名稱為“冷卻液溫度”、標識符為 coolant，預期類型選擇數值。回傳 輸入綁定，為它選擇設備下的冷卻液溫度參數。下面的示例通過 $data.current.coolant 讀取，不使用車輛參數 UUID 作為腳本欄位名。

已綁定且配置存在的讀數始終包含 value 和 unit。設備未連線、讀數過期或查詢失敗時，value 為 null，unit 仍取所選設備儲存的參數配置；無單位參數使用 unit: null。未綁定或設備、參數配置已不存在時，整個輸入為 null。

value 可以是數字或文本映射後的字串。預期類型用於編輯提示；綁定可能回傳不同類型的參數時會提示，但仍可綁定，實際值不會因此強制轉換。數字格式化前應檢查類型。更換適配器或導入他人作品後，重新綁定相應輸入即可沿用原程式碼。

function main() {
  const reading = $data.current.coolant;
  const value = reading?.value;
  const text =
    value == null
      ? '—'
      : typeof value === 'number'
        ? value.toFixed(1)
        : value.toString();
  return (
    <VStack spacing={8}>
      <Text fontSize={48} color={$env.foreground}>
        {text}
      </Text>
      <Text fontSize={16} color={$env.accent}>
        {reading?.unit ?? ''}
      </Text>
    </VStack>
  );
}

自定義儀表沒有統一固定的刷新頻率。當前輸入、輸入定義或顯示環境變化時，CapDrive 會重新執行腳本並呼叫 main()；完全相同的輸入會跳過。腳本串行執行，處理中只保留最新的待處理輸入。動畫由繪制端獨立執行，不需要逐幀運行腳本，也不會提高傳感器或 OBD 的採樣頻率。

App 統一維護當前行程最近 30 秒的已採集資料，最多按 5 Hz 採樣、保留 151 項。打開儀表可讀取已有窗口；暫停繪制或重建運行實例不丟失窗口，行程結束、切換行程或運行模式時重置。歷史增長或過期清理不會單獨觸發腳本；希望曲線隨時間推進時，可定義一個標識符為 elapsed、來源為已記錄時長的基礎輸入。

定義了 speed 和 elapsed 輸入後，可用每個歷史採樣的 elapsed.value 作橫坐標、speed.value 作縱坐標；時間戳使用毫秒，已記錄時長使用秒。保留缺測區間，不用後來的 OBD 值回填歷史。預覽使用模擬輸入，儀錶盤使用實際資料。

null 表示當前沒有可用讀數，0 是有效數值。保留這兩種狀態，儀表才能如實顯示停車、連線中斷或暫時缺測。可用 value == null ? '—' : value 處理數值，避免通過 value || 0 將所有缺測顯示為零。

文本映射可能產生空字串，也可能在未匹配時回傳數字或 null，具體行為由參數配置決定。接收文字的 View 可以顯示字串；參與計算和數字格式化的值應先檢查類型。

排查缺測時，按欄位對應的資料源檢查：基礎速度查看定位狀態；OBD 參數查看當前設備、測試讀取結果和參數配置。資料源正常後，再核對儀表選擇的欄位與程式碼表達式。