自定义仪表

外观

JavaScript 与 JSX ​

仪表源码使用 JavaScript 和 JSX。程序必须提供一个同步的 main() 函数，返回组件、组件数组、文本或 null。CapDrive 在数据或环境更新时调用它。

最小结构 ​

jsx
function main() {
  return <Text color={$env.foreground}>Hello, CapDrive</Text>;
}

Text 等大写标签是 CapDrive 的原生绘图组件。<div>、<span>、CSS 类名、浏览器事件处理器和网页样式不会在这里工作。

表达式与属性 ​

写法含义
title="速度"字符串属性
width={120}数字属性，逻辑点
clipped={true}布尔属性
color={$env.accent}从环境读取的值
{speed === null ? '—' : Math.round(speed)}JSX 内的 JavaScript 表达式
{condition ? <Text>可用</Text> : null}条件显示

JSX 属性区分大小写。fontSize 与 fontsize 不是同一个属性，fulled 是 CardContent 的实际属性名，不是 filled 或 full。

数组与稳定 key ​

jsx
function main() {
  const labels = ['N', 'E', 'S', 'W'];
  return <HStack spacing={12}>
    {labels.map(label => <Text key={label} color={$env.foreground}>{label}</Text>)}
  </HStack>;
}

同一组兄弟节点的 key 必须唯一，可以是字符串或安全整数。建议用业务含义稳定的标识，不要在每次更新时调用随机数生成 key。稳定的组件与 key 有助于保持动画和原生地图的连续性。

自定义函数组件 ​

jsx
function Value({label, value, unit}) {
  return <VStack spacing={4}>
    <Text fontSize={12} color={$env.accent}>{label}</Text>
    <Text fontSize={32} color={$env.foreground}>{value}</Text>
    <Text fontSize={10} color={$env.foreground}>{unit}</Text>
  </VStack>;
}
function main() {
  const speed = $data.current.speed;
  return <Value label="速度" value={speed === null ? '—' : Math.round(speed)}
    unit={$data.current.speedUnit}/>;
}

组件是普通同步函数，接收属性对象并返回绘图内容。它不是 React 组件，不能使用 useState、useEffect 或 React 生命周期。

可以使用哪些语言能力 ​

源码按 ECMAScript 2022 脚本解析，支持普通函数、箭头函数、数组、对象、解构、可选链、空值合并和常见标准库，例如 Math、JSON、Number.toFixed()。

不使用 import / export 模块语法。main() 不能返回 Promise，也不要用 async main()。仪表不提供 fetch、DOM、浏览器存储、文件访问或修改 App 的接口。

全局变量与单次行程存储 ​

可以把固定的颜色、刻度数组和辅助函数放在 main() 外。但不要把运行时全局变量当作可靠的行程记录：重新加载代码或重新挂载可能重新初始化执行环境。

需要保存“这次行程的峰值”等数据时，使用明确按行程划分的 $sessionStorage。调用 set() 不会主动触发一次渲染。

调试输出 ​

console.log、info、warn、error、debug 可用于调试。预览中可以查看这些输出；仪表盘日志需要在相应日志入口主动开启。不要在正式作品中无条件输出整份历史数组。