Référence API

L'instrumentation personnalisée utilise main() pour renvoyer l'arborescence View. Nous présentons ici la structure du script, l'exécution des composants d'interface et de dessin, et fournissons des accès à diverses API.

objet global

CapDrive fournit les objets globaux suivants directement dans le script d'instrumentation, sans qu'il soit nécessaire de les importer ou de les créer vous-même. Ils peuvent être lus dans main() et utilisés pour obtenir des données, s'adapter à l'environnement d'affichage, enregistrer l'état temporaire et produire des journaux.

objet	Objectif et méthodes d'accès courantes
$data	Données de conduite. Lisez l'échantillon actuel jusqu'à `$data.current` et lisez les échantillons des 30 dernières secondes de ce voyage jusqu'à `$data.history`.
$env	L'environnement d'affichage de l'instrument actuel, y compris les tailles disponibles, les couleurs du thème, les unités, la langue et le mode d'affichage, tel que `$env.width`, `$env.foreground`.
$sessionStorage	L'état temporaire de l'instance d'instrument actuelle dans le voyage en cours. Utilisez `get(key)` pour lire et `set(key, value)` pour enregistrer ; s'efface à la fin du voyage ou lors du rechargement de l'instrument.
console	Journal des scripts. Utilisez `console.log(...)`, `console.warn(...)` et d'autres méthodes pour générer des données et des informations de diagnostic.

$data et $env sont mis à jour par l'application et sont des entrées en lecture seule. Cette valeur est lue à chaque fois que main() est appelé ; la modification de la copie lue des données ne modifiera pas les données de conduite réelles. $ fait partie du nom de l'objet, utilisez directement $env.width et n'a pas besoin d'être écrit comme un appel de fonction.

Définir le contenu du dessin

main() dans le script de l'instrument renvoie l'écran décrit par JSX. Chaque nœud JSX est un View intégré, avec des attributs contrôlant la taille, la couleur et d'autres comportements de dessin, ainsi que des relations imbriquées formant l'image finale.

Le script complet ci-dessous dessine un nombre et une rangée d'unités. VStack organise deux Text de haut en bas, spacing définit l'espacement, fontSize définit la taille de la police et la couleur est fournie par l'environnement d'affichage actuel.

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'expression JavaScript peut être utilisée dans le {} de JSX. Remplacez le 78 fixe par le résultat du calcul, et le texte changera avec l'entrée ; le résultat du calcul peut également être transmis à des attributs tels que la couleur, la taille ou l'angle de l'arc.

$data : données de conduite

Les champs de $data.current proviennent de l'identifiant d'entrée de cet instrument. Remplissez la valeur native dans Réglages de l’instrument → Liaisons d’entrée ou sélectionnez le paramètre OBD et intégrez la définition de gestion Configuration des paramètres. Ce qui suit suppose que l'identifiant correspondant a été défini.

Exemple de méthode d'accès	Définition de l'entrée et contenu renvoyé
`$data.current.speed`	Entrée de vitesse de base, renvoie `{ value, unit }`.
`$data.current.gForce`	Entrée de valeur G de base, y compris `longitudinal`, `lateral`, `combined` et unités.
`$data.current.location`	Saisie de localisation de base, y compris la longitude, la latitude et les unités.
`$data.current.elapsed`	Saisie de la durée enregistrée de base, en secondes.
`$data.current.recording`	Entrée de statut d'enregistrement de base, renvoyant une valeur booléenne.
`$data.current.coolant`	OBD est entré et renvoie `{ value, unit }` ou `null` après avoir lié les paramètres du véhicule.
`$data.current.limit`	La saisie numérique renvoie directement un nombre.
`$data.current.label`	La saisie de texte renvoie directement une chaîne.
`$data.current.showUnit`	Changez d’entrée et renvoyez directement une valeur booléenne.
`$data.current.style`	Sélectionnez un élément et renvoyez la chaîne sélectionnée.

$data.history couvre les 30 dernières secondes du trajet en cours, classés de l'ancien au nouveau, et le champ d'échantillonnage est cohérent avec current ; l'entrée fixe utilise la configuration actuelle. La fenêtre peut être vide ou contenir des tests manquants. La valeur de OBD peut être un littéral de carte, le type doit d'abord être vérifié. Zéro a une signification différente de null. Règles complètes de saisie, d'unités et d'historique.

$env : Environnement d'affichage

$env décrit la zone d'affichage où se trouve l'instrument actuel. Après avoir redimensionné la carte, changé de thème ou saisi HUD, l'application fournit un environnement mis à jour. Les calculs qui reposent sur ces valeurs doivent être placés dans main().

Champ	Signification et utilisation
`$env.width`、`$env.height`	La largeur et la hauteur disponibles de l'instrument actuel sont en points d'écran. Peut être utilisé pour calculer la taille de la police, le diamètre ou les coordonnées du point final.
`$env.foreground`、`$env.accent`	La couleur du texte et la couleur d'accent du thème actuel peuvent être directement transmises à `color`, `stroke`, `background` et à d'autres attributs de couleur.
`$env.dark`	S'il faut utiliser une apparence sombre, le type est booléen.
`$env.mode`	Mode d'affichage, la valeur est `'instruments'` ou `'hud'`.
`$env.speedUnit`	Unité d'affichage de la vitesse actuelle, la valeur est `'km/h'` ou `'mph'`. Lorsque la lecture possède sa propre unité, le `unit` de la lecture est utilisé en premier.
`$env.language`	Identificateur de langue actuel de l'application, tel que `'zh-Hans'`.
`$env.reduceMotion`	Que le système ait activé les effets dynamiques réduits, vous pouvez ajuster l'animation de répétition en conséquence.
`$env.obdDevice`	`{ id, name }` pour l'appareil actuellement connecté, ou `null` si aucun appareil n'est prêt.

Par exemple, utilisez Math.min($env.width, $env.height) pour obtenir le diamètre maximum adapté pour placer un cercle parfait, et utilisez $env.foreground pour que le texte suive le thème. Définition complète de l'environnement d'affichage.

Exemple : Travailler avec des environnements de données et d'affichage

Sélectionnez la vitesse dans les paramètres du compteur. Le script suivant lit la vitesse actuelle, calcule la taille de la police en fonction de la largeur et de la hauteur de la carte, utilise les couleurs du thème et affiche les unités fournies par la lecture. Une ligne horizontale s'affiche lorsque la vitesse est manquante ; un zéro valide est affiché comme 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>
  );
}

Lorsque les données seront mises à jour, la nouvelle vitesse sera utilisée pour le prochain appel ; lorsque la taille ou le thème de la carte change, la taille et la couleur de la police utiliseront les nouvelles valeurs d'environnement. Si vous devez accumuler des valeurs maximales et d'autres états au cours d'un même voyage, vous pouvez continuer à utiliser $sessionStorage ; si vous devez vérifier l'entrée réelle, vous pouvez utiliser console.log('speed', speed) pour afficher le journal pendant le débogage.

Mise à jour de l'écran

Lorsque l'entrée actuelle, la définition d'entrée ou l'environnement d'affichage change, CapDrive fournit les derniers $data et $env, exécute l'intégralité du fichier dans la nouvelle portée locale, puis appelle le main() défini cette fois. Les calculs de niveau supérieur sont également réexécutés et les variables ordinaires ne sont pas conservées au fil du temps. Les entrées identiques sont ignorées ; seule la dernière entrée en attente est conservée dans le traitement. La maintenance de la fenêtre d'historique et les modifications internes de la durée d'échantillonnage ne déclenchent pas à elles seules l'exécution ; Les modifications d'entrée de temps explicitement définies le font.

Il n'y a pas de fréquence fixe pour les scripts ; les mises à jour réelles dépendent du temps de saisie et de traitement. Utilisez $sessionStorage pour l'état d'étendue ; utilisez animations pour la transition d'attribut, qui est exécutée indépendamment par la fin du dessin. main() doit être complété de manière synchrone pour éviter les boucles continues ou les attentes bloquantes.

Interfaces d'exploitation associées

main(): Entrée de script. Lisez cette entrée et renvoyez de manière synchrone le View, le tableau ou le contenu vide à dessiner.
animations: Définissez les comportements de transition tels que la durée, la courbe et la répétition pour les changements d'attribut de View.
Color / Gradient: Couleur de construction, couleur HDR, dégradé linéaire, dégradé radial et dégradé angulaire.
Importer et partager: Comprendre la configuration, les scripts, les ressources et les méthodes d'exportation du package d'instruments.

Dessiner des composants

Organisez les écrans dans des conteneurs et placez-y du texte, des graphiques et des vues de données. Ce qui suit répertorie tous les View intégrés par objectif ; chaque page de composant explique l'utilisation, les propriétés, le comportement par défaut et des exemples de combinaison.

contenu

Affichez les relevés, les unités, les icônes et les images, ou utilisez une zone de contenu du compteur intitulée.

Text

Afficher la lecture, les unités ou le texte descriptif. La police, la taille de la police, l'alignement, le retour à la ligne et la troncature peuvent être définis ; le contenu est uniformément converti en chaîne et les valeurs vides sont affichées comme vides.

Symbol

Utilisez SF Symbols pour dessiner des icônes système, telles que le compteur de vitesse, le thermomètre. La taille de la police du symbole, l’épaisseur de la police et la méthode de coloration peuvent être définies. La disponibilité du symbole spécifique dépend du système de l'appareil.

Image

Affiche une image provenant d'une ressource de jauge, telle qu'un logo, un arrière-plan décoratif ou une texture de carrelage. source Utilisez le nom de la ressource pour définir la méthode de mise à l'échelle, de recadrage ou de répétition selon les tailles disponibles.

CardContent

Fournit une structure d'instrument avec un titre, un contenu droit et un corps de texte. Le texte renderer obtiendra contentSize moins le titre et les marges, qui peuvent être utilisés pour organiser des figures, des graphiques ou des diagrammes.

mise en page

Organisez plusieurs View, allouez l'espace restant et construisez des dispositions horizontales, verticales, empilées et à l'échelle.

HStack

Disposez les sous-titres View de gauche à droite, en fonction des combinaisons horizontales d'icônes et de chiffres, de chiffres et d'unités, etc. spacing définit l'espacement adjacent, alignment définit l'alignement du haut et du bas ou de la ligne de base du texte au sein de cette ligne.

VStack

Disposez les sous-titres View de haut en bas, en fonction de la combinaison verticale des titres, des numéros principaux et des unités. spacing définit l'espacement adjacent et alignment définit l'alignement gauche et droit dans cette colonne.

ZStack

Empilez plusieurs View dans la même zone, adaptés aux lectures d'arrière-plan, d'échelle et de centre. Les enfants View sont dessinés séquentiellement et alignment définit leur position d'alignement commune dans le conteneur.

Spacer

Allouez l'espace restant dans la pile pour pousser le contenu des deux côtés ou réserver une distance élastique pour le contenu. minLength définit la longueur minimale, explicite width ou height peut fixer la taille dans la direction correspondante.

RadialLayout

Répartissez des échelles, des chiffres ou des symboles autour d'un cercle. radius contrôle la distance entre le centre et le centre de mise en page de View, et startAngle et sweepAngle contrôlent la plage de distribution.

RepeatedLayout

Duplique périodiquement un motif dans la fenêtre de recadrage, adapté aux balances et boussoles en mouvement continu. period définit l'intervalle de répétition, value et anchor déterminent où la valeur actuelle est alignée.

graphique

Dessinez des graduations, des progressions, des lignes et des contours personnalisés, et contrôlez l'apparence avec des propriétés telles que l'arrière-plan, le contour et l'angle.

Rectangle

Dessine un rectangle avec des coins arrondis facultatifs à utiliser avec les arrière-plans, les barres de progression et les bordures. background remplit l'intérieur, stroke traits, lineWidth et strokePosition contrôlent la largeur et la position du trait.

Circle

Dessine un cercle ou un arc parfait dans la zone disponible, adapté à la progression circulaire et aux échelles métriques. Le diamètre prend la plus petite valeur de largeur et de centre. startAngle et sweepAngle contrôlent la plage d'affichage. Lorsque tout le cercle est fermé, l’arrière-plan peut être rempli.

Ellipse

Dessine une ellipse ou un arc elliptique dans une largeur et une hauteur données. Des échelles elliptiques ou des contours décoratifs peuvent être formés par l'angle de départ, l'angle de balayage, le remplissage et le trait.

Arc

Dessinez un arc elliptique en fonction de l'angle de départ et de l'angle de balayage, adapté aux arcs d'échelle et à l'affichage de la progression. La bordure est déterminée par la largeur et la hauteur. La largeur, le point final et la position du trait sont configurables, et l'arrière-plan peut se remplir lorsqu'il est complètement fermé.

Line

Trace une ligne droite entre deux points finaux en coordonnées locales. Adapté aux lignes indicatrices, aux graduations et aux séparateurs, vous pouvez définir les styles de couleur, de largeur, de tiret et de point final.

Polyline

Dessinez une polyligne en connectant un ensemble de points en séquence. closed peut relier le dernier point et le premier point pour former un contour fermé, et permet le remplissage ; les coordonnées utilisent le nombre de points dans le View actuel.

Path

Créez des chemins avec des commandes telles que déplacer, ligne, quad, cube, arc et fermer. Convient pour personnaliser les pointeurs, les courbes et les contours combinés, ainsi que pour définir des règles de remplissage et des traits.

Combinaisons et matériaux

Appliquez des effets globaux au contenu combiné ou peignez une surface en verre dépoli.

Group

Combinez plusieurs View en un tout, en appliquant uniformément la transparence, la rotation ou d'autres effets spéciaux. L'enfant View suit les règles d'arrangement du conteneur externe et les effets spéciaux sont appliqués à l'ensemble des résultats synthétisés.

Material

Dessinez la surface d'un matériau en verre dépoli, qui peut être superposée avec du texte et des graphiques pour former une zone de contenu. type prend actuellement en charge le givré, style contrôle l'épaisseur du matériau ; l'effet visible dépend du contenu qui se cache derrière.

Graphiques et cartes

Tracez des séries de données sous forme de courbes et d'histogrammes, ou affichez des emplacements et des itinéraires.

LineChart

Tracez la série de données avec les valeurs réelles x/y sous forme de courbe. Convient aux tendances telles que la vitesse et le temps, prend en charge les plages de coordonnées, les axes et les étiquettes ; les valeurs y manquantes briseront les segments de ligne.

BarChart

Tracez chaque élément de données sous forme de barre, adaptée à la comparaison des valeurs catégorielles. Il peut être disposé horizontalement ou verticalement, définir des plages numériques, des étiquettes de catégorie et des étiquettes numériques, et prend en charge les valeurs positives et négatives.

Map

Affichez des cartes, des emplacements et des itinéraires dans le compteur. Le centre de la caméra, l'orientation, le zoom et le style de carte peuvent être définis, en utilisant path pour fournir des points d'itinéraire ; suivre la position de l'utilisateur nécessite des données de positionnement valides.

Fichiers de types et de déclarations

Les types courants définissent de manière centralisée des structures telles que les dimensions, les marges, les transformations, les traits, les animations et les données de graphique. L'éditeur fournit des indications de type pour la même API, et les fichiers de déclaration peuvent également être téléchargés pour être utilisés par des éditeurs externes.

Types communs

capdrive.d.ts