Riferimento API

La strumentazione personalizzata utilizza main() per restituire l'albero View. Qui presentiamo la struttura dello script, l'interfaccia di esecuzione e i componenti di disegno e forniamo gli ingressi a varie API.

oggetto globale

CapDrive fornisce i seguenti oggetti globali direttamente nello script di strumentazione, senza la necessità di importarli o crearli manualmente. Possono essere letti in main() e utilizzati per ottenere dati, adattarsi all'ambiente di visualizzazione, salvare lo stato temporaneo e i registri di output.

oggetto	Scopo e modalità di accesso comuni
$data	Dati di guida. Leggi il campione corrente tramite `$data.current` e leggi i campioni degli ultimi 30 secondi di questo viaggio tramite `$data.history`.
$env	L'ambiente di visualizzazione dello strumento corrente, comprese le dimensioni disponibili, i colori del tema, le unità, la lingua e la modalità di visualizzazione, come `$env.width`, `$env.foreground`.
$sessionStorage	Lo stato temporaneo dell'istanza corrente dello strumento all'interno del viaggio corrente. Usa `get(key)` per leggere e `set(key, value)` per salvare; chiaro quando si termina il viaggio o si ricarica lo strumento.
console	Registro dello script. Utilizzare `console.log(...)`, `console.warn(...)` e altri metodi per generare dati e informazioni diagnostiche.

$data e $env vengono aggiornati dall'app e sono input di sola lettura. Questo valore viene letto ogni volta che viene chiamato main(); la modifica della copia letta dei dati non modificherà i dati di guida effettivi. $ fa parte del nome dell'oggetto, utilizza $env.width direttamente e non è necessario scriverlo come chiamata di funzione.

Definire il contenuto del disegno

main() nello script dello strumento restituisce la schermata descritta da JSX. Ogni nodo JSX è un View integrato, con attributi che controllano dimensioni, colore e altri comportamenti di disegno e relazioni annidate che formano l'immagine finale.

Lo script completo di seguito disegna un numero e una riga di unità. VStack dispone due Text su e giù, spacing imposta la spaziatura, fontSize imposta la dimensione del carattere e il colore è fornito dall'ambiente di visualizzazione corrente.

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

L'espressione JavaScript può essere utilizzata nel {} di JSX. Sostituisci il 78 fisso con il risultato del calcolo e il testo cambierà con l'input; il risultato del calcolo può anche essere passato ad attributi quali colore, dimensione o angolo dell'arco.

$data: dati di guida

I campi di $data.current provengono dall'identificatore di input di questo strumento. Compila il valore nativo in Impostazioni strumento → Associazioni di ingresso o seleziona il parametro OBD e inserisci la definizione di gestione Configurazione dei parametri. Quanto segue presuppone che sia stato definito l'identificatore corrispondente.

Metodo di accesso di esempio	Definizione di input e contenuto restituito
`$data.current.speed`	Ingresso velocità base, restituisce `{ value, unit }`.
`$data.current.gForce`	Immissione del valore G di base, inclusi `longitudinal`, `lateral`, `combined` e unità.
`$data.current.location`	Immissione della posizione di base, incluse longitudine, latitudine e unità.
`$data.current.elapsed`	Immissione della durata registrata di base, in secondi.
`$data.current.recording`	Ingresso dello stato del record di base, che restituisce un valore booleano.
`$data.current.coolant`	OBD viene immesso e restituisce `{ value, unit }` o `null` dopo aver associato i parametri del veicolo.
`$data.current.limit`	L'input numerico restituisce direttamente un numero.
`$data.current.label`	L'input di testo restituisce direttamente una stringa.
`$data.current.showUnit`	Cambia input e restituisce direttamente un valore booleano.
`$data.current.style`	Seleziona un elemento e restituisce la stringa selezionata.

$data.history copre gli ultimi 30 secondi del viaggio attuale, organizzati dal vecchio al nuovo, e il campo di campionamento è coerente con current; l'ingresso fisso utilizza la configurazione corrente. La finestra potrebbe essere vuota o contenere test mancanti. Il valore di OBD può essere un map letterale, il tipo deve essere controllato prima. Zero ha un significato diverso da null. Input completo, unità e regole storiche.

$env: ambiente di visualizzazione

$env descrive l'area di visualizzazione in cui si trova lo strumento corrente. Dopo aver ridimensionato la scheda, cambiato tema o inserito HUD, l'app fornisce un ambiente aggiornato. I calcoli che si basano su questi valori dovrebbero essere inseriti in main().

Campo	Significato e utilizzo
`$env.width`、`$env.height`	La larghezza e l'altezza disponibili dello strumento corrente sono espresse in punti sullo schermo. Può essere utilizzato per calcolare la dimensione del carattere, il diametro o le coordinate del punto finale.
`$env.foreground`、`$env.accent`	Il colore del testo e il colore in risalto del tema corrente possono essere passati direttamente a `color`, `stroke`, `background` e altri attributi di colore.
`$env.dark`	Se utilizzare l'aspetto scuro, il tipo è booleano.
`$env.mode`	Modalità di visualizzazione, il valore è `'instruments'` o `'hud'`.
`$env.speedUnit`	Unità di visualizzazione della velocità attuale, il valore è `'km/h'` o `'mph'`. Quando la lettura ha una propria unità, viene utilizzato per primo il `unit` della lettura.
`$env.language`	Identificatore della lingua corrente dell'app, ad esempio `'zh-Hans'`.
`$env.reduceMotion`	Se il sistema ha abilitato gli effetti dinamici ridotti, è possibile regolare di conseguenza l'animazione ripetuta.
`$env.obdDevice`	`{ id, name }` per il dispositivo attualmente connesso o `null` se nessun dispositivo è pronto.

Ad esempio, usa Math.min($env.width, $env.height) per ottenere il diametro massimo adatto per posizionare un cerchio perfetto e usa $env.foreground per fare in modo che il testo segua il tema. Definizione completa dell'ambiente di visualizzazione.

Esempio: lavorare con dati e ambienti di visualizzazione

Selezionare la velocità nelle impostazioni del misuratore. Il seguente script legge la velocità corrente, calcola la dimensione del carattere in base alla larghezza e all'altezza della carta, utilizza i colori del tema e visualizza le unità fornite dalla lettura. Quando manca la velocità viene visualizzata una linea orizzontale; uno zero valido viene visualizzato come 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>
  );
}

Quando i dati verranno aggiornati, la nuova velocità verrà utilizzata per la chiamata successiva; quando la dimensione della carta o il tema cambiano, la dimensione e il colore del carattere utilizzeranno i nuovi valori dell'ambiente. Se hai bisogno di accumulare valori di picco e altri stati nello stesso viaggio, puoi continuare ad utilizzare $sessionStorage; se è necessario controllare l'input effettivo, è possibile utilizzare console.log('speed', speed) per visualizzare il registro durante il debug.

Aggiornamento dello schermo

Quando l'input corrente, la definizione di input o l'ambiente di visualizzazione cambia, CapDrive fornisce gli ultimi $data e $env, esegue l'intero file nel nuovo ambito locale e quindi chiama main() definito questa volta. Anche i calcoli di livello superiore vengono rieseguiti e le variabili ordinarie non vengono conservate nel tempo. Gli input identici vengono saltati; durante l'elaborazione viene mantenuto solo l'ultimo input in sospeso. La manutenzione della finestra della cronologia e le modifiche dell'ora del campione interno da sole non attivano l'esecuzione; vengono apportate modifiche all'input temporale esplicitamente definite.

Non esiste una frequenza fissa per gli script; gli aggiornamenti effettivi dipendono dall'input e dal tempo di elaborazione. Utilizzare $sessionStorage per lo stato di intervallo; utilizzare animations per la transizione degli attributi, che viene eseguita indipendentemente dalla fine del disegno. main() deve essere completato in modo sincrono per evitare cicli continui o attese bloccanti.

Interfacce operative correlate

main(): Inserimento nel copione. Leggi questo input e restituisci in modo sincrono View, array o contenuto vuoto da disegnare.
animations: Imposta i comportamenti di transizione come durata, curva e ripetizione per le modifiche agli attributi di View.
Color / Gradient: Costruisci colore, colore HDR, gradiente lineare, gradiente radiale e gradiente angolare.
Importa e condividi: Comprendere la configurazione, gli script, le risorse e i metodi di esportazione del pacchetto di strumenti.

Disegna componenti

Organizza le schermate tramite contenitori e inserisci al loro interno visualizzazioni di testo, grafica e dati. Di seguito sono elencati tutti i View integrati per scopo; ogni pagina del componente spiega l'utilizzo, le proprietà, il comportamento predefinito e gli esempi di combinazione.

contenuto

Visualizza letture, unità, icone e immagini oppure utilizza un'area contenuto del misuratore intitolata.

Text

Visualizza la lettura, le unità o il testo descrittivo. È possibile impostare il carattere, la dimensione del carattere, l'allineamento, il ritorno a capo e il troncamento della riga; il contenuto viene convertito uniformemente in una stringa e i valori vuoti vengono visualizzati come vuoti.

Symbol

Usa SF Symbols per disegnare icone di sistema, come tachimetro, termometro. È possibile impostare la dimensione del carattere del simbolo, il peso del carattere e il metodo di colorazione. La disponibilità del simbolo specifico dipende dal sistema del dispositivo.

Image

Visualizza un'immagine da una risorsa indicatore, ad esempio un logo, uno sfondo decorativo o una trama di riquadro. source Utilizza il nome della risorsa per impostare il metodo di ridimensionamento, ritaglio o ripetizione sulle dimensioni disponibili.

CardContent

Fornisce una struttura dello strumento con titolo, contenuto corretto e corpo del testo. Il testo renderer otterrà contentSize meno il titolo e i margini, che possono essere utilizzati per organizzare figure, grafici o diagrammi.

disposizione

Disporre più View, allocare lo spazio rimanente e costruire layout orizzontali, verticali, impilati e in scala.

HStack

Disporre i sottotitoli View da sinistra a destra, adatto per combinazioni orizzontali di icone e numeri, numeri e unità, ecc. spacing imposta la spaziatura adiacente, alignment imposta l'allineamento superiore e inferiore o la linea di base del testo all'interno di questa riga.

VStack

Disporre i sottotitoli View dall'alto verso il basso, adatti alla combinazione verticale di titoli, numeri principali e unità. spacing imposta la spaziatura adiacente e alignment imposta l'allineamento sinistro e destro all'interno di questa colonna.

ZStack

Impila più View nella stessa area, adatti per letture di sfondo, scala e centro. I figli View vengono disegnati in sequenza e alignment imposta la loro posizione di allineamento comune all'interno del contenitore.

Spacer

Assegna lo spazio rimanente nello Stack per spingere il contenuto su entrambi i lati o riservare una distanza elastica per il contenuto. minLength imposta la lunghezza minima, width esplicito o height possono fissare la dimensione nella direzione corrispondente.

RadialLayout

Distribuisci scale, numeri o simboli attorno a un cerchio. radius controlla la distanza dal centro al centro del layout di View e startAngle e sweepAngle controllano l'intervallo di distribuzione.

RepeatedLayout

Duplica periodicamente un modello nella finestra di ritaglio, adatto per scale e compassi in continuo movimento. period imposta l'intervallo di ripetizione, value e anchor determinano dove è allineato il valore corrente.

grafica

Disegna segni di spunta, progressioni, linee e contorni personalizzati e controlla l'aspetto con proprietà come sfondo, tratto e angolo.

Rectangle

Disegna un rettangolo con angoli arrotondati opzionali da utilizzare con sfondi, barre di avanzamento e bordi. background riempie l'interno, stroke tratti, lineWidth e strokePosition controllano la larghezza e la posizione del tratto.

Circle

Disegna un cerchio o un arco perfetto all'interno dell'area disponibile, adatto per l'avanzamento circolare e le scale metriche. Il diametro assume il valore più piccolo tra larghezza e centro. startAngle e sweepAngle controllano l'intervallo di visualizzazione. Quando l'intero cerchio è chiuso, lo sfondo può essere riempito.

Ellipse

Disegna un'ellisse o un arco ellittico entro una determinata larghezza e altezza. Scale ellittiche o contorni decorativi possono essere formati dall'angolo iniziale, dall'angolo di scansione, dal riempimento e dal tratto.

Arc

Disegna un arco ellittico in base all'angolo iniziale e all'angolo di apertura, adatto per archi in scala e visualizzazione dell'avanzamento. Il bordo è determinato dalla larghezza e dall'altezza. La larghezza, il punto finale e la posizione del tratto sono configurabili e lo sfondo può riempirsi quando è completamente chiuso.

Line

Disegna una linea retta tra due punti finali in coordinate locali. Adatto per linee indicatrici, segni di graduazione e divisori, è possibile impostare gli stili di colore, larghezza, trattino e punto finale.

Polyline

Disegna una polilinea collegando una serie di punti in sequenza. closed può collegare l'ultimo punto e il primo punto per formare un contorno chiuso e consente il riempimento; le coordinate utilizzano il numero di punti nell'attuale View.

Path

Costruisci percorsi con comandi come sposta, linea, quad, cubico, arco e chiudi. Adatto per personalizzare puntatori, curve e contorni combinati e per impostare regole di riempimento e tratti.

Combinazioni e Materiali

Applica effetti globali al contenuto combinato o dipingi una superficie in materiale di vetro smerigliato.

Group

Combina più View in un tutto, applicando uniformemente trasparenza, rotazione o altri effetti speciali. Il figlio View segue le regole di disposizione del contenitore esterno e gli effetti speciali vengono applicati all'intero set di risultati sintetizzati.

Material

Disegna la superficie di materiale in vetro smerigliato, a cui è possibile sovrapporre testo e grafica per formare un'area di contenuto. type attualmente supporta il satinato, style controlla lo spessore del materiale; l'effetto visibile dipende dal contenuto che sta dietro.

Grafici e mappe

Traccia serie di dati in curve e istogrammi o visualizza posizioni e percorsi.

LineChart

Traccia la serie di dati con i valori x/y effettivi come una curva. Adatto per tendenze quali velocità e tempo, supporta intervalli di coordinate, assi ed etichette; i valori y mancanti interromperanno i segmenti di linea.

BarChart

Traccia ciascun elemento dati come una barra, adatta per confrontare valori categoriali. Può essere disposto orizzontalmente o verticalmente, impostare intervalli numerici, etichette di categoria ed etichette numeriche e supporta valori positivi e negativi.

Map

Visualizza mappe, posizioni e percorsi all'interno del misuratore. È possibile impostare il centro della fotocamera, l'orientamento, lo zoom e lo stile della mappa, utilizzando path per fornire punti del percorso; seguire la posizione dell'utente richiede dati di posizionamento validi.

File di tipo e dichiarazione

I tipi comuni definiscono centralmente strutture quali dimensioni, margini, trasformazioni, tratti, animazioni e dati del grafico. L'editor fornisce suggerimenti sul tipo per la stessa API e i file di dichiarazione possono anche essere scaricati per essere utilizzati da editor esterni.

Tipi comuni

capdrive.d.ts