Referência da API

A instrumentação personalizada usa main() para retornar a árvore View. Aqui apresentamos a estrutura do script, a interface de execução e os componentes de desenho, e fornecemos entradas para várias APIs.

objeto global

CapDrive fornece os seguintes objetos globais diretamente no script de instrumentação, sem a necessidade de importá-los ou criá-los você mesmo. Eles podem ser lidos em main() e usados para obter dados, adaptar-se ao ambiente de exibição, salvar status temporário e gerar logs.

objeto	Finalidade e métodos de acesso comuns
$data	Dados de condução. Leia a amostra atual através de `$data.current` e leia as amostras dos últimos 30 segundos desta viagem através de `$data.history`.
$env	O ambiente de exibição do instrumento atual, incluindo tamanhos disponíveis, cores de tema, unidades, idioma e modo de exibição, como `$env.width`, `$env.foreground`.
$sessionStorage	O estado temporário da instância atual do instrumento na viagem atual. Use `get(key)` para ler e `set(key, value)` para salvar; apagado ao encerrar a viagem ou recarregar o instrumento.
console	Registro de script. Use `console.log(...)`, `console.warn(...)` e outros métodos para gerar dados e informações de diagnóstico.

$data e $env são atualizados pelo aplicativo e são entradas somente leitura. Este valor é lido cada vez que main() é chamado; modificar a cópia lida dos dados não alterará os dados de condução reais. $ faz parte do nome do objeto, usa $env.width diretamente e não precisa ser escrito como uma chamada de função.

Definir conteúdo do desenho

main() no script do instrumento retorna a tela descrita por JSX. Cada nó JSX é um View integrado, com atributos controlando tamanho, cor e outros comportamentos de desenho, e relacionamentos aninhados formando a imagem final.

O script completo abaixo desenha um número e uma linha de unidades. VStack organiza dois Text para cima e para baixo, spacing define o espaçamento, fontSize define o tamanho da fonte e a cor é fornecida pelo ambiente de exibição atual.

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

A expressão JavaScript pode ser usada em {} de JSX. Substitua o 78 fixo pelo resultado do cálculo e o texto mudará com a entrada; o resultado do cálculo também pode ser passado para atributos como cor, tamanho ou ângulo do arco.

$data: dados de condução

Os campos de $data.current vêm do identificador de entrada deste instrumento. Preencha o valor nativo em Ajustes do instrumento → Vínculos de entrada ou selecione o parâmetro OBD e insira a definição de gerenciamento Configuração de parâmetros. O seguinte pressupõe que o identificador correspondente foi definido.

Exemplo de método de acesso	Definição de entrada e conteúdo de retorno
`$data.current.speed`	Entrada de velocidade base, retorna `{ value, unit }`.
`$data.current.gForce`	Entrada de valor G básico, incluindo `longitudinal`, `lateral`, `combined` e unidades.
`$data.current.location`	Entrada básica de localização, incluindo longitude, latitude e unidades.
`$data.current.elapsed`	Entrada básica de duração gravada, em segundos.
`$data.current.recording`	Entrada básica de status de registro, retornando um valor booleano.
`$data.current.coolant`	OBD é inserido e retorna `{ value, unit }` ou `null` após vincular os parâmetros do veículo.
`$data.current.limit`	A entrada numérica retorna um número diretamente.
`$data.current.label`	A entrada de texto retorna uma string diretamente.
`$data.current.showUnit`	Alterne a entrada e retorne diretamente um valor booleano.
`$data.current.style`	Selecione um item e retorne a string selecionada.

$data.history cobre os últimos 30 segundos da viagem atual, organizados do antigo para o novo, e o campo de amostragem é consistente com current; entrada fixa usa a configuração atual. A janela pode estar vazia ou conter testes ausentes. O valor de OBD pode ser um mapa literal, o tipo deve ser verificado primeiro. Zero tem um significado diferente de null. Regras completas de entrada, unidades e histórico.

$env: Ambiente de exibição

$env descreve a área de exibição onde o instrumento atual está localizado. Após redimensionar o cartão, trocar de tema ou inserir HUD, o App disponibiliza um ambiente atualizado. Os cálculos que dependem desses valores devem ser colocados em main().

Campo	Significado e uso
`$env.width`、`$env.height`	A largura e a altura disponíveis do instrumento atual estão em pontos da tela. Pode ser usado para calcular o tamanho da fonte, o diâmetro ou as coordenadas do ponto final.
`$env.foreground`、`$env.accent`	A cor do texto e a cor de destaque do tema atual podem ser passadas diretamente para `color`, `stroke`, `background` e outros atributos de cor.
`$env.dark`	Se deve usar aparência escura, o tipo é booleano.
`$env.mode`	Modo de exibição, o valor é `'instruments'` ou `'hud'`.
`$env.speedUnit`	Unidade de exibição de velocidade atual, o valor é `'km/h'` ou `'mph'`. Quando a leitura possui unidade própria, o `unit` da leitura é utilizado primeiro.
`$env.language`	O identificador de idioma atual do aplicativo, como `'zh-Hans'`.
`$env.reduceMotion`	Quer o sistema tenha efeitos dinâmicos reduzidos ativados, você pode ajustar a animação repetida de acordo.
`$env.obdDevice`	`{ id, name }` para o dispositivo atualmente conectado ou `null` se nenhum dispositivo estiver pronto.

Por exemplo, use Math.min($env.width, $env.height) para obter o diâmetro máximo adequado para colocar um círculo perfeito e use $env.foreground para fazer o texto seguir o tema. Definição completa do ambiente de exibição.

Exemplo: Trabalhando com dados e ambientes de exibição

Selecione a velocidade nas configurações do medidor. O script a seguir lê a velocidade atual, calcula o tamanho da fonte com base na largura e altura do cartão, usa cores de tema e exibe as unidades fornecidas pela leitura. Uma linha horizontal é exibida quando falta velocidade; um zero válido é exibido 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>
  );
}

Quando os dados forem atualizados, a nova velocidade será utilizada na próxima ligação; quando o tamanho do cartão ou o tema for alterado, o tamanho e a cor da fonte usarão os novos valores de ambiente. Caso precise acumular valores de pico e outros estados na mesma viagem, você pode continuar usando $sessionStorage; se precisar verificar a entrada real, você pode usar console.log('speed', speed) para gerar o log durante a depuração.

Atualização de tela

Quando a entrada atual, a definição de entrada ou o ambiente de exibição mudam, o CapDrive fornece o $data e o $env mais recentes, executa o arquivo inteiro no novo escopo local e, em seguida, chama o main() definido desta vez. Os cálculos de nível superior também são reexecutados e as variáveis comuns não são retidas ao longo dos tempos. Entradas idênticas são ignoradas; apenas a última entrada pendente é retida no processamento. A manutenção da janela do histórico e as alterações internas do tempo de amostragem por si só não acionam a execução; alterações de entrada de tempo explicitamente definidas sim.

Não existe uma frequência fixa para scripts; as atualizações reais dependem da entrada e do tempo de processamento. Use $sessionStorage para estado span; use animations para transição de atributos, que é executada independentemente no final do desenho. main() deve ser concluído de forma síncrona para evitar loops contínuos ou esperas de bloqueio.

Interfaces operacionais relacionadas

main(): Entrada de roteiro. Leia esta entrada e retorne de forma síncrona o View, array ou conteúdo vazio a ser desenhado.
animations: Defina comportamentos de transição, como duração, curva e repetição para as alterações de atributos de View.
Color / Gradient: Cor de construção, cor HDR, gradiente linear, gradiente radial e gradiente angular.
Importe e compartilhe: Entenda a configuração, os scripts, os recursos e os métodos de exportação do pacote de instrumentos.

Desenhar componentes

Organize telas por meio de contêineres e coloque texto, gráficos e visualizações de dados neles. A seguir lista todos os View integrados por finalidade; cada página de componente explica uso, propriedades, comportamento padrão e exemplos de combinação.

contente

Exiba leituras, unidades, ícones e imagens ou use uma área de conteúdo do medidor intitulada.

Text

Exibir leitura, unidades ou texto descritivo. A fonte, tamanho da fonte, alinhamento, quebra de linha e truncamento podem ser definidos; o conteúdo é convertido uniformemente em uma string e os valores vazios são exibidos como vazios.

Symbol

Use SF Symbols para desenhar ícones do sistema, como velocímetro, termômetro. O tamanho da fonte do símbolo, a espessura da fonte e o método de coloração podem ser definidos. A disponibilidade do símbolo específico depende do sistema do dispositivo.

Image

Exibe uma imagem de um recurso de medidor, como um logotipo, um plano de fundo decorativo ou uma textura de bloco. source Use o nome do recurso para definir o método de dimensionamento, corte ou repetição para os tamanhos disponíveis.

CardContent

Fornece uma estrutura de instrumento com título, conteúdo correto e corpo do texto. O texto renderer receberá contentSize menos o título e as margens, que podem ser usadas para organizar figuras, gráficos ou tabelas.

layout

Organize vários View, aloque o espaço restante e construa layouts horizontais, verticais, empilhados e em escala.

HStack

Organize as legendas View da esquerda para a direita, adequadas para combinações horizontais de ícones e números, números e unidades, etc. spacing define o espaçamento adjacente, alignment define o alinhamento superior e inferior ou da linha de base do texto dentro desta linha.

VStack

Organize as legendas View de cima para baixo, adequadas à combinação vertical de títulos, números principais e unidades. spacing define o espaçamento adjacente e alignment define o alinhamento à esquerda e à direita nesta coluna.

ZStack

Empilhe vários View na mesma área, adequado para leituras de fundo, escala e centro. Os filhos View são desenhados sequencialmente e alignment define sua posição de alinhamento comum dentro do contêiner.

Spacer

Aloque o espaço restante na pilha para enviar conteúdo em ambos os lados ou reserve uma distância elástica para o conteúdo. minLength define o comprimento mínimo, width ou height explícito pode fixar o tamanho na direção correspondente.

RadialLayout

Distribua escalas, números ou símbolos em torno de um círculo. radius controla a distância do centro ao centro do layout de View, e startAngle e sweepAngle controlam o intervalo de distribuição.

RepeatedLayout

Duplica periodicamente um padrão na janela de corte, adequado para escalas e bússolas em movimento contínuo. period define o intervalo de repetição, value e anchor determinam onde o valor atual está alinhado.

gráficos

Desenhe marcações, progressões, linhas e contornos personalizados e controle a aparência com propriedades como plano de fundo, traço e ângulo.

Rectangle

Desenha um retângulo com cantos arredondados opcionais para uso com planos de fundo, barras de progresso e bordas. background preenche o interior, stroke traços, lineWidth e strokePosition controlam a largura e a posição do traço.

Circle

Desenha um círculo ou arco perfeito dentro da área disponível, adequado para progresso circular e escalas métricas. O diâmetro assume o menor valor de largura e centro. startAngle e sweepAngle controlam o intervalo de exibição. Quando todo o círculo estiver fechado, o fundo poderá ser preenchido.

Ellipse

Desenha uma elipse ou arco elíptico dentro de uma determinada largura e altura. Escalas elípticas ou contornos decorativos podem ser formados pelo ângulo inicial, ângulo de varredura, preenchimento e traço.

Arc

Desenhe um arco elíptico de acordo com o ângulo inicial e o ângulo de varredura, adequado para arcos de escala e exibição de progresso. A borda é determinada pela largura e altura. A largura, o ponto final e a posição do traço são configuráveis, e o fundo pode ser preenchido quando totalmente fechado.

Line

Desenha uma linha reta entre dois pontos finais em coordenadas locais. Adequado para linhas indicadoras, marcas e divisores, você pode definir os estilos de cor, largura, traço e ponto final.

Polyline

Desenhe uma polilinha conectando um conjunto de pontos em sequência. closed pode conectar o último ponto e o primeiro ponto para formar um contorno fechado e permite o preenchimento; as coordenadas usam o número de pontos no View atual.

Path

Crie caminhos com comandos como mover, linha, quad, cúbico, arco e fechar. Adequado para personalizar ponteiros, curvas e contornos combinados e definir regras de preenchimento e traços.

Combinações e Materiais

Aplique efeitos globais ao conteúdo combinado ou pinte uma superfície de vidro fosco.

Group

Combine vários View em um todo, aplicando uniformemente transparência, rotação ou outros efeitos especiais. O filho View segue as regras de organização do contêiner externo e os efeitos especiais são aplicados a todo o conjunto de resultados sintetizados.

Material

Desenhe a superfície do vidro fosco, que pode ser sobreposta com texto e gráficos para formar uma área de conteúdo. type atualmente suporta fosco, style controla a espessura do material; o efeito visível depende do conteúdo por trás dele.

Gráficos e mapas

Plote séries de dados em curvas e histogramas ou exiba locais e rotas.

LineChart

Trace a série de dados com valores reais de x/y como uma curva. Adequado para tendências como velocidade e tempo, suporta faixas de coordenadas, eixos e rótulos; valores y ausentes quebrarão os segmentos de linha.

BarChart

Plote cada item de dados como uma barra, adequada para comparar valores categóricos. Ele pode ser organizado horizontalmente ou verticalmente, definir intervalos numéricos, rótulos de categorias e rótulos numéricos e suportar valores positivos e negativos.

Map

Exiba mapas, locais e rotas dentro do medidor. O centro da câmera, a orientação, o zoom e o estilo do mapa podem ser definidos, usando path para fornecer pontos de rota; seguir a localização do usuário requer dados de posicionamento válidos.

Arquivos de tipo e declaração

Tipos comuns definem centralmente estruturas como dimensões, margens, transformações, traços, animações e dados de gráfico. O editor fornece dicas de tipo para a mesma API, e arquivos de declaração também podem ser baixados para uso por editores externos.

Tipos comuns

capdrive.d.ts