1# @ohos.sensor (传感器)(系统接口)
2
3sensor模块提供了获取传感器数据的能力,包括获取传感器属性列表,订阅传感器数据,以及一些通用的传感器算法。
4
5> **说明:**
6>
7> 本模块首批接口从API version 8开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。
8>
9> 本模块为系统接口。
10
11
12## 导入模块
13
14```ts
15import { sensor } from '@kit.SensorServiceKit';
16```
17
18## sensor.on
19
20### COLOR<sup>10+</sup>
21
22on(type: SensorId.COLOR, callback: Callback&lt;ColorResponse&gt;, options?: Options): void
23
24订阅颜色传感器数据。
25
26**系统能力**:SystemCapability.Sensors.Sensor
27
28**系统API**:此接口为系统接口
29
30**参数**:
31
32| 参数名   | 类型                                              | 必填 | 说明                                                        |
33| -------- | ------------------------------------------------- | ---- | ----------------------------------------------------------- |
34| type     | [SensorId](#sensorid9).COLOR                      | 是   | 传感器类型,该值固定为SensorId.COLOR。                      |
35| callback | Callback&lt;[ColorResponse](#colorresponse10)&gt; | 是   | 回调函数,异步上报的传感器数据固定为ColorResponse。         |
36| options  | [Options](js-apis-sensor.md#options)              | 否   | 可选参数列表,用于设置传感器上报频率,默认值为200000000ns。 |
37
38**错误码**:
39
40以下错误码的详细介绍请参见[传感器错误码](errorcode-sensor.md)和[通用错误码](../errorcode-universal.md)。
41
42| 错误码ID | 错误信息                                                     |
43| -------- | ------------------------------------------------------------ |
44| 202      | Permission check failed. A non-system application uses the system API. |
45| 401      | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. |
46| 14500101 | Service exception.                                           |
47
48**示例**:
49
50```ts
51import { sensor } from '@kit.SensorServiceKit';
52import { BusinessError } from '@kit.BasicServicesKit';
53
54try{
55  sensor.on(sensor.SensorId.COLOR, (data: sensor.ColorResponse) => {
56    console.log('Succeeded in getting the intensity of light: ' + data.lightIntensity);
57    console.log('Succeeded in getting the color temperature: ' + data.colorTemperature);
58  }, { interval: 100000000 });
59  setTimeout(() => {
60        sensor.off(sensor.SensorId.COLOR);
61  }, 500);
62} catch (error) {
63  let e: BusinessError = error as BusinessError;
64  console.error(`Failed to invoke on. Code: ${e.code}, message: ${e.message}`);
65}
66```
67
68### SAR<sup>10+</sup>
69
70on(type: SensorId.SAR, callback: Callback&lt;SarResponse&gt;, options?: Options): void
71
72订阅吸收比率传感器数据。
73
74**系统能力**:SystemCapability.Sensors.Sensor
75
76**系统API**:此接口为系统接口
77
78**参数**:
79
80| 参数名   | 类型                                          | 必填 | 说明                                                        |
81| -------- | --------------------------------------------- | ---- | ----------------------------------------------------------- |
82| type     | [SensorId](#sensorid9).SAR                    | 是   | 传感器类型,该值固定为SensorId.SAR。                        |
83| callback | Callback&lt;[SarResponse](#sarresponse10)&gt; | 是   | 回调函数,异步上报的传感器数据固定为SarResponse。           |
84| options  | [Options](js-apis-sensor.md#options)          | 否   | 可选参数列表,用于设置传感器上报频率,默认值为200000000ns。 |
85
86**错误码**:
87
88以下错误码的详细介绍请参见[传感器错误码](errorcode-sensor.md)和[通用错误码](../errorcode-universal.md)。
89
90| 错误码ID | 错误信息                                                     |
91| -------- | ------------------------------------------------------------ |
92| 202      | Permission check failed. A non-system application uses the system API. |
93| 401      | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. |
94| 14500101 | Service exception.                                           |
95
96**示例**:
97
98```ts
99import { sensor } from '@kit.SensorServiceKit';
100import { BusinessError } from '@kit.BasicServicesKit';
101
102try {
103  sensor.on(sensor.SensorId.SAR, (data: sensor.SarResponse) => {
104    console.info('Succeeded in getting specific absorption rate : ' + data.absorptionRatio);
105  }, { interval: 100000000 });
106  setTimeout(() => {
107    sensor.off(sensor.SensorId.SAR);
108  }, 500);
109} catch (error) {
110  let e: BusinessError = error as BusinessError;
111  console.error(`Failed to invoke on. Code: ${e.code}, message: ${e.message}`);
112}
113```
114
115## sensor.off
116
117### COLOR<sup>10+</sup>
118
119off(type: SensorId.COLOR, callback?: Callback&lt;ColorResponse&gt;): void
120
121取消订阅颜色传感器数据。
122
123**系统能力**:SystemCapability.Sensors.Sensor
124
125**系统API**:此接口为系统接口
126
127**参数**:
128
129| 参数名   | 类型                                              | 必填 | 说明                                                         |
130| -------- | ------------------------------------------------- | ---- | ------------------------------------------------------------ |
131| type     | [SensorId](#sensorid9).COLOR                      | 是   | 传感器类型,该值固定为SensorId.COLOR。                       |
132| callback | Callback&lt;[ColorResponse](#colorresponse10)&gt; | 否   | 需要取消订阅的回调函数,若无此参数,则取消订阅当前类型的所有回调函数。 |
133
134**错误码**:
135
136以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。
137
138| 错误码ID | 错误信息                                                     |
139| -------- | ------------------------------------------------------------ |
140| 202      | Permission check failed. A non-system application uses the system API. |
141| 401      | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. |
142
143**示例**:
144
145```ts
146import { sensor } from '@kit.SensorServiceKit';
147import { BusinessError } from '@kit.BasicServicesKit';
148
149function callback1(data: object) {
150  console.info('Succeeded in getting callback1 data: ' + JSON.stringify(data));
151}
152
153function callback2(data: object) {
154  console.info('Succeeded in getting callback2 data: ' + JSON.stringify(data));
155}
156
157try {
158  sensor.on(sensor.SensorId.COLOR, callback1);
159  sensor.on(sensor.SensorId.COLOR, callback2);
160  // 仅取消callback1的注册
161  sensor.off(sensor.SensorId.COLOR, callback1);
162  // 取消注册SensorId.COLOR的所有回调
163  sensor.off(sensor.SensorId.COLOR);
164} catch (error) {
165  let e: BusinessError = error as BusinessError;
166  console.error(`Failed to invoke off. Code: ${e.code}, message: ${e.message}`);
167}
168```
169
170### SAR<sup>10+</sup>
171
172off(type: SensorId.SAR, callback?: Callback&lt;SarResponse&gt;): void
173
174取消订阅吸收比率传感器数据。
175
176**系统能力**:SystemCapability.Sensors.Sensor
177
178**系统API**:此接口为系统接口
179
180**参数**:
181
182| 参数名   | 类型                                          | 必填 | 说明                                                         |
183| -------- | --------------------------------------------- | ---- | ------------------------------------------------------------ |
184| type     | [SensorId](#sensorid9).SAR                    | 是   | 传感器类型,该值固定为SensorId.SAR。                         |
185| callback | Callback&lt;[SarResponse](#sarresponse10)&gt; | 否   | 需要取消订阅的回调函数,若无此参数,则取消订阅当前类型的所有回调函数。 |
186
187**错误码**:
188
189以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。
190
191| 错误码ID | 错误信息                                                     |
192| -------- | ------------------------------------------------------------ |
193| 202      | Permission check failed. A non-system application uses the system API. |
194| 401      | Parameter error.Possible causes:1. Mandatory parameters are left unspecified;2. Incorrect parameter types;3. Parameter verification failed. |
195
196**示例**:
197
198```ts
199import { sensor } from '@kit.SensorServiceKit';
200import { BusinessError } from '@kit.BasicServicesKit';
201
202function callback1(data: object) {
203  console.info('Succeeded in getting callback1 data: ' + JSON.stringify(data));
204}
205
206function callback2(data: object) {
207  console.info('Succeeded in getting callback2 data: ' + JSON.stringify(data));
208}
209
210try {
211  sensor.on(sensor.SensorId.SAR, callback1);
212  sensor.on(sensor.SensorId.SAR, callback2);
213  // 仅取消callback1的注册
214  sensor.off(sensor.SensorId.SAR, callback1);
215  // 取消注册SensorId.SAR的所有回调
216  sensor.off(sensor.SensorId.SAR);
217} catch (error) {
218  let e: BusinessError = error as BusinessError;
219  console.error(`Failed to invoke off. Code: ${e.code}, message: ${e.message}`);
220}
221```
222
223## SensorId<sup>9+</sup>
224
225表示当前支持订阅或取消订阅的传感器类型。
226
227**系统能力**:以下各项对应的系统能力均为SystemCapability.Sensors.Sensor
228
229| 名称                | 值   | 说明                                          |
230| ------------------- | ---- | --------------------------------------------- |
231| COLOR<sup>10+</sup> | 14   | 颜色传感器。<br>系统API:此接口为系统接口     |
232| SAR<sup>10+</sup>   | 15   | 吸收比率传感器。<br>系统API:此接口为系统接口 |
233
234## ColorResponse<sup>10+</sup>
235
236颜色传感器数据,继承于[Response](js-apis-sensor.md#response)。
237
238**系统能力**:以下各项对应的系统能力均为SystemCapability.Sensors.Sensor
239
240**系统API**:此接口为系统接口
241
242
243| 名称             | 类型   | 可读 | 可写 | 说明                          |
244| ---------------- | ------ | ---- | ---- | ----------------------------- |
245| lightIntensity   | number | 是   | 是   | 表示光的强度,单位 : 勒克斯。 |
246| colorTemperature | number | 是   | 是   | 表示色温,单位 : 开尔文。     |
247
248## SarResponse<sup>10+ </sup>
249
250吸收比率传感器数据,继承于[Response](js-apis-sensor.md#response)。
251
252**系统能力**:以下各项对应的系统能力均为SystemCapability.Sensors.Sensor
253
254**系统API**:此接口为系统接口
255
256
257| 名称            | 类型   | 可读 | 可写 | 说明                            |
258| --------------- | ------ | ---- | ---- | ------------------------------- |
259| absorptionRatio | number | 是   | 是   | 表示具体的吸收率,单位 : W/kg。 |
260