1# 传感器 2 3 4>  **说明：** 5> 6> - 从API Version 8开始，该接口不再维护，推荐使用新接口[`@ohos.sensor`](js-apis-sensor.md)。 7> - 本模块首批接口从API version 4开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8> - 该功能使用需要对应硬件支持，仅支持真机调试。 9 10 11## 导入模块 12 13 14``` 15import sensor from '@system.sensor'; 16``` 17 18 19## 传感器错误码列表 20 21| 错误码 | 说明 | 22| ---- | -------------- | 23| 900 | 当前设备不支持相应的传感器。 | 24 25## sensor.subscribeAccelerometer 26 27subscribeAccelerometer(Object): void 28 29观察加速度数据变化。针对同一个应用，多次点击调用时，会覆盖前面的调用效果，即仅最后一次调用生效。 30 31**系统能力**：SystemCapability.Sensors.Sensor 32 33**需要权限**：ohos.permission.ACCELEROMETER，该权限为系统权限 34 35**参数：** 36 37| 参数名 | 类型 | 必填 | 说明 | 38| -------- | -------- | ---- | ---------------------------------------- | 39| interval | string | 是 | 频率参数，加速度的回调函数执行频率。<br/>默认为normal，可选值有：<br/>- game：极高的回调频率，20ms/次，适用于游戏。<br/>- ui：较高的回调频率，60ms/次，适用于UI更新。<br/>- normal：普通的回调频率，200ms/次，低功耗。 | 40| success | Function | 是 | 感应到加速度数据变化后的回调函数。 | 41| fail | Function | 否 | 接口调用失败的回调函数。 | 42 43success返回值： 44 45| 参数名 | 类型 | 说明 | 46| ---- | ------ | ------- | 47| x | number | x轴的加速度。 | 48| y | number | y轴的加速度。 | 49| z | number | z轴的加速度。 | 50 51**示例：** 52 53``` 54sensor.subscribeAccelerometer({ 55 interval: 'normal', 56 success: function(ret) { 57 console.log('X-axis data: ' + ret.x); 58 console.log('Y-axis data: ' + ret.y); 59 console.log('Z-axis data: ' + ret.z); 60 }, 61 fail: function(data, code) { 62 console.error('Subscription failed. Code: ' + code + '; Data: ' + data); 63 }, 64}); 65``` 66 67>  **说明：** 68> 建议在页面销毁时，即onDestory回调中，取消数据订阅，避免不必要的性能开销。 69 70## sensor.unsubscribeAccelerometer 71 72unsubscribeAccelerometer(): void 73 74取消订阅加速度数据。 75 76**系统能力**：SystemCapability.Sensors.Sensor 77 78**需要权限**：ohos.permission.ACCELEROMETER，该权限为系统权限 79 80**示例：** 81 82``` 83sensor.unsubscribeAccelerometer(); 84``` 85 86## sensor.subscribeCompass 87 88subscribeCompass(Object): void 89 90订阅罗盘数据变化。针对同一个应用，多次点击调用时，会覆盖前面的调用效果，即仅最后一次调用生效。 91 92**系统能力**：SystemCapability.Sensors.Sensor 93 94**参数：** 95 96| 参数名 | 类型 | 必填 | 说明 | 97| ------- | -------- | ---- | --------------- | 98| success | Function | 是 | 罗盘数据改变后触发的回调函数。 | 99| fail | Function | 否 | 接口调用失败的回调函数。 | 100 101success返回值： 102 103| 参数名 | 类型 | 说明 | 104| --------- | ------ | ---------- | 105| direction | number | 设备面对的方向度数。 | 106 107**示例：** 108 109``` 110sensor.subscribeCompass({ 111 success: function(ret) { 112 console.log('get data direction:' + ret.direction); 113 }, 114 fail: function(data, code) { 115 console.error('Subscription failed. Code: ' + code + '; Data: ' + data); 116 }, 117}); 118``` 119 120>  **说明：** 121> 建议在页面销毁时，即onDestory回调中，取消数据订阅，避免不必要的性能开销。 122 123## sensor.unsubscribeCompass 124 125unsubscribeCompass(): void 126 127取消订阅罗盘。 128 129**系统能力**：SystemCapability.Sensors.Sensor 130 131**示例：** 132 133``` 134sensor.unsubscribeCompass(); 135``` 136 137## sensor.subscribeProximity 138 139subscribeProximity(Object): void 140 141订阅距离感应数据变化。针对同一个应用，多次点击调用时，会覆盖前面的调用效果，即仅最后一次调用生效。 142 143**系统能力**：SystemCapability.Sensors.Sensor 144 145**参数：** 146 147| 参数名 | 类型 | 必填 | 说明 | 148| ------- | -------- | ---- | ----------------- | 149| success | Function | 是 | 距离感应数据改变后调用的回调函数。 | 150| fail | Function | 否 | 接口调用失败的回调函数。 | 151 152success返回值： 153 154| 参数名 | 类型 | 说明 | 155| -------- | ------ | --------------------- | 156| distance | number | 可见物体相对于设备显示屏的接近或远离状态。 | 157 158**示例：** 159 160``` 161sensor.subscribeProximity({ 162 success: function(ret) { 163 console.log('get data distance:' + ret.distance); 164 }, 165 fail: function(data, code) { 166 console.error('Subscription failed. Code: ' + code + '; Data: ' + data); 167 }, 168}); 169``` 170 171>  **说明：** 172> 建议在页面销毁时，即onDestory回调中，取消数据订阅，避免不必要的性能开销。 173 174## sensor.unsubscribeProximity 175 176unsubscribeProximity(): void 177 178取消订阅距离感应。 179 180**系统能力**：SystemCapability.Sensors.Sensor 181 182**示例：** 183 184``` 185sensor.unsubscribeProximity(); 186``` 187 188## sensor.subscribeLight 189 190sensor.subscribeLight(Object): void 191 192订阅环境光线感应数据变化。再次调用时，会覆盖前一次调用效果，即仅最后一次调用生效。 193 194**系统能力**：SystemCapability.Sensors.Sensor 195 196**参数：** 197 198| 参数名 | 类型 | 必填 | 说明 | 199| ------- | -------- | ---- | --------------- | 200| success | Function | 是 | 光线感应数据改变后的回调函数。 | 201| fail | Function | 否 | 接口调用失败的回调函数。 | 202 203success返回值： 204 205| 参数名 | 类型 | 说明 | 206| --------- | ------ | ------------ | 207| intensity | number | 光线强度，单位为lux。 | 208 209**示例：** 210 211``` 212sensor.subscribeLight({ 213 success: function(ret) { 214 console.log('get data intensity:' + ret.intensity); 215 }, 216 fail: function(data, code) { 217 console.error('Subscription failed. Code: ' + code + '; Data: ' + data); 218 }, 219}); 220``` 221 222>  **说明：** 223> 建议在页面销毁时，即onDestory回调中，取消数据订阅，避免不必要的性能开销。 224 225## sensor.unsubscribeLight 226 227unsubscribeLight(): void 228 229取消订阅环境光线感应。 230 231**系统能力**：SystemCapability.Sensors.Sensor 232 233**示例：** 234 235``` 236sensor.unsubscribeLight(); 237``` 238 239## sensor.subscribeStepCounter 240 241subscribeStepCounter(Object): void 242 243订阅计步传感器数据变化。针对同一个应用，多次点击调用时，会覆盖前面的调用效果，即仅最后一次调用生效。 244 245**系统能力**：SystemCapability.Sensors.Sensor 246 247**需要权限**：ohos.permission.ACTIVITY_MOTION 248 249**参数：** 250 251| 参数名 | 类型 | 必填 | 说明 | 252| ------- | -------- | ---- | ---------------- | 253| success | Function | 是 | 计步传感器数据改变后的回调函数。 | 254| fail | Function | 否 | 接口调用失败的回调函数。 | 255 256success返回值： 257 258| 参数名 | 类型 | 说明 | 259| ----- | ------ | --------------------- | 260| steps | number | 计步传感器重启后累计记录的步数。<br/> | 261 262**示例：** 263 264``` 265sensor.subscribeStepCounter({ 266 success: function(ret) { 267 console.log('get step value:' + ret.steps); 268 }, 269 fail: function(data, code) { 270 console.log('Subscription failed. Code: ' + code + '; Data: ' + data); 271 }, 272}); 273``` 274 275>  **说明：** 276> 建议在页面销毁时，即onDestory回调中，取消数据订阅，避免不必要的性能开销。 277 278## sensor.unsubscribeStepCounter 279 280unsubscribeStepCounter(): void 281 282取消订阅计步传感器。 283 284**系统能力**：SystemCapability.Sensors.Sensor 285 286**需要权限**：ohos.permission.ACTIVITY_MOTION 287 288**示例：** 289 290``` 291sensor.unsubscribeStepCounter(); 292``` 293 294 295## sensor.subscribeBarometer 296 297subcribeBarometer(Object): void 298 299订阅气压传感器数据变化。针对同一个应用，多次点击调用时，会覆盖前面的调用效果，即仅最后一次调用生效。 300 301**系统能力**：SystemCapability.Sensors.Sensor 302 303**参数：** 304 305| 参数名 | 类型 | 必填 | 说明 | 306| ------- | -------- | ---- | ---------------- | 307| success | Function | 是 | 气压传感器数据改变后的回调函数。 | 308| fail | Function | 否 | 接口调用失败的回调函数。 | 309 310success返回值： 311 312| 参数名 | 类型 | 说明 | 313| -------- | ------ | ----------- | 314| pressure | number | 气压值，单位：帕斯卡。 | 315 316**示例：** 317 318``` 319sensor.subscribeBarometer({ 320 success: function(ret) { 321 console.log('get data value:' + ret.pressure); 322 }, 323 fail: function(data, code) { 324 console.log('Subscription failed. Code: ' + code + '; Data: ' + data); 325 }, 326}); 327``` 328 329>  **说明：** 330> 建议在页面销毁时，即onDestory回调中，取消数据订阅，避免不必要的性能开销。 331 332 333## sensor.unsubscribeBarometer 334 335unsubscribeBarometer(): void 336 337取消订阅气压传感器。 338 339**系统能力**：SystemCapability.Sensors.Sensor 340 341**示例：** 342 343``` 344sensor.unsubscribeBarometer(); 345``` 346 347 348## sensor.subscribeHeartRate 349 350subscribeHeartRate(Object): void 351 352订阅心率传感器数据变化。针对同一个应用，多次点击调用时，会覆盖前面的调用效果，即仅最后一次调用生效。 353 354**系统能力**：SystemCapability.Sensors.Sensor 355 356**需要权限**：ohos.permission.READ_HEALTH_DATA 357 358**参数：** 359 360| 参数名 | 类型 | 必填 | 说明 | 361| ------- | -------- | ---- | ------------------------- | 362| success | Function | 是 | 心率传感器数据改变后的回调函数，默认频率5s/次。 | 363| fail | Function | 否 | 接口调用失败的回调函数。 | 364 365success返回值： 366 367| 参数名 | 类型 | 说明 | 368| --------- | ------ | ---- | 369| heartRate | number | 心率值。 | 370 371**示例：** 372 373``` 374sensor.subscribeHeartRate({ 375 success: function(ret) { 376 console.log('get heartrate value:' + ret.heartRate); 377 }, 378 fail: function(data, code) { 379 console.log('Subscription failed. Code: ' + code + '; Data: ' + data); 380 }, 381}); 382``` 383 384>  **说明：** 385> 建议在页面销毁时，即onDestory回调中，取消数据订阅，避免不必要的性能开销。 386 387 388## sensor.unsubscribeHeartRate 389 390unsubscribeHeartRate(): void 391 392取消订阅心率。 393 394**系统能力**：SystemCapability.Sensors.Sensor 395 396**需要权限**：ohos.permission.READ_HEALTH_DATA 397 398**示例：** 399 400``` 401sensor.unsubscribeHeartRate(); 402``` 403 404## sensor.subscribeOnBodyState 405 406subscribeOnBodyState(Object): void 407 408订阅设备佩戴状态。针对同一个应用，多次点击调用时，会覆盖前面的调用效果，即仅最后一次调用生效。 409 410**系统能力**：SystemCapability.Sensors.Sensor 411 412**参数：** 413 414| 参数名 | 类型 | 必填 | 说明 | 415| ------- | -------- | ---- | ------------- | 416| success | Function | 是 | 穿戴状态改变后的回调函数。 | 417| fail | Function | 否 | 接口调用失败的回调函数。 | 418 419success返回值： 420 421| 参数名 | 类型 | 说明 | 422| ----- | ------- | ------ | 423| value | boolean | 是否已佩戴。 | 424 425**示例：** 426 427``` 428sensor.subscribeOnBodyState({ 429 success: function(ret) { 430 console.log('get on-body state value:' + ret.value); 431 }, 432 fail: function(data, code) { 433 console.log('Subscription failed. Code: ' + code + '; Data: ' + data); 434 }, 435}); 436``` 437 438>  **说明：** 439> 建议在页面销毁时，即onDestory回调中，取消数据订阅，避免不必要的性能开销。 440 441## sensor.unsubscribeOnBodyState 442 443unsubscribeOnBodyState(): void 444 445取消订阅设备佩戴状态。 446 447**系统能力**：SystemCapability.Sensors.Sensor 448 449**示例：** 450 451``` 452sensor.unsubscribeOnBodyState(); 453``` 454 455## sensor.getOnBodyState 456 457getOnBodyState(Object): void 458 459获取设备佩戴状态。 460 461**系统能力**：SystemCapability.Sensors.Sensor 462 463**参数：** 464 465| 参数名 | 类型 | 必填 | 说明 | 466| -------- | -------- | ---- | ------------ | 467| success | Function | 否 | 接口调用成功的回调函数。 | 468| fail | Function | 否 | 接口调用失败的回调函数。 | 469| complete | Function | 否 | 接口调用结束的回调函数。 | 470 471success返回值： 472 473| 参数名 | 类型 | 说明 | 474| ----- | ------- | ------ | 475| value | boolean | 是否已佩戴。 | 476 477**示例：** 478 479``` 480sensor.getOnBodyState({ 481 success: function(ret) { 482 console.log('on body state: ' + ret.value); 483 }, 484 fail: function(data, code) { 485 console.log('Subscription failed. Code: ' + code + '; Data: ' + data); 486 }, 487}); 488``` 489 490## sensor.subscribeDeviceOrientation<sup>6+</sup> 491 492subscribeDeviceOrientation(interval: string, success: (data: DeviceOrientationResponse), fail?: (data: string, code: number)): void 493 494观察设备方向传感器数据变化。 495 496针对同一个应用，多次点击调用时，会覆盖前面的调用效果，即仅最后一次调用生效；针对同一个方法内，不支持多次调用。 497 498**系统能力**：SystemCapability.Sensors.Sensor 499 500**参数：** 501 502| 参数名 | 类型 | 必填 | 说明 | 503| -------- | -------- | ---- | ---------------------------------------- | 504| interval | string | 是 | 频率参数，设备方向传感器的回调函数执行频率。<br/>默认为normal，可选值有：<br/>- game：极高的回调频率，20ms/次，适用于游戏。<br/>- ui：较高的回调频率，60ms/次，适用于UI更新。<br/>- normal：普通的回调频率，200ms/次，低功耗。 | 505| success | Function | 是 | 感应到设备方向传感器数据变化后的回调函数。 | 506| fail | Function | 否 | 接口调用失败的回调函数。 | 507 508 success返回值： 509| 参数名 | 类型 | 说明 | 510| ----- | ------ | ---------------------------------------- | 511| alpha | number | 当设备坐标 X/Y 和地球 X/Y 重合时，绕着 Z 轴转动的夹角为 alpha。 | 512| beta | number | 当设备坐标 Y/Z 和地球 Y/Z 重合时，绕着 X 轴转动的夹角为 beta。 | 513| gamma | number | 当设备 X/Z 和地球 X/Z 重合时，绕着 Y 轴转动的夹角为 gamma。 | 514 515**示例：** 516 517``` 518sensor.subscribeDeviceOrientation({ 519 interval: 'normal', 520 success: function(ret) { 521 console.log('Alpha data: ' + ret.alpha); 522 console.log('Beta data: ' + ret.beta); 523 console.log('Gamma data: ' + ret.gamma); 524 }, 525 fail: function(data, code) { 526 console.error('Subscription failed. Code: ' + code + '; Data: ' + data); 527 } 528}); 529``` 530 531>  **说明：** 532> 建议在页面销毁时，即onDestory回调中，取消数据订阅，避免不必要的性能开销。 533 534## sensor.unsubscribeDeviceOrientation<sup>6+</sup> 535 536unsubscribeDeviceOrientation(): void 537 538取消订阅设备方向传感器数据。 539 540**系统能力**：SystemCapability.Sensors.Sensor 541 542**示例：** 543 544``` 545sensor.unsubscribeDeviceOrientation(); 546``` 547 548## sensor.subscribeGyroscope<sup>6+</sup> 549 550subscribeGyroscope(interval: string, success: (data: GyroscopeResponse), fail?: (data: string, code: number)): void 551 552观察陀螺仪数据变化。 553 554针对同一个应用，多次点击调用时，会覆盖前面的调用效果，即仅最后一次调用生效；针对同一个方法内，不支持多次调用。 555 556**系统能力**：SystemCapability.Sensors.Sensor 557 558**需要权限**：ohos.permission.GYROSCOPE，该权限为系统权限 559 560**参数：** 561 562| 参数名 | 类型 | 必填 | 说明 | 563| -------- | -------- | ---- | ---------------------------------------- | 564| interval | string | 是 | 频率参数，陀螺仪的回调函数执行频率。<br/>默认为normal，可选值有：<br/>- game：极高的回调频率，20ms/次，适用于游戏。<br/>- ui：较高的回调频率，60ms/次，适用于UI更新。<br/>- normal：普通的回调频率，200ms/次，低功耗。 | 565| success | Function | 是 | 感应到陀螺仪数据变化后的回调函数。 | 566| fail | Function | 否 | 接口调用失败的回调函数。 | 567 568success返回值： 569 570| 参数名 | 类型 | 说明 | 571| ---- | ------ | --------- | 572| x | number | x轴的旋转角速度。 | 573| y | number | y轴的旋转角速度。 | 574| z | number | z轴的旋转角速度。 | 575 576**示例：** 577 578``` 579sensor.subscribeGyroscope({ 580 interval: 'normal', 581 success: function(ret) { 582 console.log('X-axis data: ' + ret.x); 583 console.log('Y-axis data: ' + ret.y); 584 console.log('Z-axis data: ' + ret.z); 585 }, 586 fail: function(data, code) { 587 console.error('Subscription failed. Code: ' + code + '; data: ' + data); 588 } 589}); 590``` 591 592>  **说明：** 593> 建议在页面销毁时，即onDestory回调中，取消数据订阅，避免不必要的性能开销。 594 595## sensor.unsubscribeGyroscope<sup>6+</sup> 596 597unsubscribeGyroscope(): void 598 599取消订阅陀螺仪数据。 600 601**系统能力**：SystemCapability.Sensors.Sensor 602 603**需要权限**：ohos.permission.GYROSCOPE，该权限为系统权限 604 605**示例：** 606 607``` 608sensor.unsubscribeGyroscope(); 609``` 610
