仓颉 OpenHarmony 传感器服务开发指南:ohos.sensor 模块 API 全面解析

原创2026-10-15 13:50:561,646 阅读
文章标签:文档知识库

仓颉 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):

注意:文档标注示例为 <!-- 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。

八、开发流程与注意事项

结合 传感器开发指导(仓颉),一套完整的传感器应用开发流程为:

  1. 导入模块:import kit.SensorServiceKit.*,并按需导入 kit.PerformanceAnalysisKit.*、ohos.business_exception.BusinessException、ohos.callback_invoke.Callback1Argument;
  2. 查询传感器:调用 getSensorList() 获取设备支持的传感器列表与采样周期范围,确认目标传感器存在;
  3. 声明并申请权限:根据 约束与限制 匹配传感器与权限,参照 声明权限 配置,user_grant 类权限还需按 向用户申请授权 动态申请;
  4. 注册监听:需要持续数据用 on()(配合 Options 设置上报频率),只需单次数据用 once();
  5. 取消监听:数据不再需要时调用 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 个核心枚举,覆盖运动、环境、健康、交互四大类传感器场景。开发者只需按 开发流程 依次完成模块导入、权限配置、监听注册与注销,即可快速在仓颉模板工程中落地指南针、计步、心率监测、自动亮度调节等功能。若需进一步了解传感器能力边界与更多实践细节,可继续阅读仓库中的 传感器开发概述 与 传感器开发指导(仓颉)。

登录后查看全文
CangjieCorpus