API 참조

사용자 정의 계측은 main()을 사용하여 View 트리를 반환합니다. 여기서는 스크립트 구조, 실행 인터페이스 및 드로잉 구성 요소를 소개하고 다양한 API에 대한 입구를 제공합니다.

전역 객체

CapDrive는 직접 가져오거나 만들 필요 없이 계측 스크립트에서 직접 다음과 같은 전역 개체를 제공합니다. main()에서 읽을 수 있으며 데이터 획득, 디스플레이 환경 적응, 임시 상태 저장 및 로그 출력에 사용할 수 있습니다.

물체	목적 및 일반적인 접근 방법
$data	운전 데이터. `$data.current`을 통해 현재 샘플을 읽고, `$data.history`을 통해 이번 여행의 마지막 30초 샘플을 읽습니다.
$env	사용 가능한 크기, 테마 색상, 단위, 언어 및 `$env.width`, `$env.foreground`과 같은 디스플레이 모드를 포함한 현재 계측기의 디스플레이 환경입니다.
$sessionStorage	현재 트립 내 현재 계측기 인스턴스의 임시 상태입니다. 읽으려면 `get(key)`을 사용하고 저장하려면 `set(key, value)`을 사용하십시오. 여행을 끝내거나 악기를 다시 로드할 때 지워집니다.
console	스크립트 로그. `console.log(...)`, `console.warn(...)` 및 기타 방법을 사용하여 데이터 및 진단 정보를 출력합니다.

$data 및 $env은 앱에 의해 업데이트되며 읽기 전용 입력입니다. 이 값은 main()이 호출될 때마다 읽혀집니다. 데이터의 읽기 사본을 수정해도 실제 주행 데이터는 변경되지 않습니다. $은 개체 이름의 일부입니다. $env.width을 직접 사용하고 함수 호출로 작성할 필요가 없습니다.

도면 내용 정의

기기 스크립트의 main()은 JSX에 설명된 화면을 반환합니다. 각 JSX 노드는 크기, 색상 및 기타 그리기 동작을 제어하는 속성과 최종 그림을 형성하는 중첩 관계를 포함하는 기본 제공 View입니다.

아래의 전체 스크립트는 숫자와 단위 행을 그립니다. VStack은 두 개의 Text을 위아래로 정렬하고, spacing는 간격을 설정하고, fontSize은 글꼴 크기를 설정하며, 색상은 현재 디스플레이 환경에서 제공됩니다.

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

JavaScript 표현식은 JSX의 {}에서 사용할 수 있습니다. 고정된 78을 계산 결과로 바꾸면 텍스트가 입력에 따라 변경됩니다. 계산 결과는 색상, 크기, 호 각도 등의 속성에 전달될 수도 있습니다.

$data: 운전 데이터

$data.current의 필드는 이 계측기의 입력 식별자에서 나옵니다. 계기 설정 → 입력 바인딩에 기본 값을 입력하거나 OBD 매개변수를 선택하고 매개변수 설정 관리 정의에 맞게 조정합니다. 다음은 해당 식별자가 정의되어 있다고 가정합니다.

액세스 방법 예시	입력 정의 및 반환 콘텐츠
`$data.current.speed`	기본 속도 입력은 `{ value, unit }`을 반환합니다.
`$data.current.gForce`	`longitudinal`, `lateral`, `combined` 및 단위를 포함한 기본 G 값 입력입니다.
`$data.current.location`	경도, 위도, 단위를 포함한 기본 위치 입력입니다.
`$data.current.elapsed`	기본 녹화 기간 입력(초)입니다.
`$data.current.recording`	기본 레코드 상태 입력, 부울 값을 반환합니다.
`$data.current.coolant`	OBD이 입력되고 차량 매개변수를 바인딩한 후 `{ value, unit }` 또는 `null`를 반환합니다.
`$data.current.limit`	숫자 입력은 숫자를 직접 반환합니다.
`$data.current.label`	텍스트 입력은 문자열을 직접 반환합니다.
`$data.current.showUnit`	입력을 전환하고 부울 값을 직접 반환합니다.
`$data.current.style`	항목을 선택하고 선택한 문자열을 반환합니다.

$data.history은 현재 여행의 마지막 30초를 다루며 이전부터 새로운 순서로 정렬되며 샘플링 필드는 current과 일치합니다. 고정 입력은 현재 구성을 사용합니다. 창이 비어 있거나 누락된 테스트가 있을 수 있습니다. OBD의 값은 맵 리터럴일 수 있으며 유형을 먼저 확인해야 합니다. 0은 null과 다른 의미를 갖습니다. 전체 입력, 단위 및 내역 규칙.

$env: 디스플레이 환경

$env은 현재 기기가 위치한 디스플레이 영역을 설명합니다. 카드 크기 조정, 테마 전환 또는 HUD 입력 후 앱은 업데이트된 환경을 제공합니다. 이러한 값을 사용하는 계산은 main()에 배치되어야 합니다.

필드	의미와 사용법
`$env.width`、`$env.height`	현재 기기의 사용 가능한 너비와 높이는 화면 포인트 단위입니다. 글꼴 크기, 직경 또는 끝점 좌표를 계산하는 데 사용할 수 있습니다.
`$env.foreground`、`$env.accent`	현재 테마의 텍스트 색상과 강조 색상은 `color`, `stroke`, `background` 및 기타 색상 속성에 직접 전달될 수 있습니다.
`$env.dark`	어두운 모양을 사용할지 여부는 부울 유형입니다.
`$env.mode`	디스플레이 모드, 값은 `'instruments'` 또는 `'hud'`입니다.
`$env.speedUnit`	현재 속도 표시 단위, 값은 `'km/h'` 또는 `'mph'`입니다. 판독값에 자체 단위가 있는 경우 판독값의 `unit`이 먼저 사용됩니다.
`$env.language`	`'zh-Hans'`과 같은 앱의 현재 언어 식별자입니다.
`$env.reduceMotion`	시스템에서 동적 효과 감소를 활성화했는지 여부에 따라 반복 애니메이션을 조정할 수 있습니다.
`$env.obdDevice`	현재 연결된 장치의 경우 `{ id, name }`, 준비된 장치가 없는 경우 `null`입니다.

예를 들어 완벽한 원을 배치하는 데 적합한 최대 직경을 얻으려면 Math.min($env.width, $env.height)을 사용하고, 주제를 따르도록 텍스트를 만들려면 $env.foreground을 사용합니다. 전체 디스플레이 환경 정의.

예: 데이터 및 표시 환경 작업

미터 설정에서 속도를 선택하세요. 다음 스크립트는 현재 속도를 읽고, 카드 너비와 높이를 기준으로 글꼴 크기를 계산하고, 테마 색상을 사용하고, 판독값에서 제공하는 단위를 표시합니다. 속도가 누락되면 수평선이 표시됩니다. 유효한 0은 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>
  );
}

데이터가 업데이트되면 다음 호출에 새로운 속도가 사용됩니다. 카드 크기나 테마가 변경되면 글꼴 크기와 색상이 새로운 환경 값을 사용합니다. 동일한 여행에서 최고치 및 기타 상태를 누적해야 하는 경우 $sessionStorage을(를) 계속 사용할 수 있습니다. 실제 입력을 확인해야 하는 경우 console.log('speed', speed)을 사용하여 디버깅 중에 로그를 출력할 수 있습니다.

화면 업데이트

현재 입력, 입력 정의 또는 디스플레이 환경이 변경되면 CapDrive는 최신 $data 및 $env을 제공하고 새로운 로컬 범위에서 전체 파일을 실행한 다음 이번에 정의된 main()를 호출합니다. 최상위 수준 계산도 다시 실행되며 일반 변수는 시간이 지나도 유지되지 않습니다. 동일한 입력은 건너뜁니다. 최신 보류 입력만 처리 중에 유지됩니다. 기록 창 유지 관리 및 내부 샘플 시간 변경만으로는 실행이 트리거되지 않습니다. 명시적으로 정의된 시간 입력 변경 사항이 적용됩니다.

스크립트에는 고정된 빈도가 없습니다. 실제 업데이트는 입력 및 처리 시간에 따라 달라집니다. 범위 상태에는 $sessionStorage을 사용하십시오. 도면 끝에서 독립적으로 실행되는 속성 전환에 animations을 사용합니다. 연속 루프나 대기 차단을 방지하려면 main()을 동기식으로 완료해야 합니다.

구성 요소 그리기

컨테이너를 통해 화면을 구성하고 텍스트, 그래픽 및 데이터 보기를 컨테이너에 배치합니다. 다음은 목적에 따라 내장된 모든 View을 나열합니다. 각 구성 요소 페이지에는 사용법, 속성, 기본 동작 및 조합 예가 설명되어 있습니다.

콘텐츠

판독값, 단위, 아이콘 및 그림을 표시하거나 제목이 붙은 미터 콘텐츠 영역을 사용합니다.

Text

판독값, 단위 또는 설명 텍스트를 표시합니다. 글꼴, 글꼴 크기, 정렬, 줄 바꿈 및 잘림을 설정할 수 있습니다. 내용은 문자열로 균일하게 변환되며, 빈 값은 빈 것으로 표시됩니다.

Symbol

속도계, 온도계와 같은 시스템 아이콘을 그리려면 SF Symbols을 사용하세요. 기호 글꼴 크기, 글꼴 두께 및 색상 지정 방법을 설정할 수 있습니다. 특정 기호의 사용 가능 여부는 장치 시스템에 따라 다릅니다.

Image

로고, 장식 배경, 타일 텍스처 등 게이지 리소스의 이미지를 표시합니다. source 리소스 이름을 사용하여 크기 조정, 자르기 또는 반복 방법을 사용 가능한 크기로 설정합니다.

CardContent

제목, 올바른 내용, 본문 텍스트로 악기 구조를 제공합니다. renderer 텍스트는 그림, 그래프 또는 차트를 정렬하는 데 사용할 수 있는 제목과 여백을 제외한 contentSize을 가져옵니다.

공들여 나열한 것

여러 개의 View을 배열하고, 남은 공간을 할당하고, 수평, 수직, 스택 및 크기 조정 레이아웃을 구성합니다.

HStack

아이콘과 숫자, 숫자와 단위 등의 가로 조합에 적합하도록 자막 View을 왼쪽에서 오른쪽으로 정렬합니다. spacing은 인접 간격을 설정하고, alignment는 이 줄 내에서 위쪽 및 아래쪽 또는 텍스트 기준선 정렬을 설정합니다.

VStack

제목, 주요 번호, 단위의 수직 조합에 맞게 자막 View을 위에서 아래로 배열합니다. spacing은 인접 간격을 설정하고 alignment는 이 열 내에서 왼쪽 및 오른쪽 정렬을 설정합니다.

ZStack

배경, 규모 및 중앙 판독에 적합한 동일한 영역에 여러 개의 View을 쌓습니다. 자식 View은 순차적으로 그려지고 alignment는 컨테이너 내에서 공통 정렬 위치를 설정합니다.

Spacer

Stack에 남은 공간을 할당하여 콘텐츠를 양쪽으로 밀어 넣거나 콘텐츠에 대한 탄력적 거리를 확보합니다. minLength은 최소 길이를 설정하며, 명시적인 width 또는 height는 해당 방향의 크기를 고정할 수 있습니다.

RadialLayout

원 주위에 눈금, 숫자 또는 기호를 배포합니다. radius은 View의 중심에서 레이아웃 중심까지의 거리를 제어하고 startAngle 및 sweepAngle은 배포 범위를 제어합니다.

RepeatedLayout

자르기 창에 패턴을 주기적으로 복제합니다. 지속적으로 움직이는 저울과 나침반에 적합합니다. period은 반복 간격을 설정하고, value 및 anchor는 현재 값이 정렬되는 위치를 결정합니다.

제도법

눈금, 진행, 선 및 사용자 정의 윤곽선을 그리고 배경, 획, 각도와 같은 속성을 사용하여 모양을 제어합니다.

Rectangle

배경, 진행률 표시줄 및 테두리와 함께 사용하기 위해 선택적으로 둥근 모서리가 있는 직사각형을 그립니다. background은 내부를 채우고, stroke 획은 lineWidth 및 strokePosition은 획의 너비와 위치를 제어합니다.

Circle

원형 진행 및 미터 눈금에 적합한 사용 가능한 영역 내에 완벽한 원이나 호를 그립니다. 직경은 너비와 중심 중 작은 값을 취합니다. startAngle 및 sweepAngle은 표시 범위를 제어합니다. 원 전체를 닫으면 배경을 채울 수 있습니다.

Ellipse

지정된 너비와 높이 내에서 타원 또는 타원형 호를 그립니다. 시작 각도, 스윕 각도, 채우기 및 획을 통해 타원형 눈금 또는 장식 윤곽선을 형성할 수 있습니다.

Arc

시작 각도와 스위핑 각도에 따라 타원형 호를 그립니다. 이는 축척 호 및 진행률 표시에 적합합니다. 테두리는 너비와 높이에 따라 결정됩니다. 획의 너비, 끝점 및 위치를 구성할 수 있으며 완전히 닫히면 배경이 채워질 수 있습니다.

Line

로컬 좌표에서 두 끝점 사이에 직선을 그립니다. 표시선, 눈금 및 구분선에 적합하며 색상, 너비, 대시 및 끝점 스타일을 설정할 수 있습니다.

Polyline

일련의 점을 순서대로 연결하여 폴리라인을 그립니다. closed은 마지막 점과 첫 번째 점을 연결하여 닫힌 윤곽선을 형성하고 채우기를 허용합니다. 좌표는 현재 View의 포인트 수를 사용합니다.

Path

이동, 선, 쿼드, 큐빅, 호, 닫기 등의 명령을 사용하여 경로를 만듭니다. 포인터, 곡선 및 결합된 윤곽선을 사용자 정의하고 채우기 규칙 및 획을 설정하는 데 적합합니다.

조합 및 재료

결합된 콘텐츠에 전역 효과를 적용하거나 반투명 유리 재질 표면을 칠합니다.

Group

여러 개의 View을 전체로 결합하여 투명도, 회전 또는 기타 특수 효과를 균일하게 적용합니다. 하위 View은 외부 컨테이너의 배열 규칙을 따르며, 합성 결과 전체 집합에 특수 효과가 적용됩니다.

Material

콘텐츠 영역을 형성하기 위해 텍스트 및 그래픽과 겹쳐질 수 있는 반투명 유리 재질의 표면을 그립니다. type은 현재 반투명을 지원하고 style은 재료 두께를 제어합니다. 눈에 보이는 효과는 그 뒤에 있는 콘텐츠에 따라 달라집니다.

차트와 지도

데이터 계열을 곡선과 히스토그램으로 표시하거나 위치와 경로를 표시합니다.

LineChart

실제 x/y 값을 사용하여 데이터 시리즈를 곡선으로 그립니다. 속도 및 시간과 같은 추세에 적합하며 좌표 범위, 축 및 레이블을 지원합니다. y 값이 누락되면 선분이 끊어집니다.

BarChart

각 데이터 항목을 막대로 표시하여 범주형 값을 비교하는 데 적합합니다. 가로 또는 세로로 배열할 수 있고, 숫자 범위, 카테고리 라벨, 숫자 라벨을 설정할 수 있으며, 양수 및 음수 값을 지원합니다.

Map

미터 내에 지도, 위치 및 경로를 표시합니다. 경로 지점을 제공하기 위해 path을 사용하여 카메라 중심, 방향, 확대/축소 및 지도 스타일을 설정할 수 있습니다. 사용자의 위치를 추적하려면 유효한 위치 데이터가 필요합니다.

유형 및 선언 파일

일반 유형은 치수, 여백, 변형, 획, 애니메이션 및 차트 데이터와 같은 구조를 중앙에서 정의합니다. 편집기는 동일한 API에 대한 유형 힌트를 제공하며 외부 편집기에서 사용하기 위해 선언 파일을 다운로드할 수도 있습니다.

공통 유형

capdrive.d.ts