Referensi API

Instrumentasi khusus menggunakan main() untuk mengembalikan pohon View. Di sini kami memperkenalkan struktur skrip, menjalankan antarmuka dan komponen gambar, serta menyediakan pintu masuk ke berbagai API.

objek global

CapDrive menyediakan objek global berikut secara langsung dalam skrip instrumentasi, tanpa perlu mengimpor atau membuatnya sendiri. Mereka dapat dibaca di main() dan digunakan untuk memperoleh data, beradaptasi dengan lingkungan tampilan, menyimpan status sementara dan log keluaran.

obyek	Tujuan dan metode akses umum
$data	Data mengemudi. Baca sampel saat ini melalui `$data.current`, dan baca sampel 30 detik terakhir perjalanan ini melalui `$data.history`.
$env	Lingkungan tampilan instrumen saat ini, termasuk ukuran yang tersedia, warna tema, unit, bahasa, dan mode tampilan, seperti `$env.width`, `$env.foreground`.
$sessionStorage	Keadaan sementara dari instance instrumen saat ini dalam perjalanan saat ini. Gunakan `get(key)` untuk membaca dan `set(key, value)` untuk menyimpan; jelas saat mengakhiri perjalanan atau memuat ulang instrumen.
console	Log skrip. Gunakan `console.log(...)`, `console.warn(...)` dan metode lain untuk mengeluarkan data dan informasi diagnostik.

$data dan $env diperbarui oleh Aplikasi dan merupakan input hanya-baca. Nilai ini dibaca setiap kali main() dipanggil; memodifikasi salinan data yang telah dibaca tidak akan mengubah data mengemudi yang sebenarnya. $ adalah bagian dari nama objek, gunakan $env.width secara langsung dan tidak perlu ditulis sebagai pemanggilan fungsi.

Tentukan konten gambar

main() dalam skrip instrumen mengembalikan layar yang dijelaskan oleh JSX. Setiap node JSX adalah View bawaan, dengan atribut yang mengontrol ukuran, warna, dan perilaku gambar lainnya, serta hubungan bersarang yang membentuk gambar akhir.

Script lengkap di bawah ini menggambar sebuah angka dan deretan satuan. VStack mengatur dua Text atas dan bawah, spacing mengatur jarak, fontSize mengatur ukuran font, dan warna disediakan oleh lingkungan tampilan saat ini.

function main() {
  return (
    <VStack spacing={6}>
      <Text fontSize={48} color={$env.foreground}>
        78
      </Text>
      <Text fontSize={14} color={$env.accent}>
        km/h
      </Text>
    </VStack>
  );
}

Ekspresi JavaScript dapat digunakan di {} JSX. Ganti 78 yang tetap dengan hasil perhitungan, dan teks akan berubah dengan input; hasil perhitungan juga dapat diteruskan ke atribut seperti warna, ukuran, atau sudut busur.

$data: data mengemudi

Bidang $data.current berasal dari pengidentifikasi masukan instrumen ini. Isi nilai asli di Pengaturan instrumen → Pengikatan masukan atau pilih parameter OBD dan masukkan ke dalam definisi manajemen Konfigurasi parameter. Berikut ini mengasumsikan bahwa pengidentifikasi yang sesuai telah ditentukan.

Contoh metode akses	Masukkan definisi dan kembalikan konten
`$data.current.speed`	Input kecepatan dasar, mengembalikan `{ value, unit }`.
`$data.current.gForce`	Input nilai G dasar, termasuk `longitudinal`, `lateral`, `combined` dan satuan.
`$data.current.location`	Input lokasi dasar, termasuk bujur, lintang, dan satuan.
`$data.current.elapsed`	Input durasi rekaman dasar, dalam hitungan detik.
`$data.current.recording`	Input status rekaman dasar, mengembalikan nilai Boolean.
`$data.current.coolant`	OBD dimasukkan dan mengembalikan `{ value, unit }` atau `null` setelah mengikat parameter kendaraan.
`$data.current.limit`	Input numerik mengembalikan angka secara langsung.
`$data.current.label`	Input teks mengembalikan string secara langsung.
`$data.current.showUnit`	Ganti input dan langsung kembalikan nilai Boolean.
`$data.current.style`	Pilih item dan kembalikan string yang dipilih.

$data.history mencakup 30 detik terakhir perjalanan saat ini, disusun dari yang lama ke yang baru, dan bidang pengambilan sampel konsisten dengan current; input tetap menggunakan konfigurasi saat ini. Jendela mungkin kosong atau berisi tes yang hilang. Nilai OBD mungkin berupa peta literal, tipenya harus diperiksa terlebih dahulu. Nol memiliki arti yang berbeda dengan null. Masukan lengkap, satuan, dan aturan riwayat.

$env: Lingkungan tampilan

$env menjelaskan area tampilan tempat instrumen saat ini berada. Setelah mengubah ukuran kartu, mengganti tema, atau memasukkan HUD, Aplikasi menyediakan lingkungan yang diperbarui. Perhitungan yang mengandalkan nilai-nilai ini harus ditempatkan di main().

Bidang	Arti dan kegunaannya
`$env.width`、`$env.height`	Lebar dan tinggi yang tersedia dari instrumen saat ini ada dalam titik layar. Dapat digunakan untuk menghitung ukuran font, diameter atau koordinat titik akhir.
`$env.foreground`、`$env.accent`	Warna teks dan warna aksen tema saat ini dapat langsung diteruskan ke `color`, `stroke`, `background` dan atribut warna lainnya.
`$env.dark`	Apakah akan menggunakan tampilan gelap, tipenya adalah boolean.
`$env.mode`	Mode tampilan, nilainya adalah `'instruments'` atau `'hud'`.
`$env.speedUnit`	Satuan tampilan kecepatan saat ini, nilainya adalah `'km/h'` atau `'mph'`. Jika bacaan mempunyai satuannya sendiri, maka `unit` bacaan tersebut digunakan terlebih dahulu.
`$env.language`	Pengenal bahasa aplikasi saat ini, seperti `'zh-Hans'`.
`$env.reduceMotion`	Apakah sistem telah mengaktifkan pengurangan efek dinamis, Anda dapat menyesuaikan animasi pengulangan yang sesuai.
`$env.obdDevice`	`{ id, name }` untuk perangkat yang terhubung saat ini, atau `null` jika tidak ada perangkat yang siap.

Misalnya, gunakan Math.min($env.width, $env.height) untuk mendapatkan diameter maksimum yang sesuai untuk menempatkan lingkaran sempurna, dan gunakan $env.foreground untuk membuat teks mengikuti tema. Definisi lingkungan tampilan penuh.

Contoh: Bekerja dengan lingkungan data dan tampilan

Pilih kecepatan dalam pengaturan meteran. Skrip berikut membaca kecepatan saat ini, menghitung ukuran font berdasarkan lebar dan tinggi kartu, menggunakan warna tema, dan menampilkan satuan yang disediakan oleh pembacaan. Garis horizontal ditampilkan ketika kecepatan hilang; nol yang valid ditampilkan sebagai 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>
  );
}

Ketika data diperbarui, kecepatan baru akan digunakan untuk panggilan berikutnya; ketika ukuran kartu atau tema berubah, ukuran dan warna font akan menggunakan nilai lingkungan baru. Jika Anda perlu mengumpulkan nilai puncak dan negara bagian lain dalam perjalanan yang sama, Anda dapat terus menggunakan $sessionStorage; jika Anda perlu memeriksa masukan sebenarnya, Anda dapat menggunakan console.log('speed', speed) untuk mengeluarkan log selama proses debug.

Pembaruan layar

Ketika masukan saat ini, definisi masukan, atau lingkungan tampilan berubah, CapDrive menyediakan $data dan $env terbaru, mengeksekusi seluruh file dalam lingkup lokal baru, dan kemudian memanggil main() yang ditentukan kali ini. Penghitungan tingkat atas juga dijalankan ulang, dan variabel biasa tidak dipertahankan sepanjang waktu. Input yang identik dilewati; hanya masukan terakhir yang tertunda yang dipertahankan dalam pemrosesan. Pemeliharaan jendela riwayat dan perubahan waktu sampel internal saja tidak memicu eksekusi; perubahan input waktu yang ditentukan secara eksplisit dapat dilakukan.

Tidak ada frekuensi tetap untuk skrip; pembaruan aktual bergantung pada input dan waktu pemrosesan. Gunakan $sessionStorage untuk status rentang; gunakan animations untuk transisi atribut, yang dijalankan secara independen pada akhir gambar. main() harus diselesaikan secara serempak untuk menghindari loop terus-menerus atau menunggu pemblokiran.

Antarmuka operasi terkait

main(): Entri skrip. Baca masukan ini dan secara serempak kembalikan View, larik, atau konten kosong yang akan diambil.
animations: Tetapkan perilaku transisi seperti durasi, kurva, dan pengulangan untuk perubahan atribut View.
Color / Gradient: Buatlah warna, warna HDR, gradien linier, gradien radial, dan gradien sudut.
Impor dan bagikan: Pahami konfigurasi, skrip, sumber daya, dan metode ekspor paket instrumen.

Menggambar komponen

Atur layar melalui wadah dan tempatkan tampilan teks, grafik, dan data ke dalamnya. Berikut ini daftar semua View bawaan berdasarkan tujuannya; setiap halaman komponen menjelaskan penggunaan, properti, perilaku default, dan contoh kombinasi.

isi

Tampilkan pembacaan, satuan, ikon dan gambar, atau gunakan area konten meteran bertajuk.

Text

Menampilkan bacaan, unit atau teks deskriptif. Font, ukuran font, perataan, pembungkusan garis, dan pemotongan dapat diatur; konten diubah secara seragam menjadi string, dan nilai kosong ditampilkan sebagai kosong.

Symbol

Gunakan SF Symbols untuk menggambar ikon sistem, seperti speedometer, termometer. Ukuran font simbol, berat font, dan metode pewarnaan dapat diatur. Tersedia atau tidaknya simbol tertentu bergantung pada sistem perangkat.

Image

Menampilkan gambar dari sumber daya pengukur, seperti logo, latar belakang dekoratif, atau tekstur ubin. source Gunakan nama sumber daya untuk mengatur metode penskalaan, pemotongan, atau pengulangan ke ukuran yang tersedia.

CardContent

Menyediakan struktur instrumen dengan judul, konten yang tepat, dan teks isi. Teks renderer akan mendapatkan contentSize dikurangi judul dan margin, yang dapat digunakan untuk menyusun gambar, grafik, atau bagan.

tata letak

Susun beberapa View, alokasikan ruang yang tersisa, dan buat tata letak horizontal, vertikal, bertumpuk, dan berskala.

HStack

Susun subtitle View dari kiri ke kanan, cocok untuk kombinasi horizontal ikon dan angka, angka dan satuan, dll. spacing mengatur jarak yang berdekatan, alignment mengatur perataan garis dasar atas dan bawah atau teks dalam baris ini.

VStack

Susun subtitle View dari atas ke bawah, sesuai dengan kombinasi vertikal judul, nomor induk dan satuan. spacing mengatur jarak yang berdekatan, dan alignment mengatur perataan kiri dan kanan dalam kolom ini.

ZStack

Tumpuk beberapa View di area yang sama, cocok untuk pembacaan latar belakang, skala, dan tengah. Anak-anak View digambar secara berurutan, dan alignment menetapkan posisi penyelarasan umum mereka di dalam wadah.

Spacer

Alokasikan sisa ruang di Tumpukan untuk mendorong konten di kedua sisi atau memberikan jarak elastis untuk konten. minLength menetapkan panjang minimum, width atau height eksplisit dapat memperbaiki ukuran ke arah yang sesuai.

RadialLayout

Bagikan skala, angka, atau simbol di sekeliling lingkaran. radius mengontrol jarak dari pusat ke pusat tata letak View, dan startAngle dan sweepAngle mengontrol jangkauan distribusi.

RepeatedLayout

Menduplikasi pola secara berkala di jendela pemangkasan, cocok untuk timbangan dan kompas yang terus bergerak. period mengatur interval pengulangan, value dan anchor menentukan di mana nilai saat ini disejajarkan.

grafis

Gambar tanda centang, perkembangan, garis, dan kerangka khusus, serta kontrol tampilan dengan properti seperti latar belakang, guratan, dan sudut.

Rectangle

Menggambar persegi panjang dengan sudut membulat opsional untuk digunakan dengan latar belakang, bilah kemajuan, dan batas. background mengisi bagian dalam, stroke guratan, lineWidth dan strokePosition mengontrol lebar dan posisi guratan.

Circle

Menggambar lingkaran atau busur sempurna dalam area yang tersedia, cocok untuk kemajuan melingkar dan skala meter. Diameter mengambil nilai lebar dan pusat yang lebih kecil. startAngle dan sweepAngle mengontrol rentang tampilan. Ketika seluruh lingkaran ditutup, latar belakang dapat diisi.

Ellipse

Menggambar busur elips atau elips dengan lebar dan tinggi tertentu. Sisik elips atau garis dekoratif dapat dibentuk dengan sudut awal, sudut sapuan, isian, dan guratan.

Arc

Gambarlah busur elips sesuai dengan sudut awal dan sudut sapuan, cocok untuk busur skala dan tampilan kemajuan. Batasnya ditentukan oleh lebar dan tinggi. Lebar, titik akhir, dan posisi guratan dapat dikonfigurasi, dan latar belakang diperbolehkan terisi saat tertutup penuh.

Line

Menggambar garis lurus antara dua titik akhir pada koordinat lokal. Cocok untuk garis indikator, tanda centang, dan pembagi, Anda dapat mengatur gaya warna, lebar, tanda hubung, dan titik akhir.

Polyline

Gambarlah polyline dengan menghubungkan sekumpulan titik secara berurutan. closed dapat menghubungkan titik terakhir dan titik pertama untuk membentuk kontur tertutup, dan memungkinkan pengisian; koordinatnya menggunakan jumlah titik di View saat ini.

Path

Bangun jalur dengan perintah seperti bergerak, garis, segi empat, kubik, busur, dan tutup. Cocok untuk menyesuaikan penunjuk, kurva, dan garis gabungan, serta mengatur aturan pengisian dan guratan.

Kombinasi dan Bahan

Terapkan efek global pada konten gabungan, atau cat permukaan bahan kaca buram.

Group

Gabungkan beberapa View menjadi satu kesatuan, terapkan transparansi, rotasi, atau efek khusus lainnya secara seragam. Anak View mengikuti aturan pengaturan wadah luar, dan efek khusus diterapkan ke seluruh rangkaian hasil sintesis.

Material

Gambarlah permukaan bahan kaca buram, yang dapat ditindih dengan teks dan grafik untuk membentuk area konten. type saat ini mendukung buram, style mengontrol ketebalan material; efek yang terlihat tergantung pada konten di baliknya.

Bagan dan Peta

Plot seri data ke dalam kurva dan histogram, atau tampilkan lokasi dan rute.

LineChart

Plot rangkaian data dengan nilai aktual x/y sebagai kurva. Cocok untuk tren seperti kecepatan dan waktu, mendukung rentang koordinat, sumbu dan label; nilai y yang hilang akan merusak segmen garis.

BarChart

Plot setiap item data sebagai batang, cocok untuk membandingkan nilai kategorikal. Itu dapat diatur secara horizontal atau vertikal, mengatur rentang numerik, label kategori dan label numerik, dan mendukung nilai positif dan negatif.

Map

Menampilkan peta, lokasi, dan rute dalam meteran. Pusat kamera, orientasi, zoom, dan gaya peta dapat diatur, menggunakan path untuk menyediakan titik rute; mengikuti lokasi pengguna memerlukan data posisi yang valid.

Ketik dan deklarasi file

Tipe umum mendefinisikan struktur secara terpusat seperti dimensi, margin, transformasi, goresan, animasi, dan data bagan. Editor memberikan petunjuk tipe untuk API yang sama, dan file deklarasi juga dapat diunduh untuk digunakan oleh editor eksternal.

Tipe bersama

capdrive.d.ts