API-Referenz

Benutzerdefinierte Instrumentierung verwendet main(), um den View-Baum zurückzugeben. Hier stellen wir die Skriptstruktur, die Ausführung von Schnittstellen und Zeichenkomponenten vor und bieten Zugänge zu verschiedenen APIs.

globales Objekt

CapDrive stellt die folgenden globalen Objekte direkt im Instrumentierungsskript bereit, ohne dass Sie sie selbst importieren oder erstellen müssen. Sie können in main() gelesen und zum Abrufen von Daten, zur Anpassung an die Anzeigeumgebung, zum Speichern temporärer Status und zur Ausgabe von Protokollen verwendet werden.

Objekt	Zweck und gängige Zugriffsmethoden
$data	Fahrdaten. Lesen Sie das aktuelle Beispiel bis `$data.current` und lesen Sie die Beispiele der letzten 30 Sekunden dieser Fahrt bis `$data.history`.
$env	Die Anzeigeumgebung des aktuellen Instruments, einschließlich verfügbarer Größen, Themenfarben, Einheiten, Sprache und Anzeigemodus, z. B. `$env.width`, `$env.foreground`.
$sessionStorage	Der temporäre Status der aktuellen Instrumenteninstanz innerhalb der aktuellen Reise. Verwenden Sie `get(key)` zum Lesen und `set(key, value)` zum Speichern; klar, wenn die Reise beendet oder das Instrument neu geladen wird.
console	Skriptprotokoll. Verwenden Sie `console.log(...)`, `console.warn(...)` und andere Methoden, um Daten und Diagnoseinformationen auszugeben.

$data und $env werden von der App aktualisiert und sind schreibgeschützte Eingaben. Dieser Wert wird bei jedem Aufruf von main() gelesen; Eine Änderung der gelesenen Kopie der Daten führt nicht zu einer Änderung der tatsächlichen Fahrdaten. $ ist Teil des Objektnamens, verwendet $env.width direkt und muss nicht als Funktionsaufruf geschrieben werden.

Zeichnungsinhalte definieren

main() im Instrumentenskript gibt den von JSX beschriebenen Bildschirm zurück. Jeder JSX-Knoten ist ein integrierter View mit Attributen, die Größe, Farbe und andere Zeichenverhalten steuern, und verschachtelten Beziehungen, die das endgültige Bild bilden.

Das vollständige Skript unten zeichnet eine Zahl und eine Reihe von Einheiten. VStack ordnet zwei Text nach oben und unten an, spacing legt den Abstand fest, fontSize legt die Schriftgröße fest und die Farbe wird von der aktuellen Anzeigeumgebung bereitgestellt.

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

Der JavaScript-Ausdruck kann im {} von JSX verwendet werden. Ersetzen Sie das feste 78 durch das Berechnungsergebnis, und der Text ändert sich mit der Eingabe; Das Berechnungsergebnis kann auch an Attribute wie Farbe, Größe oder Bogenwinkel übergeben werden.

$data: Fahrdaten

Die Felder von $data.current stammen aus der Eingabekennung dieses Instruments. Geben Sie den nativen Wert in Instrumenteneinstellungen → Eingabezuordnungen ein oder wählen Sie den Parameter OBD aus und fügen Sie ihn in die Verwaltungsdefinition Parameterkonfiguration ein. Im Folgenden wird davon ausgegangen, dass der entsprechende Bezeichner definiert wurde.

Beispiel einer Zugriffsmethode	Eingabedefinition und Rückgabeinhalt
`$data.current.speed`	Eingabe der Grundgeschwindigkeit, gibt `{ value, unit }` zurück.
`$data.current.gForce`	Grundlegende G-Wert-Eingabe, einschließlich `longitudinal`, `lateral`, `combined` und Einheiten.
`$data.current.location`	Grundlegende Standorteingabe, einschließlich Längengrad, Breitengrad und Einheiten.
`$data.current.elapsed`	Grundlegende Eingabe der aufgezeichneten Dauer in Sekunden.
`$data.current.recording`	Grundlegende Datensatzstatuseingabe, die einen booleschen Wert zurückgibt.
`$data.current.coolant`	OBD wird eingegeben und gibt `{ value, unit }` oder `null` zurück, nachdem die Fahrzeugparameter gebunden wurden.
`$data.current.limit`	Die numerische Eingabe gibt direkt eine Zahl zurück.
`$data.current.label`	Die Texteingabe gibt direkt eine Zeichenfolge zurück.
`$data.current.showUnit`	Schalten Sie den Eingang um und geben Sie direkt einen booleschen Wert zurück.
`$data.current.style`	Wählen Sie ein Element aus und geben Sie die ausgewählte Zeichenfolge zurück.

$data.history deckt die letzten 30 Sekunden der aktuellen Fahrt ab, geordnet von alt nach neu, und das Abtastfeld stimmt mit current überein; Die feste Eingabe verwendet die aktuelle Konfiguration. Das Fenster ist möglicherweise leer oder enthält fehlende Tests. Der Wert von OBD kann ein Kartenliteral sein, der Typ sollte zuerst überprüft werden. Null hat eine andere Bedeutung als null. Vollständige Eingabe, Einheiten und Verlaufsregeln.

$env: Anzeigeumgebung

$env beschreibt den Anzeigebereich, in dem sich das aktuelle Instrument befindet. Nachdem Sie die Größe der Karte geändert, das Thema gewechselt oder HUD eingegeben haben, stellt die App eine aktualisierte Umgebung bereit. Berechnungen, die auf diesen Werten basieren, sollten in main() platziert werden.

Feld	Bedeutung und Verwendung
`$env.width`、`$env.height`	Die verfügbare Breite und Höhe des aktuellen Instruments werden in Bildschirmpunkten angegeben. Kann zur Berechnung von Schriftgröße, Durchmesser oder Endpunktkoordinaten verwendet werden.
`$env.foreground`、`$env.accent`	Die Textfarbe und die Akzentfarbe des aktuellen Themas können direkt an `color`, `stroke`, `background` und andere Farbattribute übergeben werden.
`$env.dark`	Gibt an, ob ein dunkles Erscheinungsbild verwendet werden soll. Der Typ ist boolesch.
`$env.mode`	Anzeigemodus, Wert ist `'instruments'` oder `'hud'`.
`$env.speedUnit`	Anzeigeeinheit der aktuellen Geschwindigkeit, Wert ist `'km/h'` oder `'mph'`. Wenn der Messwert eine eigene Einheit hat, wird zuerst der `unit` des Messwerts verwendet.
`$env.language`	Die aktuelle Sprachkennung der App, z. B. `'zh-Hans'`.
`$env.reduceMotion`	Unabhängig davon, ob das System reduzierte dynamische Effekte aktiviert hat, können Sie die Wiederholungsanimation entsprechend anpassen.
`$env.obdDevice`	`{ id, name }` für das aktuell verbundene Gerät oder `null`, wenn kein Gerät bereit ist.

Verwenden Sie beispielsweise Math.min($env.width, $env.height), um den maximalen Durchmesser zu erhalten, der zum Platzieren eines perfekten Kreises geeignet ist, und verwenden Sie $env.foreground, um den Text dem Thema anzupassen. Vollständige Definition der Anzeigeumgebung.

Beispiel: Arbeiten mit Daten- und Anzeigeumgebungen

Wählen Sie die Geschwindigkeit in den Messgeräteinstellungen aus. Das folgende Skript liest die aktuelle Geschwindigkeit, berechnet die Schriftgröße basierend auf der Kartenbreite und -höhe, verwendet Themenfarben und zeigt die von der Anzeige bereitgestellten Einheiten an. Bei fehlender Geschwindigkeit wird eine horizontale Linie angezeigt; eine gültige Null wird als 0 angezeigt.

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>
  );
}

Wenn die Daten aktualisiert werden, wird die neue Geschwindigkeit für den nächsten Anruf verwendet; Wenn sich die Kartengröße oder das Design ändert, werden für Schriftgröße und -farbe die neuen Umgebungswerte verwendet. Wenn Sie Spitzenwerte und andere Zustände auf derselben Reise akkumulieren müssen, können Sie weiterhin $sessionStorage verwenden; Wenn Sie die tatsächliche Eingabe überprüfen müssen, können Sie console.log('speed', speed) verwenden, um das Protokoll während des Debuggens auszugeben.

Bildschirmaktualisierung

Wenn sich die aktuelle Eingabe, Eingabedefinition oder Anzeigeumgebung ändert, stellt CapDrive die neuesten $data und $env bereit, führt die gesamte Datei im neuen lokalen Bereich aus und ruft dann die diesmal definierte main() auf. Berechnungen der obersten Ebene werden ebenfalls erneut ausgeführt und gewöhnliche Variablen werden nicht über die Zeit hinweg beibehalten. Identische Eingaben werden übersprungen; nur die letzte ausstehende Eingabe bleibt bei der Verarbeitung erhalten. Die Wartung des Verlaufsfensters und interne Änderungen der Abtastzeit allein lösen keine Ausführung aus; explizit definierte Zeiteingabeänderungen tun dies.

Es gibt keine feste Häufigkeit für Skripte; Tatsächliche Aktualisierungen hängen von der Eingabe und der Verarbeitungszeit ab. Verwenden Sie $sessionStorage für den Span-Status; Verwenden Sie animations für den Attributübergang, der vom Zeichnungsende unabhängig ausgeführt wird. main() sollte synchron abgeschlossen werden, um Endlosschleifen oder blockierende Wartezeiten zu vermeiden.

Zugehörige Bedienoberflächen

main(): Skripteintrag. Lesen Sie diese Eingabe und geben Sie synchron den zu zeichnenden View, das Array oder den leeren Inhalt zurück.
animations: Legen Sie Übergangsverhalten wie Dauer, Kurve und Wiederholung für die Attributänderungen von View fest.
Color / Gradient: Konstruieren Sie Farbe, HDR-Farbe, linearen Farbverlauf, radialen Farbverlauf und Winkelverlauf.
Importieren und teilen: Verstehen Sie die Konfiguration, Skripte, Ressourcen und Exportmethoden des Instrumentenpakets.

Komponenten zeichnen

Organisieren Sie Bildschirme durch Container und platzieren Sie Text, Grafiken und Datenansichten darin. Im Folgenden werden alle integrierten View nach Zweck aufgelistet; Auf jeder Komponentenseite werden Verwendung, Eigenschaften, Standardverhalten und Kombinationsbeispiele erläutert.

Inhalt

Zeigen Sie Messwerte, Einheiten, Symbole und Bilder an oder verwenden Sie einen betitelten Messgerätinhaltsbereich.

Text

Anzeige von Messwerten, Einheiten oder beschreibendem Text. Schriftart, Schriftgröße, Ausrichtung, Zeilenumbruch und Kürzung können eingestellt werden; Der Inhalt wird einheitlich in eine Zeichenfolge konvertiert und leere Werte werden als leer angezeigt.

Symbol

Verwenden Sie SF Symbols, um Systemsymbole wie Tachometer und Thermometer zu zeichnen. Die Schriftgröße, Schriftstärke und Farbmethode des Symbols kann eingestellt werden. Ob das spezifische Symbol verfügbar ist, hängt vom Gerätesystem ab.

Image

Zeigt ein Bild aus einer Messgerätressource an, z. B. einem Logo, einem dekorativen Hintergrund oder einer Kacheltextur. source Verwenden Sie den Ressourcennamen, um die Skalierungs-, Zuschneide- oder Wiederholungsmethode auf die verfügbaren Größen festzulegen.

CardContent

Bietet eine Instrumentenstruktur mit Titel, rechtem Inhalt und Textkörper. Der Text renderer erhält contentSize abzüglich des Titels und der Ränder, die zum Anordnen von Abbildungen, Grafiken oder Diagrammen verwendet werden können.

Layout

Ordnen Sie mehrere View an, weisen Sie den verbleibenden Platz zu und erstellen Sie horizontale, vertikale, gestapelte und skalierte Layouts.

HStack

Ordnen Sie die Untertitel View von links nach rechts an, geeignet für horizontale Kombinationen von Symbolen und Zahlen, Zahlen und Einheiten usw. spacing legt den angrenzenden Abstand fest, alignment legt die Ober- und Unterseite oder die Ausrichtung der Textgrundlinie innerhalb dieser Zeile fest.

VStack

Ordnen Sie die Untertitel View von oben nach unten an, passend zur vertikalen Kombination von Titeln, Hauptnummern und Einheiten. spacing legt den angrenzenden Abstand fest und alignment legt die linke und rechte Ausrichtung innerhalb dieser Spalte fest.

ZStack

Stapeln Sie mehrere View im gleichen Bereich, geeignet für Hintergrund-, Skalen- und Mittenablesungen. Die untergeordneten Elemente View werden nacheinander gezeichnet und alignment legt ihre gemeinsame Ausrichtungsposition innerhalb des Containers fest.

Spacer

Weisen Sie den verbleibenden Platz im Stapel zu, um Inhalte auf beiden Seiten zu verschieben, oder reservieren Sie elastischen Abstand für Inhalte. minLength legt die Mindestlänge fest, explizit width oder height können die Größe in der entsprechenden Richtung festlegen.

RadialLayout

Verteilen Sie Skalen, Zahlen oder Symbole im Kreis. radius steuert den Abstand von der Mitte zur Layoutmitte von View, und startAngle und sweepAngle steuern den Verteilungsbereich.

RepeatedLayout

Dupliziert regelmäßig ein Muster im Zuschneidefenster, geeignet für die kontinuierliche Bewegung von Maßstäben und Zirkeln. period legt das Wiederholungsintervall fest, value und anchor bestimmen, wo der aktuelle Wert ausgerichtet wird.

Grafik

Zeichnen Sie Striche, Verläufe, Linien und benutzerdefinierte Umrisse und steuern Sie das Erscheinungsbild mit Eigenschaften wie Hintergrund, Strich und Winkel.

Rectangle

Zeichnet ein Rechteck mit optional abgerundeten Ecken zur Verwendung mit Hintergründen, Fortschrittsbalken und Rahmen. background füllt den Innenraum, stroke Striche, lineWidth und strokePosition steuern die Breite und Position des Strichs.

Circle

Zeichnet einen perfekten Kreis oder Bogen innerhalb des verfügbaren Bereichs, geeignet für kreisförmige Fortschritts- und Meterskalen. Der Durchmesser nimmt den kleineren Wert von Breite und Mitte an. startAngle und sweepAngle steuern den Anzeigebereich. Wenn der gesamte Kreis geschlossen ist, kann der Hintergrund ausgefüllt werden.

Ellipse

Zeichnet eine Ellipse oder einen elliptischen Bogen innerhalb einer bestimmten Breite und Höhe. Elliptische Schuppen oder dekorative Umrisse können durch Startwinkel, Schwungwinkel, Füllung und Strich gebildet werden.

Arc

Zeichnen Sie einen elliptischen Bogen entsprechend dem Startwinkel und dem Kehrwinkel, der für Maßstabsbögen und Fortschrittsanzeige geeignet ist. Der Rand wird durch Breite und Höhe bestimmt. Die Breite, der Endpunkt und die Position des Strichs sind konfigurierbar und der Hintergrund kann sich ausfüllen, wenn er vollständig geschlossen ist.

Line

Zeichnet eine gerade Linie zwischen zwei Endpunkten in lokalen Koordinaten. Geeignet für Indikatorlinien, Häkchen und Trennlinien. Sie können Farbe, Breite, Strich- und Endpunktstile festlegen.

Polyline

Zeichnen Sie eine Polylinie, indem Sie eine Reihe von Punkten nacheinander verbinden. closed kann den letzten Punkt und den ersten Punkt verbinden, um eine geschlossene Kontur zu bilden, und ermöglicht das Füllen; Die Koordinaten verwenden die Anzahl der Punkte im aktuellen View.

Path

Erstellen Sie Pfade mit Befehlen wie „Verschieben“, „Linie“, „Quadrat“, „Kubisch“, „Bogen“ und „Schließen“. Geeignet zum Anpassen von Zeigern, Kurven und kombinierten Umrissen sowie zum Festlegen von Füllregeln und Strichen.

Kombinationen und Materialien

Wenden Sie globale Effekte auf kombinierte Inhalte an oder malen Sie eine Oberfläche aus Milchglasmaterial.

Group

Kombinieren Sie mehrere View zu einem Ganzen und wenden Sie dabei gleichmäßig Transparenz, Drehung oder andere Spezialeffekte an. Das untergeordnete Element View folgt den Anordnungsregeln des äußeren Containers und die Spezialeffekte werden auf den gesamten Satz synthetisierter Ergebnisse angewendet.

Material

Zeichnen Sie die Oberfläche aus Milchglasmaterial, das mit Text und Grafiken überlagert werden kann, um einen Inhaltsbereich zu bilden. type unterstützt derzeit mattiert, style steuert die Materialstärke; Der sichtbare Effekt hängt vom Inhalt dahinter ab.

Diagramme und Karten

Stellen Sie Datenreihen in Kurven und Histogrammen dar oder zeigen Sie Standorte und Routen an.

LineChart

Zeichnen Sie die Datenreihe mit den tatsächlichen x/y-Werten als Kurve. Geeignet für Trends wie Geschwindigkeit und Zeit, unterstützt Koordinatenbereiche, Achsen und Beschriftungen; Fehlende y-Werte führen zum Bruch von Liniensegmenten.

BarChart

Stellen Sie jedes Datenelement als Balken dar, der zum Vergleich kategorialer Werte geeignet ist. Es kann horizontal oder vertikal angeordnet werden, numerische Bereiche, Kategoriebeschriftungen und numerische Beschriftungen festlegen und unterstützt positive und negative Werte.

Map

Zeigen Sie Karten, Standorte und Routen im Messgerät an. Kameramitte, Ausrichtung, Zoom und Kartenstil können eingestellt werden, indem path zur Bereitstellung von Routenpunkten verwendet wird; Für die Verfolgung des Standorts des Benutzers sind gültige Positionsdaten erforderlich.

Typ- und Deklarationsdateien

Gängige Typen definieren zentral Strukturen wie Abmessungen, Ränder, Transformationen, Striche, Animationen und Diagrammdaten. Der Editor stellt Typhinweise für dieselbe API bereit, und Deklarationsdateien können auch zur Verwendung durch externe Editoren heruntergeladen werden.

Gemeinsame Typen

capdrive.d.ts