From 8ac2c58ed7104017e24bed4663004d3cd36cc514 Mon Sep 17 00:00:00 2001 From: wangmaolin Date: Mon, 30 Jun 2025 19:15:02 +0800 Subject: [PATCH] Sensor Add API 19 Document Signed-off-by: wangmaolin --- .../device/sensor/sensor-guidelines.md | 83 +- .../device/sensor/sensorservice-kit-intro.md | 11 +- .../device/sensor/vibrator-guidelines.md | 126 +- .../js-apis-sensor-sys.md | 177 +- .../apis-sensor-service-kit/js-apis-sensor.md | 2178 +++++++++++++++-- .../js-apis-vibrator.md | 286 ++- 6 files changed, 2651 insertions(+), 210 deletions(-) diff --git a/zh-cn/application-dev/device/sensor/sensor-guidelines.md b/zh-cn/application-dev/device/sensor/sensor-guidelines.md index ee3936492e5..eaa2a8b4b91 100644 --- a/zh-cn/application-dev/device/sensor/sensor-guidelines.md +++ b/zh-cn/application-dev/device/sensor/sensor-guidelines.md @@ -10,12 +10,15 @@ ## 接口说明 -| 名称 | 描述 | -| -------- | -------- | -| sensor.on(sensorId, callback:AsyncCallback<Response>): void | 持续监听传感器数据变化。 | -| sensor.once(sensorId, callback:AsyncCallback<Response>): void | 获取一次传感器数据变化。 | -| sensor.off(sensorId, callback?:AsyncCallback<void>): void | 注销传感器数据的监听。 | -| sensor.getSensorList(callback: AsyncCallback\>): void| 获取设备上的所有传感器信息。 | +| 名称 | 描述 | +| -------- |---------------------------------| +| sensor.on(sensorId, callback:AsyncCallback<Response>, options?: Options): void | 持续监听传感器数据变化。 | +| sensor.on(type: 'sensorStatusChange', callback: Callback<SensorStatusEvent>): void | 监听传感器动态上下线的状态变化，callback返回传感器状态事件数据。 | +| sensor.once(sensorId, callback:AsyncCallback<Response>): void | 获取一次传感器数据变化。 | +| sensor.off(sensorId, callback?:AsyncCallback<void>): void | 注销传感器数据的监听。 | +| sensor.off(sensorId, sensorInfoParam?: SensorInfoParam, callback?:AsyncCallback<void>): void | 注销传感器数据的监听，可传入设置参数。 | +| sensor.off(type: 'sensorStatusChange', callback?: Callback<SensorStatusEvent>): void | 注销传感器动态上下线的状态变化的监听。 | +| sensor.getSensorList(callback: AsyncCallback\>): void| 获取设备上的所有传感器信息。 | ## 开发步骤 @@ -48,16 +51,53 @@ 该传感器支持的最小采样周期为5000000纳秒，最大采样周期是200000000纳秒。不同传感器支持的采样周期范围也不同，interval应该设置在传感器支持范围内，大于最大值时以最大值上报数据，小于最小值时以最小值上报数据。设置数值越小数据上报越频繁，其功耗越大。 + 根据设备Id查询传感器。 + ```ts + try { + const deviceId = 1; + // 第一个参数deviceId 非必填，默认查询的为本地设备 + const sensorList: sensor.Sensor[] = sensor.getSensorListByDeviceSync(deviceId); + console.log(`sensorList length: ${sensorList.length}`); + console.log(`sensorList: ${JSON.stringify(sensorList)}`); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to get sensorList. Code: ${e.code}, message: ${e.message}`); + } + ``` + 3. 检查是否已经配置相应权限，具体配置方式请参考[声明权限](../../security/AccessToken/declare-permissions.md)。 4. 注册监听。可以通过on()和once()两种接口监听传感器的调用结果。 通过on()接口，实现对传感器的持续监听，传感器上报周期interval设置为100000000纳秒。 - ```ts - sensor.on(sensor.SensorId.ACCELEROMETER, (data: sensor.AccelerometerResponse) => { - console.info("Succeeded in obtaining data. x: " + data.x + " y: " + data.y + " z: " + data.z); - }, { interval: 100000000 }); + ```ts + import { sensor } from '@kit.SensorServiceKit'; + import { BusinessError } from '@kit.BasicServicesKit'; + + try { + sensor.on(sensor.SensorId.ACCELEROMETER, (data: sensor.AccelerometerResponse) => { + console.info("Succeeded in obtaining data. x: " + data.x + " y: " + data.y + " z: " + data.z); + }, { interval: 100000000 }); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to get sensorList. Code: ${e.code}, message: ${e.message}`); + } + ``` + + 第三个参数还可以传入SensorInfoParam，传递deviceId、sensorIndex。 + ```ts + import { sensor } from '@kit.SensorServiceKit'; + import { BusinessError } from '@kit.BasicServicesKit'; + + try { + sensor.on(sensor.SensorId.ACCELEROMETER, (data: sensor.AccelerometerResponse) => { + console.info("Succeeded in obtaining data. x: " + data.x + " y: " + data.y + " z: " + data.z); + }, { interval: 100000000, sensorInfoParam: { deviceId: 1, sensorIndex: 3 } }); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to get sensorList. Code: ${e.code}, message: ${e.message}`); + } ``` ![输入图片说明](figures/002.png) @@ -74,6 +114,29 @@ 5. 取消持续监听。 + 取消持续监听，此场景下未订阅而取消监听为异常行为，需处理异常。 ```ts sensor.off(sensor.SensorId.ACCELEROMETER); + ``` + + 根据SensorInfoParam取消监听。 + ```ts + sensor.off(sensor.SensorId.ACCELEROMETER, { deviceId: 1, sensorIndex: 3 }); + ``` + +6. 动态传感器状态的监听，在收到设备下线事件通知时，用户应主动调用off关闭该设备上的传感器。 + + 注册监听, SensorStatusEvent 会返回事件时间戳、传感器ID、传感器索引、上线或下线、设备id、设备名称等值。 + ```ts + sensor.on('sensorStatusChange', (data: sensor.SensorStatusEvent) => { + console.log(`timestamp: ${data.timestamp}, + deviceId: ${data.deviceId} deviceName: ${data.deviceName} + sensorId: ${data.sensorId} sensorIndex:${data.sensorIndex} isSensorOnline: ${data.isSensorOnline}`) + }); + ``` + + 取消监听。 + ```ts + // 请在订阅后在使用此接口取消订阅 + sensor.off('sensorStatusChange'); ``` \ No newline at end of file diff --git a/zh-cn/application-dev/device/sensor/sensorservice-kit-intro.md b/zh-cn/application-dev/device/sensor/sensorservice-kit-intro.md index b3908d1fe61..35f4c422c1b 100644 --- a/zh-cn/application-dev/device/sensor/sensorservice-kit-intro.md +++ b/zh-cn/application-dev/device/sensor/sensorservice-kit-intro.md @@ -4,9 +4,14 @@ Sensor Service Kit（传感器服务）使应用程序能够从传感器获取原始数据，并提供振感控制能力。 -- Sensor（传感器）模块是应用访问底层硬件传感器的一种设备抽象概念。开发者可根据传感器提供的相关接口订阅传感器数据，并根据传感器数据定制相应的算法开发各类应用，比如指南针、运动健康、游戏等。 +- Sensor（传感器）模块是应用访问底层硬件传感器的一种设备抽象概念。开发者可根据传感器提供的相关接口订阅传感器数据，并根据传感器数据定制相应的算法开发各类应用，比如指南针、运动健康、游戏等。 + - 本地传感器: 设备内置的传感器，常用的包括加速度传感器、陀螺仪、温度传感器等。 + - 动态传感器: 指外置的动态传感器，模块能力可以更细化的控制每个动态传感器。可通过on、off等接口监听到动态传感器的状态变化（连接、断开）。 - Vibrator（振动）模块最大化开放马达器件能力，通过拓展马达服务实现振动与交互融合设计，打造细腻精致的一体化振动体验和差异化体验，提升用户交互效率和易用性、提升用户体验、增强品牌竞争力。 + - 本地马达: 设备内置的马达，常用的包括转子马达、线性马达等。 + - 动态马达: 设备外置的多个马达支持独立控制，且可以根据设备的连接、马达的状态等信息进行灵活的管理。动态马达广泛应用于外接设备，包括手柄、外接振动器等。 + ## 约束限制 @@ -18,8 +23,10 @@ Sensor Service Kit（传感器服务）使应用程序能够从传感器获取 - 传感器数据订阅和取消订阅接口成对调用，当不再需要订阅传感器数据时，开发者需要调用取消订阅接口停止数据上报。 +- 动态传感器断开后应用需要主动解除订阅操作。 ### Vibrator - 要使用振动的功能，设备必须具有对应的器件。 -- 针对马达，开发者需要请求相应的权限才能使用。 \ No newline at end of file +- 针对马达，开发者需要请求相应的权限才能使用。 +- 多个振动器的控制：存在多个设备、多个振动器时，需要应用自行选择控制振动的马达。 \ No newline at end of file diff --git a/zh-cn/application-dev/device/sensor/vibrator-guidelines.md b/zh-cn/application-dev/device/sensor/vibrator-guidelines.md index 3ed362bf170..2f0620816fb 100644 --- a/zh-cn/application-dev/device/sensor/vibrator-guidelines.md +++ b/zh-cn/application-dev/device/sensor/vibrator-guidelines.md @@ -10,16 +10,21 @@ ## 接口说明 -| 名称 | 描述 | -| ------------------------------------------------------------ | ------------------------------------------------------------ | -| startVibration(effect: VibrateEffect, attribute: VibrateAttribute): Promise<void> | 根据指定振动效果和振动属性触发马达振动，使用Promise异步回调。 | -| startVibration(effect: VibrateEffect, attribute: VibrateAttribute, callback: AsyncCallback<void>): void | 根据指定振动效果和振动属性触发马达振动，使用Callback异步回调。 | -| stopVibration(stopMode: VibratorStopMode): Promise<void> | 按照指定模式停止马达的振动，使用Promise异步回调。 | -| stopVibration(stopMode: VibratorStopMode, callback: AsyncCallback<void>): void | 按照指定模式停止马达的振动，使用Callback异步回调。 | -| stopVibration(): Promise<void> | 停止所有模式的马达振动，使用Promise异步回调。 | -| stopVibration(callback: AsyncCallback<void>): void | 停止所有模式的马达振动，使用Callback异步回调。 | -| isSupportEffect(effectId: string): Promise<boolean> | 查询是否支持传入的参数effectId。返回true则表示支持，否则不支持，使用Promise异步回调。 | -| isSupportEffect(effectId: string, callback: AsyncCallback<boolean>): void | 查询是否支持传入的参数effectId。返回true则表示支持，否则不支持，使用Callback异步回调。 | +| 名称 | 描述 | +| ------------------------------------------------------------ |-----------------------------------------------------------------------------| +| startVibration(effect: VibrateEffect, attribute: VibrateAttribute): Promise<void> | 根据指定振动效果和振动属性触发马达振动，使用Promise异步回调。 | +| startVibration(effect: VibrateEffect, attribute: VibrateAttribute, callback: AsyncCallback<void>): void | 根据指定振动效果和振动属性触发马达振动，使用Callback异步回调。 | +| stopVibration(stopMode: VibratorStopMode): Promise<void> | 按照指定模式停止马达的振动，使用Promise异步回调。 | +| stopVibration(stopMode: VibratorStopMode, callback: AsyncCallback<void>): void | 按照指定模式停止马达的振动，使用Callback异步回调。 | +| stopVibration(): Promise<void> | 停止所有模式的马达振动，使用Promise异步回调。 | +| stopVibration(param?: VibratorInfoParam): Promise<void> | 不传参则停止本地设备所有马达的振动，也可传参停止指定马达振动，使用Promise异步回调。 | +| stopVibration(callback: AsyncCallback<void>): void | 停止所有模式的马达振动，使用Callback异步回调。 | +| isSupportEffect(effectId: string): Promise<boolean> | 查询是否支持传入的参数effectId。返回true则表示支持，否则不支持，使用Promise异步回调。 | +| isSupportEffect(effectId: string, callback: AsyncCallback<boolean>): void | 查询是否支持传入的参数effectId。返回true则表示支持，否则不支持，使用Callback异步回调。 | +| getEffectInfoSync(effectId: string, param?: VibratorInfoParam): EffectInfo | 同步查询是否支持传入的参数effectId，param可指定具体马达。返回EffectInfo中isEffectSupported字段可判断是否支持。 | +| getVibratorInfoSync(param?: VibratorInfoParam): Array<VibratorInfo> | 同步查询一个或所有设备的马达信息列表。返回VibratorInfo包含设备ID、马达ID、设备名称、是否支持高清振动、是否本地设备等信息。 | +| on(type: 'vibratorStateChange', callback: Callback<VibratorStatusEvent>): void | 注册马达设备上线下状态变化的监听。callback参数VibratorStatusEvent可返回事件时间戳、设备ID、马达数量、上线或下线等信息。 | +| off(type: 'vibratorStateChange', callback?: Callback<VibratorStatusEvent>): void | 注销马达设备上线下状态变化的监听。 | ## 振动效果说明 @@ -151,7 +156,42 @@ Json文件共包含3个属性。 1. 控制设备上的振动器，需要申请权限ohos.permission.VIBRATE。具体配置方式请参考[声明权限](../../security/AccessToken/declare-permissions.md)。 -2. 根据指定振动效果和振动属性触发马达振动。 +2. 振动器查询。 + + **情形一** 查询所有马达信息： + + ```ts + import { vibrator } from '@kit.SensorServiceKit'; + import { BusinessError } from '@kit.BasicServicesKit'; + + try { + const vibratorInfoList: vibrator.VibratorInfo[] = vibrator.getVibratorInfoSync(); + console.log(`vibratorInfoList: ${JSON.stringify(vibratorInfoList)}`); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`); + } + ``` + + **情形二** 查询指定设备的一个或多个马达信息： + + ```ts + import { vibrator } from '@kit.SensorServiceKit'; + import { BusinessError } from '@kit.BasicServicesKit'; + + try { + const vibratorParam: vibrator.VibratorInfoParam = { + deviceId: 1 // deviceid 需要是查询出来真实存在的设备 + } + const vibratorInfoList: vibrator.VibratorInfo[] = vibrator.getVibratorInfoSync(vibratorParam); + console.log(`vibratorInfoList: ${JSON.stringify(vibratorInfoList)}`); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`); + } + ``` + +3. 根据指定振动效果和振动属性触发马达振动。 **情形一** 按照指定持续时间触发马达振动： @@ -276,7 +316,7 @@ Json文件共包含3个属性。 } ``` -3. 停止马达的振动。 +4. 停止马达的振动。 **方式一** 按照指定模式停止对应的马达振动，自定义振动不支持此类停止方式： @@ -343,6 +383,68 @@ Json文件共包含3个属性。 } ``` + **方式三** 停止指定设备的振动： + + ```ts + import { vibrator } from '@kit.SensorServiceKit'; + import { BusinessError } from '@kit.BasicServicesKit'; + + const vibratorInfoParam: vibrator.VibratorInfoParam = { + deviceId: 1 // deviceid 需要是查询出来真实存在的设备 + } + try { + vibrator.stopVibration(vibratorInfoParam).then(() => { + console.info('Succeed in stopping vibration'); + }, (error: BusinessError) => { + console.error(`Failed to stop vibration. Code: ${error.code}, message: ${error.message}`); + }); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`); + } + ``` + + +5. 动态马达状态变化监听。 + + 注册监听。 + ```ts + import { vibrator } from '@kit.SensorServiceKit'; + import { BusinessError } from '@kit.BasicServicesKit'; + + // 回调函数 + const vibratorStateChangeCallback = (data: vibrator.VibratorStatusEvent) => { + console.log('vibrator state callback info:', JSON.stringify(data)); + } + + try { + // 订阅 vibratorStateChange事件 + vibrator.on('vibratorStateChange', vibratorStateChangeCallback); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`); + } + ``` + + 取消监听,取消传入的callback需与注册的一致。 + ```ts + import { vibrator } from '@kit.SensorServiceKit'; + import { BusinessError } from '@kit.BasicServicesKit'; + + // 回调函数 + const vibratorStateChangeCallback = (data: vibrator.VibratorStatusEvent) => { + console.log('vibrator state callback info:', JSON.stringify(data)); + } + try { + // 取消订阅 vibratorStateChange事件 + vibrator.off('vibratorStateChange', vibratorStateChangeCallback); + // 取消订阅所有 vibratorStateChange事件 + // vibrator.off('vibratorStateChange'); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`); + } + ``` ## 相关实例 diff --git a/zh-cn/application-dev/reference/apis-sensor-service-kit/js-apis-sensor-sys.md b/zh-cn/application-dev/reference/apis-sensor-service-kit/js-apis-sensor-sys.md index bef249ae92a..de3b7b544d2 100644 --- a/zh-cn/application-dev/reference/apis-sensor-service-kit/js-apis-sensor-sys.md +++ b/zh-cn/application-dev/reference/apis-sensor-service-kit/js-apis-sensor-sys.md @@ -126,10 +126,10 @@ off(type: SensorId.COLOR, callback?: Callback<ColorResponse>): void **参数**： -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------------------------------------------------- | ---- | ------------------------------------------------------------ | -| type | [SensorId](#sensorid9).COLOR | 是 | 传感器类型，该值固定为SensorId.COLOR。 | -| callback | Callback<[ColorResponse](#colorresponse10)> | 否 | 需要取消订阅的回调函数，若无此参数，则取消订阅当前类型的所有回调函数。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- |--------------------------------------------------------| ---- | ------------------------------------------------------------ | +| type | [SensorId](#sensorid9).COLOR | 是 | 传感器类型，该值固定为SensorId.COLOR。 | +| callback | Callback<[ColorResponse](#colorresponse10)> | 否 | 需要取消订阅的回调函数，若无此参数，则取消订阅当前类型的所有回调函数。 | **错误码**： @@ -167,6 +167,84 @@ try { } ``` +### COLOR19+ + +off(type: SensorId.COLOR, sensorInfoParam?: SensorInfoParam, callback?: Callback<ColorResponse>): void + +取消订阅颜色传感器数据。 + +**系统能力**：SystemCapability.Sensors.Sensor + +**系统API**：此接口为系统接口 + +**参数**： + +| 参数名 | 类型 | 必填 | 说明 | +| -------- |--------------------------------------------------------| ---- | ------------------------------------------------------------ | +| type | [SensorId](#sensorid9).COLOR | 是 | 传感器类型，该值固定为SensorId.COLOR。 | +| sensorInfoParam | [SensorInfoParam](#sensorinfoparam19) | 否 | 传感器传入设置参数，可指定deviceId、sensorIndex | +| callback | Callback<[ColorResponse](#colorresponse10)> | 否 | 需要取消订阅的回调函数，若无此参数，则取消订阅当前类型的所有回调函数。 | + +**错误码**： + +以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 + +| 错误码ID | 错误信息 | +| -------- | ------------------------------------------------------------ | +| 202 | Permission check failed. A non-system application uses the system API. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | + +**示例**： + +```ts +import { sensor } from '@kit.SensorServiceKit'; +import { BusinessError } from '@kit.BasicServicesKit'; + +enum Ret { OK, Failed = -1 } + +// 传感器回调 +const sensorCallback = (response: sensor.ColorResponse) => { + console.log(`callback response: ${JSON.stringify(response)}`); +} +// 传感器监听类型 +const sensorType = sensor.SensorId.COLOR; +const sensorInfoParam: sensor.SensorInfoParam = {}; + +function sensorSubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + // 查询所有的传感器 + const sensorList: sensor.Sensor[] = sensor.getSensorListSync(); + if (!sensorList.length) { + return Ret.Failed; + } + // 根据实际业务逻辑获取目标传感器 + const targetSensor: sensor.Sensor = sensorList[0]; + sensorInfoParam.deviceId = targetSensor.deviceId ?? -1; + sensorInfoParam.sensorIndex = targetSensor.sensorIndex ?? -1; + // 订阅传感器事件 + sensor.on(sensorType, sensorCallback, { sensorInfoParam }); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.on. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; +} + +function sensorUnsubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + sensor.off(sensorType, sensorInfoParam, sensorCallback); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.off. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; +} +``` + ### SAR10+ off(type: SensorId.SAR, callback?: Callback<SarResponse>): void @@ -220,6 +298,84 @@ try { } ``` +### SAR19+ + +off(type: SensorId.SAR, sensorInfoParam?: SensorInfoParam, callback?: Callback<SarResponse>): void + +取消订阅吸收比率传感器数据。 + +**系统能力**：SystemCapability.Sensors.Sensor + +**系统API**：此接口为系统接口 + +**参数**： + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------------------------- | ---- | ------------------------------------------------------------ | +| type | [SensorId](#sensorid9).SAR | 是 | 传感器类型，该值固定为SensorId.SAR。 | +| sensorInfoParam | [SensorInfoParam](#sensorinfoparam19) | 否 | 传感器传入设置参数，可指定deviceId、sensorIndex | +| callback | Callback<[SarResponse](#sarresponse10)> | 否 | 需要取消订阅的回调函数，若无此参数，则取消订阅当前类型的所有回调函数。 | + +**错误码**： + +以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 + +| 错误码ID | 错误信息 | +| -------- |-----------------------------------------------------------------------------------------------------------------------------------------| +| 202 | Permission check failed. A non-system application uses the system API. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | + +**示例**： + +```ts +import { sensor } from '@kit.SensorServiceKit'; +import { BusinessError } from '@kit.BasicServicesKit'; + +enum Ret { OK, Failed = -1 } + +// 传感器回调 +const sensorCallback = (response: sensor.SarResponse) => { + console.log(`callback response: ${JSON.stringify(response)}`); +} +// 传感器监听类型 +const sensorType = sensor.SensorId.SAR; +const sensorInfoParam: sensor.SensorInfoParam = {}; + +function sensorSubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + // 查询所有的传感器 + const sensorList: sensor.Sensor[] = sensor.getSensorListSync(); + if (!sensorList.length) { + return Ret.Failed; + } + // 根据实际业务逻辑获取目标传感器 + const targetSensor: sensor.Sensor = sensorList[0]; + sensorInfoParam.deviceId = targetSensor.deviceId ?? -1; + sensorInfoParam.sensorIndex = targetSensor.sensorIndex ?? -1; + // 订阅传感器事件 + sensor.on(sensorType, sensorCallback, { sensorInfoParam }); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.on. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; +} + +function sensorUnsubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + sensor.off(sensorType, sensorInfoParam, sensorCallback); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.off. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; +} +``` + ## SensorId9+ 表示当前支持订阅或取消订阅的传感器类型。 @@ -257,3 +413,16 @@ try { | 名称 | 类型 | 只读 | 可选 | 说明 | | --------------- | ------ | ---- | ---- | ------------------------------- | | absorptionRatio | number | 是 | 是 | 表示具体的吸收率，单位 : W/kg。 | + + +## SensorInfoParam19+ + +传感器传入设置参数。 + +**系统能力**：以下各项对应的系统能力均为SystemCapability.Sensors.Sensor + + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ---------------------- | ---- |-------------------------| +| deviceId | number | 否 | 设备ID：默认值为-1，表示本地设备。 | +| sensorIndex | number | 否 | 传感器索引：默认值为0，为设备上的默认传感器。 | \ No newline at end of file diff --git a/zh-cn/application-dev/reference/apis-sensor-service-kit/js-apis-sensor.md b/zh-cn/application-dev/reference/apis-sensor-service-kit/js-apis-sensor.md index 6d42c823276..a718bef49b4 100644 --- a/zh-cn/application-dev/reference/apis-sensor-service-kit/js-apis-sensor.md +++ b/zh-cn/application-dev/reference/apis-sensor-service-kit/js-apis-sensor.md @@ -1010,6 +1010,49 @@ try { } ``` +### sensorStatusChange19+ + +on(type: 'sensorStatusChange', callback: Callback<SensorStatusEvent>): void + +监听传感器上线下线状态的变化，callback返回传感器状态事件数据。 + +**系统能力**：SystemCapability.Sensors.Sensor + +**参数**： + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------------------------------------------ | ---- | ----------------------------------------------------------- | +| sensorStatusChange | 固定传入'sensorStatusChange' | 是 | 状态监听固定参数。 | +| callback | Callback<[SensorStatusEvent](#sensorstatusevent19)> | 是 | 回调函数，异步上报的传感器事件数据SensorStatusEvent。 | + +**错误码**： + +以下错误码的详细介绍请参见[传感器错误码](errorcode-sensor.md)和[通用错误码](../errorcode-universal.md)。 + +| 错误码ID | 错误信息 | +| -------- | ------------------------------------------------------------ | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | + +**示例**： + +```ts +import { sensor } from '@kit.SensorServiceKit'; +import { BusinessError } from '@kit.BasicServicesKit'; + +try { + sensor.on('sensorStatusChange', (data: sensor.SensorStatusEvent) => { + console.info('sensorStatusChange : ' + JSON.stringify(data)); + }); + setTimeout(() => { + sensor.off('sensorStatusChange'); + }, 5000); +} catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke on. Code: ${e.code}, message: ${e.message}`); +} +``` + + ## sensor.once9+ ### ACCELEROMETER9+ @@ -1922,10 +1965,10 @@ off(type: SensorId.ACCELEROMETER, callback?: Callback<AccelerometerResponse&g **参数**： -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | -| type | [SensorId](#sensorid9).ACCELEROMETER | 是 | 传感器类型，该值固定为SensorId.ACCELEROMETER。 | -| callback | Callback<[AccelerometerResponse](#accelerometerresponse)> | 否 | 需要取消订阅的回调函数，若无此参数，则取消订阅当前类型的所有回调函数。 | +| 参数名 | 类型 | 必填 | 说明 | +|-------------------------------| ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | +| type | [SensorId](#sensorid9).ACCELEROMETER | 是 | 传感器类型，该值固定为SensorId.ACCELEROMETER。 | +| callback | Callback<[AccelerometerResponse](#accelerometerresponse)> | 否 | 需要取消订阅的回调函数，若无此参数，则取消订阅当前类型的所有回调函数。 | **错误码**： @@ -1963,6 +2006,86 @@ try { } ``` +### ACCELEROMETER19+ + +off(type: SensorId.ACCELEROMETER, sensorInfoParam?: SensorInfoParam, callback?: Callback<AccelerometerResponse>): void + +取消订阅加速度传感器数据。 + +**需要权限**：ohos.permission.ACCELEROMETER + +**原子化服务API**：从API Version 19开始，该接口支持在原子化服务中使用。 + +**系统能力**：SystemCapability.Sensors.Sensor + +**参数**： + +| 参数名 | 类型 | 必填 | 说明 | +|--------------------| ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | +| type | [SensorId](#sensorid9).ACCELEROMETER | 是 | 传感器类型，该值固定为SensorId.ACCELEROMETER。 | +| sensorInfoParam | [SensorInfoParam](#sensorinfoparam19) | 否 | 传感器传入设置参数，可指定deviceId、sensorIndex | +| callback | Callback<[AccelerometerResponse](#accelerometerresponse)> | 否 | 需要取消订阅的回调函数，若无此参数，则取消订阅当前类型的所有回调函数。 | + +**错误码**： + +以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 + +| 错误码ID | 错误信息 | +| -------- | ------------------------------------------------------------ | +| 201 | Permission denied. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | + +**示例**： + +```ts +import { sensor } from '@kit.SensorServiceKit'; +import { BusinessError } from '@kit.BasicServicesKit'; + +enum Ret { OK, Failed = -1 } + +// 传感器回调 +const sensorCallback = (response: sensor.AccelerometerResponse) => { + console.log(`callback response: ${JSON.stringify(response)}`); +} +// 传感器监听类别 +const sensorType = sensor.SensorId.ACCELEROMETER; +const sensorInfoParam: sensor.SensorInfoParam = {}; + +function sensorSubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + // 查询所有的传感器 + const sensorList: sensor.Sensor[] = sensor.getSensorListSync(); + if (!sensorList.length) { + return Ret.Failed; + } + // 根据实际业务逻辑获取目标传感器 + const targetSensor: sensor.Sensor = sensorList[0]; + sensorInfoParam.deviceId = targetSensor.deviceId ?? -1; + sensorInfoParam.sensorIndex = targetSensor.sensorIndex ?? -1; + // 订阅传感器事件 + sensor.on(sensorType, sensorCallback, { sensorInfoParam }); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.on. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; +} + +function sensorUnsubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + sensor.off(sensorType, sensorInfoParam, sensorCallback); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.off. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; +} +``` + ### ACCELEROMETER_UNCALIBRATED9+ off(type: SensorId.ACCELEROMETER_UNCALIBRATED, callback?: Callback<AccelerometerUncalibratedResponse>): void @@ -2016,6 +2139,84 @@ try { } ``` +### ACCELEROMETER_UNCALIBRATED19+ + +off(type: SensorId.ACCELEROMETER_UNCALIBRATED, sensorInfoParam?: SensorInfoParam, callback?: Callback<AccelerometerUncalibratedResponse>): void + +取消订阅未校准加速度传感器数据。 + +**需要权限**：ohos.permission.ACCELEROMETER + +**系统能力**：SystemCapability.Sensors.Sensor + +**参数**： + +| 参数名 | 类型 | 必填 | 说明 | +|------------------| ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | +| type | [SensorId](#sensorid9).ACCELEROMETER_UNCALIBRATED | 是 | 传感器类型，该值固定为SensorId.ACCELEROMETER_UNCALIBRATED。 | +| sensorInfoParam | [SensorInfoParam](#sensorinfoparam19) | 否 | 传感器传入设置参数，可指定deviceId、sensorIndex | +| callback | Callback<[AccelerometerUncalibratedResponse](#accelerometeruncalibratedresponse)> | 否 | 需要取消订阅的回调函数，若无此参数，则取消订阅当前类型的所有回调函数。 | + +**错误码**： + +以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 + +| 错误码ID | 错误信息 | +| -------- | ------------------------------------------------------------ | +| 201 | Permission denied. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | + +**示例**： + +```ts +import { sensor } from '@kit.SensorServiceKit'; +import { BusinessError } from '@kit.BasicServicesKit'; + +enum Ret { OK, Failed = -1 } + +// 传感器回调 +const sensorCallback = (response: sensor.AccelerometerUncalibratedResponse) => { + console.log(`callback response: ${JSON.stringify(response)}`); +} +// 传感器监听类型 +const sensorType = sensor.SensorId.ACCELEROMETER_UNCALIBRATED; +const sensorInfoParam: sensor.SensorInfoParam = {}; + +function sensorSubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + // 查询所有的传感器 + const sensorList: sensor.Sensor[] = sensor.getSensorListSync(); + if (!sensorList.length) { + return Ret.Failed; + } + // 根据实际业务逻辑获取目标传感器 + const targetSensor: sensor.Sensor = sensorList[0]; + sensorInfoParam.deviceId = targetSensor.deviceId ?? -1; + sensorInfoParam.sensorIndex = targetSensor.sensorIndex ?? -1; + // 订阅传感器事件 + sensor.on(sensorType, sensorCallback, { sensorInfoParam }); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.on. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; +} + +function sensorUnsubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + sensor.off(sensorType, sensorInfoParam, sensorCallback); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.off. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; +} +``` + ### AMBIENT_LIGHT9+ off(type: SensorId.AMBIENT_LIGHT, callback?: Callback<LightResponse>): void @@ -2066,6 +2267,81 @@ try { } ``` +### AMBIENT_LIGHT19+ + +off(type: SensorId.AMBIENT_LIGHT, sensorInfoParam?: SensorInfoParam, callback?: Callback<LightResponse>): void + +取消订阅环境光传感器数据。 + +**系统能力**：SystemCapability.Sensors.Sensor + +**参数**： + +| 参数名 | 类型 | 必填 | 说明 | +|------------------| ----------------------------------------------- | ---- | ------------------------------------------------------------ | +| type | [SensorId](#sensorid9).AMBIENT_LIGHT | 是 | 传感器类型，该值固定为SensorId.AMBIENT_LIGHT。 | +| sensorInfoParam | [SensorInfoParam](#sensorinfoparam19) | 否 | 传感器传入设置参数，可指定deviceId、sensorIndex | +| callback | Callback<[LightResponse](#lightresponse)> | 否 | 需要取消订阅的回调函数，若无此参数，则取消订阅当前类型的所有回调函数。 | + +**错误码**： + +以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 + +| 错误码ID | 错误信息 | +| -------- | ------------------------------------------------------------ | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | + +**示例**： + +```ts +import { sensor } from '@kit.SensorServiceKit'; +import { BusinessError } from '@kit.BasicServicesKit'; + +enum Ret { OK, Failed = -1 } + +// 传感器回调 +const sensorCallback = (response: sensor.LightResponse) => { + console.log(`callback response: ${JSON.stringify(response)}`); +} +// 传感器监听类型 +const sensorType = sensor.SensorId.AMBIENT_LIGHT; +const sensorInfoParam: sensor.SensorInfoParam = {}; + +function sensorSubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + // 查询所有的传感器 + const sensorList: sensor.Sensor[] = sensor.getSensorListSync(); + if (!sensorList.length) { + return Ret.Failed; + } + // 根据实际业务逻辑获取目标传感器 + const targetSensor: sensor.Sensor = sensorList[0]; + sensorInfoParam.deviceId = targetSensor.deviceId ?? -1; + sensorInfoParam.sensorIndex = targetSensor.sensorIndex ?? -1; + // 订阅传感器事件 + sensor.on(sensorType, sensorCallback, { sensorInfoParam }); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.on. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; +} + +function sensorUnsubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + sensor.off(sensorType, sensorInfoParam, sensorCallback); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.off. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; +} +``` + ### AMBIENT_TEMPERATURE9+ off(type: SensorId.AMBIENT_TEMPERATURE, callback?: Callback<AmbientTemperatureResponse>): void @@ -2116,6 +2392,82 @@ try { } ``` +### AMBIENT_TEMPERATURE19+ + +off(type: SensorId.AMBIENT_TEMPERATURE, sensorInfoParam?: SensorInfoParam, callback?: Callback<AmbientTemperatureResponse>): void + +取消订阅温度传感器数据。 + +**系统能力**：SystemCapability.Sensors.Sensor + +**参数**： + +| 参数名 | 类型 | 必填 | 说明 | +|------------------| ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | +| type | [SensorId](#sensorid9).AMBIENT_TEMPERATURE | 是 | 传感器类型，该值固定为SensorId.AMBIENT_TEMPERATURE。 | +| sensorInfoParam | [SensorInfoParam](#sensorinfoparam19) | 否 | 传感器传入设置参数，可指定deviceId、sensorIndex | +| callback | Callback<[AmbientTemperatureResponse](#ambienttemperatureresponse)> | 否 | 需要取消订阅的回调函数，若无此参数，则取消订阅当前类型的所有回调函数。 | + +**错误码**： + +以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 + +| 错误码ID | 错误信息 | +| -------- | ------------------------------------------------------------ | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | + +**示例**： + +```ts +import { sensor } from '@kit.SensorServiceKit'; +import { BusinessError } from '@kit.BasicServicesKit'; + +enum Ret { OK, Failed = -1 } + +// 传感器回调 +const sensorCallback = (response: sensor.AmbientTemperatureResponse) => { + console.log(`callback response: ${JSON.stringify(response)}`); +} +// 传感器监听类型 +const sensorType = sensor.SensorId.AMBIENT_TEMPERATURE; +const sensorInfoParam: sensor.SensorInfoParam = {}; + +function sensorSubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + // 查询所有的传感器 + const sensorList: sensor.Sensor[] = sensor.getSensorListSync(); + if (!sensorList.length) { + return Ret.Failed; + } + // 根据实际业务逻辑获取目标传感器 + const targetSensor: sensor.Sensor = sensorList[0]; + sensorInfoParam.deviceId = targetSensor.deviceId ?? -1; + sensorInfoParam.sensorIndex = targetSensor.sensorIndex ?? -1; + // 订阅传感器事件 + sensor.on(sensorType, sensorCallback, { sensorInfoParam }); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.on. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; +} + +function sensorUnsubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + sensor.off(sensorType, sensorInfoParam, sensorCallback); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.off. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; +} +``` + + ### BAROMETER9+ off(type: SensorId.BAROMETER, callback?: Callback<BarometerResponse>): void @@ -2166,6 +2518,81 @@ try { } ``` +### BAROMETER19+ + +off(type: SensorId.BAROMETER, sensorInfoParam?: SensorInfoParam, callback?: Callback<BarometerResponse>): void + +取消订阅气压计传感器数据。 + +**系统能力**：SystemCapability.Sensors.Sensor + +**参数**： + +| 参数名 | 类型 | 必填 | 说明 | +|------------------| ------------------------------------------------------- | ---- | ------------------------------------------------------------ | +| type | [SensorId](#sensorid9).BAROMETER | 是 | 传感器类型，该值固定为SensorId.BAROMETER。 | +| sensorInfoParam | [SensorInfoParam](#sensorinfoparam19) | 否 | 传感器传入设置参数，可指定deviceId、sensorIndex | +| callback | Callback<[BarometerResponse](#barometerresponse)> | 否 | 需要取消订阅的回调函数，若无此参数，则取消订阅当前类型的所有回调函数。 | + +**错误码**： + +以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 + +| 错误码ID | 错误信息 | +| -------- | ------------------------------------------------------------ | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | + +**示例**： + +```ts +import { sensor } from '@kit.SensorServiceKit'; +import { BusinessError } from '@kit.BasicServicesKit'; + +enum Ret { OK, Failed = -1 } + +// 传感器回调 +const sensorCallback = (response: sensor.BarometerResponse) => { + console.log(`callback response: ${JSON.stringify(response)}`); +} +// 传感器监听类型 +const sensorType = sensor.SensorId.BAROMETER; +const sensorInfoParam: sensor.SensorInfoParam = {}; + +function sensorSubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + // 查询所有的传感器 + const sensorList: sensor.Sensor[] = sensor.getSensorListSync(); + if (!sensorList.length) { + return Ret.Failed; + } + // 根据实际业务逻辑获取目标传感器 + const targetSensor: sensor.Sensor = sensorList[0]; + sensorInfoParam.deviceId = targetSensor.deviceId ?? -1; + sensorInfoParam.sensorIndex = targetSensor.sensorIndex ?? -1; + // 订阅传感器事件 + sensor.on(sensorType, sensorCallback, { sensorInfoParam }); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.on. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; +} + +function sensorUnsubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + sensor.off(sensorType, sensorInfoParam, sensorCallback); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.off. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; +} +``` + ### GRAVITY9+ off(type: SensorId.GRAVITY, callback?: Callback<GravityResponse>): void @@ -2217,24 +2644,21 @@ try { ``` -### GYROSCOPE9+ - -off(type: SensorId.GYROSCOPE, callback?: Callback<GyroscopeResponse>): void - -取消订阅陀螺仪传感器数据。 +### GRAVITY19+ -**需要权限**：ohos.permission.GYROSCOPE +off(type: SensorId.GRAVITY, sensorInfoParam?: SensorInfoParam, callback?: Callback<GravityResponse>): void -**原子化服务API**：从API Version 11开始，该接口支持在原子化服务中使用。 +取消订阅重力传感器数据。 **系统能力**：SystemCapability.Sensors.Sensor **参数**： -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------------------------------------------------------- | ---- | ------------------------------------------------------------ | -| type | [SensorId](#sensorid9).GYROSCOPE | 是 | 传感器类型，该值固定为SensorId.GYROSCOPE。 | -| callback | Callback<[GyroscopeResponse](#gyroscoperesponse)> | 否 | 需要取消订阅的回调函数，若无此参数，则取消订阅当前类型的所有回调函数。 | +| 参数名 | 类型 | 必填 | 说明 | +|------------------| --------------------------------------------------- | ---- | ------------------------------------------------------------ | +| type | [SensorId](#sensorid9).GRAVITY | 是 | 传感器类型，该值固定为SensorId.GRAVITY。 | +| sensorInfoParam | [SensorInfoParam](#sensorinfoparam19) | 否 | 传感器传入设置参数，可指定deviceId、sensorIndex | +| callback | Callback<[GravityResponse](#gravityresponse)> | 否 | 需要取消订阅的回调函数，若无此参数，则取消订阅当前类型的所有回调函数。 | **错误码**： @@ -2242,8 +2666,7 @@ off(type: SensorId.GYROSCOPE, callback?: Callback<GyroscopeResponse>): voi | 错误码ID | 错误信息 | | -------- | ------------------------------------------------------------ | -| 201 | Permission denied. | -| 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | **示例**： @@ -2251,26 +2674,185 @@ off(type: SensorId.GYROSCOPE, callback?: Callback<GyroscopeResponse>): voi import { sensor } from '@kit.SensorServiceKit'; import { BusinessError } from '@kit.BasicServicesKit'; -function callback1(data: object) { - console.info('Succeeded in getting callback1 data: ' + JSON.stringify(data)); -} +enum Ret { OK, Failed = -1 } -function callback2(data: object) { - console.info('Succeeded in getting callback2 data: ' + JSON.stringify(data)); +// 传感器回调 +const sensorCallback = (response: sensor.GravityResponse) => { + console.log(`callback response: ${JSON.stringify(response)}`); } +// 传感器监听类型 +const sensorType = sensor.SensorId.GRAVITY; +const sensorInfoParam: sensor.SensorInfoParam = {}; -try { - sensor.on(sensor.SensorId.GYROSCOPE, callback1); - sensor.on(sensor.SensorId.GYROSCOPE, callback2); - // 仅取消callback1的注册 - sensor.off(sensor.SensorId.GYROSCOPE, callback1); - // 取消注册SensorId.GYROSCOPE的所有回调 - sensor.off(sensor.SensorId.GYROSCOPE); -} catch (error) { - let e: BusinessError = error as BusinessError; - console.error(`Failed to invoke off. Code: ${e.code}, message: ${e.message}`); +function sensorSubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + // 查询所有的传感器 + const sensorList: sensor.Sensor[] = sensor.getSensorListSync(); + if (!sensorList.length) { + return Ret.Failed; + } + // 根据实际业务逻辑获取目标传感器 + const targetSensor: sensor.Sensor = sensorList[0]; + sensorInfoParam.deviceId = targetSensor.deviceId ?? -1; + sensorInfoParam.sensorIndex = targetSensor.sensorIndex ?? -1; + // 订阅传感器事件 + sensor.on(sensorType, sensorCallback, { sensorInfoParam }); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.on. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; } -``` + +function sensorUnsubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + sensor.off(sensorType, sensorInfoParam, sensorCallback); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.off. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; +} +``` + +### GYROSCOPE9+ + +off(type: SensorId.GYROSCOPE, callback?: Callback<GyroscopeResponse>): void + +取消订阅陀螺仪传感器数据。 + +**需要权限**：ohos.permission.GYROSCOPE + +**原子化服务API**：从API Version 11开始，该接口支持在原子化服务中使用。 + +**系统能力**：SystemCapability.Sensors.Sensor + +**参数**： + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------------------------------------- | ---- | ------------------------------------------------------------ | +| type | [SensorId](#sensorid9).GYROSCOPE | 是 | 传感器类型，该值固定为SensorId.GYROSCOPE。 | +| callback | Callback<[GyroscopeResponse](#gyroscoperesponse)> | 否 | 需要取消订阅的回调函数，若无此参数，则取消订阅当前类型的所有回调函数。 | + +**错误码**： + +以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 + +| 错误码ID | 错误信息 | +| -------- | ------------------------------------------------------------ | +| 201 | Permission denied. | +| 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | + +**示例**： + +```ts +import { sensor } from '@kit.SensorServiceKit'; +import { BusinessError } from '@kit.BasicServicesKit'; + +function callback1(data: object) { + console.info('Succeeded in getting callback1 data: ' + JSON.stringify(data)); +} + +function callback2(data: object) { + console.info('Succeeded in getting callback2 data: ' + JSON.stringify(data)); +} + +try { + sensor.on(sensor.SensorId.GYROSCOPE, callback1); + sensor.on(sensor.SensorId.GYROSCOPE, callback2); + // 仅取消callback1的注册 + sensor.off(sensor.SensorId.GYROSCOPE, callback1); + // 取消注册SensorId.GYROSCOPE的所有回调 + sensor.off(sensor.SensorId.GYROSCOPE); +} catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke off. Code: ${e.code}, message: ${e.message}`); +} +``` + +### GYROSCOPE19+ + +off(type: SensorId.GYROSCOPE, sensorInfoParam?: SensorInfoParam, callback?: Callback<GyroscopeResponse>): void + +取消订阅陀螺仪传感器数据。 + +**需要权限**：ohos.permission.GYROSCOPE + +**原子化服务API**：从API Version 19开始，该接口支持在原子化服务中使用。 + +**系统能力**：SystemCapability.Sensors.Sensor + +**参数**： + +| 参数名 | 类型 | 必填 | 说明 | +|------------------| ------------------------------------------------------- | ---- | ------------------------------------------------------------ | +| type | [SensorId](#sensorid9).GYROSCOPE | 是 | 传感器类型，该值固定为SensorId.GYROSCOPE。 | +| sensorInfoParam | [SensorInfoParam](#sensorinfoparam19) | 否 | 传感器传入设置参数，可指定deviceId、sensorIndex | +| callback | Callback<[GyroscopeResponse](#gyroscoperesponse)> | 否 | 需要取消订阅的回调函数，若无此参数，则取消订阅当前类型的所有回调函数。 | + +**错误码**： + +以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 + +| 错误码ID | 错误信息 | +| -------- | ------------------------------------------------------------ | +| 201 | Permission denied. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | + +**示例**： + +```ts +import { sensor } from '@kit.SensorServiceKit'; +import { BusinessError } from '@kit.BasicServicesKit'; + +enum Ret { OK, Failed = -1 } + +// 传感器回调 +const sensorCallback = (response: sensor.GyroscopeResponse) => { + console.log(`callback response: ${JSON.stringify(response)}`); +} +// 传感器监听类型 +const sensorType = sensor.SensorId.GYROSCOPE; +const sensorInfoParam: sensor.SensorInfoParam = {}; + +function sensorSubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + // 查询所有的传感器 + const sensorList: sensor.Sensor[] = sensor.getSensorListSync(); + if (!sensorList.length) { + return Ret.Failed; + } + // 根据实际业务逻辑获取目标传感器 + const targetSensor: sensor.Sensor = sensorList[0]; + sensorInfoParam.deviceId = targetSensor.deviceId ?? -1; + sensorInfoParam.sensorIndex = targetSensor.sensorIndex ?? -1; + // 订阅传感器事件 + sensor.on(sensorType, sensorCallback, { sensorInfoParam }); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.on. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; +} + +function sensorUnsubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + sensor.off(sensorType, sensorInfoParam, sensorCallback); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.off. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; +} +``` ### GYROSCOPE_UNCALIBRATED9+ @@ -2325,6 +2907,84 @@ try { } ``` +### GYROSCOPE_UNCALIBRATED19+ + +off(type: SensorId.GYROSCOPE_UNCALIBRATED, sensorInfoParam?: SensorInfoParam, callback?: Callback<GyroscopeUncalibratedResponse>): void + +取消订阅未校准陀螺仪传感器数据。 + +**需要权限**：ohos.permission.GYROSCOPE + +**系统能力**：SystemCapability.Sensors.Sensor + +**参数**： + +| 参数名 | 类型 | 必填 | 说明 | +|------------------| ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | +| type | [SensorId](#sensorid9).GYROSCOPE_UNCALIBRATED | 是 | 传感器类型，该值固定为SensorId.GYROSCOPE_UNCALIBRATED。 | +| sensorInfoParam | [SensorInfoParam](#sensorinfoparam19) | 否 | 传感器传入设置参数，可指定deviceId、sensorIndex | +| callback | Callback<[GyroscopeUncalibratedResponse](#gyroscopeuncalibratedresponse)> | 否 | 需要取消订阅的回调函数，若无此参数，则取消订阅当前类型的所有回调函数。 | + +**错误码**： + +以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 + +| 错误码ID | 错误信息 | +| -------- | ------------------------------------------------------------ | +| 201 | Permission denied. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | + +**示例**： + +```ts +import { sensor } from '@kit.SensorServiceKit'; +import { BusinessError } from '@kit.BasicServicesKit'; + +enum Ret { OK, Failed = -1 } + +// 传感器回调 +const sensorCallback = (response: sensor.GyroscopeUncalibratedResponse) => { + console.log(`callback response: ${JSON.stringify(response)}`); +} +// 传感器监听类型 +const sensorType = sensor.SensorId.GYROSCOPE_UNCALIBRATED; +const sensorInfoParam: sensor.SensorInfoParam = {}; + +function sensorSubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + // 查询所有的传感器 + const sensorList: sensor.Sensor[] = sensor.getSensorListSync(); + if (!sensorList.length) { + return Ret.Failed; + } + // 根据实际业务逻辑获取目标传感器 + const targetSensor: sensor.Sensor = sensorList[0]; + sensorInfoParam.deviceId = targetSensor.deviceId ?? -1; + sensorInfoParam.sensorIndex = targetSensor.sensorIndex ?? -1; + // 订阅传感器事件 + sensor.on(sensorType, sensorCallback, { sensorInfoParam }); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.on. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; +} + +function sensorUnsubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + sensor.off(sensorType, sensorInfoParam, sensorCallback); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.off. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; +} +``` + ### HALL9+ off(type: SensorId.HALL, callback?: Callback<HallResponse>): void @@ -2375,6 +3035,81 @@ try { } ``` +### HALL19+ + +off(type: SensorId.HALL, sensorInfoParam?: SensorInfoParam, callback?: Callback<HallResponse>): void + +取消订阅霍尔传感器数据。 + +**系统能力**：SystemCapability.Sensors.Sensor + +**参数**： + +| 参数名 | 类型 | 必填 | 说明 | +|------------------| --------------------------------------------- | ---- | ------------------------------------------------------------ | +| type | [SensorId](#sensorid9).HALL | 是 | 传感器类型，该值固定为SensorId.HALL。 | +| sensorInfoParam | [SensorInfoParam](#sensorinfoparam19) | 否 | 传感器传入设置参数，可指定deviceId、sensorIndex | +| callback | Callback<[HallResponse](#hallresponse)> | 否 | 需要取消订阅的回调函数，若无此参数，则取消订阅当前类型的所有回调函数。 | + +**错误码**： + +以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 + +| 错误码ID | 错误信息 | +| -------- | ------------------------------------------------------------ | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | + +**示例**： + +```ts +import { sensor } from '@kit.SensorServiceKit'; +import { BusinessError } from '@kit.BasicServicesKit'; + +enum Ret { OK, Failed = -1 } + +// 传感器回调 +const sensorCallback = (response: sensor.HallResponse) => { + console.log(`callback response: ${JSON.stringify(response)}`); +} +// 传感器监听类型 +const sensorType = sensor.SensorId.HALL; +const sensorInfoParam: sensor.SensorInfoParam = {}; + +function sensorSubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + // 查询所有的传感器 + const sensorList: sensor.Sensor[] = sensor.getSensorListSync(); + if (!sensorList.length) { + return Ret.Failed; + } + // 根据实际业务逻辑获取目标传感器 + const targetSensor: sensor.Sensor = sensorList[0]; + sensorInfoParam.deviceId = targetSensor.deviceId ?? -1; + sensorInfoParam.sensorIndex = targetSensor.sensorIndex ?? -1; + // 订阅传感器事件 + sensor.on(sensorType, sensorCallback, { sensorInfoParam }); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.on. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; +} + +function sensorUnsubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + sensor.off(sensorType, sensorInfoParam, sensorCallback); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.off. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; +} +``` + ### HEART_RATE9+ off(type: SensorId.HEART_RATE, callback?: Callback<HeartRateResponse>): void @@ -2428,6 +3163,84 @@ try { } ``` +### HEART_RATE19+ + +off(type: SensorId.HEART_RATE, sensorInfoParam?: SensorInfoParam, callback?: Callback<HeartRateResponse>): void + +取消订阅心率传感器数据。 + +**需要权限**：ohos.permission.READ_HEALTH_DATA + +**系统能力**：SystemCapability.Sensors.Sensor + +**参数**： + +| 参数名 | 类型 | 必填 | 说明 | +|------------------| ------------------------------------------------------- | ---- | ------------------------------------------------------------ | +| type | [SensorId](#sensorid9).HEART_RATE | 是 | 传感器类型，该值固定为SensorId.HEART_RATE。 | +| sensorInfoParam | [SensorInfoParam](#sensorinfoparam19) | 否 | 传感器传入设置参数，可指定deviceId、sensorIndex | +| callback | Callback<[HeartRateResponse](#heartrateresponse)> | 否 | 需要取消订阅的回调函数，若无此参数，则取消订阅当前类型的所有回调函数。 | + +**错误码**： + +以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 + +| 错误码ID | 错误信息 | +| -------- | ------------------------------------------------------------ | +| 201 | Permission denied. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | + +**示例**： + +```ts +import { sensor } from '@kit.SensorServiceKit'; +import { BusinessError } from '@kit.BasicServicesKit'; + +enum Ret { OK, Failed = -1 } + +// 传感器回调 +const sensorCallback = (response: sensor.HeartRateResponse) => { + console.log(`callback response: ${JSON.stringify(response)}`); +} +// 传感器监听类型 +const sensorType = sensor.SensorId.HEART_RATE; +const sensorInfoParam: sensor.SensorInfoParam = {}; + +function sensorSubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + // 查询所有的传感器 + const sensorList: sensor.Sensor[] = sensor.getSensorListSync(); + if (!sensorList.length) { + return Ret.Failed; + } + // 根据实际业务逻辑获取目标传感器 + const targetSensor: sensor.Sensor = sensorList[0]; + sensorInfoParam.deviceId = targetSensor.deviceId ?? -1; + sensorInfoParam.sensorIndex = targetSensor.sensorIndex ?? -1; + // 订阅传感器事件 + sensor.on(sensorType, sensorCallback, { sensorInfoParam }); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.on. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; +} + +function sensorUnsubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + sensor.off(sensorType, sensorInfoParam, sensorCallback); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.off. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; +} +``` + ### HUMIDITY9+ off(type: SensorId.HUMIDITY, callback?: Callback<HumidityResponse>): void @@ -2478,6 +3291,81 @@ try { } ``` +### HUMIDITY19+ + +off(type: SensorId.HUMIDITY, sensorInfoParam?: SensorInfoParam, callback?: Callback<HumidityResponse>): void + +取消订阅湿度传感器数据。 + +**系统能力**：SystemCapability.Sensors.Sensor + +**参数**： + +| 参数名 | 类型 | 必填 | 说明 | +|------------------| ----------------------------------------------------- | ---- | ------------------------------------------------------------ | +| type | [SensorId](#sensorid9).HUMIDITY | 是 | 传感器类型，该值固定为SensorId.HUMIDITY。 | +| sensorInfoParam | [SensorInfoParam](#sensorinfoparam19) | 否 | 传感器传入设置参数，可指定deviceId、sensorIndex | +| callback | Callback<[HumidityResponse](#humidityresponse)> | 否 | 需要取消订阅的回调函数，若无此参数，则取消订阅当前类型的所有回调函数。 | + +**错误码**： + +以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 + +| 错误码ID | 错误信息 | +| -------- | ------------------------------------------------------------ | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | + +**示例**： + +```ts +import { sensor } from '@kit.SensorServiceKit'; +import { BusinessError } from '@kit.BasicServicesKit'; + +enum Ret { OK, Failed = -1 } + +// 传感器回调 +const sensorCallback = (response: sensor.HumidityResponse) => { + console.log(`callback response: ${JSON.stringify(response)}`); +} +// 传感器监听类型 +const sensorType = sensor.SensorId.HUMIDITY; +const sensorInfoParam: sensor.SensorInfoParam = {}; + +function sensorSubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + // 查询所有的传感器 + const sensorList: sensor.Sensor[] = sensor.getSensorListSync(); + if (!sensorList.length) { + return Ret.Failed; + } + // 根据实际业务逻辑获取目标传感器 + const targetSensor: sensor.Sensor = sensorList[0]; + sensorInfoParam.deviceId = targetSensor.deviceId ?? -1; + sensorInfoParam.sensorIndex = targetSensor.sensorIndex ?? -1; + // 订阅传感器事件 + sensor.on(sensorType, sensorCallback, { sensorInfoParam }); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.on. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; +} + +function sensorUnsubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + sensor.off(sensorType, sensorInfoParam, sensorCallback); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.off. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; +} +``` + ### LINEAR_ACCELEROMETER9+ off(type: SensorId.LINEAR_ACCELEROMETER, callback?: Callback<LinearAccelerometerResponse>): void @@ -2531,20 +3419,23 @@ try { } ``` -### MAGNETIC_FIELD9+ +### LINEAR_ACCELEROMETER19+ -off(type: SensorId.MAGNETIC_FIELD, callback?: Callback<MagneticFieldResponse>): void +off(type: SensorId.LINEAR_ACCELEROMETER, sensorInfoParam?: SensorInfoParam, callback?: Callback<LinearAccelerometerResponse>): void -取消订阅磁场传感器数据。 +取消订阅线性加速度传感器数据。 -**系统能力**：SystemCapability.Sensors.Sensor +**需要权限**：ohos.permission.ACCELEROMETER + +**系统能力**：SystemCapability.Sensors.Sensor **参数**： -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | -| type | [SensorId](#sensorid9).MAGNETIC_FIELD | 是 | 传感器类型，该值固定为SensorId.MAGNETIC_FIELD。 | -| callback | Callback<[MagneticFieldResponse](#magneticfieldresponse)> | 否 | 需要取消订阅的回调函数，若无此参数，则取消订阅当前类型的所有回调函数。 | +| 参数名 | 类型 | 必填 | 说明 | +|------------------| ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | +| type | [SensorId](#sensorid9).LINEAR_ACCELEROMETER | 是 | 传感器类型，该值固定为SensorId.LINEAR_ACCELERATION。 | +| sensorInfoParam | [SensorInfoParam](#sensorinfoparam19) | 否 | 传感器传入设置参数，可指定deviceId、sensorIndex | +| callback | Callback<[LinearAccelerometerResponse](#linearaccelerometerresponse)> | 否 | 需要取消订阅的回调函数，若无此参数，则取消订阅当前类型的所有回调函数。 | **错误码**： @@ -2552,7 +3443,82 @@ off(type: SensorId.MAGNETIC_FIELD, callback?: Callback<MagneticFieldResponse& | 错误码ID | 错误信息 | | -------- | ------------------------------------------------------------ | -| 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | +| 201 | Permission denied. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | + +**示例**： + +```ts +import { sensor } from '@kit.SensorServiceKit'; +import { BusinessError } from '@kit.BasicServicesKit'; + +enum Ret { OK, Failed = -1 } + +// 传感器回调 +const sensorCallback = (response: sensor.LinearAccelerometerResponse) => { + console.log(`callback response: ${JSON.stringify(response)}`); +} +// 传感器监听类型 +const sensorType = sensor.SensorId.LINEAR_ACCELEROMETER; +const sensorInfoParam: sensor.SensorInfoParam = {}; + +function sensorSubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + // 查询所有的传感器 + const sensorList: sensor.Sensor[] = sensor.getSensorListSync(); + if (!sensorList.length) { + return Ret.Failed; + } + // 根据实际业务逻辑获取目标传感器 + const targetSensor: sensor.Sensor = sensorList[0]; + sensorInfoParam.deviceId = targetSensor.deviceId ?? -1; + sensorInfoParam.sensorIndex = targetSensor.sensorIndex ?? -1; + // 订阅传感器事件 + sensor.on(sensorType, sensorCallback, { sensorInfoParam }); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.on. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; +} + +function sensorUnsubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + sensor.off(sensorType, sensorInfoParam, sensorCallback); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.off. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; +} +``` + +### MAGNETIC_FIELD9+ + +off(type: SensorId.MAGNETIC_FIELD, callback?: Callback<MagneticFieldResponse>): void + +取消订阅磁场传感器数据。 + +**系统能力**：SystemCapability.Sensors.Sensor + +**参数**： + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | +| type | [SensorId](#sensorid9).MAGNETIC_FIELD | 是 | 传感器类型，该值固定为SensorId.MAGNETIC_FIELD。 | +| callback | Callback<[MagneticFieldResponse](#magneticfieldresponse)> | 否 | 需要取消订阅的回调函数，若无此参数，则取消订阅当前类型的所有回调函数。 | + +**错误码**： + +以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 + +| 错误码ID | 错误信息 | +| -------- | ------------------------------------------------------------ | +| 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | **示例**： @@ -2581,6 +3547,81 @@ try { } ``` +### MAGNETIC_FIELD19+ + +off(type: SensorId.MAGNETIC_FIELD, sensorInfoParam?: SensorInfoParam, callback?: Callback<MagneticFieldResponse>): void + +取消订阅磁场传感器数据。 + +**系统能力**：SystemCapability.Sensors.Sensor + +**参数**： + +| 参数名 | 类型 | 必填 | 说明 | +|------------------| ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | +| type | [SensorId](#sensorid9).MAGNETIC_FIELD | 是 | 传感器类型，该值固定为SensorId.MAGNETIC_FIELD。 | +| sensorInfoParam | [SensorInfoParam](#sensorinfoparam19) | 否 | 传感器传入设置参数，可指定deviceId、sensorIndex | +| callback | Callback<[MagneticFieldResponse](#magneticfieldresponse)> | 否 | 需要取消订阅的回调函数，若无此参数，则取消订阅当前类型的所有回调函数。 | + +**错误码**： + +以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 + +| 错误码ID | 错误信息 | +| -------- | ------------------------------------------------------------ | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | + +**示例**： + +```ts +import { sensor } from '@kit.SensorServiceKit'; +import { BusinessError } from '@kit.BasicServicesKit'; + +enum Ret { OK, Failed = -1 } + +// 传感器回调 +const sensorCallback = (response: sensor.MagneticFieldResponse) => { + console.log(`callback response: ${JSON.stringify(response)}`); +} +// 传感器监听类型 +const sensorType = sensor.SensorId.MAGNETIC_FIELD; +const sensorInfoParam: sensor.SensorInfoParam = {}; + +function sensorSubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + // 查询所有的传感器 + const sensorList: sensor.Sensor[] = sensor.getSensorListSync(); + if (!sensorList.length) { + return Ret.Failed; + } + // 根据实际业务逻辑获取目标传感器 + const targetSensor: sensor.Sensor = sensorList[0]; + sensorInfoParam.deviceId = targetSensor.deviceId ?? -1; + sensorInfoParam.sensorIndex = targetSensor.sensorIndex ?? -1; + // 订阅传感器事件 + sensor.on(sensorType, sensorCallback, { sensorInfoParam }); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.on. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; +} + +function sensorUnsubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + sensor.off(sensorType, sensorInfoParam, sensorCallback); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.off. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; +} +``` + ### MAGNETIC_FIELD_UNCALIBRATED9+ off(type: SensorId.MAGNETIC_FIELD_UNCALIBRATED, callback?: Callback<MagneticFieldUncalibratedResponse>): void @@ -2631,6 +3672,81 @@ try { } ``` +### MAGNETIC_FIELD_UNCALIBRATED19+ + +off(type: SensorId.MAGNETIC_FIELD_UNCALIBRATED, sensorInfoParam?: SensorInfoParam, callback?: Callback<MagneticFieldUncalibratedResponse>): void + +取消订阅未校准的磁场传感器数据。 + +**系统能力**：SystemCapability.Sensors.Sensor + +**参数**： + +| 参数名 | 类型 | 必填 | 说明 | +|------------------| ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | +| type | [SensorId](#sensorid9).MAGNETIC_FIELD_UNCALIBRATED | 是 | 传感器类型，该值固定为SensorId.MAGNETIC_FIELD_UNCALIBRATED。 | +| sensorInfoParam | [SensorInfoParam](#sensorinfoparam19) | 否 | 传感器传入设置参数，可指定deviceId、sensorIndex | +| callback | Callback<[MagneticFieldUncalibratedResponse](#magneticfielduncalibratedresponse)> | 否 | 需要取消订阅的回调函数，若无此参数，则取消订阅当前类型的所有回调函数。 | + +**错误码**： + +以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 + +| 错误码ID | 错误信息 | +| -------- | ------------------------------------------------------------ | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | + +**示例**： + +```ts +import { sensor } from '@kit.SensorServiceKit'; +import { BusinessError } from '@kit.BasicServicesKit'; + +enum Ret { OK, Failed = -1 } + +// 传感器回调 +const sensorCallback = (response: sensor.MagneticFieldUncalibratedResponse) => { + console.log(`callback response: ${JSON.stringify(response)}`); +} +// 传感器监听类型 +const sensorType = sensor.SensorId.MAGNETIC_FIELD_UNCALIBRATED; +const sensorInfoParam: sensor.SensorInfoParam = {}; + +function sensorSubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + // 查询所有的传感器 + const sensorList: sensor.Sensor[] = sensor.getSensorListSync(); + if (!sensorList.length) { + return Ret.Failed; + } + // 根据实际业务逻辑获取目标传感器 + const targetSensor: sensor.Sensor = sensorList[0]; + sensorInfoParam.deviceId = targetSensor.deviceId ?? -1; + sensorInfoParam.sensorIndex = targetSensor.sensorIndex ?? -1; + // 订阅传感器事件 + sensor.on(sensorType, sensorCallback, { sensorInfoParam }); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.on. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; +} + +function sensorUnsubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + sensor.off(sensorType, sensorInfoParam, sensorCallback); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.off. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; +} +``` + ### ORIENTATION9+ off(type: SensorId.ORIENTATION, callback?: Callback<OrientationResponse>): void @@ -2643,10 +3759,524 @@ off(type: SensorId.ORIENTATION, callback?: Callback<OrientationResponse>): **参数**： -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ----------------------------------------------------------- | ---- | ------------------------------------------------------------ | -| type | [SensorId](#sensorid9).ORIENTATION | 是 | 传感器类型，该值固定为SensorId.ORIENTATION。 | -| callback | Callback<[OrientationResponse](#orientationresponse)> | 否 | 需要取消订阅的回调函数，若无此参数，则取消订阅当前类型的所有回调函数。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ----------------------------------------------------------- | ---- | ------------------------------------------------------------ | +| type | [SensorId](#sensorid9).ORIENTATION | 是 | 传感器类型，该值固定为SensorId.ORIENTATION。 | +| callback | Callback<[OrientationResponse](#orientationresponse)> | 否 | 需要取消订阅的回调函数，若无此参数，则取消订阅当前类型的所有回调函数。 | + +**错误码**： + +以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 + +| 错误码ID | 错误信息 | +| -------- | ------------------------------------------------------------ | +| 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | + +**示例**： + +```ts +import { sensor } from '@kit.SensorServiceKit'; +import { BusinessError } from '@kit.BasicServicesKit'; + +function callback1(data: object) { + console.info('Succeeded in getting callback1 data: ' + JSON.stringify(data)); +} + +function callback2(data: object) { + console.info('Succeeded in getting callback2 data: ' + JSON.stringify(data)); +} + +try { + sensor.on(sensor.SensorId.ORIENTATION, callback1); + sensor.on(sensor.SensorId.ORIENTATION, callback2); + // 仅取消callback1的注册 + sensor.off(sensor.SensorId.ORIENTATION, callback1); + // 取消注册SensorId.ORIENTATION的所有回调 + sensor.off(sensor.SensorId.ORIENTATION); +} catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke off. Code: ${e.code}, message: ${e.message}`); +} +``` + +### ORIENTATION19+ + +off(type: SensorId.ORIENTATION, sensorInfoParam?: SensorInfoParam, callback?: Callback<OrientationResponse>): void + +取消订阅方向传感器数据。 + +**原子化服务API**：从API Version 19开始，该接口支持在原子化服务中使用。 + +**系统能力**：SystemCapability.Sensors.Sensor + +**参数**： + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ----------------------------------------------------------- | ---- | ------------------------------------------------------------ | +| type | [SensorId](#sensorid9).ORIENTATION | 是 | 传感器类型，该值固定为SensorId.ORIENTATION。 | +| sensorInfoParam | [SensorInfoParam](#sensorinfoparam19) | 否 | 传感器传入设置参数，可指定deviceId、sensorIndex | +| callback | Callback<[OrientationResponse](#orientationresponse)> | 否 | 需要取消订阅的回调函数，若无此参数，则取消订阅当前类型的所有回调函数。 | + +**错误码**： + +以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 + +| 错误码ID | 错误信息 | +| -------- | ------------------------------------------------------------ | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | + +**示例**： + +```ts +import { sensor } from '@kit.SensorServiceKit'; +import { BusinessError } from '@kit.BasicServicesKit'; + +enum Ret { OK, Failed = -1 } + +// 传感器回调 +const sensorCallback = (response: sensor.OrientationResponse) => { + console.log(`callback response: ${JSON.stringify(response)}`); +} +// 传感器监听类型 +const sensorType = sensor.SensorId.ORIENTATION; +const sensorInfoParam: sensor.SensorInfoParam = {}; + +function sensorSubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + // 查询所有的传感器 + const sensorList: sensor.Sensor[] = sensor.getSensorListSync(); + if (!sensorList.length) { + return Ret.Failed; + } + // 根据实际业务逻辑获取目标传感器 + const targetSensor: sensor.Sensor = sensorList[0]; + sensorInfoParam.deviceId = targetSensor.deviceId ?? -1; + sensorInfoParam.sensorIndex = targetSensor.sensorIndex ?? -1; + // 订阅传感器事件 + sensor.on(sensorType, sensorCallback, { sensorInfoParam }); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.on. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; +} + +function sensorUnsubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + sensor.off(sensorType, sensorInfoParam, sensorCallback); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.off. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; +} +``` + +### PEDOMETER9+ + +off(type: SensorId.PEDOMETER, callback?: Callback<PedometerResponse>): void + +取消订阅计步器传感器数据。 + +**需要权限**：ohos.permission.ACTIVITY_MOTION + +**系统能力**：SystemCapability.Sensors.Sensor + +**参数**： + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------------------------------------- | ---- | ------------------------------------------------------------ | +| type | [SensorId](#sensorid9).PEDOMETER | 是 | 传感器类型，该值固定为SensorId.PEDOMETER。 | +| callback | Callback<[PedometerResponse](#pedometerresponse)> | 否 | 需要取消订阅的回调函数，若无此参数，则取消订阅当前类型的所有回调函数。 | + +**错误码**： + +以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 + +| 错误码ID | 错误信息 | +| -------- | ------------------------------------------------------------ | +| 201 | Permission denied. | +| 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | + +**示例**： + +```ts +import { sensor } from '@kit.SensorServiceKit'; +import { BusinessError } from '@kit.BasicServicesKit'; + +function callback1(data: object) { + console.info('Succeeded in getting callback1 data: ' + JSON.stringify(data)); +} + +function callback2(data: object) { + console.info('Succeeded in getting callback2 data: ' + JSON.stringify(data)); +} + +try { + sensor.on(sensor.SensorId.PEDOMETER, callback1); + sensor.on(sensor.SensorId.PEDOMETER, callback2); + // 仅取消callback1的注册 + sensor.off(sensor.SensorId.PEDOMETER, callback1); + // 取消注册SensorId.ORIENTATION的所有回调 + sensor.off(sensor.SensorId.PEDOMETER); +} catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke off. Code: ${e.code}, message: ${e.message}`); +} +``` + +### PEDOMETER19+ + +off(type: SensorId.PEDOMETER, sensorInfoParam?: SensorInfoParam, callback?: Callback<PedometerResponse>): void + +取消订阅计步器传感器数据。 + +**需要权限**：ohos.permission.ACTIVITY_MOTION + +**系统能力**：SystemCapability.Sensors.Sensor + +**参数**： + +| 参数名 | 类型 | 必填 | 说明 | +|------------------| ------------------------------------------------------- | ---- | ------------------------------------------------------------ | +| type | [SensorId](#sensorid9).PEDOMETER | 是 | 传感器类型，该值固定为SensorId.PEDOMETER。 | +| sensorInfoParam | [SensorInfoParam](#sensorinfoparam19) | 否 | 传感器传入设置参数，可指定deviceId、sensorIndex | +| callback | Callback<[PedometerResponse](#pedometerresponse)> | 否 | 需要取消订阅的回调函数，若无此参数，则取消订阅当前类型的所有回调函数。 | + +**错误码**： + +以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 + +| 错误码ID | 错误信息 | +| -------- | ------------------------------------------------------------ | +| 201 | Permission denied. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | + +**示例**： + +```ts +import { sensor } from '@kit.SensorServiceKit'; +import { BusinessError } from '@kit.BasicServicesKit'; + +enum Ret { OK, Failed = -1 } + +// 传感器回调 +const sensorCallback = (response: sensor.PedometerResponse) => { + console.log(`callback response: ${JSON.stringify(response)}`); +} +// 传感器监听类型 +const sensorType = sensor.SensorId.PEDOMETER; +const sensorInfoParam: sensor.SensorInfoParam = {}; + +function sensorSubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + // 查询所有的传感器 + const sensorList: sensor.Sensor[] = sensor.getSensorListSync(); + if (!sensorList.length) { + return Ret.Failed; + } + // 根据实际业务逻辑获取目标传感器 + const targetSensor: sensor.Sensor = sensorList[0]; + sensorInfoParam.deviceId = targetSensor.deviceId ?? -1; + sensorInfoParam.sensorIndex = targetSensor.sensorIndex ?? -1; + // 订阅传感器事件 + sensor.on(sensorType, sensorCallback, { sensorInfoParam }); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.on. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; +} + +function sensorUnsubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + sensor.off(sensorType, sensorInfoParam, sensorCallback); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.off. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; +} +``` + +### PEDOMETER_DETECTION9+ + +off(type: SensorId.PEDOMETER_DETECTION, callback?: Callback<PedometerDetectionResponse>): void + +取消订阅计步检测器传感器数据。 + +**需要权限**：ohos.permission.ACTIVITY_MOTION + +**系统能力**：SystemCapability.Sensors.Sensor + +**参数**： + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | +| type | [SensorId](#sensorid9).PEDOMETER_DETECTION | 是 | 传感器类型，该值固定为SensorId.PEDOMETER_DETECTION。 | +| callback | Callback<[PedometerDetectionResponse](#pedometerdetectionresponse)> | 否 | 需要取消订阅的回调函数，若无此参数，则取消订阅当前类型的所有回调函数。 | + +**错误码**： + +以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 + +| 错误码ID | 错误信息 | +| -------- | ------------------------------------------------------------ | +| 201 | Permission denied. | +| 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | + +**示例**： + +```ts +import { sensor } from '@kit.SensorServiceKit'; +import { BusinessError } from '@kit.BasicServicesKit'; + +function callback1(data: object) { + console.info('Succeeded in getting callback1 data: ' + JSON.stringify(data)); +} + +function callback2(data: object) { + console.info('Succeeded in getting callback2 data: ' + JSON.stringify(data)); +} + +try { + sensor.on(sensor.SensorId.PEDOMETER_DETECTION, callback1); + sensor.on(sensor.SensorId.PEDOMETER_DETECTION, callback2); + // 仅取消callback1的注册 + sensor.off(sensor.SensorId.PEDOMETER_DETECTION, callback1); + // 取消注册SensorId.PEDOMETER_DETECTION的所有回调 + sensor.off(sensor.SensorId.PEDOMETER_DETECTION); +} catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke off. Code: ${e.code}, message: ${e.message}`); +} +``` + +### PEDOMETER_DETECTION19+ + +off(type: SensorId.PEDOMETER_DETECTION, sensorInfoParam?: SensorInfoParam, callback?: Callback<PedometerDetectionResponse>): void + +取消订阅计步检测器传感器数据。 + +**需要权限**：ohos.permission.ACTIVITY_MOTION + +**系统能力**：SystemCapability.Sensors.Sensor + +**参数**： + +| 参数名 | 类型 | 必填 | 说明 | +|------------------| ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | +| type | [SensorId](#sensorid9).PEDOMETER_DETECTION | 是 | 传感器类型，该值固定为SensorId.PEDOMETER_DETECTION。 | +| sensorInfoParam | [SensorInfoParam](#sensorinfoparam19) | 否 | 传感器传入设置参数，可指定deviceId、sensorIndex | +| callback | Callback<[PedometerDetectionResponse](#pedometerdetectionresponse)> | 否 | 需要取消订阅的回调函数，若无此参数，则取消订阅当前类型的所有回调函数。 | + +**错误码**： + +以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 + +| 错误码ID | 错误信息 | +| -------- | ------------------------------------------------------------ | +| 201 | Permission denied. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | + +**示例**： + +```ts +import { sensor } from '@kit.SensorServiceKit'; +import { BusinessError } from '@kit.BasicServicesKit'; + +enum Ret { OK, Failed = -1 } + +// 传感器回调 +const sensorCallback = (response: sensor.PedometerDetectionResponse) => { + console.log(`callback response: ${JSON.stringify(response)}`); +} +// 传感器监听类型 +const sensorType = sensor.SensorId.PEDOMETER_DETECTION; +const sensorInfoParam: sensor.SensorInfoParam = {}; + +function sensorSubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + // 查询所有的传感器 + const sensorList: sensor.Sensor[] = sensor.getSensorListSync(); + if (!sensorList.length) { + return Ret.Failed; + } + // 根据实际业务逻辑获取目标传感器 + const targetSensor: sensor.Sensor = sensorList[0]; + sensorInfoParam.deviceId = targetSensor.deviceId ?? -1; + sensorInfoParam.sensorIndex = targetSensor.sensorIndex ?? -1; + // 订阅传感器事件 + sensor.on(sensorType, sensorCallback, { sensorInfoParam }); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.on. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; +} + +function sensorUnsubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + sensor.off(sensorType, sensorInfoParam, sensorCallback); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.off. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; +} +``` + +### PROXIMITY9+ + +off(type: SensorId.PROXIMITY, callback?: Callback<ProximityResponse>): void + +取消订阅接近光传感器数据。 + +**系统能力**：SystemCapability.Sensors.Sensor + +**参数**： + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------------------------------------- | ---- | ------------------------------------------------------------ | +| type | [SensorId](#sensorid9).PROXIMITY | 是 | 传感器类型，该值固定为SensorId.PROXIMITY。 | +| callback | Callback<[ProximityResponse](#proximityresponse)> | 否 | 需要取消订阅的回调函数，若无此参数，则取消订阅当前类型的所有回调函数。 | + +**错误码**： + +以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 + +| 错误码ID | 错误信息 | +| -------- | ------------------------------------------------------------ | +| 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | + +**示例**： + +```ts +import { sensor } from '@kit.SensorServiceKit'; +import { BusinessError } from '@kit.BasicServicesKit'; + +function callback1(data: object) { + console.info('Succeeded in getting callback1 data: ' + JSON.stringify(data)); +} + +function callback2(data: object) { + console.info('Succeeded in getting callback2 data: ' + JSON.stringify(data)); +} + +try { + sensor.on(sensor.SensorId.PROXIMITY, callback1); + sensor.on(sensor.SensorId.PROXIMITY, callback2); + // 仅取消callback1的注册 + sensor.off(sensor.SensorId.PROXIMITY, callback1); + // 取消注册SensorId.PROXIMITY的所有回调 + sensor.off(sensor.SensorId.PROXIMITY); +} catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke off. Code: ${e.code}, message: ${e.message}`); +} +``` + +### PROXIMITY19+ + +off(type: SensorId.PROXIMITY, sensorInfoParam?: SensorInfoParam, callback?: Callback<ProximityResponse>): void + +取消订阅接近光传感器数据。 + +**系统能力**：SystemCapability.Sensors.Sensor + +**参数**： + +| 参数名 | 类型 | 必填 | 说明 | +|-----------------| ------------------------------------------------------- | ---- | ------------------------------------------------------------ | +| type | [SensorId](#sensorid9).PROXIMITY | 是 | 传感器类型，该值固定为SensorId.PROXIMITY。 | +| sensorInfoParam | [SensorInfoParam](#sensorinfoparam19) | 否 | 传感器传入设置参数，可指定deviceId、sensorIndex | +| callback | Callback<[ProximityResponse](#proximityresponse)> | 否 | 需要取消订阅的回调函数，若无此参数，则取消订阅当前类型的所有回调函数。 | + +**错误码**： + +以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 + +| 错误码ID | 错误信息 | +| -------- | ------------------------------------------------------------ | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | + +**示例**： + +```ts +import { sensor } from '@kit.SensorServiceKit'; +import { BusinessError } from '@kit.BasicServicesKit'; + +enum Ret { OK, Failed = -1 } + +// 传感器回调 +const sensorCallback = (response: sensor.ProximityResponse) => { + console.log(`callback response: ${JSON.stringify(response)}`); +} +// 传感器监听类型 +const sensorType = sensor.SensorId.PROXIMITY; +const sensorInfoParam: sensor.SensorInfoParam = {}; + +function sensorSubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + // 查询所有的传感器 + const sensorList: sensor.Sensor[] = sensor.getSensorListSync(); + if (!sensorList.length) { + return Ret.Failed; + } + // 根据实际业务逻辑获取目标传感器 + const targetSensor: sensor.Sensor = sensorList[0]; + sensorInfoParam.deviceId = targetSensor.deviceId ?? -1; + sensorInfoParam.sensorIndex = targetSensor.sensorIndex ?? -1; + // 订阅传感器事件 + sensor.on(sensorType, sensorCallback, { sensorInfoParam }); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.on. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; +} + +function sensorUnsubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + sensor.off(sensorType, sensorInfoParam, sensorCallback); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.off. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; +} +``` + +### ROTATION_VECTOR9+ + +off(type: SensorId.ROTATION_VECTOR, callback?: Callback<RotationVectorResponse>): void + +取消订阅旋转矢量传感器数据。 + +**系统能力**：SystemCapability.Sensors.Sensor + +**参数**： + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | +| type | [SensorId](#sensorid9).ROTATION_VECTOR | 是 | 传感器类型，该值固定为SensorId.ROTATION_VECTOR。 | +| callback | Callback<[RotationVectorResponse](#rotationvectorresponse)> | 否 | 需要取消订阅的回调函数，若无此参数，则取消订阅当前类型的所有回调函数。 | **错误码**： @@ -2671,34 +4301,33 @@ function callback2(data: object) { } try { - sensor.on(sensor.SensorId.ORIENTATION, callback1); - sensor.on(sensor.SensorId.ORIENTATION, callback2); + sensor.on(sensor.SensorId.ROTATION_VECTOR, callback1); + sensor.on(sensor.SensorId.ROTATION_VECTOR, callback2); // 仅取消callback1的注册 - sensor.off(sensor.SensorId.ORIENTATION, callback1); - // 取消注册SensorId.ORIENTATION的所有回调 - sensor.off(sensor.SensorId.ORIENTATION); + sensor.off(sensor.SensorId.ROTATION_VECTOR, callback1); + // 取消注册SensorId.ROTATION_VECTOR的所有回调 + sensor.off(sensor.SensorId.ROTATION_VECTOR); } catch (error) { let e: BusinessError = error as BusinessError; console.error(`Failed to invoke off. Code: ${e.code}, message: ${e.message}`); } ``` -### PEDOMETER9+ - -off(type: SensorId.PEDOMETER, callback?: Callback<PedometerResponse>): void +### ROTATION_VECTOR19+ -取消订阅计步器传感器数据。 +off(type: SensorId.ROTATION_VECTOR, sensorInfoParam?: SensorInfoParam, callback?: Callback<RotationVectorResponse>): void -**需要权限**：ohos.permission.ACTIVITY_MOTION +取消订阅旋转矢量传感器数据。 **系统能力**：SystemCapability.Sensors.Sensor **参数**： -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------------------------------------------------------- | ---- | ------------------------------------------------------------ | -| type | [SensorId](#sensorid9).PEDOMETER | 是 | 传感器类型，该值固定为SensorId.PEDOMETER。 | -| callback | Callback<[PedometerResponse](#pedometerresponse)> | 否 | 需要取消订阅的回调函数，若无此参数，则取消订阅当前类型的所有回调函数。 | +| 参数名 | 类型 | 必填 | 说明 | +|------------------| ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | +| type | [SensorId](#sensorid9).ROTATION_VECTOR | 是 | 传感器类型，该值固定为SensorId.ROTATION_VECTOR。 | +| sensorInfoParam | [SensorInfoParam](#sensorinfoparam19) | 否 | 传感器传入设置参数，可指定deviceId、sensorIndex | +| callback | Callback<[RotationVectorResponse](#rotationvectorresponse)> | 否 | 需要取消订阅的回调函数，若无此参数，则取消订阅当前类型的所有回调函数。 | **错误码**： @@ -2706,8 +4335,7 @@ off(type: SensorId.PEDOMETER, callback?: Callback<PedometerResponse>): voi | 错误码ID | 错误信息 | | -------- | ------------------------------------------------------------ | -| 201 | Permission denied. | -| 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | **示例**： @@ -2715,43 +4343,65 @@ off(type: SensorId.PEDOMETER, callback?: Callback<PedometerResponse>): voi import { sensor } from '@kit.SensorServiceKit'; import { BusinessError } from '@kit.BasicServicesKit'; -function callback1(data: object) { - console.info('Succeeded in getting callback1 data: ' + JSON.stringify(data)); +enum Ret { OK, Failed = -1 } + +// 传感器回调 +const sensorCallback = (response: sensor.RotationVectorResponse) => { + console.log(`callback response: ${JSON.stringify(response)}`); } +// 传感器监听类型 +const sensorType = sensor.SensorId.ROTATION_VECTOR; +const sensorInfoParam: sensor.SensorInfoParam = {}; -function callback2(data: object) { - console.info('Succeeded in getting callback2 data: ' + JSON.stringify(data)); +function sensorSubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + // 查询所有的传感器 + const sensorList: sensor.Sensor[] = sensor.getSensorListSync(); + if (!sensorList.length) { + return Ret.Failed; + } + // 根据实际业务逻辑获取目标传感器 + const targetSensor: sensor.Sensor = sensorList[0]; + sensorInfoParam.deviceId = targetSensor.deviceId ?? -1; + sensorInfoParam.sensorIndex = targetSensor.sensorIndex ?? -1; + // 订阅传感器事件 + sensor.on(sensorType, sensorCallback, { sensorInfoParam }); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.on. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; } -try { - sensor.on(sensor.SensorId.PEDOMETER, callback1); - sensor.on(sensor.SensorId.PEDOMETER, callback2); - // 仅取消callback1的注册 - sensor.off(sensor.SensorId.PEDOMETER, callback1); - // 取消注册SensorId.ORIENTATION的所有回调 - sensor.off(sensor.SensorId.PEDOMETER); -} catch (error) { - let e: BusinessError = error as BusinessError; - console.error(`Failed to invoke off. Code: ${e.code}, message: ${e.message}`); +function sensorUnsubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + sensor.off(sensorType, sensorInfoParam, sensorCallback); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.off. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; } ``` -### PEDOMETER_DETECTION9+ - -off(type: SensorId.PEDOMETER_DETECTION, callback?: Callback<PedometerDetectionResponse>): void +### SIGNIFICANT_MOTION9+ -取消订阅计步检测器传感器数据。 +off(type: SensorId.SIGNIFICANT_MOTION, callback?: Callback<SignificantMotionResponse>): void -**需要权限**：ohos.permission.ACTIVITY_MOTION +取消订阅有效运动传感器数据。 -**系统能力**：SystemCapability.Sensors.Sensor +**系统能力**:SystemCapability.Sensors.Sensor **参数**： | 参数名 | 类型 | 必填 | 说明 | | -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | -| type | [SensorId](#sensorid9).PEDOMETER_DETECTION | 是 | 传感器类型，该值固定为SensorId.PEDOMETER_DETECTION。 | -| callback | Callback<[PedometerDetectionResponse](#pedometerdetectionresponse)> | 否 | 需要取消订阅的回调函数，若无此参数，则取消订阅当前类型的所有回调函数。 | +| type | [SensorId](#sensorid9).SIGNIFICANT_MOTION | 是 | 传感器类型，该值固定为SensorId.SIGNIFICANT_MOTION。 | +| callback | Callback<[SignificantMotionResponse](#significantmotionresponse)> | 否 | 需要取消订阅的回调函数，若无此参数，则取消订阅当前类型的所有回调函数。 | **错误码**： @@ -2759,7 +4409,6 @@ off(type: SensorId.PEDOMETER_DETECTION, callback?: Callback<PedometerDetectio | 错误码ID | 错误信息 | | -------- | ------------------------------------------------------------ | -| 201 | Permission denied. | | 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | **示例**： @@ -2777,32 +4426,33 @@ function callback2(data: object) { } try { - sensor.on(sensor.SensorId.PEDOMETER_DETECTION, callback1); - sensor.on(sensor.SensorId.PEDOMETER_DETECTION, callback2); + sensor.on(sensor.SensorId.SIGNIFICANT_MOTION, callback1); + sensor.on(sensor.SensorId.SIGNIFICANT_MOTION, callback2); // 仅取消callback1的注册 - sensor.off(sensor.SensorId.PEDOMETER_DETECTION, callback1); - // 取消注册SensorId.PEDOMETER_DETECTION的所有回调 - sensor.off(sensor.SensorId.PEDOMETER_DETECTION); + sensor.off(sensor.SensorId.SIGNIFICANT_MOTION, callback1); + // 取消注册SensorId.SIGNIFICANT_MOTION的所有回调 + sensor.off(sensor.SensorId.SIGNIFICANT_MOTION); } catch (error) { let e: BusinessError = error as BusinessError; console.error(`Failed to invoke off. Code: ${e.code}, message: ${e.message}`); } ``` -### PROXIMITY9+ +### SIGNIFICANT_MOTION19+ -off(type: SensorId.PROXIMITY, callback?: Callback<ProximityResponse>): void +off(type: SensorId.SIGNIFICANT_MOTION, sensorInfoParam?: SensorInfoParam, callback?: Callback<SignificantMotionResponse>): void -取消订阅接近光传感器数据。 +取消订阅有效运动传感器数据。 -**系统能力**：SystemCapability.Sensors.Sensor +**系统能力**:SystemCapability.Sensors.Sensor **参数**： -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------------------------------------------------------- | ---- | ------------------------------------------------------------ | -| type | [SensorId](#sensorid9).PROXIMITY | 是 | 传感器类型，该值固定为SensorId.PROXIMITY。 | -| callback | Callback<[ProximityResponse](#proximityresponse)> | 否 | 需要取消订阅的回调函数，若无此参数，则取消订阅当前类型的所有回调函数。 | +| 参数名 | 类型 | 必填 | 说明 | +|------------------| ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | +| type | [SensorId](#sensorid9).SIGNIFICANT_MOTION | 是 | 传感器类型，该值固定为SensorId.SIGNIFICANT_MOTION。 | +| sensorInfoParam | [SensorInfoParam](#sensorinfoparam19) | 否 | 传感器传入设置参数，可指定deviceId、sensorIndex | +| callback | Callback<[SignificantMotionResponse](#significantmotionresponse)> | 否 | 需要取消订阅的回调函数，若无此参数，则取消订阅当前类型的所有回调函数。 | **错误码**： @@ -2810,7 +4460,7 @@ off(type: SensorId.PROXIMITY, callback?: Callback<ProximityResponse>): voi | 错误码ID | 错误信息 | | -------- | ------------------------------------------------------------ | -| 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | **示例**： @@ -2818,32 +4468,56 @@ off(type: SensorId.PROXIMITY, callback?: Callback<ProximityResponse>): voi import { sensor } from '@kit.SensorServiceKit'; import { BusinessError } from '@kit.BasicServicesKit'; -function callback1(data: object) { - console.info('Succeeded in getting callback1 data: ' + JSON.stringify(data)); +enum Ret { OK, Failed = -1 } + +// 传感器回调 +const sensorCallback = (response: sensor.SignificantMotionResponse) => { + console.log(`callback response: ${JSON.stringify(response)}`); } +// 传感器监听类型 +const sensorType = sensor.SensorId.SIGNIFICANT_MOTION; +const sensorInfoParam: sensor.SensorInfoParam = {}; -function callback2(data: object) { - console.info('Succeeded in getting callback2 data: ' + JSON.stringify(data)); +function sensorSubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + // 查询所有的传感器 + const sensorList: sensor.Sensor[] = sensor.getSensorListSync(); + if (!sensorList.length) { + return Ret.Failed; + } + // 根据实际业务逻辑获取目标传感器 + const targetSensor: sensor.Sensor = sensorList[0]; + sensorInfoParam.deviceId = targetSensor.deviceId ?? -1; + sensorInfoParam.sensorIndex = targetSensor.sensorIndex ?? -1; + // 订阅传感器事件 + sensor.on(sensorType, sensorCallback, { sensorInfoParam }); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.on. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; } -try { - sensor.on(sensor.SensorId.PROXIMITY, callback1); - sensor.on(sensor.SensorId.PROXIMITY, callback2); - // 仅取消callback1的注册 - sensor.off(sensor.SensorId.PROXIMITY, callback1); - // 取消注册SensorId.PROXIMITY的所有回调 - sensor.off(sensor.SensorId.PROXIMITY); -} catch (error) { - let e: BusinessError = error as BusinessError; - console.error(`Failed to invoke off. Code: ${e.code}, message: ${e.message}`); +function sensorUnsubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + sensor.off(sensorType, sensorInfoParam, sensorCallback); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.off. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; } ``` -### ROTATION_VECTOR9+ +### WEAR_DETECTION9+ -off(type: SensorId.ROTATION_VECTOR, callback?: Callback<RotationVectorResponse>): void +off(type: SensorId.WEAR_DETECTION, callback?: Callback<WearDetectionResponse>): void -取消订阅旋转矢量传感器数据。 +取消订阅佩戴检测传感器数据。 **系统能力**：SystemCapability.Sensors.Sensor @@ -2851,8 +4525,8 @@ off(type: SensorId.ROTATION_VECTOR, callback?: Callback<RotationVectorRespons | 参数名 | 类型 | 必填 | 说明 | | -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | -| type | [SensorId](#sensorid9).ROTATION_VECTOR | 是 | 传感器类型，该值固定为SensorId.ROTATION_VECTOR。 | -| callback | Callback<[RotationVectorResponse](#rotationvectorresponse)> | 否 | 需要取消订阅的回调函数，若无此参数，则取消订阅当前类型的所有回调函数。 | +| type | [SensorId](#sensorid9).WEAR_DETECTION | 是 | 传感器类型，该值固定为SensorId.WEAR_DETECTION。 | +| callback | Callback<[WearDetectionResponse](#weardetectionresponse)> | 否 | 需要取消订阅的回调函数，若无此参数，则取消订阅当前类型的所有回调函数。 | **错误码**： @@ -2877,32 +4551,33 @@ function callback2(data: object) { } try { - sensor.on(sensor.SensorId.ROTATION_VECTOR, callback1); - sensor.on(sensor.SensorId.ROTATION_VECTOR, callback2); + sensor.on(sensor.SensorId.WEAR_DETECTION, callback1); + sensor.on(sensor.SensorId.WEAR_DETECTION, callback2); // 仅取消callback1的注册 - sensor.off(sensor.SensorId.ROTATION_VECTOR, callback1); - // 取消注册SensorId.ROTATION_VECTOR的所有回调 - sensor.off(sensor.SensorId.ROTATION_VECTOR); + sensor.off(sensor.SensorId.WEAR_DETECTION, callback1); + // 取消注册SensorId.WEAR_DETECTION的所有回调 + sensor.off(sensor.SensorId.WEAR_DETECTION); } catch (error) { let e: BusinessError = error as BusinessError; console.error(`Failed to invoke off. Code: ${e.code}, message: ${e.message}`); } ``` -### SIGNIFICANT_MOTION9+ +### WEAR_DETECTION19+ -off(type: SensorId.SIGNIFICANT_MOTION, callback?: Callback<SignificantMotionResponse>): void +off(type: SensorId.WEAR_DETECTION, sensorInfoParam?: SensorInfoParam, callback?: Callback<WearDetectionResponse>): void -取消订阅有效运动传感器数据。 +取消订阅佩戴检测传感器数据。 -**系统能力**:SystemCapability.Sensors.Sensor +**系统能力**：SystemCapability.Sensors.Sensor **参数**： -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | -| type | [SensorId](#sensorid9).SIGNIFICANT_MOTION | 是 | 传感器类型，该值固定为SensorId.SIGNIFICANT_MOTION。 | -| callback | Callback<[SignificantMotionResponse](#significantmotionresponse)> | 否 | 需要取消订阅的回调函数，若无此参数，则取消订阅当前类型的所有回调函数。 | +| 参数名 | 类型 | 必填 | 说明 | +|------------------| ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | +| type | [SensorId](#sensorid9).WEAR_DETECTION | 是 | 传感器类型，该值固定为SensorId.WEAR_DETECTION。 | +| sensorInfoParam | [SensorInfoParam](#sensorinfoparam19) | 否 | 传感器传入设置参数，可指定deviceId、sensorIndex | +| callback | Callback<[WearDetectionResponse](#weardetectionresponse)> | 否 | 需要取消订阅的回调函数，若无此参数，则取消订阅当前类型的所有回调函数。 | **错误码**： @@ -2910,7 +4585,7 @@ off(type: SensorId.SIGNIFICANT_MOTION, callback?: Callback<SignificantMotionR | 错误码ID | 错误信息 | | -------- | ------------------------------------------------------------ | -| 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | **示例**： @@ -2918,49 +4593,73 @@ off(type: SensorId.SIGNIFICANT_MOTION, callback?: Callback<SignificantMotionR import { sensor } from '@kit.SensorServiceKit'; import { BusinessError } from '@kit.BasicServicesKit'; -function callback1(data: object) { - console.info('Succeeded in getting callback1 data: ' + JSON.stringify(data)); +enum Ret { OK, Failed = -1 } + +// 传感器回调 +const sensorCallback = (response: sensor.WearDetectionResponse) => { + console.log(`callback response: ${JSON.stringify(response)}`); } +// 传感器监听类型 +const sensorType = sensor.SensorId.WEAR_DETECTION; +const sensorInfoParam: sensor.SensorInfoParam = {}; -function callback2(data: object) { - console.info('Succeeded in getting callback2 data: ' + JSON.stringify(data)); +function sensorSubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + // 查询所有的传感器 + const sensorList: sensor.Sensor[] = sensor.getSensorListSync(); + if (!sensorList.length) { + return Ret.Failed; + } + // 根据实际业务逻辑获取目标传感器 + const targetSensor: sensor.Sensor = sensorList[0]; + sensorInfoParam.deviceId = targetSensor.deviceId ?? -1; + sensorInfoParam.sensorIndex = targetSensor.sensorIndex ?? -1; + // 订阅传感器事件 + sensor.on(sensorType, sensorCallback, { sensorInfoParam }); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.on. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; } -try { - sensor.on(sensor.SensorId.SIGNIFICANT_MOTION, callback1); - sensor.on(sensor.SensorId.SIGNIFICANT_MOTION, callback2); - // 仅取消callback1的注册 - sensor.off(sensor.SensorId.SIGNIFICANT_MOTION, callback1); - // 取消注册SensorId.SIGNIFICANT_MOTION的所有回调 - sensor.off(sensor.SensorId.SIGNIFICANT_MOTION); -} catch (error) { - let e: BusinessError = error as BusinessError; - console.error(`Failed to invoke off. Code: ${e.code}, message: ${e.message}`); +function sensorUnsubscribe(): Ret { + let ret: Ret = Ret.OK; + try { + sensor.off(sensorType, sensorInfoParam, sensorCallback); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke sensor.off. Code: ${e.code}, message: ${e.message}`); + ret = Ret.Failed; + } + return ret; } ``` -### WEAR_DETECTION9+ +### sensorStatusChange19+ -off(type: SensorId.WEAR_DETECTION, callback?: Callback<WearDetectionResponse>): void +off(type: 'sensorStatusChange', callback?: Callback<SensorStatusEvent>): void -取消订阅佩戴检测传感器数据。 +取消监听传感器变化。 **系统能力**：SystemCapability.Sensors.Sensor **参数**： -| 参数名 | 类型 | 必填 | 说明 | -| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | -| type | [SensorId](#sensorid9).WEAR_DETECTION | 是 | 传感器类型，该值固定为SensorId.WEAR_DETECTION。 | -| callback | Callback<[WearDetectionResponse](#weardetectionresponse)> | 否 | 需要取消订阅的回调函数，若无此参数，则取消订阅当前类型的所有回调函数。 | +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------------------------------------------ | ---- | ----------------------------------------------------------- | +| sensorStatusChange | 固定传入'sensorStatusChange' | 是 | 状态监听固定参数。 | +| callback | Callback<[SensorStatusEvent](#sensorstatusevent19)> | 否 | sensor.on传入的回调函数，不传则取消所有监听。 | **错误码**： -以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 +以下错误码的详细介绍请参见[传感器错误码](errorcode-sensor.md)和[通用错误码](../errorcode-universal.md)。 | 错误码ID | 错误信息 | | -------- | ------------------------------------------------------------ | -| 401 | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. | +| 14500101 | Service exception.Possible causes:1. Sensor hdf service exception;2. Sensor service ipc exception;3.Sensor data channel exception. | **示例**： @@ -2968,27 +4667,115 @@ off(type: SensorId.WEAR_DETECTION, callback?: Callback<WearDetectionResponse& import { sensor } from '@kit.SensorServiceKit'; import { BusinessError } from '@kit.BasicServicesKit'; -function callback1(data: object) { - console.info('Succeeded in getting callback1 data: ' + JSON.stringify(data)); +try { + const statusChangeCallback = (data: sensor.SensorStatusEvent) => { + console.info('sensorStatusChange : ' + JSON.stringify(data)); + } + const statusChangeCallback2 = (data: sensor.SensorStatusEvent) => { + console.info('sensorStatusChange2 : ' + JSON.stringify(data)); + } + // 注册两个设备上线消息监听回调 + sensor.on('sensorStatusChange', statusChangeCallback); + sensor.on('sensorStatusChange', statusChangeCallback2); + + // 3秒后注销第一个监听 + setTimeout(() => { + sensor.off('sensorStatusChange', statusChangeCallback); + }, 3000); + // 5秒后注销所有监听 + setTimeout(() => { + sensor.off('sensorStatusChange'); + }, 5000); +} catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to invoke on. Code: ${e.code}, message: ${e.message}`); } +``` -function callback2(data: object) { - console.info('Succeeded in getting callback2 data: ' + JSON.stringify(data)); + +## sensor.getSensorListByDeviceSync19+ + +getSensorListByDeviceSync(deviceId?: number): Array<Sensor> + +同步获取设备的所有传感器信息。 + +**系统能力**：SystemCapability.Sensors.Sensor + +**参数**： + +| 参数名 | 类型 | 必填 | 说明 | +| --------------- | ------------------------------------------------------------ | ---- |--------| +| deviceId | number | 否 | 设备ID，默认为查询本地设备。 | + + +**返回值**： + +| 类型 | 说明 | +| ---------------------------------------------------------- | -------------- | +| Array<[Sensor](#sensor9)> | 传感器属性列表。 | + + +**示例**： + +```ts +import { sensor } from '@kit.SensorServiceKit'; +import { BusinessError } from '@kit.BasicServicesKit'; + +try { + const deviceId = 1; + // 第一个参数deviceId 非必填 + const sensorList: sensor.Sensor[] = sensor.getSensorListByDeviceSync(deviceId); + console.log(`sensorList length: ${sensorList.length}`); + console.log(`sensorList: ${JSON.stringify(sensorList)}`); +} catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`Failed to get sensorList. Code: ${e.code}, message: ${e.message}`); } +``` + + +## sensor.getSingleSensorByDeviceSync19+ + +getSingleSensorByDeviceSync(type: SensorId, deviceId?: number): Array<Sensor> + +同步获取指定设备和类型的传感器信息。 + +**系统能力**：SystemCapability.Sensors.Sensor + +**参数**： + +| 参数名 | 类型 | 必填 | 说明 | +| --------------- | ------------------------------------------------------------ | ---- |----------| +| type | [SensorId](#sensorid9) | 是 | 指定传感器类型。 | +| deviceId | number | 否 | 设备ID，默认为查询本地设备。 | + + +**返回值**： + +| 类型 | 说明 | +| ---------------------------------------------------------- | -------------- | +| Array<[Sensor](#sensor9)> | 传感器属性列表。 | + + +**示例**： + +```ts +import { sensor } from '@kit.SensorServiceKit'; +import { BusinessError } from '@kit.BasicServicesKit'; try { - sensor.on(sensor.SensorId.WEAR_DETECTION, callback1); - sensor.on(sensor.SensorId.WEAR_DETECTION, callback2); - // 仅取消callback1的注册 - sensor.off(sensor.SensorId.WEAR_DETECTION, callback1); - // 取消注册SensorId.WEAR_DETECTION的所有回调 - sensor.off(sensor.SensorId.WEAR_DETECTION); + const deviceId = 1; + // 第二个参数deviceId 非必填 + const sensorList: sensor.Sensor[] = sensor.getSingleSensorByDeviceSync(sensor.SensorId.ACCELEROMETER, deviceId); + console.log(`sensorList length: ${sensorList.length}`); + console.log(`sensorList Json: ${JSON.stringify(sensorList)}`); } catch (error) { let e: BusinessError = error as BusinessError; - console.error(`Failed to invoke off. Code: ${e.code}, message: ${e.message}`); + console.error(`Failed to get sensorList. Code: ${e.code}, message: ${e.message}`); } ``` + ## sensor.getGeomagneticInfo9+ getGeomagneticInfo(locationOptions: LocationOptions, timeMillis: number, callback: AsyncCallback<GeomagneticResponse>): void @@ -4232,6 +6019,36 @@ try { | WEAR_DETECTION | 280 | 佩戴检测传感器。 | | ACCELEROMETER_UNCALIBRATED | 281 | 未校准加速度计传感器。 | + +## SensorInfoParam19+ + +传感器传入设置参数，多传感器情况下通过deviceId、sensorIndex控制指定传感器。 + +**系统能力**：以下各项对应的系统能力均为SystemCapability.Sensors.Sensor + + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ---------------------- | ---- |-------------------------| +| deviceId | number | 否 | 设备ID：默认值为-1，表示本地设备，其它设备Id需通过[getSensorListByDeviceSync](#sensorgetsensorlistbydevicesync19)查询。 | +| sensorIndex | number | 否 | 传感器索引：默认值为0，为设备上的默认传感器，其它传感器Id需通过[getSensorListByDeviceSync](#sensorgetsensorlistbydevicesync19)查询。 | + + +## SensorStatusEvent19+ + +设备状态变化事件数据。 + +**系统能力**：以下各项对应的系统能力均为SystemCapability.Sensors.Sensor + + +| 参数名 | 类型 | 说明 | +| ------ | ---------------------- | ------------ | +| timestamp | number | 事件发生的时间戳。 | +| sensorId | number | 传感器ID。 | +| sensorIndex | number | 传感器索引。 | +| isSensorOnline | boolean | 传感器上线或者下线，true为上线，false为下线。 | +| deviceId | number | 设备ID。 | +| deviceName | string | 设备名称。 | + ## SensorType(deprecated) 表示要订阅或取消订阅的传感器类型。 @@ -4297,18 +6114,22 @@ try { **系统能力**：以下各项对应的系统能力均为SystemCapability.Sensors.Sensor -| 名称 | 类型 | 只读 | 可选 | 说明 | -| --------------- | -------- | ---------------------- | ---------------------- | ---------------------- | -| sensorName | string | 是 | 否 | 传感器名称。 | -| vendorName | string | 是 | 否 | 传感器供应商。 | -| firmwareVersion | string | 是 | 否 | 传感器固件版本。 | -| hardwareVersion | string | 是 | 否 | 传感器硬件版本。 | -| sensorId | number | 是 | 否 | 传感器类型id。 | -| maxRange | number | 是 | 否 | 传感器测量范围的最大值。 | -| minSamplePeriod | number | 是 | 否 | 允许的最小采样周期。 | -| maxSamplePeriod | number | 是 | 否 | 允许的最大采样周期。 | -| precision | number | 是 | 否 | 传感器精度。 | -| power | number | 是 | 否 | 传感器功率的估计值，单位：mA。 | +| 名称 | 类型 | 只读 | 可选 | 说明 | +|-----------------------------|---------|----|----|------------------| +| sensorName | string | 是 | 否 | 传感器名称。 | +| vendorName | string | 是 | 否 | 传感器供应商。 | +| firmwareVersion | string | 是 | 否 | 传感器固件版本。 | +| hardwareVersion | string | 是 | 否 | 传感器硬件版本。 | +| sensorId | number | 是 | 否 | 传感器类型id。 | +| maxRange | number | 是 | 否 | 传感器测量范围的最大值。 | +| minSamplePeriod | number | 是 | 否 | 允许的最小采样周期。 | +| maxSamplePeriod | number | 是 | 否 | 允许的最大采样周期。 | +| precision | number | 是 | 否 | 传感器精度。 | +| power | number | 是 | 否 | 传感器功率的估计值，单位：mA。 | +| sensorIndex19+ | number | 是 | 是 | 传感器索引。 | +| deviceId19+ | number | 是 | 是 | 设备ID。 | +| deviceName19+ | string | 是 | 是 | 设备名称。 | +| isLocalSensor19+ | boolean | 是 | 是 | 是否本地传感器。 | ## AccelerometerResponse @@ -4611,6 +6432,7 @@ try { | 名称 | 类型 | 只读 | 可选 | 说明 | | -------- | ----------------------------------------------------------- | ---- | ---- | ------------------------------------------------------------ | | interval | number\|[SensorFrequency](#sensorfrequency11)11+ | 是 | 是 | 表示传感器的上报频率，默认值为200000000ns。该属性有最小值和最大值的限制，由硬件支持的上报频率决定，当设置频率大于最大值时以最大值上报数据，小于最小值时以最小值上报数据。 | +| sensorInfoParam19+ | [SensorInfoParam](#sensorinfoparam19) | 是 | 是 | 传感器传入设置参数，可指定deviceId、sensorIndex | ## SensorFrequency11+ diff --git a/zh-cn/application-dev/reference/apis-sensor-service-kit/js-apis-vibrator.md b/zh-cn/application-dev/reference/apis-sensor-service-kit/js-apis-vibrator.md index f3487af5fe2..b4498208f22 100644 --- a/zh-cn/application-dev/reference/apis-sensor-service-kit/js-apis-vibrator.md +++ b/zh-cn/application-dev/reference/apis-sensor-service-kit/js-apis-vibrator.md @@ -629,6 +629,55 @@ stopVibration(): Promise<void> } ``` +## vibrator.stopVibration19+ + +stopVibration(param?: VibratorInfoParam): Promise<void> + +不传参默认停止本地设备所有马达的振动，也可传递参数停止指定设备马达振动。使用promise异步回调。 + +**需要权限**：ohos.permission.VIBRATE + +**系统能力**：SystemCapability.Sensors.MiscDevice + +**参数**： + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------------------------------------------ | ---- |-----------------------------------| +| param | [VibratorInfoParam](#vibratorinfoparam19) | 否 | 指出需要控制的设备和马达信息，不传参默认控制的为本地设备的全部马达 | + +**返回值**： + +| 类型 | 说明 | +| ------------------- | ------------- | +| Promise<void> | Promise对象。 | + +**错误码**： + +以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 + +| 错误码ID | 错误信息 | +| -------- | ------------------ | +| 201 | Permission denied. | +| 14600101 | Device operation failed. | + +**示例**： + + ```ts + import { vibrator } from '@kit.SensorServiceKit'; + import { BusinessError } from '@kit.BasicServicesKit'; + + try { + vibrator.stopVibration({ deviceId: 1, vibratorId: 3 }).then(() => { + console.info('Succeed in stopping vibration'); + }, (error: BusinessError) => { + console.error(`Failed to stop vibration. Code: ${error.code}, message: ${error.message}`); + }); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`); + } + ``` + ## vibrator.stopVibrationSync12+ stopVibrationSync(): void @@ -843,6 +892,234 @@ isSupportEffectSync(effectId: string): boolean } ``` +## vibrator.getEffectInfoSync19+ + +getEffectInfoSync(effectId: string, param?: VibratorInfoParam): EffectInfo; + +通过设备ID和可控马达ID获取预置振动效果信息，用于判断该预置振动效果是否受支持。 + +**系统能力**：SystemCapability.Sensors.MiscDevice + +**参数**： + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------------------------------------------ | ---- |-----------------------------| +| effectId | string | 是 | 待确认的预置振动效果。 | +| param | [VibratorInfoParam](#vibratorinfoparam19) | 否 | 指出需要查询的设备和马达信息，默认查询的是本地设备。 | + +**错误码**： + +以下错误码的详细介绍请参见[振动错误码](errorcode-vibrator.md)。 + +| 错误码ID | 错误信息 | +| -------- | ------------------------ | +| 14600101 | Device operation failed. | + +**返回值**： + +| 类型 | 说明 | +| ------- | --------------------------------------------------------- | +| [EffectInfo](#effectinfo19) | 该信息包括指示是否支持该效果。 | + + +**示例**： + + ```ts + import { vibrator } from '@kit.SensorServiceKit'; + import { BusinessError } from '@kit.BasicServicesKit'; + + try { + const effectInfo: vibrator.EffectInfo = vibrator.getEffectInfoSync('haptic.clock.timer', { deviceId: 1, vibratorId: 3}); + console.log(`isEffectSupported: ${effectInfo.isEffectSupported}`); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`); + } + ``` + + +## vibrator.getVibratorInfoSync19+ + +getVibratorInfoSync(param?: VibratorInfoParam): Array<VibratorInfo>; + +查询一个或所有设备的马达信息列表。 + +**系统能力**：SystemCapability.Sensors.MiscDevice + +**参数**： + +| 参数名 | 类型 | 必填 | 说明 | +| -------- |-----------------------------------------| ---- |-----------------------------------| +| param | [VibratorInfoParam](#vibratorinfoparam19) | 否 | 指出需要控制的设备和马达信息,不传参默认查询所有设备所有马达的信息 | + +**返回值**： + +| 类型 | 说明 | +|-------------------------------| --------------------------------------------------------- | +| [VibratorInfo](#vibratorinfo19) | 马达设备的信息。 | + + +**示例**： + + ```ts + import { vibrator } from '@kit.SensorServiceKit'; + import { BusinessError } from '@kit.BasicServicesKit'; + + try { + const vibratorInfoList: vibrator.VibratorInfo[] = vibrator.getVibratorInfoSync({ deviceId: 1, vibratorId: 3 }); + console.log(`vibratorInfoList: ${JSON.stringify(vibratorInfoList)}`); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`); + } + ``` + + +## vibrator.on19+ + +on(type: 'vibratorStateChange', callback: Callback<VibratorStatusEvent>): void + +注册一个回调函数，在马达上线或下线时触发回调。 + +**系统能力**：SystemCapability.Sensors.MiscDevice + +**参数**： + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------------------------------------------ | ---- | ----------------------------------------------------------- | +| type | 'vibratorStateChange' | 是 | 监听类型，该值固定为vibratorStateChange。 | +| callback | Callback<[VibratorStatusEvent](#vibratorstatusevent19)> | 是 | 回调函数，回调参数数据为VibratorStatusEvent。 | + +**错误码**： + +以下错误码的详细介绍请参见[振动错误码](errorcode-vibrator.md)。 + +| 错误码ID | 错误信息 | +| -------- | ------------------------ | +| 14600101 | Device operation failed. | + + +**示例**： + + ```ts + import { vibrator } from '@kit.SensorServiceKit'; + import { BusinessError } from '@kit.BasicServicesKit'; + + // 回调函数 + const vibratorStateChangeCallback = (data: vibrator.VibratorStatusEvent) => { + console.log('vibrator state callback info:', JSON.stringify(data)); + } + + try { + // 订阅 vibratorStateChange事件 + vibrator.on('vibratorStateChange', vibratorStateChangeCallback); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`); + } + ``` + + +## vibrator.off19+ + +off(type: 'vibratorStateChange', callback?: Callback<VibratorStatusEvent>): void + +注销马达上线或下线事件的回调函数。 + +**系统能力**：SystemCapability.Sensors.MiscDevice + +**参数**： + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------------------------------------------ | ---- | ----------------------------------------------------------- | +| type | 'vibratorStateChange' | 是 | 监听类型，该值固定为vibratorStateChange。 | +| callback | Callback<[VibratorStatusEvent](#vibratorstatusevent19)> | 否 | 回调函数，回调参数数据为VibratorStatusEvent，不填此参数则为注销所有callback | + +**错误码**： + +以下错误码的详细介绍请参见[振动错误码](errorcode-vibrator.md)。 + +| 错误码ID | 错误信息 | +| -------- | ------------------------ | +| 14600101 | Device operation failed. | + + +**示例**： + + ```ts + import { vibrator } from '@kit.SensorServiceKit'; + import { BusinessError } from '@kit.BasicServicesKit'; + + // 回调函数 + const vibratorStateChangeCallback = (data: vibrator.VibratorStatusEvent) => { + console.log('vibrator state callback info:', JSON.stringify(data)); + } + try { + // 取消订阅 vibratorStateChange事件 + vibrator.off('vibratorStateChange', vibratorStateChangeCallback); + // 取消订阅所有 vibratorStateChange事件 + // vibrator.off('vibratorStateChange'); + } catch (error) { + let e: BusinessError = error as BusinessError; + console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`); + } + ``` + + +## VibratorStatusEvent19+ + +振动设备上线、下线状态事件信息。 + +**系统能力**：SystemCapability.Sensors.MiscDevice + + +| 名称 | 类型 | 说明 | +| ---- | ------ |----------------------------------| +| timestamp | number | 报告事件的时间戳。 | +| deviceId | number | 设备的ID。 | +| vibratorCount | number | 设备上的马达的数量。 | +| isVibratorOnline | boolean | 指示设备的上线和下线状态，true表示上线，false表示下线。 | + + +## VibratorInfoParam19+ + +设备上马达的参数。默认情况下，VibratorInfoParam默认为查询或控制本地全部马达。 + +**系统能力**：SystemCapability.Sensors.MiscDevice + + +| 名称 | 类型 | 只读 | 可选 | 说明 | +| ---- | ------ | ---- | ---- |------------------------------------------------------------| +| deviceId | number | 否 | 是 | 设备的ID：默认值为-1，控制的为本地设备，其它设备Id需使用[getEffectInfoSync](#vibratorgeteffectinfosync19)查询。 | +| vibratorId | number | 否 | 是 | 马达ID：默认值为-1，控制的是该设备的全部马达，其它马达Id需使用[getEffectInfoSync](#vibratorgeteffectinfosync19)查询。 | + + + +## EffectInfo19+ + +查询的预制效果信息。 + +**系统能力**：SystemCapability.Sensors.MiscDevice + + +| 名称 | 类型 | 说明 | +| ---- | ------ |------------| +| isEffectSupported | boolean | 预制效果是否支持，true表示支持，false表示不支持。 | + + +## VibratorInfo19+ + +表示查询的马达信息。 + +| 名称 | 类型 | 说明 | +| ---- | ------ |-----------| +| deviceId | number | 设备ID。 | +| vibratorId | number | 马达ID。 | +| deviceName | string | 设备名称。 | +| isHdHapticSupported | boolean | 是否支持高清振动。 | +| isLocalVibrator | boolean | 是否为本地设备。 | + + ## vibrator.isHdHapticSupported12+ isHdHapticSupported(): boolean @@ -1247,10 +1524,11 @@ build(): VibratorPattern; **系统能力**：SystemCapability.Sensors.MiscDevice -| 名称 | 类型 | 必填 | 说明 | -| ----- | ---------------- | ---- | ------------------------------------------------------------ | -| id | number | 否 | 振动器ID， 默认值为0。 | -| usage | [Usage](#usage9) | 是 | 马达振动的使用场景。默认值为'unknown'，取值范围只允许在[Usage](#usage9)提供的类型中选取。 | +| 名称 | 类型 | 必填 | 说明 | +|------------------------| ---------------- | ---- | ------------------------------------------------------------ | +| id | number | 否 | 马达ID， 默认值为0。 | +| deviceId19+ | number | 否 | 设备ID。 | +| usage | [Usage](#usage9) | 是 | 马达振动的使用场景。默认值为'unknown'，取值范围只允许在[Usage](#usage9)提供的类型中选取。 | ## Usage9+ -- Gitee