洛汐文档库

外观

system.sensor 补充 API

约 837 字大约 3 分钟

2026-07-15

官网当前只文档化气压计、加速度计和罗盘。目标固件还实现以下传感器接口。

专用订阅接口

订阅方法取消方法回调数据
subscribeProximity(options)unsubscribeProximity(){ distance: number }
subscribeLight(options)unsubscribeLight(){ intensity: number }
subscribeStepCounter(options)unsubscribeStepCounter(){ steps: number }
subscribeHumidity(options)unsubscribeHumidity(){ humidity: number }
subscribeAmbientTemperature(options)unsubscribeAmbientTemperature(){ temperature: number }

回调数据单位没有在 JIDL 中声明。distance、intensity、humidity、temperature 和 steps 都只能确认是 Number；不要未经真机校准就写死 cm、lux、%、°C 等单位标签。

通用 options：

字段类型说明
reservedBoolean默认 false
intervalString仅部分传感器使用；加速度计默认 normal
callbackFunction数据回调
failFunction(message, code)；光照 JIDL 中没有 fail 字段

每种专用订阅都应与对应取消方法成对使用：

sensor.subscribeProximity({
  reserved: false,
  callback: ({ distance }) => console.log(distance),
  fail: (message, code) => console.error(code, message)
})

// 页面销毁时
sensor.unsubscribeProximity()

光照订阅的 JIDL 没有 fail 字段，因此不要依赖失败回调：

sensor.subscribeLight({
  reserved: false,
  callback: ({ intensity }) => console.log(intensity)
})

通用 sensor.subscribe(options)

参数类型必填说明
typeInteger是sensor.DATA_TYPES 中的类型值
reservedBoolean否默认 false
intervalString否默认 low；实现识别 low、mid、high
callbackFunction是传感器数据回调
failFunction否失败回调

返回订阅 ID/状态整数。对应取消方法为：

sensor.unsubscribe(type)

虽然 subscribe() 返回整数，但 unsubscribe() 接收的是传感器 type，不是返回值。固件日志把非法 callback ID、传感器不支持、interval 非法、内存不足和底层 topic 订阅失败区分为不同失败路径。

通用订阅示例：

const type = sensor.DATA_TYPES.HUMIDITY

if (sensor.checkAvailable(type)) {
  const status = sensor.subscribe({
    type,
    reserved: false,
    interval: 'low',
    callback: data => console.log('sensor data', data),
    fail: (message, code) => console.error(code, message)
  })
  console.log('subscribe status:', status)
}

实现识别 low、mid、high。专用加速度计接口的默认 interval 是 normal，不要把两套默认值混为一谈。采样越快通常越耗电。

sensor.getRecentData(options)

获取某传感器最近一次数据。

参数类型必填
typeInteger是
successFunction否；接收 { data, dataType }
failFunction否
completeFunction否
sensor.getRecentData({
  type: sensor.DATA_TYPES.PROXIMITY,
  success: ({ data, dataType }) => {
    console.log(dataType, data)
  },
  fail: (message, code) => console.error(code, message),
  complete: () => console.log('read complete')
})

data 是宽泛对象，结构通常与对应订阅回调一致。最近值可能是缓存，不等同于此刻重新采样。

sensor.checkAvailable(type)

同步返回 Boolean，表示指定传感器类型是否存在。

传入未知编号时应视为 false；固件存在 sensor type is not exist/sensor not exist 错误路径。

sensor.DATA_TYPES

固件成员表至少包含以下名称：

  • ACCELEROMETER
  • COMPASS
  • PROXIMITY
  • STEP_COUNTER
  • BAROMETER
  • HUMIDITY
  • AMBIENT_TEMPERATURE
  • WRIST_LIFT

二进制未保留足够信息来安全恢复所有数值，运行时应读取常量对象而不是硬编码。

if (sensor.checkAvailable(sensor.DATA_TYPES.HUMIDITY)) {
  sensor.subscribeHumidity({
    callback: res => console.log(res.humidity),
    fail: (msg, code) => console.error(code, msg)
  })
}

生命周期和并发

  • 在 onDestroy 中取消所有已建立订阅；
  • 避免同时使用同一种传感器的专用订阅和通用订阅，除非真机确认底层支持多订阅者；
  • reserved 的业务语义没有公开，保持默认 false；
  • 计步器在无对应硬件/系统服务的产品上会明确失败；
  • 腕抬 WRIST_LIFT 只在常量痕迹中确认，没有专用订阅签名，应通过通用 API 探测。

机型可用性

Xiaomi Smart Band 10 ProXiaomi Watch S4 41mm
△△

获取源代码