Справочник API

Пользовательский инструментарий использует main() для возврата дерева View. Здесь мы представляем структуру скрипта, работающий интерфейс и компоненты рисования, а также предоставляем доступ к различным API.

глобальный объект

CapDrive предоставляет следующие глобальные объекты непосредственно в сценарии инструментирования, без необходимости импортировать или создавать их самостоятельно. Их можно прочитать в main() и использовать для получения данных, адаптации к среде отображения, сохранения временного статуса и вывода журналов.

объект	Назначение и общие методы доступа
$data	Данные о вождении. Считайте текущий образец через `$data.current` и считайте образцы за последние 30 секунд этого путешествия через `$data.history`.
$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`	Ввод базового значения G, включая `longitudinal`, `lateral`, `combined` и единицы измерения.
`$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 может быть литералом карты, сначала следует проверить тип. Ноль имеет другое значение, чем 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.

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() должен выполняться синхронно, чтобы избежать непрерывных циклов или ожиданий блокировки.

Сопутствующие рабочие интерфейсы

main(): Запись сценария. Прочитайте этот ввод и синхронно верните View, массив или пустое содержимое для рисования.
animations: Установите поведение перехода, такое как продолжительность, кривая и повторение, для изменений атрибута View.
Color / Gradient: Построить цвет, цвет HDR, линейный градиент, радиальный градиент и угловой градиент.
Импортируйте и делитесь: Изучите конфигурацию, сценарии, ресурсы и методы экспорта пакета инструментов.

Рисование компонентов

Организуйте экраны с помощью контейнеров и размещайте в них текст, графику и представления данных. Ниже перечислены все встроенные View по назначению; на каждой странице компонента объясняются использование, свойства, поведение по умолчанию и примеры комбинаций.

содержание

Отображайте показания, единицы измерения, значки и изображения или используйте область содержимого счетчика с названием.

Text

Отображение показаний, единиц измерения или описательного текста. Можно установить шрифт, размер шрифта, выравнивание, перенос строк и усечение; содержимое равномерно преобразуется в строку, а пустые значения отображаются как пустые.

Symbol

Используйте SF Symbols для рисования системных значков, таких как спидометр, термометр. Можно установить размер шрифта символа, толщину шрифта и метод окраски. Доступность конкретного символа зависит от системы устройства.

Image

Отображает изображение из ресурса датчика, например логотип, декоративный фон или текстуру плитки. source Используйте имя ресурса, чтобы установить метод масштабирования, обрезки или повторения в соответствии с доступными размерами.

CardContent

Предоставляет структуру инструмента с заголовком, нужным содержимым и основным текстом. Текст renderer получит contentSize минус заголовок и поля, которые можно использовать для упорядочения рисунков, графиков или диаграмм.

макет

Расположите несколько View, выделите оставшееся пространство и создайте горизонтальные, вертикальные, сложенные и масштабируемые макеты.

HStack

Расположите субтитры View слева направо, подходящее для горизонтальных комбинаций значков и цифр, чисел и единиц измерения и т. д. spacing задает соседний интервал, alignment задает верх и низ или выравнивание базовой линии текста внутри этой строки.

VStack

Расположите субтитры View сверху вниз, подходящее для вертикального сочетания заголовков, основных цифр и единиц измерения. spacing устанавливает расстояние между соседями, а alignment устанавливает выравнивание по левому и правому краю этого столбца.

ZStack

Уложите несколько View в одну и ту же область, подходящую для фоновых, масштабных и центральных показаний. Дочерние элементы View рисуются последовательно, а alignment устанавливает их общую позицию выравнивания внутри контейнера.

Spacer

Выделите оставшееся пространство в стеке, чтобы разместить контент с обеих сторон, или зарезервируйте гибкое расстояние для контента. 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