ZIP 包格式 #

仪表 ZIP 是可编辑的分享格式。常规分享直接从 App 导出即可；本页说明手工制作示例包或检查导入失败时使用的格式。

目录结构 #

instrument.zip
├── manifest.json
├── main.jsx
└── assets/
    └── badge.png

文件直接位于 ZIP 根目录，不要再套一层外部文件夹。没有素材时也要包含空的 assets/ 目录。源码使用 UTF-8，图片引用与素材文件名一致，区分大小写。

清单字段 #

{
  "formatVersion": 1,
  "title": "我的速度表",
  "appVersion": "1.2.1",
  "dataIDs": ["speed"]
}

示例中的版本号仅说明结构，不能当作所有新接口的最低版本承诺。手工打包时应使用实际支持所用功能的版本；App 导出会写入当前 App 版本。

数据声明 #

没有 dataIDs 或数组为空时，仪表不读取任何驾驶数据。基础数据 ID 见 $data 参考，例如 speed、gForce、heading、location、timestamp。

OBD 声明保存来源设备和参数：device/<设备 UUID>/<参数 ID>。脚本仍通过 current.obd[参数 ID] 读取；其他设备的同名参数不会自动接管绑定。

dataIDs 最多 256 项，不能重复；每项不为空、不含换行，最长 256 个 UTF-8 字节。编辑器中的数据选择会生成这些声明，常规使用无需手写。

导入行为 #

1. 读取并验证清单，再比较 App 版本。
2. 当前 App 低于 appVersion 时，停止导入并提示更新；相同或更高版本可继续。
3. 验证源码、ZIP 路径和图片资源，编译源码并生成缩略图。
4. 创建一个新的用户仪表，不覆盖已有的同名作品。

版本比较逐段比较数字，缺失的末尾段视为零，例如 1.2 与 1.2.0 相同；构建号不参与版本门槛比较。ZIP 名称不决定作品名，作品名来自 title。

包含与不包含的内容 #

导出携带源码、图片素材和数据声明。它不包含驾驶路线、传感器历史、单次行程存储、编译产物或缩略图。

素材需要符合 App 的图片限制。路径穿越、符号链接、重复文件名、校验不符和超限资源会导致导入失败。缺少有效清单的旧 ZIP 不会被当作兼容包继续执行。