1# @ohos.sensor (传感器)(系统接口) 2<!--Kit: Sensor Service Kit--> 3<!--Subsystem: Sensors--> 4<!--Owner: @dilligencer--> 5<!--Designer: @butterls--> 6<!--Tester: @murphy84--> 7<!--Adviser: @hu-zhiqiong--> 8 9sensor模块提供了获取传感器数据的能力，包括获取传感器属性列表，订阅传感器数据，以及一些通用的传感器算法。 10 11> **说明：** 12> 13> 本模块首批接口从API version 8开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 14> 15> 本模块为系统接口。 16 17 18## 导入模块 19 20```ts 21import { sensor } from '@kit.SensorServiceKit'; 22``` 23 24## sensor.on 25 26### COLOR<sup>10+</sup> 27 28on(type: SensorId.COLOR, callback: Callback<ColorResponse>, options?: Options): void 29 30订阅颜色传感器数据。 31 32**系统能力**：SystemCapability.Sensors.Sensor 33 34**系统API**：此接口为系统接口 35 36**参数**： 37 38| 参数名 | 类型 | 必填 | 说明 | 39| -------- | ------------------------------------------------- | ---- | ----------------------------------------------------------- | 40| type | [SensorId](#sensorid9).COLOR | 是 | 传感器类型，该值固定为SensorId.COLOR。 | 41| callback | Callback<[ColorResponse](#colorresponse10)> | 是 | 回调函数，异步上报的传感器数据固定为ColorResponse。 | 42| options | [Options](js-apis-sensor.md#options) | 否 | 可选参数列表，用于设置传感器上报频率，默认值为200000000ns。 | 43 44**错误码**： 45 46以下错误码的详细介绍请参见[传感器错误码](errorcode-sensor.md)和[通用错误码](../errorcode-universal.md)。 47 48| 错误码ID | 错误信息 | 49| -------- | ------------------------------------------------------------ | 50| 202 | Permission check failed. A non-system application uses the system API. | 51| 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | 52| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | 53 54**示例**： 55 56```ts 57import { sensor } from '@kit.SensorServiceKit'; 58import { BusinessError } from '@kit.BasicServicesKit'; 59 60try{ 61 sensor.on(sensor.SensorId.COLOR, (data: sensor.ColorResponse) => { 62 console.log('Succeeded in getting the intensity of light: ' + data.lightIntensity); 63 console.log('Succeeded in getting the color temperature: ' + data.colorTemperature); 64 }, { interval: 100000000 }); 65 setTimeout(() => { 66 sensor.off(sensor.SensorId.COLOR); 67 }, 500); 68} catch (error) { 69 let e: BusinessError = error as BusinessError; 70 console.error(`Failed to invoke on. Code: ${e.code}, message: ${e.message}`); 71} 72``` 73 74### SAR<sup>10+</sup> 75 76on(type: SensorId.SAR, callback: Callback<SarResponse>, options?: Options): void 77 78订阅吸收比率传感器数据。 79 80**系统能力**：SystemCapability.Sensors.Sensor 81 82**系统API**：此接口为系统接口 83 84**参数**： 85 86| 参数名 | 类型 | 必填 | 说明 | 87| -------- | --------------------------------------------- | ---- | ----------------------------------------------------------- | 88| type | [SensorId](#sensorid9).SAR | 是 | 传感器类型，该值固定为SensorId.SAR。 | 89| callback | Callback<[SarResponse](#sarresponse10)> | 是 | 回调函数，异步上报的传感器数据固定为SarResponse。 | 90| options | [Options](js-apis-sensor.md#options) | 否 | 可选参数列表，用于设置传感器上报频率，默认值为200000000ns。 | 91 92**错误码**： 93 94以下错误码的详细介绍请参见[传感器错误码](errorcode-sensor.md)和[通用错误码](../errorcode-universal.md)。 95 96| 错误码ID | 错误信息 | 97| -------- | ------------------------------------------------------------ | 98| 202 | Permission check failed. A non-system application uses the system API. | 99| 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | 100| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | 101 102**示例**： 103 104```ts 105import { sensor } from '@kit.SensorServiceKit'; 106import { BusinessError } from '@kit.BasicServicesKit'; 107 108try { 109 sensor.on(sensor.SensorId.SAR, (data: sensor.SarResponse) => { 110 console.info('Succeeded in getting specific absorption rate : ' + data.absorptionRatio); 111 }, { interval: 100000000 }); 112 setTimeout(() => { 113 sensor.off(sensor.SensorId.SAR); 114 }, 500); 115} catch (error) { 116 let e: BusinessError = error as BusinessError; 117 console.error(`Failed to invoke on. Code: ${e.code}, message: ${e.message}`); 118} 119``` 120 121## sensor.off 122 123### COLOR<sup>10+</sup> 124 125off(type: SensorId.COLOR, callback?: Callback<ColorResponse>): void 126 127取消订阅颜色传感器数据。 128 129**系统能力**：SystemCapability.Sensors.Sensor 130 131**系统API**：此接口为系统接口 132 133**参数**： 134 135| 参数名 | 类型 | 必填 | 说明 | 136| -------- |--------------------------------------------------------| ---- | ------------------------------------------------------------ | 137| type | [SensorId](#sensorid9).COLOR | 是 | 传感器类型，该值固定为SensorId.COLOR。 | 138| callback | Callback<[ColorResponse](#colorresponse10)> | 否 | 需要取消订阅的回调函数，若无此参数，则取消订阅当前类型的所有回调函数。 | 139 140**错误码**： 141 142以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 143 144| 错误码ID | 错误信息 | 145| -------- | ------------------------------------------------------------ | 146| 202 | Permission check failed. A non-system application uses the system API. | 147| 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | 148 149**示例**： 150 151```ts 152import { sensor } from '@kit.SensorServiceKit'; 153import { BusinessError } from '@kit.BasicServicesKit'; 154 155function callback1(data: object) { 156 console.info('Succeeded in getting callback1 data: ' + JSON.stringify(data)); 157} 158 159function callback2(data: object) { 160 console.info('Succeeded in getting callback2 data: ' + JSON.stringify(data)); 161} 162 163try { 164 sensor.on(sensor.SensorId.COLOR, callback1); 165 sensor.on(sensor.SensorId.COLOR, callback2); 166 // 仅取消callback1的注册 167 sensor.off(sensor.SensorId.COLOR, callback1); 168 // 取消注册SensorId.COLOR的所有回调 169 sensor.off(sensor.SensorId.COLOR); 170} catch (error) { 171 let e: BusinessError = error as BusinessError; 172 console.error(`Failed to invoke off. Code: ${e.code}, message: ${e.message}`); 173} 174``` 175 176### COLOR<sup>19+</sup> 177 178off(type: SensorId.COLOR, sensorInfoParam?: SensorInfoParam, callback?: Callback<ColorResponse>): void 179 180取消订阅颜色传感器数据。 181 182**系统能力**：SystemCapability.Sensors.Sensor 183 184**系统API**：此接口为系统接口 185 186**参数**： 187 188| 参数名 | 类型 | 必填 | 说明 | 189| -------- |--------------------------------------------------------| ---- | ------------------------------------------------------------ | 190| type | [SensorId](#sensorid9).COLOR | 是 | 传感器类型，该值固定为SensorId.COLOR。 | 191| sensorInfoParam | [SensorInfoParam](#sensorinfoparam19) | 否 | 传感器传入设置参数，可指定deviceId、sensorIndex | 192| callback | Callback<[ColorResponse](#colorresponse10)> | 否 | 需要取消订阅的回调函数，若无此参数，则取消订阅当前类型的所有回调函数。 | 193 194**错误码**： 195 196以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 197 198| 错误码ID | 错误信息 | 199| -------- | ------------------------------------------------------------ | 200| 202 | Permission check failed. A non-system application uses the system API. | 201| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | 202 203**示例**： 204 205```ts 206import { sensor } from '@kit.SensorServiceKit'; 207import { BusinessError } from '@kit.BasicServicesKit'; 208 209enum Ret { OK, Failed = -1 } 210 211// 传感器回调 212const sensorCallback = (response: sensor.ColorResponse) => { 213 console.log(`callback response: ${JSON.stringify(response)}`); 214} 215// 传感器监听类型 216const sensorType = sensor.SensorId.COLOR; 217const sensorInfoParam: sensor.SensorInfoParam = {}; 218 219function sensorSubscribe(): Ret { 220 let ret: Ret = Ret.OK; 221 try { 222 // 查询所有的传感器 223 const sensorList: sensor.Sensor[] = sensor.getSensorListSync(); 224 if (!sensorList.length) { 225 return Ret.Failed; 226 } 227 // 根据实际业务逻辑获取目标传感器。 228 const targetSensor = sensorList 229 // 按需过滤deviceId为1、sensorId为2的所有传感器。此处示例仅做展示，开发者需要自行调整筛选逻辑。 230 .filter((sensor: sensor.Sensor) => sensor.deviceId === 1 && sensor.sensorId === 2) 231 // 可能存在的多个同类型传感器，选择sensorIndex为0的传感器。 232 .find((sensor: sensor.Sensor) => sensor.sensorIndex === 0); 233 if (!targetSensor) { 234 return Ret.Failed; 235 } 236 sensorInfoParam.deviceId = targetSensor.deviceId; 237 sensorInfoParam.sensorIndex = targetSensor.sensorIndex; 238 // 订阅传感器事件 239 sensor.on(sensorType, sensorCallback, { sensorInfoParam }); 240 } catch (error) { 241 let e: BusinessError = error as BusinessError; 242 console.error(`Failed to invoke sensor.on. Code: ${e.code}, message: ${e.message}`); 243 ret = Ret.Failed; 244 } 245 return ret; 246} 247 248function sensorUnsubscribe(): Ret { 249 let ret: Ret = Ret.OK; 250 try { 251 sensor.off(sensorType, sensorInfoParam, sensorCallback); 252 } catch (error) { 253 let e: BusinessError = error as BusinessError; 254 console.error(`Failed to invoke sensor.off. Code: ${e.code}, message: ${e.message}`); 255 ret = Ret.Failed; 256 } 257 return ret; 258} 259``` 260 261### SAR<sup>10+</sup> 262 263off(type: SensorId.SAR, callback?: Callback<SarResponse>): void 264 265取消订阅吸收比率传感器数据。 266 267**系统能力**：SystemCapability.Sensors.Sensor 268 269**系统API**：此接口为系统接口 270 271**参数**： 272 273| 参数名 | 类型 | 必填 | 说明 | 274| -------- | --------------------------------------------- | ---- | ------------------------------------------------------------ | 275| type | [SensorId](#sensorid9).SAR | 是 | 传感器类型，该值固定为SensorId.SAR。 | 276| callback | Callback<[SarResponse](#sarresponse10)> | 否 | 需要取消订阅的回调函数，若无此参数，则取消订阅当前类型的所有回调函数。 | 277 278**错误码**： 279 280以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 281 282| 错误码ID | 错误信息 | 283| -------- | ------------------------------------------------------------ | 284| 202 | Permission check failed. A non-system application uses the system API. | 285| 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | 286 287**示例**： 288 289```ts 290import { sensor } from '@kit.SensorServiceKit'; 291import { BusinessError } from '@kit.BasicServicesKit'; 292 293function callback1(data: object) { 294 console.info('Succeeded in getting callback1 data: ' + JSON.stringify(data)); 295} 296 297function callback2(data: object) { 298 console.info('Succeeded in getting callback2 data: ' + JSON.stringify(data)); 299} 300 301try { 302 sensor.on(sensor.SensorId.SAR, callback1); 303 sensor.on(sensor.SensorId.SAR, callback2); 304 // 仅取消callback1的注册 305 sensor.off(sensor.SensorId.SAR, callback1); 306 // 取消注册SensorId.SAR的所有回调 307 sensor.off(sensor.SensorId.SAR); 308} catch (error) { 309 let e: BusinessError = error as BusinessError; 310 console.error(`Failed to invoke off. Code: ${e.code}, message: ${e.message}`); 311} 312``` 313 314### SAR<sup>19+</sup> 315 316off(type: SensorId.SAR, sensorInfoParam?: SensorInfoParam, callback?: Callback<SarResponse>): void 317 318取消订阅吸收比率传感器数据。 319 320**系统能力**：SystemCapability.Sensors.Sensor 321 322**系统API**：此接口为系统接口 323 324**参数**： 325 326| 参数名 | 类型 | 必填 | 说明 | 327| -------- | --------------------------------------------- | ---- | ------------------------------------------------------------ | 328| type | [SensorId](#sensorid9).SAR | 是 | 传感器类型，该值固定为SensorId.SAR。 | 329| sensorInfoParam | [SensorInfoParam](#sensorinfoparam19) | 否 | 传感器传入设置参数，可指定deviceId、sensorIndex | 330| callback | Callback<[SarResponse](#sarresponse10)> | 否 | 需要取消订阅的回调函数，若无此参数，则取消订阅当前类型的所有回调函数。 | 331 332**错误码**： 333 334以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 335 336| 错误码ID | 错误信息 | 337| -------- |-----------------------------------------------------------------------------------------------------------------------------------------| 338| 202 | Permission check failed. A non-system application uses the system API. | 339| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | 340 341**示例**： 342 343```ts 344import { sensor } from '@kit.SensorServiceKit'; 345import { BusinessError } from '@kit.BasicServicesKit'; 346 347enum Ret { OK, Failed = -1 } 348 349// 传感器回调 350const sensorCallback = (response: sensor.SarResponse) => { 351 console.log(`callback response: ${JSON.stringify(response)}`); 352} 353// 传感器监听类型 354const sensorType = sensor.SensorId.SAR; 355const sensorInfoParam: sensor.SensorInfoParam = {}; 356 357function sensorSubscribe(): Ret { 358 let ret: Ret = Ret.OK; 359 try { 360 // 查询所有的传感器 361 const sensorList: sensor.Sensor[] = sensor.getSensorListSync(); 362 if (!sensorList.length) { 363 return Ret.Failed; 364 } 365 // 根据实际业务逻辑获取目标传感器。 366 const targetSensor = sensorList 367 // 按需过滤deviceId为1、sensorId为2的所有传感器。此处示例仅做展示，开发者需要自行调整筛选逻辑。 368 .filter((sensor: sensor.Sensor) => sensor.deviceId === 1 && sensor.sensorId === 2) 369 // 可能存在的多个同类型传感器，选择sensorIndex为0的传感器。 370 .find((sensor: sensor.Sensor) => sensor.sensorIndex === 0); 371 if (!targetSensor) { 372 return Ret.Failed; 373 } 374 sensorInfoParam.deviceId = targetSensor.deviceId; 375 sensorInfoParam.sensorIndex = targetSensor.sensorIndex; 376 // 订阅传感器事件 377 sensor.on(sensorType, sensorCallback, { sensorInfoParam }); 378 } catch (error) { 379 let e: BusinessError = error as BusinessError; 380 console.error(`Failed to invoke sensor.on. Code: ${e.code}, message: ${e.message}`); 381 ret = Ret.Failed; 382 } 383 return ret; 384} 385 386function sensorUnsubscribe(): Ret { 387 let ret: Ret = Ret.OK; 388 try { 389 sensor.off(sensorType, sensorInfoParam, sensorCallback); 390 } catch (error) { 391 let e: BusinessError = error as BusinessError; 392 console.error(`Failed to invoke sensor.off. Code: ${e.code}, message: ${e.message}`); 393 ret = Ret.Failed; 394 } 395 return ret; 396} 397``` 398 399## SensorId<sup>9+</sup> 400 401表示当前支持订阅或取消订阅的传感器类型。 402 403**系统能力**：以下各项对应的系统能力均为SystemCapability.Sensors.Sensor 404 405| 名称 | 值 | 说明 | 406| ------------------- | ---- | ----------------------------------------------- | 407| COLOR<sup>10+</sup> | 14 | 颜色传感器。<br>系统API：此接口为系统接口。 | 408| SAR<sup>10+</sup> | 15 | 吸收比率传感器。<br>系统API：此接口为系统接口。 | 409 410## ColorResponse<sup>10+</sup> 411 412颜色传感器数据，继承于[Response](js-apis-sensor.md#response)。 413 414**系统能力**：以下各项对应的系统能力均为SystemCapability.Sensors.Sensor 415 416**系统API**：此接口为系统接口 417 418 419| 名称 | 类型 | 只读 | 可选 | 说明 | 420| ---------------- | ------ | ---- | ---- | ----------------------------- | 421| lightIntensity | number | 否 | 否 | 表示光的强度，单位 : 勒克斯。 | 422| colorTemperature | number | 否 | 否 | 表示色温，单位 : 开尔文。 | 423 424## SarResponse<sup>10+ </sup> 425 426吸收比率传感器数据，继承于[Response](js-apis-sensor.md#response)。 427 428**系统能力**：以下各项对应的系统能力均为SystemCapability.Sensors.Sensor 429 430**系统API**：此接口为系统接口 431 432 433| 名称 | 类型 | 只读 | 可选 | 说明 | 434| --------------- | ------ | ---- | ---- | ------------------------------- | 435| absorptionRatio | number | 否 | 否 | 表示具体的吸收率，单位 : W/kg。 | 436 437 438## SensorInfoParam<sup>19+</sup> 439 440传感器传入设置参数。 441 442**系统能力**：以下各项对应的系统能力均为SystemCapability.Sensors.Sensor 443 444**原子化服务API**：从API Version 19开始，该接口支持在原子化服务中使用。 445 446| 名称 | 类型 | 只读 | 可选 | 说明 | 447| ----------- | -------- | ---- | ---- | -------------------------- | 448| deviceId | number | 否 | 是 | 设备ID：默认值为-1，表示本地设备，设备ID需通过[getSensorList](js-apis-sensor.md#sensorgetsensorlist9)查询或者监听设备上下线接口[on](js-apis-sensor.md#sensorstatuschange19)获取。<br/>**原子化服务API**：从API Version 19开始，该接口支持在原子化服务中使用。 | 449| sensorIndex | number | 否 | 是 | 传感器索引：默认值为0，为设备上的默认传感器。其它传感器ID需通过[getSensorList](js-apis-sensor.md#sensorgetsensorlist9)查询或者监听设备上下线接口[on](js-apis-sensor.md#sensorstatuschange19)获取<br/>**原子化服务API**：从API Version 19开始，该接口支持在原子化服务中使用。 |