Referencia de API

La instrumentación personalizada utiliza main() para devolver el árbol View. Aquí presentamos la estructura del script, la interfaz de ejecución y los componentes de dibujo, y proporcionamos entradas a varias API.

objeto global

CapDrive proporciona los siguientes objetos globales directamente en el script de instrumentación, sin la necesidad de importarlos o crearlos usted mismo. Se pueden leer en main() y usarse para obtener datos, adaptarse al entorno de visualización, guardar estados temporales y registros de salida.

objeto	Finalidad y métodos de acceso comunes
$data	Datos de conducción. Lea la muestra actual hasta `$data.current` y lea las muestras de los últimos 30 segundos de este viaje hasta `$data.history`.
$env	El entorno de visualización del instrumento actual, incluidos los tamaños disponibles, los colores del tema, las unidades, el idioma y el modo de visualización, como `$env.width`, `$env.foreground`.
$sessionStorage	El estado temporal de la instancia del instrumento actual dentro del viaje actual. Utilice `get(key)` para leer y `set(key, value)` para guardar; clara al finalizar el viaje o recargar el instrumento.
console	Registro de guiones. Utilice `console.log(...)`, `console.warn(...)` y otros métodos para generar datos e información de diagnóstico.

$data y $env son actualizados por la aplicación y son entradas de solo lectura. Este valor se lee cada vez que se llama a main(); modificar la copia leída de los datos no cambiará los datos de conducción reales. $ es parte del nombre del objeto, use $env.width directamente y no es necesario escribirlo como una llamada de función.

Definir el contenido del dibujo.

main() en el script del instrumento devuelve la pantalla descrita por JSX. Cada nodo JSX es un View integrado, con atributos que controlan el tamaño, el color y otros comportamientos de dibujo, y relaciones anidadas que forman la imagen final.

El guión completo a continuación dibuja un número y una fila de unidades. VStack organiza dos Text hacia arriba y hacia abajo, spacing establece el espaciado, fontSize establece el tamaño de fuente y el color lo proporciona el entorno de visualización actual.

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

La expresión JavaScript se puede utilizar en el {} de JSX. Reemplace el 78 fijo con el resultado del cálculo y el texto cambiará con la entrada; el resultado del cálculo también se puede pasar a atributos como color, tamaño o ángulo de arco.

$data: datos de conducción

Los campos de $data.current provienen del identificador de entrada de este instrumento. Complete el valor nativo en Ajustes del instrumento → Vinculaciones de entrada o seleccione el parámetro OBD y acceda a la definición de gestión Configuración de parámetros. Lo siguiente supone que se ha definido el identificador correspondiente.

Método de acceso de ejemplo	Definición de entrada y contenido devuelto
`$data.current.speed`	Entrada de velocidad base, devuelve `{ value, unit }`.
`$data.current.gForce`	Entrada de valor G básico, incluidos `longitudinal`, `lateral`, `combined` y unidades.
`$data.current.location`	Entrada de ubicación básica, incluida longitud, latitud y unidades.
`$data.current.elapsed`	Entrada básica de duración grabada, en segundos.
`$data.current.recording`	Entrada básica del estado del registro, que devuelve un valor booleano.
`$data.current.coolant`	Se ingresa OBD y devuelve `{ value, unit }` o `null` después de vincular los parámetros del vehículo.
`$data.current.limit`	La entrada numérica devuelve un número directamente.
`$data.current.label`	La entrada de texto devuelve una cadena directamente.
`$data.current.showUnit`	Cambie la entrada y devuelva directamente un valor booleano.
`$data.current.style`	Seleccione un elemento y devuelva la cadena seleccionada.

$data.history cubre los últimos 30 segundos del viaje actual, ordenados de antiguo a nuevo, y el campo de muestreo es coherente con current; La entrada fija utiliza la configuración actual. La ventana puede estar vacía o contener pruebas faltantes. El valor de OBD puede ser un literal de mapa; primero se debe verificar el tipo. Cero tiene un significado diferente que null. Entrada completa, unidades y reglas históricas..

$env: entorno de visualización

$env describe el área de visualización donde se encuentra el instrumento actual. Después de cambiar el tamaño de la tarjeta, cambiar de tema o ingresar HUD, la aplicación proporciona un entorno actualizado. Los cálculos que se basan en estos valores deben colocarse en main().

Campo	Significado y uso
`$env.width`、`$env.height`	El ancho y alto disponibles del instrumento actual están en puntos de pantalla. Se puede utilizar para calcular el tamaño de fuente, el diámetro o las coordenadas del punto final.
`$env.foreground`、`$env.accent`	El color del texto y el color de acento del tema actual se pueden pasar directamente a `color`, `stroke`, `background` y otros atributos de color.
`$env.dark`	Ya sea para usar apariencia oscura, el tipo es booleano.
`$env.mode`	Modo de visualización, el valor es `'instruments'` o `'hud'`.
`$env.speedUnit`	Unidad de visualización de velocidad actual, el valor es `'km/h'` o `'mph'`. Cuando la lectura tiene su propia unidad, se utiliza primero el `unit` de la lectura.
`$env.language`	Identificador de idioma actual de la aplicación, como `'zh-Hans'`.
`$env.reduceMotion`	Si el sistema tiene habilitados los efectos dinámicos reducidos, puede ajustar la repetición de la animación en consecuencia.
`$env.obdDevice`	`{ id, name }` para el dispositivo actualmente conectado, o `null` si no hay ningún dispositivo listo.

Por ejemplo, use Math.min($env.width, $env.height) para obtener el diámetro máximo adecuado para colocar un círculo perfecto y use $env.foreground para hacer que el texto siga el tema. Definición completa del entorno de visualización.

Ejemplo: trabajar con datos y entornos de visualización

Seleccione la velocidad en la configuración del medidor. El siguiente script lee la velocidad actual, calcula el tamaño de fuente en función del ancho y alto de la tarjeta, utiliza colores del tema y muestra las unidades proporcionadas por la lectura. Se muestra una línea horizontal cuando falta velocidad; un cero válido se muestra como 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>
  );
}

Cuando se actualicen los datos, la nueva velocidad se utilizará para la siguiente llamada; cuando el tamaño de la tarjeta o el tema cambian, el tamaño y el color de la fuente utilizarán los nuevos valores del entorno. Si necesita acumular valores máximos y otros estados en el mismo viaje, puede continuar usando $sessionStorage; Si necesita verificar la entrada real, puede usar console.log('speed', speed) para generar el registro durante la depuración.

Actualización de pantalla

Cuando la entrada actual, la definición de entrada o el entorno de visualización cambian, CapDrive proporciona los últimos $data y $env, ejecuta el archivo completo en el nuevo alcance local y luego llama al main() definido esta vez. Los cálculos de nivel superior también se vuelven a ejecutar y las variables ordinarias no se retienen en el tiempo. Se omiten entradas idénticas; sólo se retiene en el procesamiento la última entrada pendiente. El mantenimiento de la ventana del historial y los cambios internos en el tiempo de muestra por sí solos no desencadenan la ejecución; Los cambios de entrada de tiempo definidos explícitamente sí lo hacen.

No existe una frecuencia fija para los guiones; las actualizaciones reales dependen de la entrada y el tiempo de procesamiento. Utilice $sessionStorage para el estado de extensión; use animations para la transición de atributos, que el final del dibujo ejecuta de forma independiente. main() debe completarse sincrónicamente para evitar bucles continuos o esperas de bloqueo.

Interfaces operativas relacionadas

main(): Entrada de guión. Lea esta entrada y devuelva sincrónicamente el View, matriz o contenido vacío que se dibujará.
animations: Establezca comportamientos de transición como duración, curva y repetición para los cambios de atributos de View.
Color / Gradient: Color de construcción, color HDR, degradado lineal, degradado radial y degradado angular.
Importar y compartir: Comprender la configuración, los scripts, los recursos y los métodos de exportación del paquete de instrumentos.

Dibujar componentes

Organice pantallas a través de contenedores y coloque vistas de texto, gráficos y datos en ellos. A continuación se enumeran todos los View integrados por propósito; La página de cada componente explica el uso, las propiedades, el comportamiento predeterminado y los ejemplos de combinación.

contenido

Muestre lecturas, unidades, íconos e imágenes, o use un área de contenido del medidor titulada.

Text

Muestra lectura, unidades o texto descriptivo. Se puede configurar la fuente, el tamaño de la fuente, la alineación, el ajuste de línea y el truncamiento; el contenido se convierte uniformemente en una cadena y los valores vacíos se muestran como vacíos.

Symbol

Utilice SF Symbols para dibujar iconos del sistema, como velocímetro o termómetro. Se puede configurar el tamaño de fuente del símbolo, el peso de la fuente y el método de coloración. La disponibilidad del símbolo específico depende del sistema del dispositivo.

Image

Muestra una imagen de un recurso de calibre, como un logotipo, un fondo decorativo o una textura de mosaico. source Utilice el nombre del recurso para configurar el método de escalado, recorte o repetición a los tamaños disponibles.

CardContent

Proporciona una estructura de instrumento con título, contenido correcto y texto del cuerpo. El texto renderer obtendrá contentSize menos el título y los márgenes, que se pueden utilizar para organizar figuras, gráficos o tablas.

disposición

Organice varios View, asigne el espacio restante y construya diseños horizontales, verticales, apilados y a escala.

HStack

Organice los subtítulos View de izquierda a derecha, adecuados para combinaciones horizontales de íconos y números, números y unidades, etc. spacing establece el espaciado adyacente, alignment establece la alineación superior e inferior o la línea base del texto dentro de esta línea.

VStack

Organice los subtítulos View de arriba a abajo, adecuados para la combinación vertical de títulos, números principales y unidades. spacing establece el espaciado adyacente y alignment establece la alineación izquierda y derecha dentro de esta columna.

ZStack

Apile varios View en la misma área, adecuados para lecturas de fondo, escala y centro. Los hijos View se dibujan secuencialmente y alignment establece su posición de alineación común dentro del contenedor.

Spacer

Asigne el espacio restante en la pila para empujar el contenido en ambos lados o reserve una distancia elástica para el contenido. minLength establece la longitud mínima, width o height explícitos pueden fijar el tamaño en la dirección correspondiente.

RadialLayout

Distribuya escalas, números o símbolos alrededor de un círculo. radius controla la distancia desde el centro hasta el centro de diseño de View, y startAngle y sweepAngle controlan el rango de distribución.

RepeatedLayout

Duplica periódicamente un patrón en la ventana de recorte, adecuado para escalas y compases en movimiento continuo. period establece el intervalo de repetición, value y anchor determinan dónde está alineado el valor actual.

gráficos

Dibuja marcas, progresiones, líneas y contornos personalizados, y controla la apariencia con propiedades como fondo, trazo y ángulo.

Rectangle

Dibuja un rectángulo con esquinas redondeadas opcionales para usar con fondos, barras de progreso y bordes. background rellena el interior, stroke trazos, lineWidth y strokePosition controlan el ancho y la posición del trazo.

Circle

Dibuja un círculo o arco perfecto dentro del área disponible, adecuado para progreso circular y escalas de metros. El diámetro toma el valor menor de ancho y centro. startAngle y sweepAngle controlan el rango de visualización. Cuando se cierra todo el círculo, se puede rellenar el fondo.

Ellipse

Dibuja una elipse o un arco elíptico dentro de un ancho y alto determinados. Se pueden formar escalas elípticas o contornos decorativos mediante ángulo inicial, ángulo de barrido, relleno y trazo.

Arc

Dibuje un arco elíptico según el ángulo inicial y el ángulo de barrido, adecuado para arcos de escala y visualización de progreso. El borde está determinado por el ancho y el alto. El ancho, el punto final y la posición del trazo son configurables, y se permite que el fondo se llene cuando está completamente cerrado.

Line

Dibuja una línea recta entre dos puntos finales en coordenadas locales. Adecuado para líneas indicadoras, ticks y divisores, puede configurar el color, el ancho, el guión y los estilos de punto final.

Polyline

Dibuja una polilínea conectando un conjunto de puntos en secuencia. closed puede conectar el último punto y el primer punto para formar un contorno cerrado y permite el relleno; las coordenadas utilizan el número de puntos en el View actual.

Path

Construya caminos con comandos como mover, línea, cuadrilátero, cúbico, arco y cerrar. Adecuado para personalizar punteros, curvas y contornos combinados, y establecer reglas de relleno y trazos.

Combinaciones y Materiales

Aplique efectos globales al contenido combinado o pinte una superficie de material de vidrio esmerilado.

Group

Combine varios View en un todo, aplicando uniformemente transparencia, rotación u otros efectos especiales. El niño View sigue las reglas de disposición del contenedor exterior y los efectos especiales se aplican a todo el conjunto de resultados sintetizados.

Material

Dibuje la superficie del material de vidrio esmerilado, que se puede superponer con texto y gráficos para formar un área de contenido. type actualmente admite esmerilado, style controla el espesor del material; el efecto visible depende del contenido detrás de él.

Gráficos y mapas

Trace series de datos en curvas e histogramas, o muestre ubicaciones y rutas.

LineChart

Trace la serie de datos con valores reales de x/y como una curva. Adecuado para tendencias como velocidad y tiempo, admite rangos de coordenadas, ejes y etiquetas; Los valores y faltantes romperán los segmentos de línea.

BarChart

Trace cada elemento de datos como una barra, adecuada para comparar valores categóricos. Se puede organizar horizontal o verticalmente, establecer rangos numéricos, etiquetas de categorías y etiquetas numéricas, y admite valores positivos y negativos.

Map

Muestra mapas, ubicaciones y rutas dentro del medidor. Se pueden configurar el centro de la cámara, la orientación, el zoom y el estilo del mapa, usando path para proporcionar puntos de ruta; Seguir la ubicación del usuario requiere datos de posicionamiento válidos.

Archivos de tipo y declaración

Los tipos comunes definen de forma centralizada estructuras como dimensiones, márgenes, transformaciones, trazos, animaciones y datos de gráficos. El editor proporciona sugerencias de tipo para la misma API y los archivos de declaración también se pueden descargar para que los utilicen editores externos.

Tipos comunes

capdrive.d.ts