仓颉 OpenHarmony 传感器服务开发指南:ohos.sensor 模块 API 全面解析
仓颉 OpenHarmony 传感器服务开发指南:ohos.sensor 模块 API 全面解析
本文基于 CangjieCorpus 仓库中 Sensor Service Kit(传感器服务)API 参考文档,系统讲解仓颉语言在 OpenHarmony 平台通过
kit.SensorServiceKit.*使用传感器能力的完整方法。文章覆盖模块导入与权限要求、getSensorList/getSingleSensor/on/once/off五个核心函数、全量响应数据类型与SensorId/IntervalOption/SensorAccuracy三个枚举,以及传感器特有错误码 14500101 / 14500102 的排查处理。读者读完可直接在仓颉模板工程中编写可编译运行的传感器订阅、采样与注销代码,用于指南针、运动健康、游戏、智能穿戴等应用场景。
一、Sensor Service Kit 与 ohos.sensor 模块概述
Sensor Service Kit(传感器服务)是 OpenHarmony 为仓颉应用提供的传感器访问能力框架(Beta 特性)。其中 sensor(ohos.sensor)模块负责提供获取传感器数据的能力,包括:
- 获取传感器属性列表(设备上所有传感器的名称、厂商、采样周期、精度、功耗等信息);
- 订阅传感器数据(持续监听
on)与单次获取(once); - 取消订阅传感器数据(
off); - 一些通用的传感器算法与配套数据结构(上报频率选项、精度挡位、多传感器定位参数等)。
从仓库中的 传感器开发概述 可以看到,系统传感器是应用访问底层硬件传感器的一种设备抽象概念。开发者可依据传感器 API 查询设备传感器、订阅数据,并基于数据定制算法开发指南针、运动健康、游戏等应用。该文档还明确了传感器系统由 Sensor API、Sensor Framework、Sensor Service 和 HDF 层 四个模块构成:API 层简化应用开发;Framework 层实现订阅管理与数据通道;Service 层完成 HD_IDL 数据接收、解析分发与权限管控;HDF 层负责 FIFO/频率策略选择与设备适配。
1.1 导入模块
在仓颉代码中通过如下语句导入传感器能力(对应 cj-apis-sensor.md 的导入模块章节):
import kit.SensorServiceKit.*
示例代码中还常配合使用日志与异常处理模块:
import kit.PerformanceAnalysisKit.* // Hilog 日志能力
import ohos.business_exception.BusinessException
import ohos.callback_invoke.* // Callback1Argument / CallbackObject 回调类型
1.2 权限要求
调用传感器 API 前,需在应用配置中声明相应权限,不同传感器对应的权限清单如下(源自 cj-apis-sensor.md 权限列表与 传感器开发概述):
| 权限 | 敏感级别 | 覆盖传感器 |
|---|---|---|
ohos.permission.ACCELEROMETER |
system_grant | 加速度传感器、加速度未校准传感器、线性加速度传感器 |
ohos.permission.GYROSCOPE |
system_grant | 陀螺仪传感器、陀螺仪未校准传感器 |
ohos.permission.READ_HEALTH_DATA |
user_grant | 心率传感器(健康数据) |
此外,计步器类传感器在 传感器开发概述 中对应 ohos.permission.ACTIVITY_MOTION(user_grant)。权限的具体声明方式参见 声明权限,向用户申请授权参见 向用户申请授权。
1.3 API 示例代码使用说明
API 文档中的示例遵循以下约定(见 cj-apis-sensor.md):
- 若示例代码首行有
// index.cj注释,表示该示例可在仓颉模板工程的index.cj文件中直接编译运行; - 若示例需要获取 Context 应用上下文(即 cj-apis-app-ability-ui_ability.md 中定义的
Context类),需在仓颉模板工程的main_ability.cj文件中进行配置; - 示例工程及配置模板的总体说明见 仓颉示例代码说明。
注意:文档标注示例为
<!-- compile -->,说明这些示例经过可编译性验证,可直接复制到模板工程使用。
1.4 系统能力与起始版本
本文档所有接口的系统能力均为 SystemCapability.Sensors.Sensor,起始版本为 API version 22(Beta 特性,使用前请确认目标设备与 SDK 版本支持)。
二、API 总览
ohos.sensor 模块对外暴露 5 个顶层函数,配合多个数据类与枚举使用。函数清单如下:
| 函数 | 签名(简写) | 功能 |
|---|---|---|
getSensorList() |
getSensorList(): Array<Sensor> |
获取设备上所有传感器信息 |
getSingleSensor(SensorId) |
getSingleSensor(sensorType: SensorId): Sensor |
获取指定类型传感器信息 |
on<T>(SensorId, Callback1Argument<T>, ?Options) |
on<T>(sensorType: SensorId, callback: Callback1Argument<T>, option!: ?Options = None): Unit where T <: Response |
持续订阅传感器数据 |
once<T>(SensorId, Callback1Argument<T>) |
once<T>(sensorType: SensorId, callback: Callback1Argument<T>): Unit where T <: Response |
获取一次传感器数据 |
off(SensorId, ?CallbackObject) |
off(sensorType: SensorId, callback!: ?CallbackObject = None): Unit |
取消订阅传感器数据 |
数据类型方面,模块定义了:
- 数据响应类:
Response(基类)及其 20 余个派生类(AccelerometerResponse、GyroscopeResponse、OrientationResponse等),每类对应一种传感器的上报数据结构; - 配置类:
Options(上报频率)、SensorInfoParam(多传感器定位参数)、Sensor(传感器属性信息); - 枚举:
SensorId(传感器类型)、IntervalOption(上报频率选项)、SensorAccuracy(数据精度挡位)。
三、函数详解与示例
3.1 func getSensorList():获取全部传感器信息
public func getSensorList(): Array<Sensor>
功能:获取设备上的所有传感器信息,返回传感器属性列表。
返回值:Array<Sensor>,即 Sensor 对象的数组。
异常:抛出 BusinessException,对应错误码如下:
| 错误码ID | 错误信息 |
|---|---|
| 14500101 | Service exception. Possible causes: 1. Sensor hdf service exception; 2. Sensor service ipc exception; 3. Sensor data channel exception. |
示例(// index.cj 中编译运行):
// index.cj
import kit.SensorServiceKit.*
import kit.PerformanceAnalysisKit.*
import ohos.business_exception.BusinessException
try {
let sensors = getSensorList()
for (index in 0..sensors.size) {
Hilog.info(0, "test", "Succeeded in getting sensor${index}: ${sensors[index].sensorId}", "")
}
} catch (e: BusinessException) {
Hilog.info(0, "test", "Failed to get sensor list. Code: ${e.code}, message: ${e.message}", "")
}
3.2 func getSingleSensor(SensorId):获取指定类型传感器
public func getSingleSensor(sensorType: SensorId): Sensor
参数:
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| sensorType | SensorId | 是 | - | 传感器类型 |
返回值:Sensor 对象,包含该类型传感器的属性信息。
异常(对应 传感器错误码):
| 错误码ID | 错误信息 |
|---|---|
| 14500101 | Service exception. Possible causes: 1. Sensor hdf service exception; 2. Sensor service ipc exception; 3. Sensor data channel exception. |
| 14500102 | The sensor is not supported by the device. |
示例(获取加速度传感器信息):
// index.cj
import kit.SensorServiceKit.*
import kit.PerformanceAnalysisKit.*
import ohos.business_exception.BusinessException
try {
let sensors = getSingleSensor(SensorId.Accelerometer)
Hilog.info(0, "test", "Succeeded in getting sensor: ${sensors.sensorName}", "")
} catch (e: BusinessException) {
Hilog.error(0, "test", "Code: ${e.code}, message: ${e.message}", "")
}
3.3 func on:持续订阅传感器数据
public func on<T>(sensorType: SensorId, callback: Callback1Argument<T>, option!: ?Options = None): Unit where T <: Response
功能:订阅传感器数据,传感器按设定的上报周期持续回调。这是应用最常用的接口。
参数:
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| sensorType | SensorId | 是 | - | 传感器类型 |
| callback | Callback1Argument(即 cj-api-callback_invoke.md 中的 Callback1Argument<T>) |
是 | - | 回调函数,接收异步上报的传感器数据 |
| option | ?Options | 否 | None | 命名参数。 可选参数列表,用于设置传感器上报频率,默认值为 200000000 ns(200ms) |
说明:T 是泛型参数,约束为 T <: Response,即每种传感器类型对应的响应数据类型不同(例如加速度传感器对应 AccelerometerResponse)。回调类型 Callback1Argument<T> 的 invoke 方法签名固定为 invoke(err: ?BusinessException, arg: T),用于接收业务数据或异常。
异常:
| 错误码ID | 错误信息 |
|---|---|
| 201 | Permission verification failed. The application does not have permission to call the API. |
| 14500101 | Service exception. Possible causes: 1. Sensor hdf service exception; 2. Sensor service ipc exception; 3. Sensor data channel exception. |
示例(订阅加速度传感器,自定义上报周期为 100000000 ns):
// index.cj
import kit.SensorServiceKit.*
import kit.PerformanceAnalysisKit.*
import ohos.business_exception.BusinessException
import ohos.callback_invoke.*
class AccelerometerCallback <: Callback1Argument<AccelerometerResponse> {
init() {}
public func invoke(err: ?BusinessException, arg: AccelerometerResponse): Unit {
Hilog.info(0, "test", "Succeeded in getting AccelerometerCallback arg: timestamp: ${arg.timestamp}, x: ${arg.x}, y: ${arg.y}, z: ${arg.z}", "")
}
}
let callback = AccelerometerCallback()
let options = Options(interval: IntervalOption.SensorNumber(100000000))
try {
on(SensorId.Accelerometer, callback, option: options)
} catch (e: BusinessException) {
Hilog.error(0, "test", "Code: ${e.code}, message: ${e.message}", "")
}
3.4 func once:获取一次传感器数据
public func once<T>(sensorType: SensorId, callback: Callback1Argument<T>): Unit where T <: Response
功能:获取一次传感器数据。回调异步上报单次数据,适合一次性采样场景。
参数:
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
| sensorType | SensorId | 是 | - | 传感器类型 |
| callback | Callback1Argument<T> | 是 | - | 回调函数,异步上报的传感器数据,每种传感器类型对应的数据类型不同 |
异常:
| 错误码ID | 错误信息 |
|---|---|
| 201 | Permission verification failed. The application does not have permission to call the API. |
| 14500101 | Service exception. |
示例(获取一次陀螺仪数据):
// index.cj
import kit.SensorServiceKit.*
import kit.PerformanceAnalysisKit.*
import ohos.business_exception.BusinessException
import ohos.callback_invoke.*
class GyroscopeCallback <: Callback1Argument<GyroscopeResponse> {
init() {}
public func invoke(err: ?BusinessException, arg: GyroscopeResponse): Unit {
Hilog.info(0, "test", "Succeeded in getting GyroscopeCallback arg: timestamp: ${arg.timestamp}, x: ${arg.x}, y: ${arg.y}, z: ${arg.z}", "")
}
}
let callback = GyroscopeCallback()
try {
once(SensorId.Gyroscope, callback)
} catch (e: BusinessException) {
Hilog.error(0, "test", "Code: ${e.code}, message: ${e.message}", "")
}
3.5 func off:取消订阅传感器数据
public func off(sensorType: SensorId, callback!: ?CallbackObject = None): Unit
功能:取消订阅传感器数据。订阅与取消订阅需成对调用(见 传感器开发概述),避免不再需要数据时传感器持续上报造成功耗浪费。
参数:
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| sensorType | SensorId | 是 | - | 传感器类型 |
| callback | ?CallbackObject(即 cj-api-callback_invoke.md 中的 CallbackObject) |
否 | None | 命名参数。 需要取消订阅的回调函数;若无此参数,则取消订阅当前类型的所有回调函数 |
异常:
| 错误码ID | 错误信息 |
|---|---|
| 201 | Permission verification failed. The application does not have permission to call the API. |
示例(演示按回调精确注销与按类型全量注销两种用法):
// index.cj
import kit.SensorServiceKit.*
import kit.PerformanceAnalysisKit.*
import ohos.business_exception.BusinessException
import ohos.callback_invoke.*
class SensorCallback <: Callback1Argument<OrientationResponse> {
init() {}
public func invoke(err: ?BusinessException, arg: OrientationResponse): Unit {
Hilog.info(0, "test", "Succeeded in getting SensorCallback1 arg: steps: ${arg.timestamp}, alpha: ${arg.alpha}, beta: ${arg.beta}, gamma: ${arg.gamma}", "")
}
}
let callback1 = SensorCallback()
let callback2 = SensorCallback()
try {
on(SensorId.Orientation, callback1)
on(SensorId.Orientation, callback2)
// 仅取消callback1的注册
off(SensorId.Orientation, callback: callback1)
// 取消注册SensorId.Orientation的所有回调
off(SensorId.Orientation)
} catch (e: BusinessException) {
Hilog.error(0, "test", "Code: ${e.code}, message: ${e.message}", "")
}
四、传感器数据响应类型(Response 体系)
所有传感器数据都通过 Response 的派生类上报。Response 是开放基类,提供统一的 timestamp 与 accuracy 字段。
4.1 基类 Response
public open class Response {
public var timestamp: Int64
public var accuracy: SensorAccuracy
}
| 字段 | 类型 | 说明 |
|---|---|---|
timestamp |
Int64 | 传感器数据上报的时间戳,从设备开机开始计时到上报数据的时间,单位:ns |
accuracy |
SensorAccuracy | 传感器数据上报的精度挡位值 |
4.2 派生响应类清单
各传感器类型对应的响应类及数据字段汇总如下(字段类型均为 Float32,除特别说明外均可读写):
| 响应类 | 功能 | 字段及说明 |
|---|---|---|
AccelerometerResponse |
加速度传感器数据 | x/y/z:三轴线性加速度,单位 m/s² |
AccelerometerUncalibratedResponse |
未校准加速度计数据 | x/y/z:未校准加速度(m/s²);biasX/biasY/biasZ:未校准加速度偏量(m/s²) |
LinearAccelerometerResponse |
线性加速度数据 | x/y/z:线性加速度(不含重力),单位 m/s² |
GravityResponse |
重力传感器数据 | x/y/z:三轴重力加速度,单位 m/s² |
GyroscopeResponse |
陀螺仪数据 | x/y/z:三轴旋转角速度,单位 rad/s,取值为实际上报物理量 |
GyroscopeUncalibratedResponse |
未校准陀螺仪数据 | x/y/z:未校准旋转角速度(rad/s);biasX/biasY/biasZ:角速度偏量(rad/s) |
MagneticFieldResponse |
磁场传感器数据 | x/y/z:三轴环境磁场强度,单位 μT |
MagneticFieldUncalibratedResponse |
未校准磁场数据 | x/y/z:未校准磁场强度(μT);biasX/biasY/biasZ:磁场强度偏量(μT) |
OrientationResponse |
方向传感器数据 | alpha:绕 Z 轴旋转角,0-360 度;beta:绕 X 轴旋转角,0-±180 度;gamma:绕 Y 轴旋转角,0-±90 度 |
RotationVectorResponse |
旋转矢量数据 | x/y/z:旋转矢量三分量;w:标量,描述设备相对参考方向的旋转状态,单位弧度 |
AmbientTemperatureResponse |
温度传感器数据 | temperature:环境温度,单位摄氏度 |
BarometerResponse |
气压计数据 | pressure:压力值,单位百帕 |
HumidityResponse |
湿度传感器数据 | humidity:相对湿度,以百分比(%)表示 |
LightResponse |
环境光传感器数据 | intensity:光强,单位勒克斯;colorTemperature:色温(开尔文,?Float32 可选,不支持时返回传感器自定义固定值);infraredLuminance:红外亮度(cd/m²,?Float32 可选) |
HallResponse |
霍尔传感器数据 | status:霍尔状态,0 表示无磁力吸引,大于 0 表示有 |
ProximityResponse |
接近光传感器数据 | distance:可见物体与设备显示器的接近程度,0 表示接近,大于 0 表示远离 |
HeartRateResponse |
心率传感器数据 | heartRate:心率值,单位 bpm |
PedometerResponse |
计步传感器数据 | steps:行走步数,初始值 0,订阅后每走一步累计加一 |
PedometerDetectionResponse |
计步检测数据 | scalar:1 表示产生计步行走动作,0 表示未发生运动 |
SignificantMotionResponse |
有效运动数据 | scalar:1 表示存在大幅度运动(x、y、z 三轴) |
WearDetectionResponse |
佩戴检测数据 | value:1 表示已穿戴,0 表示未穿戴 |
五、传感器属性与配置类
5.1 class Sensor:传感器属性信息
public class Sensor {
public var sensorName: String
public var vendorName: String
public var firmwareVersion: String
public var hardwareVersion: String
public var sensorId: Int32
public var maxRange: Float32
public var minSamplePeriod: Int64
public var maxSamplePeriod: Int64
public var precision: Float32
public var power: Float32
}
| 字段 | 类型 | 说明 |
|---|---|---|
sensorName |
String | 传感器名称 |
vendorName |
String | 传感器供应商 |
firmwareVersion |
String | 传感器固件版本 |
hardwareVersion |
String | 传感器硬件版本 |
sensorId |
Int32 | 传感器类型 id |
maxRange |
Float32 | 传感器测量范围的最大值 |
minSamplePeriod |
Int64 | 允许的最小采样周期 |
maxSamplePeriod |
Int64 | 允许的最大采样周期 |
precision |
Float32 | 传感器精度 |
power |
Float32 | 传感器功率的估计值,单位 mA |
从 传感器开发指导(仓颉) 的示例可知,minSamplePeriod 与 maxSamplePeriod 决定了该传感器支持的上报周期区间,例如加速度传感器通常支持 2000000 ns 到 200000000 ns 的采样周期。上报周期 interval 应设置在传感器支持范围内:大于最大值时以最大值上报,小于最小值时以最小值上报;数值越小数据上报越频繁,功耗越大。
5.2 class Options:上报频率配置
public class Options {
public var interval: IntervalOption
public var sensorInfoParam:?SensorInfoParam
public init(interval!: IntervalOption = NormalMode, sensorInfoParam!: ?SensorInfoParam = None)
}
| 字段/参数 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
interval |
IntervalOption | 否 | NormalMode | 传感器上报频率,默认值为 200000000 ns。该属性受硬件支持频率范围的上下限约束:设置频率大于最大值时以最大值上报,小于最小值时以最小值上报 |
sensorInfoParam |
?SensorInfoParam | 否 | None | 传感器传入设置参数,可指定 deviceId、sensorIndex |
5.3 class SensorInfoParam:多传感器定位参数
public class SensorInfoParam {
public var deviceId: Int32
public var sensorIndex: Int32
public init(deviceId!: Int32 = -1, sensorIndex!: Int32 = 0)
}
| 字段/参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
deviceId |
Int32 | -1 | 设备 ID。默认值 -1 表示本地设备;其他设备 ID 需通过 getSensorList 查询或监听设备上下线接口获取 |
sensorIndex |
Int32 | 0 | 传感器索引。默认值 0 为设备上的默认传感器;其他传感器索引需通过 getSensorList 查询或监听设备上下线接口获取 |
该配置类用于同一设备存在多个同类型传感器(多传感器场景)时,精确指定要订阅的传感器实例。
六、枚举类型详解
6.1 enum SensorId:传感器类型
public enum SensorId <: Equatable<SensorId> & ToString {
| Accelerometer
| Gyroscope
| AmbientLight
| MagneticField
| Barometer
| Hall
| Proximity
| Humidity
| Orientation
| Gravity
| LinearAccelerometer
| RotationVector
| AmbientTemperature
| MagneticFieldUncalibrated
| GyroscopeUncalibrated
| SignificantMotion
| PedometerDetection
| Pedometer
| HeartRate
| WearDetection
| AccelerometerUncalibrated
| ...
}
该枚举表示当前支持订阅或取消订阅的传感器类型,作为 on / once / off / getSingleSensor 的第一参数。各枚举值与传感器对应关系如下:
| 枚举值 | 传感器 | 对应响应类 |
|---|---|---|
Accelerometer |
加速度传感器 | AccelerometerResponse |
AccelerometerUncalibrated |
未校准加速度计传感器 | AccelerometerUncalibratedResponse |
LinearAccelerometer |
线性加速度传感器 | LinearAccelerometerResponse |
Gravity |
重力传感器 | GravityResponse |
Gyroscope |
陀螺仪传感器 | GyroscopeResponse |
GyroscopeUncalibrated |
未校准陀螺仪传感器 | GyroscopeUncalibratedResponse |
MagneticField |
磁场传感器 | MagneticFieldResponse |
MagneticFieldUncalibrated |
未校准磁场传感器 | MagneticFieldUncalibratedResponse |
Orientation |
方向传感器 | OrientationResponse |
RotationVector |
旋转矢量传感器 | RotationVectorResponse |
AmbientLight |
环境光传感器 | LightResponse |
AmbientTemperature |
环境温度传感器 | AmbientTemperatureResponse |
Barometer |
气压计传感器 | BarometerResponse |
Humidity |
湿度传感器 | HumidityResponse |
Hall |
霍尔传感器 | HallResponse |
Proximity |
接近光传感器 | ProximityResponse |
HeartRate |
心率传感器 | HeartRateResponse |
Pedometer |
计步传感器 | PedometerResponse |
PedometerDetection |
计步检测传感器 | PedometerDetectionResponse |
SignificantMotion |
有效运动传感器 | SignificantMotionResponse |
WearDetection |
佩戴检测传感器 | WearDetectionResponse |
SensorId 还提供以下成员方法:
| 方法 | 签名 | 说明 |
|---|---|---|
== |
public operator func ==(other: SensorId): Bool |
判断两个 SensorId 是否相等 |
!= |
public operator func !=(other: SensorId): Bool |
判断两个 SensorId 是否不相等 |
getValue() |
public func getValue(): Int32 |
获取枚举值 |
toString() |
public func toString(): String |
将枚举值转换为字符串 |
6.2 enum IntervalOption:上报频率选项
public enum IntervalOption <: Equatable<IntervalOption> & ToString {
| SensorNumber(Int64)
| GameMode
| UIMode
| NormalMode
| ...
}
| 枚举值 | 频率值 | 说明 |
|---|---|---|
SensorNumber(Int64) |
自定义 | 自定义传感器上报频率,频率值为指定的纳秒数 |
GameMode |
20000000 ns | 游戏模式频率,在硬件支持的频率范围内时生效 |
UIMode |
60000000 ns | UI 模式频率,在硬件支持的频率范围内时生效 |
NormalMode |
200000000 ns | 常规模式频率,值固定为 'normal' 字符串,在硬件支持的频率范围内时生效 |
该枚举提供 == / != / toString() 三个成员方法,语义与 SensorId 相同。使用示例:Options(interval: IntervalOption.SensorNumber(100000000)) 即设置 100 ms 的自定义上报周期。
6.3 enum SensorAccuracy:数据精度挡位
public enum SensorAccuracy <: Equatable<SensorAccuracy> & ToString {
| AccuracyUnreliable
| AccuracyLow
| AccuracyMedium
| AccuracyHigh
| ...
}
| 枚举值 | 说明 |
|---|---|
AccuracyUnreliable |
传感器数据不可信 |
AccuracyLow |
传感器低档位精度 |
AccuracyMedium |
传感器中档位精度 |
AccuracyHigh |
传感器高档位精度 |
该枚举同样提供 == / != / toString() 方法,可通过 Response.accuracy 字段读取每次上报数据的精度等级。
七、SensorId 全类型订阅示例(模式化写法)
API 文档为每个 SensorId 枚举值都提供了完整的 on / once / off 三段式示例。所有传感器类型的写法结构完全一致,仅回调类名与响应类型不同。以加速度传感器为例,完整的生命周期代码如下:
// index.cj
import kit.SensorServiceKit.*
import kit.PerformanceAnalysisKit.*
import ohos.business_exception.BusinessException
import ohos.callback_invoke.*
class AccelerometerCallback1 <: Callback1Argument<AccelerometerResponse> {
init() {}
public func invoke(err: ?BusinessException, arg: AccelerometerResponse): Unit {
Hilog.info(0, "test", "Accelerometer data: timestamp: ${arg.timestamp}, x: ${arg.x}, y: ${arg.y}, z: ${arg.z}", "")
}
}
let callback = AccelerometerCallback1()
let options = Options(interval: IntervalOption.SensorNumber(100000000))
try {
// 订阅传感器数据
on(SensorId.Accelerometer, callback, option: options)
// 获取一次传感器数据
once(SensorId.Accelerometer, callback)
// 取消订阅传感器数据
off(SensorId.Accelerometer, callback: callback)
} catch (e: BusinessException) {
Hilog.error(0, "test", "Code: ${e.code}, message: ${e.message}", "")
}
替换 SensorId 枚举值、回调实现类与 Callback1Argument<T> 的泛型参数(T 换成 响应类清单 中对应的响应类型),即可将该模式套用到 AmbientLight、Barometer、Humidity、HeartRate、WearDetection 等全部传感器,例如:
- 环境光:
on(SensorId.AmbientLight, callback, option: options),回调使用LightResponse; - 计步:
on(SensorId.Pedometer, callback, option: options),回调使用PedometerResponse; - 佩戴检测:
on(SensorId.WearDetection, callback, option: options),回调使用WearDetectionResponse。
八、开发流程与注意事项
结合 传感器开发指导(仓颉),一套完整的传感器应用开发流程为:
- 导入模块:
import kit.SensorServiceKit.*,并按需导入kit.PerformanceAnalysisKit.*、ohos.business_exception.BusinessException、ohos.callback_invoke.Callback1Argument; - 查询传感器:调用
getSensorList()获取设备支持的传感器列表与采样周期范围,确认目标传感器存在; - 声明并申请权限:根据 约束与限制 匹配传感器与权限,参照 声明权限 配置,user_grant 类权限还需按 向用户申请授权 动态申请;
- 注册监听:需要持续数据用
on()(配合Options设置上报频率),只需单次数据用once(); - 取消监听:数据不再需要时调用
off()停止上报,订阅与取消订阅接口务必成对调用。
需要注意的工程约束:
- 周期传感器与瞬时传感器:周期传感器按设定固定间隔采集并输出数据(如
AMBIENT_TEMPERATURE、GRAVITY、HUMIDITY、BAROMETER),option生效;瞬时传感器受特定触发事件影响才输出数据(如HALL、PROXIMITY、WEAR_DETECTION、PEDOMETER、PEDOMETER_DETECTION),不受option约束; - 多传感器定位:同一类型存在多个传感器实例时,通过
Options(sensorInfoParam: SensorInfoParam(deviceId: ..., sensorIndex: ...))指定目标; - 回调错误处理:回调的
invoke(err: ?BusinessException, arg: T)首参携带异常信息,业务侧应检查err是否为空后再处理数据。
九、错误码与异常处理
传感器模块特有的错误码定义在 传感器错误码 中,调用失败时以 BusinessException 抛出,可通过 e.code 与 e.message 获取详情。通用错误码(如 201)参见 通用错误码说明文档。
9.1 14500101 传感器服务异常
| 项 | 内容 |
|---|---|
| 错误信息 | Service exception. |
| 错误描述 | 调用 on、once、off 接口时,若 hdi 服务异常,会报此错误码 |
| 可能原因 | 访问 hdi 服务状态异常 |
| 处理步骤 | ① 定时重试操作,如间隔 1s 或按指数增长间隔重试;② 连续重试 3 次不可用则停止尝试,期间可优先通过获取器件列表(getSensorList)的方式进一步获取设备可用性 |
9.2 14500102 设备不支持该传感器
| 项 | 内容 |
|---|---|
| 错误信息 | The sensor is not supported by the device. |
| 错误描述 | 调用 getSingleSensor 接口时,若设备不支持该传感器,会报此错误码 |
| 可能原因 | 底层器件未适配传感器,设备不支持该传感器 |
| 处理步骤 | 使用 getSingleSensor 接口,返回 14500102 即表示设备不支持该传感器,应用侧应据此做降级或提示处理 |
9.3 常见错误码汇总
| 错误码ID | 触发接口 | 含义 |
|---|---|---|
| 201 | on / once / off |
权限校验失败,应用未申请相应权限,需核对 权限要求 |
| 14500101 | getSensorList / getSingleSensor / on / once |
传感器服务异常(hdf / ipc / 数据通道) |
| 14500102 | getSingleSensor |
设备不支持该类型传感器 |
十、总结
ohos.sensor 模块为仓颉应用提供了完整的传感器能力闭环:通过 getSensorList / getSingleSensor 探测设备传感器能力,通过 on / once 获取数据流或单次采样,通过 off 及时释放订阅。围绕这些接口,cj-apis-sensor.md 定义了 20 余种响应类型与 3 个核心枚举,覆盖运动、环境、健康、交互四大类传感器场景。开发者只需按 开发流程 依次完成模块导入、权限配置、监听注册与注销,即可快速在仓颉模板工程中落地指南针、计步、心率监测、自动亮度调节等功能。若需进一步了解传感器能力边界与更多实践细节,可继续阅读仓库中的 传感器开发概述 与 传感器开发指导(仓颉)。