diff --git a/zh-cn/application-dev/reference/apis/js-apis-system-sensor.md b/zh-cn/application-dev/reference/apis/js-apis-system-sensor.md index 545e00496d9d495c1421544bc2808a7f9c5936da..2f3d54255a9a81a80a337a8877df9e76c032fecc 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-system-sensor.md +++ b/zh-cn/application-dev/reference/apis/js-apis-system-sensor.md @@ -1,16 +1,14 @@ # @system.sensor (传感器) -## 模块说明 - sensor模块提供订阅传感器数据基本能力，主要包含查询传感器的列表、订阅/取消传感器的数据、执行控制命令等。 根据传感器的用途，可以将传感器分为六大类：运动类传感器、环境类传感器、方向类传感器、光线类传感器、健康类传感器、其他类传感器（如霍尔传感器），每一大类传感器包含不同类型的传感器，某种类型的传感器可能是单一的物理传感器，也可能是由多个物理传感器复合而成。 -> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** +> **说明：** > > - 从API Version 8开始，该接口不再维护，推荐使用新接口[`@ohos.sensor`](js-apis-sensor.md)。 -> - 本模块首批接口从API version 4开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 +> - 本模块首批接口从API version 3开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 > - 该功能使用需要对应硬件支持，仅支持真机调试。 @@ -21,15 +19,9 @@ sensor模块提供订阅传感器数据基本能力，主要包含查询传感 import sensor from '@system.sensor'; ``` -## 传感器错误码列表 - -| 错误码 | 说明 | -| ---- | -------------- | -| 900 | 当前设备不支持相应的传感器。 | - ## sensor.subscribeAccelerometer -subscribeAccelerometer(Object): void + subscribeAccelerometer(options: subscribeAccelerometerOptions): void 观察加速度数据变化。针对同一个应用，多次点击调用时，会覆盖前面的调用效果，即仅最后一次调用生效。 @@ -39,23 +31,13 @@ subscribeAccelerometer(Object): void **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | -------- | ---- | ---------------------------------------- | -| interval | string | 是 | 频率参数，加速度的回调函数执行频率。
默认为normal，可选值有：
- game：极高的回调频率，20ms/次，适用于游戏。
- ui：较高的回调频率，60ms/次，适用于UI更新。
- normal：普通的回调频率，200ms/次，低功耗。 | -| success | Function | 是 | 感应到加速度数据变化后的回调函数。 | -| fail | Function | 否 | 接口调用失败的回调函数。 | - -success返回值： - -| 参数名 | 类型 | 说明 | -| ---- | ------ | ------- | -| x | number | x轴的加速度。 | -| y | number | y轴的加速度。 | -| z | number | z轴的加速度。 | +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ------------------------------------------------------------ | ---- | ------------------------------------------ | +| options | [subscribeAccelerometerOptions](#subscribeaccelerometeroptions) | 是 | 监听加速度传感器数据的回调函数的执行频率。 | **示例：** -``` +```js sensor.subscribeAccelerometer({ interval: 'normal', success: function(ret) { @@ -69,7 +51,7 @@ sensor.subscribeAccelerometer({ }); ``` -> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** +> **说明：** > 建议在页面销毁时，即onDestory回调中，取消数据订阅，避免不必要的性能开销。 ## sensor.unsubscribeAccelerometer @@ -84,13 +66,13 @@ unsubscribeAccelerometer(): void **示例：** -``` +```js sensor.unsubscribeAccelerometer(); ``` ## sensor.subscribeCompass -subscribeCompass(Object): void + subscribeCompass(options: SubscribeCompassOptions): void 订阅罗盘数据变化。针对同一个应用，多次点击调用时，会覆盖前面的调用效果，即仅最后一次调用生效。 @@ -98,20 +80,13 @@ subscribeCompass(Object): void **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ------- | -------- | ---- | --------------- | -| success | Function | 是 | 罗盘数据改变后触发的回调函数。 | -| fail | Function | 否 | 接口调用失败的回调函数。 | - -success返回值： - -| 参数名 | 类型 | 说明 | -| --------- | ------ | ---------- | -| direction | number | 设备面对的方向度数。 | +| 参数名 | 类型 | 必填 | 说明 | +| ------- | --------------------------------------------------- | ---- | -------------------------------- | +| options | [SubscribeCompassOptions](#subscribecompassoptions) | 是 | 当罗盘传感器数据发生变化时调用。 | **示例：** -``` +```js sensor.subscribeCompass({ success: function(ret) { console.log('get data direction:' + ret.direction); @@ -122,7 +97,7 @@ sensor.subscribeCompass({ }); ``` -> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** +> **说明：** > 建议在页面销毁时，即onDestory回调中，取消数据订阅，避免不必要的性能开销。 ## sensor.unsubscribeCompass @@ -135,13 +110,13 @@ unsubscribeCompass(): void **示例：** -``` +```js sensor.unsubscribeCompass(); ``` ## sensor.subscribeProximity -subscribeProximity(Object): void + subscribeProximity(options: SubscribeProximityOptions): void 订阅距离感应数据变化。针对同一个应用，多次点击调用时，会覆盖前面的调用效果，即仅最后一次调用生效。 @@ -149,20 +124,13 @@ subscribeProximity(Object): void **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ------- | -------- | ---- | ----------------- | -| success | Function | 是 | 距离感应数据改变后调用的回调函数。 | -| fail | Function | 否 | 接口调用失败的回调函数。 | - -success返回值： - -| 参数名 | 类型 | 说明 | -| -------- | ------ | --------------------- | -| distance | number | 可见物体相对于设备显示屏的接近或远离状态。 | +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ------------------------------------------------------- | ---- | -------------------------------- | +| options | [SubscribeProximityOptions](#subscribeproximityoptions) | 是 | 当距离传感器数据发生变化时调用。 | **示例：** -``` +```js sensor.subscribeProximity({ success: function(ret) { console.log('get data distance:' + ret.distance); @@ -173,7 +141,7 @@ sensor.subscribeProximity({ }); ``` -> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** +> **说明：** > 建议在页面销毁时，即onDestory回调中，取消数据订阅，避免不必要的性能开销。 ## sensor.unsubscribeProximity @@ -186,13 +154,13 @@ unsubscribeProximity(): void **示例：** -``` +```js sensor.unsubscribeProximity(); ``` ## sensor.subscribeLight -sensor.subscribeLight(Object): void + subscribeLight(options: SubscribeLightOptions): void 订阅环境光线感应数据变化。再次调用时，会覆盖前一次调用效果，即仅最后一次调用生效。 @@ -200,20 +168,13 @@ sensor.subscribeLight(Object): void **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ------- | -------- | ---- | --------------- | -| success | Function | 是 | 光线感应数据改变后的回调函数。 | -| fail | Function | 否 | 接口调用失败的回调函数。 | - -success返回值： - -| 参数名 | 类型 | 说明 | -| --------- | ------ | ------------ | -| intensity | number | 光线强度，单位为lux。 | +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ----------------------------------------------- | ---- | ---------------------------------- | +| options | [SubscribeLightOptions](#subscribelightoptions) | 是 | 当环境光传感器数据发生变化时调用。 | **示例：** -``` +```js sensor.subscribeLight({ success: function(ret) { console.log('get data intensity:' + ret.intensity); @@ -224,7 +185,7 @@ sensor.subscribeLight({ }); ``` -> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** +> **说明：** > 建议在页面销毁时，即onDestory回调中，取消数据订阅，避免不必要的性能开销。 ## sensor.unsubscribeLight @@ -237,13 +198,13 @@ unsubscribeLight(): void **示例：** -``` +```js sensor.unsubscribeLight(); ``` ## sensor.subscribeStepCounter -subscribeStepCounter(Object): void + subscribeStepCounter(options: SubscribeStepCounterOptions): void 订阅计步传感器数据变化。针对同一个应用，多次点击调用时，会覆盖前面的调用效果，即仅最后一次调用生效。 @@ -253,20 +214,13 @@ subscribeStepCounter(Object): void **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ------- | -------- | ---- | ---------------- | -| success | Function | 是 | 计步传感器数据改变后的回调函数。 | -| fail | Function | 否 | 接口调用失败的回调函数。 | - -success返回值： - -| 参数名 | 类型 | 说明 | -| ----- | ------ | --------------------- | -| steps | number | 计步传感器重启后累计记录的步数。
| +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ----------------------------------------------------------- | ---- | -------------------------------------- | +| options | [SubscribeStepCounterOptions](#subscribestepcounteroptions) | 是 | 当步进计数器传感器数据发生变化时调用。 | **示例：** -``` +```js sensor.subscribeStepCounter({ success: function(ret) { console.log('get step value:' + ret.steps); @@ -277,7 +231,7 @@ sensor.subscribeStepCounter({ }); ``` -> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** +> **说明：** > 建议在页面销毁时，即onDestory回调中，取消数据订阅，避免不必要的性能开销。 ## sensor.unsubscribeStepCounter @@ -292,14 +246,14 @@ unsubscribeStepCounter(): void **示例：** -``` +```js sensor.unsubscribeStepCounter(); ``` ## sensor.subscribeBarometer -subscribeBarometer(Object): void +subscribeBarometer(options: SubscribeBarometerOptions): void 订阅气压传感器数据变化。针对同一个应用，多次点击调用时，会覆盖前面的调用效果，即仅最后一次调用生效。 @@ -307,20 +261,13 @@ subscribeBarometer(Object): void **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ------- | -------- | ---- | ---------------- | -| success | Function | 是 | 气压传感器数据改变后的回调函数。 | -| fail | Function | 否 | 接口调用失败的回调函数。 | - -success返回值： - -| 参数名 | 类型 | 说明 | -| -------- | ------ | ----------- | -| pressure | number | 气压值，单位：帕斯卡。 | +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ------------------------------------------------------- | ---- | ---------------------------------- | +| options | [SubscribeBarometerOptions](#subscribebarometeroptions) | 是 | 当气压计传感器数据发生变化时调用。 | **示例：** -``` +```js sensor.subscribeBarometer({ success: function(ret) { console.log('get data value:' + ret.pressure); @@ -331,7 +278,7 @@ sensor.subscribeBarometer({ }); ``` -> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** +> **说明：** > 建议在页面销毁时，即onDestory回调中，取消数据订阅，避免不必要的性能开销。 @@ -345,14 +292,14 @@ unsubscribeBarometer(): void **示例：** -``` +```js sensor.unsubscribeBarometer(); ``` ## sensor.subscribeHeartRate -subscribeHeartRate(Object): void + subscribeHeartRate(options: SubscribeHeartRateOptions): void 订阅心率传感器数据变化。针对同一个应用，多次点击调用时，会覆盖前面的调用效果，即仅最后一次调用生效。 @@ -362,20 +309,13 @@ subscribeHeartRate(Object): void **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ------- | -------- | ---- | ------------------------- | -| success | Function | 是 | 心率传感器数据改变后的回调函数，默认频率5s/次。 | -| fail | Function | 否 | 接口调用失败的回调函数。 | - -success返回值： - -| 参数名 | 类型 | 说明 | -| --------- | ------ | ---- | -| heartRate | number | 心率值。 | +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ------------------------------------------------------- | ---- | -------------------------------- | +| options | [SubscribeHeartRateOptions](#subscribeheartrateoptions) | 是 | 当心率传感器数据发生变化时调用。 | **示例：** -``` +```js sensor.subscribeHeartRate({ success: function(ret) { console.log('get heartrate value:' + ret.heartRate); @@ -386,7 +326,7 @@ sensor.subscribeHeartRate({ }); ``` -> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** +> **说明：** > 建议在页面销毁时，即onDestory回调中，取消数据订阅，避免不必要的性能开销。 @@ -402,13 +342,13 @@ unsubscribeHeartRate(): void **示例：** -``` +```js sensor.unsubscribeHeartRate(); ``` ## sensor.subscribeOnBodyState -subscribeOnBodyState(Object): void + subscribeOnBodyState(options: SubscribeOnBodyStateOptions): void 订阅设备佩戴状态。针对同一个应用，多次点击调用时，会覆盖前面的调用效果，即仅最后一次调用生效。 @@ -416,20 +356,13 @@ subscribeOnBodyState(Object): void **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| ------- | -------- | ---- | ------------- | -| success | Function | 是 | 穿戴状态改变后的回调函数。 | -| fail | Function | 否 | 接口调用失败的回调函数。 | - -success返回值： - -| 参数名 | 类型 | 说明 | -| ----- | ------- | ------ | -| value | boolean | 是否已佩戴。 | +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ----------------------------------------------------------- | ---- | ---------------------- | +| options | [SubscribeOnBodyStateOptions](#subscribeonbodystateoptions) | 是 | 当穿着状态改变时调用。 | **示例：** -``` +```js sensor.subscribeOnBodyState({ success: function(ret) { console.log('get on-body state value:' + ret.value); @@ -440,7 +373,7 @@ sensor.subscribeOnBodyState({ }); ``` -> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** +> **说明：** > 建议在页面销毁时，即onDestory回调中，取消数据订阅，避免不必要的性能开销。 ## sensor.unsubscribeOnBodyState @@ -453,13 +386,13 @@ unsubscribeOnBodyState(): void **示例：** -``` +```js sensor.unsubscribeOnBodyState(); ``` ## sensor.getOnBodyState -getOnBodyState(Object): void + getOnBodyState(options: GetOnBodyStateOptions): void 获取设备佩戴状态。 @@ -467,21 +400,13 @@ getOnBodyState(Object): void **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | -------- | ---- | ------------ | -| success | Function | 否 | 接口调用成功的回调函数。 | -| fail | Function | 否 | 接口调用失败的回调函数。 | -| complete | Function | 否 | 接口调用结束的回调函数。 | - -success返回值： - -| 参数名 | 类型 | 说明 | -| ----- | ------- | ------ | -| value | boolean | 是否已佩戴。 | +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ----------------------------------------------- | ---- | -------------------------- | +| options | [GetOnBodyStateOptions](#getonbodystateoptions) | 是 | 获取传感器磨损状态时调用。 | **示例：** -``` +```js sensor.getOnBodyState({ success: function(ret) { console.log('on body state: ' + ret.value); @@ -494,7 +419,7 @@ sensor.getOnBodyState({ ## sensor.subscribeDeviceOrientation6+ -subscribeDeviceOrientation(interval: string, success: (data: DeviceOrientationResponse), fail?: (data: string, code: number)): void + subscribeDeviceOrientation(options: SubscribeDeviceOrientationOptions): void 观察设备方向传感器数据变化。 @@ -504,22 +429,13 @@ subscribeDeviceOrientation(interval: string, success: (data: DeviceOrientationRe **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | -------- | ---- | ---------------------------------------- | -| interval | string | 是 | 频率参数，设备方向传感器的回调函数执行频率。
默认为normal，可选值有：
- game：极高的回调频率，20ms/次，适用于游戏。
- ui：较高的回调频率，60ms/次，适用于UI更新。
- normal：普通的回调频率，200ms/次，低功耗。 | -| success | Function | 是 | 感应到设备方向传感器数据变化后的回调函数。 | -| fail | Function | 否 | 接口调用失败的回调函数。 | - - success返回值： -| 参数名 | 类型 | 说明 | -| ----- | ------ | ---------------------------------------- | -| alpha | number | 当设备坐标 X/Y 和地球 X/Y 重合时，绕着 Z 轴转动的夹角为 alpha。 | -| beta | number | 当设备坐标 Y/Z 和地球 Y/Z 重合时，绕着 X 轴转动的夹角为 beta。 | -| gamma | number | 当设备 X/Z 和地球 X/Z 重合时，绕着 Y 轴转动的夹角为 gamma。 | +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ------------------------------------------------------------ | ---- | ------------------------------------------------ | +| options | [SubscribeDeviceOrientationOptions](#subscribedeviceorientationoptions) | 是 | 用于监听设备方向传感器数据的回调函数的执行频率。 | **示例：** -``` +```js sensor.subscribeDeviceOrientation({ interval: 'normal', success: function(ret) { @@ -533,7 +449,7 @@ sensor.subscribeDeviceOrientation({ }); ``` -> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** +> **说明：** > 建议在页面销毁时，即onDestory回调中，取消数据订阅，避免不必要的性能开销。 ## sensor.unsubscribeDeviceOrientation6+ @@ -546,13 +462,13 @@ unsubscribeDeviceOrientation(): void **示例：** -``` +```js sensor.unsubscribeDeviceOrientation(); ``` ## sensor.subscribeGyroscope6+ -subscribeGyroscope(interval: string, success: (data: GyroscopeResponse), fail?: (data: string, code: number)): void + subscribeGyroscope(options: SubscribeGyroscopeOptions): void 观察陀螺仪数据变化。 @@ -564,23 +480,13 @@ subscribeGyroscope(interval: string, success: (data: GyroscopeResponse), fail?: **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | -------- | ---- | ---------------------------------------- | -| interval | string | 是 | 频率参数，陀螺仪的回调函数执行频率。
默认为normal，可选值有：
- game：极高的回调频率，20ms/次，适用于游戏。
- ui：较高的回调频率，60ms/次，适用于UI更新。
- normal：普通的回调频率，200ms/次，低功耗。 | -| success | Function | 是 | 感应到陀螺仪数据变化后的回调函数。 | -| fail | Function | 否 | 接口调用失败的回调函数。 | - -success返回值： - -| 参数名 | 类型 | 说明 | -| ---- | ------ | --------- | -| x | number | x轴的旋转角速度。 | -| y | number | y轴的旋转角速度。 | -| z | number | z轴的旋转角速度。 | +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ------------------------------------------------------- | ---- | ---------------------------------------------- | +| options | [SubscribeGyroscopeOptions](#subscribegyroscopeoptions) | 是 | 用于侦听陀螺仪传感器数据的回调函数的执行频率。 | **示例：** -``` +```js sensor.subscribeGyroscope({ interval: 'normal', success: function(ret) { @@ -594,7 +500,7 @@ sensor.subscribeGyroscope({ }); ``` -> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** +> **说明：** > 建议在页面销毁时，即onDestory回调中，取消数据订阅，避免不必要的性能开销。 ## sensor.unsubscribeGyroscope6+ @@ -609,6 +515,253 @@ unsubscribeGyroscope(): void **示例：** -``` +```js sensor.unsubscribeGyroscope(); ``` + +## subscribeAccelerometerOptions + +用于监听加速度传感器数据的回调函数的执行频率。 + +**需要权限**：ohos.permission.ACCELEROMETER + +**系统能力**：SystemCapability.Sensors.Sensor + +| 名称 | 类型 | 必填 | 说明 | +| -------- | ----------------------------------------------- | ---- | ------------------------------------------------------------ | +| interval | string | 是 | 频率参数，加速度的回调函数执行频率。 默认为normal，可选值有： - game：极高的回调频率，20ms/次，适用于游戏。 - ui：较高的回调频率，60ms/次，适用于UI更新。 - normal：普通的回调频率，200ms/次，低功耗。 | +| success | [AccelerometerResponse](#accelerometerresponse) | 是 | 感应到加速度数据变化后的回调函数。 | +| fail | Function | 否 | 接口调用失败的回调函数。 | + +## AccelerometerResponse + +感应到加速度数据变化后的回调函数。 + +**需要权限**：ohos.permission.ACCELEROMETER + +**系统能力**：SystemCapability.Sensors.Sensor + +| 名称 | 类型 | 必填 | 说明 | +| ---- | ------ | ---- | ------------- | +| x | number | 是 | x轴的加速度。 | +| y | number | 是 | y轴的加速度。 | +| z | number | 是 | z轴的加速度。 | + +## SubscribeCompassOptions + +当罗盘传感器数据发生变化时调用。 + +**系统能力**：SystemCapability.Sensors.Sensor + +| 名称 | 类型 | 必填 | 说明 | +| ------- | ----------------------------------- | ---- | ------------------------------ | +| success | [CompassResponse](#compassresponse) | 是 | 罗盘数据改变后触发的回调函数。 | +| fail | Function | 否 | 接口调用失败的回调函数。 | + +## CompassResponse + +罗盘数据改变后触发的回调函数。 + +**系统能力**：SystemCapability.Sensors.Sensor + +| 名称 | 类型 | 必填 | 说明 | +| --------- | ------ | ---- | -------------------- | +| direction | number | 是 | 设备面对的方向度数。 | + +## SubscribeProximityOptions + +当距离传感器数据发生变化时调用。 + +**系统能力**：SystemCapability.Sensors.Sensor + +| 名称 | 类型 | 必填 | 说明 | +| ------- | --------------------------------------- | ---- | ---------------------------------- | +| success | [ProximityResponse](#proximityresponse) | 是 | 距离感应数据改变后调用的回调函数。 | +| fail | Function | 否 | 接口调用失败的回调函数。 | + +## ProximityResponse + +距离感应数据改变后调用的回调函数。 + +**系统能力**：SystemCapability.Sensors.Sensor + +| 名称 | 类型 | 必填 | 说明 | +| -------- | ------ | ---- | ------------------------------------------ | +| distance | number | 是 | 可见物体相对于设备显示屏的接近或远离状态。 | + +## SubscribeLightOptions + +当环境光传感器数据发生变化时调用。 + +**系统能力**：SystemCapability.Sensors.Sensor + +| 名称 | 类型 | 必填 | 说明 | +| ------- | ------------------------------- | ---- | ------------------------------ | +| success | [LightResponse](#lightresponse) | 是 | 光线感应数据改变后的回调函数。 | +| fail | Function | 否 | 接口调用失败的回调函数。 | + +## LightResponse + +光线感应数据改变后的回调函数。 + +**系统能力**：SystemCapability.Sensors.Sensor + +| 名称 | 类型 | 必填 | 说明 | +| --------- | ------ | ---- | --------------------- | +| intensity | number | 是 | 光线强度，单位为lux。 | + +## SubscribeStepCounterOptions + +当步进计数器传感器数据发生变化时调用。 + +**需要权限**：ohos.permission.ACTIVITY_MOTION + +**系统能力**：SystemCapability.Sensors.Sensor + +| 名称 | 类型 | 必填 | 说明 | +| ------- | ------------------------------------------- | ---- | -------------------------------- | +| success | [StepCounterResponse](#stepcounterresponse) | 是 | 计步传感器数据改变后的回调函数。 | +| fail | Function | 否 | 接口调用失败的回调函数。 | + +## StepCounterResponse + +计步传感器数据改变后的回调函数。 + +**需要权限**：ohos.permission.ACTIVITY_MOTION + +**系统能力**：SystemCapability.Sensors.Sensor + +| 名称 | 类型 | 必填 | 说明 | +| ----- | ------ | ---- | -------------------------------- | +| steps | number | 是 | 计步传感器重启后累计记录的步数。 | + +## SubscribeBarometerOptions + +当气压计传感器数据发生变化时调用。 + +**系统能力**：SystemCapability.Sensors.Sensor + +| 名称 | 类型 | 必填 | 说明 | +| ------- | --------------------------------------- | ---- | -------------------------------- | +| success | [BarometerResponse](#barometerresponse) | 是 | 气压传感器数据改变后的回调函数。 | +| fail | Function | 否 | 接口调用失败的回调函数。 | + +## BarometerResponse + +气压传感器数据改变后的回调函数。 + +**系统能力**：SystemCapability.Sensors.Sensor + +| 名称 | 类型 | 必填 | 说明 | +| -------- | ------ | ---- | ---------------------- | +| pressure | number | 是 | 气压值，单位：帕斯卡。 | + +## SubscribeHeartRateOptions + +当心率传感器数据发生变化时调用。 + +**需要权限**：ohos.permission.READ_HEALTH_DATA + +**系统能力**：SystemCapability.Sensors.Sensor + +| 名称 | 类型 | 必填 | 说明 | +| ------- | --------------------------------------- | ---- | ----------------------------------------------- | +| success | [HeartRateResponse](#heartrateresponse) | 是 | 心率传感器数据改变后的回调函数，默认频率5s/次。 | +| fail | Function | 否 | 接口调用失败的回调函数。 | + +## HeartRateResponse + +心率传感器数据改变后的回调函数，默认频率5s/次。 + +**需要权限**：ohos.permission.READ_HEALTH_DATA + +**系统能力**：SystemCapability.Sensors.Sensor + +| 名称 | 类型 | 必填 | 说明 | +| --------- | ------ | ---- | -------- | +| heartRate | number | 是 | 心率值。 | + +## SubscribeOnBodyStateOptions + +当穿着状态改变时调用。 + +**系统能力**：SystemCapability.Sensors.Sensor + +| 名称 | 类型 | 必填 | 说明 | +| ------- | ------------------------------------------- | ---- | -------------------------- | +| success | [OnBodyStateResponse](#onbodystateresponse) | 是 | 穿戴状态改变后的回调函数。 | +| fail | Function | 否 | 接口调用失败的回调函数。 | + +## OnBodyStateResponse + +传感器是否磨损。 + +**系统能力**：SystemCapability.Sensors.Sensor + +| 名称 | 类型 | 必填 | 说明 | +| ----- | ------- | ---- | ------------ | +| value | boolean | 是 | 是否已佩戴。 | + +## GetOnBodyStateOptions + + 获取传感器磨损状态时调用。 + +**系统能力**：SystemCapability.Sensors.Sensor + +| 名称 | 类型 | 必填 | 说明 | +| -------- | ------------------------------------------- | ---- | ------------------------ | +| success | [OnBodyStateResponse](#onbodystateresponse) | 否 | 接口调用成功的回调函数。 | +| fail | Function | 否 | 接口调用失败的回调函数。 | +| complete | Function | 否 | 接口调用结束的回调函数。 | + +## SubscribeDeviceOrientationOptions6+ + +用于监听设备方向传感器数据的回调函数的执行频率。 + +**系统能力**：SystemCapability.Sensors.Sensor + +| 名称 | 类型 | 必填 | 说明 | +| -------- | ------------------------------------------------------- | ---- | ------------------------------------------------------------ | +| interval | string | 是 | 频率参数，设备方向传感器的回调函数执行频率。
默认为normal，可选值有：
- game：极高的回调频率，20ms/次，适用于游戏。
- ui：较高的回调频率，60ms/次，适用于UI更新。
- normal：普通的回调频率，200ms/次，低功耗。 | +| success | [DeviceOrientationResponse](#deviceorientationresponse) | 是 | 感应到设备方向传感器数据变化后的回调函数。 | +| fail | Function | 否 | 接口调用失败的回调函数。 | + +## DeviceOrientationResponse6+ + +感应到设备方向传感器数据变化后的回调函数。 + +**系统能力**：SystemCapability.Sensors.Sensor + +| 名称 | 类型 | 必填 | 说明 | +| ----- | ------ | ---- | ------------------------------------------------------------ | +| alpha | number | 是 | 当设备坐标 X/Y 和地球 X/Y 重合时，绕着 Z 轴转动的夹角为 alpha。 | +| beta | number | 是 | 当设备坐标 Y/Z 和地球 Y/Z 重合时，绕着 X 轴转动的夹角为 beta。 | +| gamma | number | 是 | 当设备 X/Z 和地球 X/Z 重合时，绕着 Y 轴转动的夹角为 gamma。 | + +## SubscribeGyroscopeOptions6+ + +用于侦听陀螺仪传感器数据的回调函数的执行频率。 + +**需要权限**：ohos.permission.GYROSCOPE + +**系统能力**：SystemCapability.Sensors.Sensor + +| 名称 | 类型 | 必填 | 说明 | +| -------- | --------------------------------------- | ---- | ------------------------------------------------------------ | +| interval | string | 是 | 频率参数，陀螺仪的回调函数执行频率。
默认为normal，可选值有：
- game：极高的回调频率，20ms/次，适用于游戏。
- ui：较高的回调频率，60ms/次，适用于UI更新。
- normal：普通的回调频率，200ms/次，低功耗。 | +| success | [GyroscopeResponse](#gyroscoperesponse) | 是 | 感应到陀螺仪数据变化后的回调函数。 | +| fail | Function | 否 | 接口调用失败的回调函数。 | + +## GyroscopeResponse6+ + +感应到陀螺仪数据变化后的回调函数。 + +**需要权限**：ohos.permission.GYROSCOPE + +**系统能力**：SystemCapability.Sensors.Sensor + +| 名称 | 类型 | 必填 | 说明 | +| ---- | ------ | ---- | ----------------- | +| x | number | 是 | x轴的旋转角速度。 | +| y | number | 是 | y轴的旋转角速度。 | +| z | number | 是 | z轴的旋转角速度。 | \ No newline at end of file diff --git a/zh-cn/application-dev/reference/apis/js-apis-system-vibrate.md b/zh-cn/application-dev/reference/apis/js-apis-system-vibrate.md index c77faf7b3978c263e41591c796e7bbb8fec4b8f5..7726086cc4e0c4e0327b773d8278e9240fcb5041 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-system-vibrate.md +++ b/zh-cn/application-dev/reference/apis/js-apis-system-vibrate.md @@ -1,14 +1,12 @@ # @system.vibrator (振动) -## 模块说明 - vibrator模块提供控制马达振动的能力，主要包含灯的列表查询、打开灯、关闭灯等接口，振动器的列表查询、振动器的振动器效果查询、触发/关闭振动器等接口。 控制类小器件指的是设备上的LED灯和振动器。其中，LED灯主要用作指示（如充电状态）、闪烁功能（如三色灯）等；振动器主要用于闹钟、开关机振动、来电振动等场景。 -> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：** -> - 本模块首批接口从API version 4开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 +> **说明：** +> - 本模块首批接口从API version 3开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 > - 从API Version 8开始，该接口不再维护，推荐使用新接口[`@ohos.vibrator`](js-apis-vibrator.md)。 > - 该功能使用需要对应硬件支持，仅支持真机调试。 @@ -22,26 +20,23 @@ import vibrator from '@system.vibrator'; ## vibrator.vibrate -vibrate(Object): void + vibrate(options?: VibrateOptions): void 触发设备振动。 -**系统能力**：SystemCapability.Sensors.MiscDevice +**需要权限**：ohos.permission.VIBRATE -**需要权限**：ohos.permission.VIBRATE，该权限为系统权限 +**系统能力**：SystemCapability.Sensors.MiscDevice **参数：** -| 参数名 | 类型 | 必填 | 说明 | -| -------- | -------- | -------- | -------- | -| mode | string | 否 | 振动的模式，其中long表示长振动，short表示短振动，默认值为long。 | -| success | Function | 是 | 感应到振动数据变化后的回调函数。 | -| fail | Function | 否 | 接口调用失败的回调函数。 | -| complete | Function | 否 | 接口调用结束的回调函数。 | +| 参数名 | 类型 | 必填 | 说明 | +| ------- | --------------------------------- | ---- | ---------- | +| options | [VibrateOptions](#vibrateoptions) | 否 | 振动模式。 | **示例：** -``` +```js vibrator.vibrate({ mode: 'short', success: function() { @@ -56,3 +51,17 @@ vibrator.vibrate({ }); ``` +## VibrateOptions + +振动模式。 + +**需要权限**：ohos.permission.VIBRATE + +**系统能力**：SystemCapability.Sensors.MiscDevice + +| 名称 | 类型 | 必填 | 说明 | +| -------- | -------- | ---- | ------------------------------------------------------------ | +| mode | string | 否 | 振动的模式，其中long表示长振动，short表示短振动，默认值为long。 | +| success | Function | 否 | 感应到振动数据变化后的回调函数。 | +| fail | Function | 否 | 接口调用失败的回调函数。 | +| complete | Function | 否 | 接口调用结束的回调函数。 | \ No newline at end of file