# 传感器 sensor

# 接口声明

{ "name": "system.sensor" }
1

# 导入模块

import sensor from '@system.sensor' 或 const sensor = require('@system.sensor')
1

# 接口定义

# sensor.subscribeAccelerometer(OBJECT)

监听重力感应数据。如果多次调用，仅最后一次调用生效

# 参数：

参数名 类型 必填 说明
reserved Boolean 否 是否持久化订阅，默认为 false。机制：设置为 true，页面跳转，不会自动取消订阅，需手动取消订阅
interval String 否 监听加速度数据回调函数的执行频率，默认normal
callback Function 是 重力感应数据变化后会回调此函数。

interval 的合法值：

值 说明
game 适用于更新游戏的回调频率，在 20ms/次 左右
ui 适用于更新 UI 的回调频率，在 60ms/次 左右
normal 普通的回调频率，在 200ms/次 左右
# callback 返回值：
参数名 类型 说明
x Integer x 轴加速度
y Integer y 轴加速度
z Integer z 轴加速度

# 示例：

sensor.subscribeAccelerometer({
  callback: function(ret) {
    console.log(`handling callback, x = ${ret.x}, y = ${ret.y}, z = ${ret.z}`)
  }
})
1
2
3
4
5

# sensor.unsubscribeAccelerometer()

取消监听重力感应数据

# 参数：

无

# 示例：

sensor.unsubscribeAccelerometer()
1

# sensor.subscribeCompass(OBJECT)

监听罗盘数据。如果多次调用，仅最后一次调用生效

# 参数：

参数名 类型 必填 说明
reserved Boolean 否 是否持久化订阅，默认为 false。机制：设置为 true，页面跳转，不会自动取消订阅，需手动取消订阅
callback Function 是 罗盘数据变化后会回调此函数。
# callback 返回值：
参数名 类型 说明
direction Number 表示设备的y轴和地球磁场北极之间的角度，当面朝北，角度为0；朝南角度为π；朝东角度π/2；朝西角度-π/2
accuracy Number 精度
值 说明
3 高精度
2 中等精度
1 低精度
-1 不可信，传感器失去连接
0 不可信，原因未知

# 示例：

sensor.subscribeCompass({
  callback: function(ret) {
    console.log(`handling callback, direction = ${ret.direction}`)
  }
})
1
2
3
4
5

# sensor.unsubscribeCompass()

取消监听罗盘数据

# 参数：

无

# 示例：

sensor.unsubscribeCompass()
1

# sensor.subscribeStepCounter(OBJECT)

监听计步传感器数据。如果多次调用，仅最后一次调用生效。

# 参数：

参数名 类型 必填 说明
reserved Boolean 否 是否持久化订阅，默认为 false。机制：设置为 true，页面跳转，不会自动取消订阅，需手动取消订阅
callback Function 是 计步传感器数据变化后会回调此函数。
fail Function 否 失败回调
# callback 返回值：
参数名 类型 说明
steps Number 计步传感器当前累计记录的步数。每次手机重启，这个值就会从 0 开始重新计算。
# fail 返回错误代码
错误码 说明
1000 当前设备不支持计步传感器

# 示例：

sensor.subscribeStepCounter({
  callback: function(ret) {
    console.log(`handling callback, steps = ${ret.steps}`)
  },
  fail: function(data, code) {
    console.log(`handling fail, code = ${code}`)
  }
})
1
2
3
4
5
6
7
8

# sensor.unsubscribeStepCounter()

取消监听计步传感器数据。

# 参数：

无

# 示例：

sensor.unsubscribeStepCounter()
1

# sensor 聚合接口 3+

# sensor.DATA_TYPES

传感器类型映射

类型 值 说明 是否支持单次获取
GPS 0 GPS，地理位置 是
BAROMETER 1 气压计 是
ACCELEROMETER 2 加速度 是
COMPASS 3 罗盘 是
AMBIENT_TEMPERATURE 7 环境温度 是
HUMIDITY 12 湿度 是
WRIST_LIFT 22 抬腕 否

# sensor.getRecentData(OBJECT)

获取传感器最近一次的数据

# 参数：

参数名 类型 必填 说明
type Number 是 传感器类型（需此类型支持单次获取），详见sensor.DATA_TYPES
success Function 是 成功回调
fail Function 否 失败回调
complete Function 否 执行结束后的回调

# success 返回值Object：

参数名 类型 说明
dataType Number 传感器类型，详见sensor.DATA_TYPES
data Object 传感器数据，详见参数说明 SensorData

# 示例

sensor.getRecentData({
  type: sensor.DATA_TYPES.GPS,
  success: function(data) {
    console.log(
      `handling success: data = ${JSON.stringify(data)}`
    )
  },
  fail: function(data, code) {
    console.log(`handling fail, code = ${code}, errorMsg=${data}`)
  },
  complete: function() {
    console.log('handling complete')
  }
})
1
2
3
4
5
6
7
8
9
10
11
12
13
14

# sensor.subscribe(OBJECT)

传感器订阅，支持多订阅

# 参数：

参数名 类型 必填 说明
type Number 是 传感器类型，详见sensor.DATA_TYPES
interval String 否 监听数据回调函数的执行频率
可选值：'high'、'mid'、 'low'，默认值'low'
各个厂商之间频率可能存在差异
callback Function 是 订阅回调函数
fail Function 否 失败回调

# 返回值：

返回token值作为订阅id

类型 说明
Number 本次订阅对应的key值

# callback 返回值Object：

详见参数说明 SensorData

# 示例

const token = sensor.subscribe({
  type: sensor.DATA_TYPES.GPS,
  callback: function(data) {
    console.log(`handling callback, data = ${data}`)
  },
  fail: function(data, code) {
    console.log(`handling fail, code = ${code}, errorMsg=${data}`)
  }
})
1
2
3
4
5
6
7
8
9

# sensor.unsubscribe(token)

取消传感器订阅

# 参数：

类型 必填 说明
Number 是 取消token对应的订阅

# 示例

// subscribe
const token = sensor.subscribe({
  type: sensor.DATA_TYPES.GPS,
  callback: function(data) {
    console.log(`handling callback, data = ${data}`)
  },
  fail: function(data, code) {
    console.log(`handling fail, code = ${code}, errorMsg=${data}`)
  }
})

// unsubscribe
sensor.unsubscribe(token)
1
2
3
4
5
6
7
8
9
10
11
12
13

# sensor.checkAvailable(type)

检查某个类型传感器是否硬件可用（包含物理传感器和虚拟传感器）

# 参数：

类型 必填 说明
Number 是 查询的传感器类型，详见sensor.DATA_TYPES

# 返回值：

返回token值作为订阅id

类型 说明
Boolean 传感器是否可用：true可用，false为不可用

# 示例

const available = sensor.checkAvailable(sensor.DATA_TYPES.GPS)
1

# 参数说明

# SensorData

传感器类型 返回值 说明
GPS {
    longitude: Number,
    latitude: Number,
    altitude: Number,
    speed: Number,
    accuracy: Number
}		 小数点后四舍五入保留五位小数
longitude：经度
latitude：纬度
altitude：海拔、高度，单位m
speed：速度值，单位m/s
accuracy：精确度，值为正整数
BAROMETER {
    pressure: Number
}		 小数点后四舍五入保留五位小数
pressure：压力、压强，单位hpa，百帕
ACCELEROMETER {
    x: Number,
    y: Number,
    z: Number
}		 小数点后四舍五入保留五位小数
x：x轴加速度，单位m/s^2
y：y轴加速度，单位m/s^2
z：z轴加速度，单位m/s^2
COMPASS {
    direction: Number,
    accuracy: Number
}		 direction：表示设备的y轴和地球磁场北极之间的角度，当面朝北，角度为0；朝南角度为π；朝东角度π/2；朝西角度-π/2
accuracy：精度
可取值：3: 高精度、2: 中等精度、1: 低精度、-1: 不可信，传感器失去连接、0: 不可信，原因未知
AMBIENT_TEMPERATURE {
     temperature：Number
}		 temperature：环境温度（单位：摄氏度）
温度范围：-45 至 130
数据精度：保留1位小数，如：38.6
HUMIDITY {
     humidity：Number
}		 湿度值
测量环境的相对湿度，以百分比 (%) 表示
数据范围：0 至 100
数据精度：整数，如：71
WRIST_LIFT 无 无