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 はアプリによって更新され、読み取り専用の入力です。この値は、main() が呼び出されるたびに読み取られます。読み取られたデータのコピーを変更しても、実際の走行データは変更されません。 $ はオブジェクト名の一部であり、$env.width を直接使用し、関数呼び出しとして記述する必要はありません。

描画コンテンツを定義する

機器スクリプトの main() は、JSX で記述された画面を返します。各 JSX ノードは組み込みの View であり、サイズ、色、その他の描画動作を制御する属性と、最終的な画像を形成するネストされた関係を備えています。

以下の完全なスクリプトは、ユニットの番号と行を描画します。 VStack は 2 つの 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>
  );
}

JavaScript 式は JSX の {} で使用できます。固定の 78 を計算結果に置き換えると、テキストが入力に応じて変化します。計算結果は、色、サイズ、円弧の角度などの属性に渡すこともできます。

$data: 走行データ

$data.current のフィールドは、この機器の入力識別子から取得されます。 メーター設定 → 入力の割り当て にネイティブ値を入力するか、OBD パラメーターを選択して パラメータ設定 管理定義に組み込みます。以下では、対応する識別子が定義されていると仮定します。

アクセス方法例	定義を入力して内容を返す
`$data.current.speed`	ベース速度入力、`{ value, unit }` を返します。
`$data.current.gForce`	`longitudinal`、`lateral`、`combined` および単位を含む、基本的な G 値入力。
`$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 を入力したりすると、アプリは更新された環境を提供します。これらの値に依存する計算は 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`	アプリの現在の言語識別子 (`'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() は、連続ループやブロック待機を避けるために同期的に完了する必要があります。

描画コンポーネント

コンテナーを通じて画面を整理し、テキスト、グラフィックス、データビューをコンテナーに配置します。以下に、すべての組み込み View を目的別にリストします。各コンポーネントのページでは、使用法、プロパティ、デフォルトの動作、組み合わせ例について説明します。

コンテンツ

測定値、単位、アイコン、写真を表示するか、タイトル付きのメーターコンテンツ領域を使用します。

Text

読み、単位、または説明テキストを表示します。フォント、フォントサイズ、配置、行の折り返し、切り捨てを設定できます。内容は一律に文字列に変換され、空の値は空として表示されます。

Symbol

SF Symbols を使用して、速度計、温度計などのシステムアイコンを描画します。シンボルのフォントサイズ、フォントの太さ、色付け方法を設定できます。特定のシンボルが使用できるかどうかは、デバイスのシステムによって異なります。

Image

ロゴ、装飾的な背景、タイルテクスチャなどのゲージリソースからの画像を表示します。 source リソース名を使用して、スケーリング、トリミング、または繰り返し方法を使用可能なサイズに設定します。

CardContent

タイトル、権利内容、本文テキストを含む楽器構造を提供します。テキスト renderer からは、図、グラフ、チャートの配置に使用できるタイトルと余白を除いた contentSize が得られます。

レイアウト

複数の View を配置し、残りのスペースを割り当て、水平、垂直、積み重ね、スケールレイアウトを構築します。

HStack

アイコンと数字、数字と単位などの水平方向の組み合わせに適した、字幕 View を左から右に配置します。 spacing は隣接する間隔を設定し、alignment はこの行内の上下またはテキストのベースラインの配置を設定します。

VStack

タイトル、本文番号、単位の縦の組み合わせに合わせて、字幕 View を上から下に配置します。 spacing は隣接する間隔を設定し、alignment はこの列内の左右の配置を設定します。

ZStack

複数の View を同じ領域に積み重ねて、背景、スケール、中心の読み取りに適しています。子の View は順番に描画され、alignment はコンテナ内での共通の位置合わせ位置を設定します。

Spacer

スタック内の残りのスペースを割り当てて、コンテンツを両側にプッシュするか、コンテンツ用の弾性距離を確保します。 minLength は最小長を設定し、明示的な width または height は対応する方向のサイズを固定できます。

RadialLayout

円の周りにスケール、数字、または記号を配置します。 radius は View の中心からレイアウト中心までの距離を制御し、startAngle と sweepAngle は分布範囲を制御します。

RepeatedLayout

トリミングウィンドウ内のパターンを定期的に複製します。スケールやコンパスを連続的に移動する場合に適しています。 period は繰り返し間隔を設定し、value と anchor は現在の値がどこに配置されるかを決定します。

グラフィックス

ティック、プログレッション、ライン、カスタムアウトラインを描画し、背景、ストローク、角度などのプロパティで外観を制御します。

Rectangle

背景、進行状況バー、および境界線で使用するために、オプションで角が丸い四角形を描画します。 background は内部を塗りつぶし、stroke ストローク、lineWidth および strokePosition はストロークの幅と位置を制御します。

Circle

利用可能な領域内に完全な円または円弧を描きます。円形の進行状況やメータースケールに適しています。直径は、幅と中心の小さい方の値になります。 startAngle と sweepAngle は表示範囲を制御します。円全体を閉じると背景を塗りつぶすことができます。

Ellipse

指定された幅と高さ内で楕円または楕円弧を描画します。楕円スケールや装飾的な輪郭は、開始角度、スイープ角度、塗りつぶし、ストロークによって形成できます。

Arc

開始角度と掃引角度に従って楕円弧を描きます。スケール円弧や進捗表示に適しています。境界線は幅と高さによって決まります。ストロークの幅、終点、位置は設定可能で、完全に閉じたときに背景を塗りつぶすことができます。

Line

ローカル座標で 2 つの端点の間に直線を描きます。インジケーターの線、目盛り、区切り線に適しており、色、幅、破線、端点のスタイルを設定できます。

Polyline

一連の点を順番に接続してポリラインを描画します。 closed は、最後の点と最初の点を接続して閉じた輪郭を形成し、塗りつぶしを行うことができます。座標には、現在の View 内のポイントの数が使用されます。

Path

移動、直線、四角形、立方体、円弧、閉じるなどのコマンドを使用してパスを作成します。ポインター、曲線、組み合わせたアウトラインのカスタマイズ、塗りつぶしルールとストロークの設定に適しています。

組み合わせと素材

結合されたコンテンツにグローバル効果を適用したり、すりガラス素材の表面をペイントしたりできます。

Group

複数の View を 1 つに結合し、透明度、回転、その他の特殊効果を均一に適用します。子 View は外側のコンテナの配置規則に従い、合成結果のセット全体に特殊効果が適用されます。

Material

すりガラス素材の表面を描画し、テキストやグラフィックを重ねてコンテンツ領域を形成します。 type は現在つや消しをサポートしており、style は材料の厚さを制御します。目に見える効果はその背後にあるコンテンツによって異なります。

チャートと地図

データ系列を曲線やヒストグラムにプロットしたり、位置やルートを表示したりできます。

LineChart

実際の x/y 値を使用してデータ系列を曲線としてプロットします。速度や時間などの傾向に適しており、座標範囲、軸、ラベルをサポートしています。 y 値が欠落していると、行セグメントが分割されます。

BarChart

カテゴリ値の比較に適した、各データ項目を棒としてプロットします。水平方向または垂直方向に配置でき、数値範囲、カテゴリラベル、数値ラベルを設定でき、正の値と負の値をサポートします。

Map

メーター内の地図、場所、ルートを表示します。 path を使用してルートポイントを提供し、カメラの中心、方向、ズーム、地図スタイルを設定できます。ユーザーの位置を追跡するには、有効な位置データが必要です。

タイプファイルと宣言ファイル

一般的なタイプは、寸法、マージン、変換、ストローク、アニメーション、チャートデータなどの構造を一元的に定義します。エディターは同じ API の型ヒントを提供し、外部エディターで使用するために宣言ファイルをダウンロードすることもできます。

共通の型

capdrive.d.ts