@system.sensor (Sensor)

The Sensor module provides APIs for querying the sensor list, subscribing to or unsubscribing from sensor data, and executing control commands.

The sensors are classified into the following categories based on their functions: motion, environment, orientation, light, body, and other categories (such as Hall effect sensors). Each category includes different sensor types. A sensor type may be a single hardware sensor or a composite of multiple hardware sensors.

NOTE

• The APIs of this module are no longer maintained since API version 8. You are advised to use @ohos.sensor instead.
• The initial APIs of this module are supported since API version 3. Newly added APIs will be marked with a superscript to indicate their earliest API version.
• This module requires hardware support and can only be debugged on real devices.

Modules to Import

import sensor from '@system.sensor';

sensor.subscribeAccelerometer

subscribeAccelerometer(options: subscribeAccelerometerOptions): void

Subscribes to data changes of the acceleration sensor. If this API is called multiple times for the same application, the last call takes effect.

System capability: SystemCapability.Sensors.Sensor.Lite

Required permissions: ohos.permission.ACCELEROMETER (a system permission)

Parameters

Name	Type	Mandatory	Description
options	subscribeAccelerometerOptions	Yes	Type of data to return.

Example

import sensor from '@system.sensor';
import { AccelerometerResponse, subscribeAccelerometerOptions } from '@system.sensor';

let accelerometerOptions: subscribeAccelerometerOptions = {
  interval: 'normal',
  success: (ret: AccelerometerResponse) => {
    console.info('Succeeded in subscribing. X-axis data: ' + ret.x);
    console.info('Succeeded in subscribing. Y-axis data: ' + ret.y);
    console.info('Succeeded in subscribing. Z-axis data: ' + ret.z);
  },
  fail: (data: string, code: number) => {
    console.error(`Failed to subscription. Code: ${code}, data: ${data}`);
  },
};
sensor.subscribeAccelerometer(accelerometerOptions);

NOTE To reduce performance overhead, you are advised to unsubscribe from the sensor data in the onDestroy callback.

sensor.unsubscribeAccelerometer

unsubscribeAccelerometer(): void

Unsubscribes from data changes of the acceleration sensor.

System capability: SystemCapability.Sensors.Sensor.Lite

Required permissions: ohos.permission.ACCELEROMETER (a system permission)

Example

sensor.unsubscribeAccelerometer();

sensor.subscribeCompass

subscribeCompass(options: SubscribeCompassOptions): void

Subscribes to data changes of the compass sensor. If this API is called multiple times for the same application, the last call takes effect.

System capability: SystemCapability.Sensors.Sensor.Lite

Parameters

Name	Type	Mandatory	Description
options	SubscribeCompassOptions	Yes	Type of data to return.

Example

import sensor from '@system.sensor';
import { CompassResponse, SubscribeCompassOptions } from '@system.sensor';

let subscribeCompassOptions: SubscribeCompassOptions = {
  success: (ret: CompassResponse) => {
    console.info('Succeeded in subscribing. Get data direction:' + ret.direction);
  },
  fail: (data: string, code: number) => {
    console.error(`Failed to subscription. Code: ${code}, data: ${data}`);
  },
};
sensor.subscribeCompass(subscribeCompassOptions);

NOTE To reduce performance overhead, you are advised to unsubscribe from the sensor data in the onDestroy callback.

sensor.unsubscribeCompass

unsubscribeCompass(): void

Unsubscribes from data changes of the compass sensor.

System capability: SystemCapability.Sensors.Sensor.Lite

Example

sensor.unsubscribeCompass();

sensor.subscribeProximity

subscribeProximity(options: SubscribeProximityOptions): void

Subscribes to data changes of the proximity sensor. If this API is called multiple times for the same application, the last call takes effect.

System capability: SystemCapability.Sensors.Sensor.Lite

Parameters

Name	Type	Mandatory	Description
options	SubscribeProximityOptions	Yes	Type of data to return.

Example

import sensor from '@system.sensor';
import { ProximityResponse, SubscribeProximityOptions } from '@system.sensor';

let subscribeProximityOptions: SubscribeProximityOptions = {
  success: (ret: ProximityResponse) => {
    console.info('Succeeded in subscribing. Get data distance:' + ret.distance);
  },
  fail: (data: string, code: number) => {
    console.error(`Failed to subscription. Code: ${code}, data: ${data}`);
  },
};
sensor.subscribeProximity(subscribeProximityOptions);

NOTE To reduce performance overhead, you are advised to unsubscribe from the sensor data in the onDestroy callback.

sensor.unsubscribeProximity

unsubscribeProximity(): void

Unsubscribes from data changes of the proximity sensor.

System capability: SystemCapability.Sensors.Sensor.Lite

Example

sensor.unsubscribeProximity();

sensor.subscribeLight

subscribeLight(options: SubscribeLightOptions): void

Subscribes to data changes of the ambient light sensor. If this API is called multiple times, the last call takes effect.

System capability: SystemCapability.Sensors.Sensor.Lite

Parameters

Name	Type	Mandatory	Description
options	SubscribeLightOptions	Yes	Type of data to return.

Example

import sensor from '@system.sensor';
import { LightResponse, SubscribeLightOptions } from '@system.sensor';

let subscribeLightOptions: SubscribeLightOptions = {
  success: (ret: LightResponse) => {
    console.info('Succeeded in subscribing. Get data intensity:' + ret.intensity);
  },
  fail: (data: string, code: number) => {
    console.error(`Failed to subscription. Code: ${code}, data: ${data}`);
  },
};
sensor.subscribeLight(subscribeLightOptions);

NOTE To reduce performance overhead, you are advised to unsubscribe from the sensor data in the onDestroy callback.

sensor.unsubscribeLight

unsubscribeLight(): void

Unsubscribes from data changes of the ambient light sensor.

System capability: SystemCapability.Sensors.Sensor.Lite

Example

sensor.unsubscribeLight();

sensor.subscribeStepCounter

subscribeStepCounter(options: SubscribeStepCounterOptions): void

Subscribes to data changes of the step counter sensor. If this API is called multiple times for the same application, the last call takes effect.

System capability: SystemCapability.Sensors.Sensor.Lite

Required permissions: ohos.permission.ACTIVITY_MOTION

Parameters

Name	Type	Mandatory	Description
options	SubscribeStepCounterOptions	Yes	Type of data to return.

Example

import sensor from '@system.sensor';
import { StepCounterResponse, SubscribeStepCounterOptions } from '@system.sensor';

let subscribeStepCounterOptions: SubscribeStepCounterOptions = {
  success: (ret: StepCounterResponse) => {
    console.info('Succeeded in subscribing. Get step value:' + ret.steps);
  },
  fail: (data: string, code: number) => {
    console.error(`Failed to subscription. Code: ${code}, data: ${data}`);
  },
};
sensor.subscribeStepCounter(subscribeStepCounterOptions);

NOTE To reduce performance overhead, you are advised to unsubscribe from the sensor data in the onDestroy callback.

sensor.unsubscribeStepCounter

unsubscribeStepCounter(): void

Unsubscribes from data changes of the step counter sensor.

System capability: SystemCapability.Sensors.Sensor.Lite

Required permissions: ohos.permission.ACTIVITY_MOTION

Example

sensor.unsubscribeStepCounter();

sensor.subscribeBarometer

subscribeBarometer(options: SubscribeBarometerOptions): void

Subscribes to data changes of the barometer sensor. If this API is called multiple times for the same application, the last call takes effect.

System capability: SystemCapability.Sensors.Sensor.Lite

Parameters

Name	Type	Mandatory	Description
options	SubscribeBarometerOptions	Yes	Type of data to return.

Example

import sensor from '@system.sensor';
import { BarometerResponse, SubscribeBarometerOptions } from '@system.sensor';

let subscribeBarometerOptions: SubscribeBarometerOptions = {
  success: (ret: BarometerResponse) => {
    console.info('Succeeded in subscribing. Get data value:' + ret.pressure);
  },
  fail: (data: string, code: number) => {
    console.error(`Failed to subscription. Code: ${code}, data: ${data}`);
  },
};
sensor.subscribeBarometer(subscribeBarometerOptions);

NOTE To reduce performance overhead, you are advised to unsubscribe from the sensor data in the onDestroy callback.

sensor.unsubscribeBarometer

unsubscribeBarometer(): void

Unsubscribes from data changes of the barometer sensor.

System capability: SystemCapability.Sensors.Sensor.Lite

Example

sensor.unsubscribeBarometer();

sensor.subscribeHeartRate

subscribeHeartRate(options: SubscribeHeartRateOptions): void

Subscribes to data changes of the heart rate sensor. If this API is called multiple times for the same application, the last call takes effect.

System capability: SystemCapability.Sensors.Sensor.Lite

Required permissions: ohos.permission.READ_HEALTH_DATA

Parameters

Name	Type	Mandatory	Description
options	SubscribeHeartRateOptions	Yes	Type of data to return.

Example

import sensor from '@system.sensor';
import { HeartRateResponse, SubscribeHeartRateOptions } from '@system.sensor';

let subscribeHeartRateOptions: SubscribeHeartRateOptions = {
  success: (ret: HeartRateResponse) => {
    console.info('Succeeded in subscribing. Get heartrate value:' + ret.heartRate);
  },
  fail: (data: string, code: number) => {
    console.error(`Failed to subscription. Code: ${code}, data: ${data}`);
  },
};
sensor.subscribeHeartRate(subscribeHeartRateOptions);

NOTE To reduce performance overhead, you are advised to unsubscribe from the sensor data in the onDestroy callback.

sensor.unsubscribeHeartRate

unsubscribeHeartRate(): void

Unsubscribes from data changes of the heart rate sensor.

System capability: SystemCapability.Sensors.Sensor.Lite

Required permissions: ohos.permission.READ_HEALTH_DATA

Example

sensor.unsubscribeHeartRate();

sensor.subscribeOnBodyState

subscribeOnBodyState(options: SubscribeOnBodyStateOptions): void

Subscribes to changes of the wearing state of a wearable device. If this API is called multiple times for the same application, the last call takes effect.

System capability: SystemCapability.Sensors.Sensor.Lite

Parameters

Name	Type	Mandatory	Description
options	SubscribeOnBodyStateOptions	Yes	Type of data to return.

Example

import sensor from '@system.sensor';
import { OnBodyStateResponse, SubscribeOnBodyStateOptions } from '@system.sensor';

let subscribeOnBodyStateOptions: SubscribeOnBodyStateOptions = {
  success: (ret: OnBodyStateResponse) => {
    console.info('Succeeded in subscribing. Get on-body state value:' + ret.value);
  },
  fail: (data: string, code: number) => {
    console.error(`Failed to subscription. Code: ${code}, data: ${data}`);
  },
};
sensor.subscribeOnBodyState(subscribeOnBodyStateOptions);

NOTE To reduce performance overhead, you are advised to unsubscribe from the sensor data in the onDestroy callback.

sensor.unsubscribeOnBodyState

unsubscribeOnBodyState(): void

Unsubscribes from changes of the wearing state of a wearable device.

System capability: SystemCapability.Sensors.Sensor.Lite

Example

sensor.unsubscribeOnBodyState();

sensor.getOnBodyState

getOnBodyState(options: GetOnBodyStateOptions): void

Obtains the wearing state of a wearable device.

System capability: SystemCapability.Sensors.Sensor.Lite

Parameters

Name	Type	Mandatory	Description
options	GetOnBodyStateOptions	Yes	Type of data to return.

Example

import sensor from '@system.sensor';
import { OnBodyStateResponse, GetOnBodyStateOptions } from '@system.sensor';

let getOnBodyStateOptions: GetOnBodyStateOptions = {
  success: (ret: OnBodyStateResponse) => {
    console.info('Succeeded in subscribing. On body state: ' + ret.value);
  },
  fail: (data: string, code: number) => {
    console.error(`Failed to subscription. Code: ${code}, data: ${data}`);
  },
};
sensor.getOnBodyState(getOnBodyStateOptions);

sensor.subscribeDeviceOrientation⁶⁺

subscribeDeviceOrientation(options: SubscribeDeviceOrientationOptions): void

Subscribes to data changes of the device orientation sensor.

If this API is called multiple times for the same application, the last call takes effect. However, this API cannot be called multiple times in one click event.

System capability: SystemCapability.Sensors.Sensor.Lite

Parameters

Name	Type	Mandatory	Description
options	SubscribeDeviceOrientationOptions	Yes	Type of data to return.

Example

import sensor from '@system.sensor';
import { DeviceOrientationResponse, SubscribeDeviceOrientationOptions } from '@system.sensor';

let subscribeDeviceOrientationOptions: SubscribeDeviceOrientationOptions = {
  interval: 'normal',
  success: (ret: DeviceOrientationResponse) => {
    console.info('Succeeded in subscribing. Alpha data: ' + ret.alpha);
    console.info('Succeeded in subscribing. Beta data: ' + ret.beta);
    console.info('Succeeded in subscribing. Gamma data: ' + ret.gamma);
  },
  fail: (data: string, code: number) => {
    console.error(`Failed to subscription. Code: ${code}, data: ${data}`);
  }
};
sensor.subscribeDeviceOrientation(subscribeDeviceOrientationOptions);

NOTE To reduce performance overhead, you are advised to unsubscribe from the sensor data in the onDestroy callback.

sensor.unsubscribeDeviceOrientation⁶⁺

unsubscribeDeviceOrientation(): void

Unsubscribes from data changes of the device orientation sensor.

System capability: SystemCapability.Sensors.Sensor.Lite

Example

sensor.unsubscribeDeviceOrientation();

sensor.subscribeGyroscope⁶⁺

subscribeGyroscope(options: SubscribeGyroscopeOptions): void

Subscribes to data changes of the gyroscope sensor.

If this API is called multiple times for the same application, the last call takes effect. However, this API cannot be called multiple times in one click event.

System capability: SystemCapability.Sensors.Sensor.Lite

Required permissions: ohos.permission.GYROSCOPE (a system permission)

Parameters

Name	Type	Mandatory	Description
options	SubscribeGyroscopeOptions	Yes	Type of data to return.

Example

import sensor from '@system.sensor';
import { GyroscopeResponse, SubscribeGyroscopeOptions } from '@system.sensor';

let subscribeGyroscopeOptions: SubscribeGyroscopeOptions = {
  interval: 'normal',
  success: (ret: GyroscopeResponse) => {
    console.info('Succeeded in subscribing. X-axis data: ' + ret.x);
    console.info('Succeeded in subscribing. Y-axis data: ' + ret.y);
    console.info('Succeeded in subscribing. Z-axis data: ' + ret.z);
  },
  fail: (data: string, code: number) => {
    console.error(`Failed to subscription. Code: ${code}, data: ${data}`);
  }
};
sensor.subscribeGyroscope(subscribeGyroscopeOptions);

NOTE To reduce performance overhead, you are advised to unsubscribe from the sensor data in the onDestroy callback.

sensor.unsubscribeGyroscope⁶⁺

unsubscribeGyroscope(): void

Unsubscribes from data changes of the gyroscope sensor.

System capability: SystemCapability.Sensors.Sensor.Lite

Required permissions: ohos.permission.GYROSCOPE (a system permission)

Example

sensor.unsubscribeGyroscope();

subscribeAccelerometerOptions

Defines the type of data to return for a subscription to the acceleration sensor data.

Required permissions: ohos.permission.ACCELEROMETER

System capability: SystemCapability.Sensors.Sensor.Lite

Name	Type	Mandatory	Description
interval	string	Yes	Execution frequency of the callback for returning the acceleration sensor data. The default value is normal. The options are as follows: - game: called at an interval of 20 ms, which is applicable to gaming scenarios. - ui: called at an interval of 60 ms, which is applicable to UI updating scenarios. - normal: called at an interval of 200 ms, which is applicable to power-saving scenarios.
success	AccelerometerResponse	Yes	Called when the acceleration sensor data changes.
fail	Function	No	Callback upon an API call failure.

AccelerometerResponse

Defines the type of data to include in an AccelerometerResponse object.

Required permissions: ohos.permission.ACCELEROMETER

System capability: SystemCapability.Sensors.Sensor.Lite

Name	Type	Mandatory	Description
x	number	Yes	Acceleration on the x-axis.
y	number	Yes	Acceleration on the y-axis.
z	number	Yes	Acceleration on the z-axis.

SubscribeCompassOptions

Defines the type of data to return for a subscription to the compass sensor data.

System capability: SystemCapability.Sensors.Sensor.Lite

Name	Type	Mandatory	Description
success	CompassResponse	Yes	Called when the compass sensor data changes.
fail	Function	No	Callback upon an API call failure.

CompassResponse

Defines the type of data to include in a CompassResponse object.

System capability: SystemCapability.Sensors.Sensor.Lite

Name	Type	Mandatory	Description
direction	number	Yes	Direction of the device, in degrees.

SubscribeProximityOptions

Defines the type of data to return for a subscription to the proximity sensor data.

System capability: SystemCapability.Sensors.Sensor.Lite

Name	Type	Mandatory	Description
success	ProximityResponse	Yes	Called when the proximity sensor data changes.
fail	Function	No	Callback upon an API call failure.

ProximityResponse

Defines the type of data to include in a ProximityResponse object.

System capability: SystemCapability.Sensors.Sensor.Lite

Name	Type	Mandatory	Description
distance	number	Yes	Distance between a visible object and the device screen.

SubscribeLightOptions

Defines the type of data to return for a subscription to the ambient light sensor data.

System capability: SystemCapability.Sensors.Sensor.Lite

Name	Type	Mandatory	Description
success	LightResponse	Yes	Called when the ambient light sensor data changes.
fail	Function	No	Callback upon an API call failure.

LightResponse

Defines the type of data to include in a LightResponse object.

System capability: SystemCapability.Sensors.Sensor.Lite

Name	Type	Mandatory	Description
intensity	number	Yes	Light intensity, in lux.

SubscribeStepCounterOptions

Defines the type of data to return for a subscription to the step counter sensor data.

Required permissions: ohos.permission.ACTIVITY_MOTION

System capability: SystemCapability.Sensors.Sensor.Lite

Name	Type	Mandatory	Description
success	StepCounterResponse	Yes	Called when the step counter sensor data changes.
fail	Function	No	Callback upon an API call failure.

StepCounterResponse

Defines the type of data to include in a StepCounterResponse object.

Required permissions: ohos.permission.ACTIVITY_MOTION

System capability: SystemCapability.Sensors.Sensor.Lite

Name	Type	Mandatory	Description
steps	number	Yes	Number of counted steps after the sensor is restarted.

SubscribeBarometerOptions

Defines the type of data to return for a subscription to the barometer sensor data.

System capability: SystemCapability.Sensors.Sensor.Lite

Name	Type	Mandatory	Description
success	BarometerResponse	Yes	Called when the barometer sensor data changes.
fail	Function	No	Callback upon an API call failure.

BarometerResponse

Defines the type of data to include in a BarometerResponse object.

System capability: SystemCapability.Sensors.Sensor.Lite

Name	Type	Mandatory	Description
pressure	number	Yes	Pressure, in pascal.

SubscribeHeartRateOptions

Defines the type of data to return for a subscription to the heart rate sensor data.

Required permissions: ohos.permission.READ_HEALTH_DATA

System capability: SystemCapability.Sensors.Sensor.Lite

Name	Type	Mandatory	Description
success	HeartRateResponse	Yes	Called when the heart rate sensor data changes. This callback is invoked every five seconds.
fail	Function	No	Callback upon an API call failure.

HeartRateResponse

Defines the type of data to include in a HeartRateResponse object.

Required permissions: ohos.permission.READ_HEALTH_DATA

System capability: SystemCapability.Sensors.Sensor.Lite

Name	Type	Mandatory	Description
heartRate	number	Yes	Heart rate.

SubscribeOnBodyStateOptions

Defines the type of data to return for a subscription to the wearing state changes.

System capability: SystemCapability.Sensors.Sensor.Lite

Name	Type	Mandatory	Description
success	OnBodyStateResponse	Yes	Called when the wearing state changes.
fail	Function	No	Callback upon an API call failure.

OnBodyStateResponse

Defines the wearing state.

System capability: SystemCapability.Sensors.Sensor.Lite

Name	Type	Mandatory	Description
value	boolean	Yes	Whether the wearable device is worn.

GetOnBodyStateOptions

Defines the type of data to return for obtaining the wearing state.

System capability: SystemCapability.Sensors.Sensor.Lite

Name	Type	Mandatory	Description
success	OnBodyStateResponse	Yes	Callback upon a successful API call.
fail	Function	No	Callback upon an API call failure.
complete	Function	No	Called when the API call is complete.

SubscribeDeviceOrientationOptions⁶⁺

Defines the type of data to return for a subscription to the device orientation sensor data.

System capability: SystemCapability.Sensors.Sensor.Lite

Name	Type	Mandatory	Description
interval	string	Yes	Interval at which the callback is invoked to return the device orientation sensor data. The default value is normal. The options are as follows: - game: called at an interval of 20 ms, which is applicable to gaming scenarios. - ui: called at an interval of 60 ms, which is applicable to UI updating scenarios. - normal: called at an interval of 200 ms, which is applicable to power-saving scenarios.
success	DeviceOrientationResponse	Yes	Called when the device orientation sensor data changes.
fail	Function	No	Callback upon an API call failure.

DeviceOrientationResponse⁶⁺

Defines the type of data to include in a DeviceOrientationResponse object.

System capability: SystemCapability.Sensors.Sensor.Lite

Name	Type	Mandatory	Description
alpha	number	Yes	Rotation angle around the Z axis when the X/Y axis of the device coincides with the X/Y axis of the earth.
beta	number	Yes	Rotation angle around the X axis when the Y/Z axis of the device coincides with the Y/Z axis of the earth.
gamma	number	Yes	Rotation angle around the Y axis when the X/Z axis of the device coincides with the X/Z axis of the earth.

SubscribeGyroscopeOptions⁶⁺

Defines the type of data to return for a subscription to the gyroscope sensor data.

Required permissions: ohos.permission.GYROSCOPE

System capability: SystemCapability.Sensors.Sensor.Lite

Name	Type	Mandatory	Description
interval	string	Yes	Interval at which the callback is invoked to return the gyroscope sensor data. The default value is normal. The options are as follows: - game: called at an interval of 20 ms, which is applicable to gaming scenarios. - ui: called at an interval of 60 ms, which is applicable to UI updating scenarios. - normal: called at an interval of 200 ms, which is applicable to power-saving scenarios.
success	GyroscopeResponse	Yes	Called when the gyroscope sensor data changes.
fail	Function	No	Callback upon an API call failure.

GyroscopeResponse⁶⁺

Defines the type of data to include in a GyroscopeResponse object.

Required permissions: ohos.permission.GYROSCOPE

System capability: SystemCapability.Sensors.Sensor.Lite

Name	Type	Mandatory	Description
x	number	Yes	Rotation angular velocity of the X axis.
y	number	Yes	Rotation angular velocity of the Y axis.
z	number	Yes	Rotation angular velocity of the Z axis.

你可能感兴趣的鸿蒙文章

harmony 鸿蒙APIs

harmony 鸿蒙System Common Events (To Be Deprecated Soon)

harmony 鸿蒙System Common Events

harmony 鸿蒙API Reference Document Description

harmony 鸿蒙Enterprise Device Management Overview (for System Applications Only)

harmony 鸿蒙BundleStatusCallback

harmony 鸿蒙@ohos.bundle.innerBundleManager (innerBundleManager)

harmony 鸿蒙@ohos.distributedBundle (Distributed Bundle Management)

harmony 鸿蒙@ohos.bundle (Bundle)

harmony 鸿蒙@ohos.enterprise.EnterpriseAdminExtensionAbility (EnterpriseAdminExtensionAbility)