@ohos.sensor (传感器)(系统接口)

sensor模块提供了获取传感器数据的能力，包括获取传感器属性列表，订阅传感器数据，以及一些通用的传感器算法。

说明：

本模块首批接口从API version 8开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。

本模块为系统接口。

导入模块

import { sensor } from '@kit.SensorServiceKit';

sensor.on

COLOR¹⁰⁺

on(type: SensorId.COLOR, callback: Callback<ColorResponse>, options?: Options): void

订阅颜色传感器数据。

系统能力：SystemCapability.Sensors.Sensor

系统API：此接口为系统接口

参数：

参数名	类型	必填	说明
type	SensorId.COLOR	是	传感器类型，该值固定为SensorId.COLOR。
callback	Callback<ColorResponse>	是	回调函数，异步上报的传感器数据固定为ColorResponse。
options	Options	否	可选参数列表，用于设置传感器上报频率，默认值为200000000ns。

错误码：

以下错误码的详细介绍请参见传感器错误码和通用错误码。

错误码ID	错误信息
202	Permission check failed. A non-system application uses the system API.
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.

示例：

import { sensor } from '@kit.SensorServiceKit';
import { BusinessError } from '@kit.BasicServicesKit';

try{
  sensor.on(sensor.SensorId.COLOR, (data: sensor.ColorResponse) => {
    console.info('Succeeded in getting the intensity of light: ' + data.lightIntensity);
    console.info('Succeeded in getting the color temperature: ' + data.colorTemperature);
  }, { interval: 100000000 });
  setTimeout(() => {
        sensor.off(sensor.SensorId.COLOR);
  }, 500);
} catch (error) {
  let e: BusinessError = error as BusinessError;
  console.error(`Failed to invoke on. Code: ${e.code}, message: ${e.message}`);
}

SAR¹⁰⁺

on(type: SensorId.SAR, callback: Callback<SarResponse>, options?: Options): void

订阅吸收比率传感器数据。

系统能力：SystemCapability.Sensors.Sensor

系统API：此接口为系统接口

参数：

参数名	类型	必填	说明
type	SensorId.SAR	是	传感器类型，该值固定为SensorId.SAR。
callback	Callback<SarResponse>	是	回调函数，异步上报的传感器数据固定为SarResponse。
options	Options	否	可选参数列表，用于设置传感器上报频率，默认值为200000000ns。

错误码：

以下错误码的详细介绍请参见传感器错误码和通用错误码。

错误码ID	错误信息
202	Permission check failed. A non-system application uses the system API.
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.

示例：

import { sensor } from '@kit.SensorServiceKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  sensor.on(sensor.SensorId.SAR, (data: sensor.SarResponse) => {
    console.info('Succeeded in getting specific absorption rate : ' + data.absorptionRatio);
  }, { interval: 100000000 });
  setTimeout(() => {
    sensor.off(sensor.SensorId.SAR);
  }, 500);
} catch (error) {
  let e: BusinessError = error as BusinessError;
  console.error(`Failed to invoke on. Code: ${e.code}, message: ${e.message}`);
}

sensor.off

COLOR¹⁰⁺

off(type: SensorId.COLOR, callback?: Callback<ColorResponse>): void

取消订阅颜色传感器数据。

系统能力：SystemCapability.Sensors.Sensor

系统API：此接口为系统接口

参数：

参数名	类型	必填	说明
type	SensorId.COLOR	是	传感器类型，该值固定为SensorId.COLOR。
callback	Callback<ColorResponse>	否	需要取消订阅的回调函数，若无此参数，则取消订阅当前类型的所有回调函数。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID	错误信息
202	Permission check failed. A non-system application uses the system API.
401	Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed.

示例：

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.COLOR, callback1);
  sensor.on(sensor.SensorId.COLOR, callback2);
  // 仅取消callback1的注册
  sensor.off(sensor.SensorId.COLOR, callback1);
  // 取消注册SensorId.COLOR的所有回调
  sensor.off(sensor.SensorId.COLOR);
} catch (error) {
  let e: BusinessError = error as BusinessError;
  console.error(`Failed to invoke off. Code: ${e.code}, message: ${e.message}`);
}

COLOR¹⁹⁺

off(type: SensorId.COLOR, sensorInfoParam?: SensorInfoParam, callback?: Callback<ColorResponse>): void

取消订阅颜色传感器数据。

系统能力：SystemCapability.Sensors.Sensor

系统API：此接口为系统接口

参数：

参数名	类型	必填	说明
type	SensorId.COLOR	是	传感器类型，该值固定为SensorId.COLOR。
sensorInfoParam	SensorInfoParam	否	传感器传入设置参数，可指定deviceId、sensorIndex
callback	Callback<ColorResponse>	否	需要取消订阅的回调函数，若无此参数，则取消订阅当前类型的所有回调函数。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码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.

示例：

import { sensor } from '@kit.SensorServiceKit';
import { BusinessError } from '@kit.BasicServicesKit';

enum Ret { OK, Failed = -1 }

// 传感器回调
const sensorCallback = (response: sensor.ColorResponse) => {
  console.info(`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 = sensorList
      // 按需过滤deviceId为1、sensorId为2的所有传感器。此处示例仅做展示，开发者需要自行调整筛选逻辑。
      .filter((sensor: sensor.Sensor) => sensor.deviceId === 1 && sensor.sensorId === 2)
      // 可能存在的多个同类型传感器，选择sensorIndex为0的传感器。
      .find((sensor: sensor.Sensor) => sensor.sensorIndex === 0);
    if (!targetSensor) {
      return Ret.Failed;
    }
    sensorInfoParam.deviceId = targetSensor.deviceId;
    sensorInfoParam.sensorIndex = targetSensor.sensorIndex;
    // 订阅传感器事件
    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;
}

SAR¹⁰⁺

off(type: SensorId.SAR, callback?: Callback<SarResponse>): void

取消订阅吸收比率传感器数据。

系统能力：SystemCapability.Sensors.Sensor

系统API：此接口为系统接口

参数：

参数名	类型	必填	说明
type	SensorId.SAR	是	传感器类型，该值固定为SensorId.SAR。
callback	Callback<SarResponse>	否	需要取消订阅的回调函数，若无此参数，则取消订阅当前类型的所有回调函数。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码ID	错误信息
202	Permission check failed. A non-system application uses the system API.
401	Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed.

示例：

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.SAR, callback1);
  sensor.on(sensor.SensorId.SAR, callback2);
  // 仅取消callback1的注册
  sensor.off(sensor.SensorId.SAR, callback1);
  // 取消注册SensorId.SAR的所有回调
  sensor.off(sensor.SensorId.SAR);
} catch (error) {
  let e: BusinessError = error as BusinessError;
  console.error(`Failed to invoke off. Code: ${e.code}, message: ${e.message}`);
}

SAR¹⁹⁺

off(type: SensorId.SAR, sensorInfoParam?: SensorInfoParam, callback?: Callback<SarResponse>): void

取消订阅吸收比率传感器数据。

系统能力：SystemCapability.Sensors.Sensor

系统API：此接口为系统接口

参数：

参数名	类型	必填	说明
type	SensorId.SAR	是	传感器类型，该值固定为SensorId.SAR。
sensorInfoParam	SensorInfoParam	否	传感器传入设置参数，可指定deviceId、sensorIndex
callback	Callback<SarResponse>	否	需要取消订阅的回调函数，若无此参数，则取消订阅当前类型的所有回调函数。

错误码：

以下错误码的详细介绍请参见通用错误码。

错误码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.

示例：

import { sensor } from '@kit.SensorServiceKit';
import { BusinessError } from '@kit.BasicServicesKit';

enum Ret { OK, Failed = -1 }

// 传感器回调
const sensorCallback = (response: sensor.SarResponse) => {
  console.info(`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 = sensorList
      // 按需过滤deviceId为1、sensorId为2的所有传感器。此处示例仅做展示，开发者需要自行调整筛选逻辑。
      .filter((sensor: sensor.Sensor) => sensor.deviceId === 1 && sensor.sensorId === 2)
      // 可能存在的多个同类型传感器，选择sensorIndex为0的传感器。
      .find((sensor: sensor.Sensor) => sensor.sensorIndex === 0);
    if (!targetSensor) {
      return Ret.Failed;
    }
    sensorInfoParam.deviceId = targetSensor.deviceId;
    sensorInfoParam.sensorIndex = targetSensor.sensorIndex;
    // 订阅传感器事件
    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;
}

SensorId⁹⁺

表示当前支持订阅或取消订阅的传感器类型。

系统能力：以下各项对应的系统能力均为SystemCapability.Sensors.Sensor

名称	值	说明
COLOR¹⁰⁺	14	颜色传感器。系统API：此接口为系统接口。
SAR¹⁰⁺	15	吸收比率传感器。系统API：此接口为系统接口。

ColorResponse¹⁰⁺

颜色传感器数据，继承于Response。

系统能力：以下各项对应的系统能力均为SystemCapability.Sensors.Sensor

系统API：此接口为系统接口

名称	类型	只读	可选	说明
lightIntensity	number	否	否	表示光的强度，单位 : 勒克斯。
colorTemperature	number	否	否	表示色温，单位 : 开尔文。

SarResponse¹⁰⁺

吸收比率传感器数据，继承于Response。

系统能力：以下各项对应的系统能力均为SystemCapability.Sensors.Sensor

系统API：此接口为系统接口

名称	类型	只读	可选	说明
absorptionRatio	number	否	否	表示具体的吸收率，单位 : W/kg。

SensorInfoParam¹⁹⁺

传感器传入设置参数。

系统能力：以下各项对应的系统能力均为SystemCapability.Sensors.Sensor

原子化服务API：从API version 19开始，该接口支持在原子化服务中使用。

名称	类型	只读	可选	说明
deviceId	number	否	是	设备ID：默认值为-1，表示本地设备，设备ID需通过getSensorList查询或者监听设备上下线接口sensorStatusChange获取。
sensorIndex	number	否	是	传感器索引：默认值为0，为设备上的默认传感器。其它传感器ID需通过getSensorList查询或者监听设备上下线接口sensorStatusChange获取。

@ohos.sensor (传感器)(系统接口)

导入模块

sensor.on

COLOR10+

SAR10+

sensor.off

COLOR10+

COLOR19+

SAR10+

SAR19+

SensorId9+

ColorResponse10+

SarResponse10+

SensorInfoParam19+

COLOR¹⁰⁺

SAR¹⁰⁺

COLOR¹⁰⁺

COLOR¹⁹⁺

SAR¹⁰⁺

SAR¹⁹⁺

SensorId⁹⁺

ColorResponse¹⁰⁺

SarResponse¹⁰⁺

SensorInfoParam¹⁹⁺