• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# @ohos.vibrator (Vibrator)
2
3The **vibrator** module provides APIs for starting or stopping vibration.
4
5> **NOTE**
6>
7> The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version.
8
9
10## Modules to Import
11
12```js
13import vibrator from '@ohos.vibrator';
14```
15
16## vibrator.startVibration<sup>9+</sup>
17
18startVibration(effect: VibrateEffect, attribute: VibrateAttribute, callback: AsyncCallback&lt;void&gt;): void
19
20Starts vibration with the specified effect and attribute. This API uses an asynchronous callback to return the result.
21
22**Required permissions**: ohos.permission.VIBRATE
23
24**System capability**: SystemCapability.Sensors.MiscDevice
25
26**Parameters**
27
28| Name   | Type                                  | Mandatory| Description                                                      |
29| --------- | -------------------------------------- | ---- | :--------------------------------------------------------- |
30| effect    | [VibrateEffect](#vibrateeffect9)       | Yes  | Vibration effect.                                            |
31| attribute | [VibrateAttribute](#vibrateattribute9) | Yes  | Vibration attribute.                                            |
32| callback  | AsyncCallback&lt;void&gt;              | Yes  | Callback used to return the result. If the vibration starts, **err** is **undefined**; otherwise, **err** is an error object.|
33
34**Error codes**
35
36For details about the error codes, see [Vibrator Error Codes](../errorcodes/errorcode-vibrator.md).
37
38| ID| Error Message                |
39| -------- | ------------------------ |
40| 14600101 | Device operation failed. |
41
42**Example**
43
44```js
45try {
46    vibrator.startVibration({
47        type: 'time',
48        duration: 1000,
49    }, {
50        id: 0,
51        usage: 'alarm'
52    }, (error) => {
53        if (error) {
54            console.error('vibrate fail, error.code: ' + error.code + 'error.message: ', + error.message);
55            return;
56        }
57        console.log('Callback returned to indicate a successful vibration.');
58    });
59} catch (err) {
60    console.error('errCode: ' + err.code + ' ,msg: ' + err.message);
61}
62```
63
64## vibrator.startVibration<sup>9+</sup>
65
66startVibration(effect: VibrateEffect, attribute: VibrateAttribute): Promise&lt;void&gt;
67
68Starts vibration with the specified effect and attribute. This API uses a promise to return the result.
69
70**Required permissions**: ohos.permission.VIBRATE
71
72**System capability**: SystemCapability.Sensors.MiscDevice
73
74**Parameters**
75
76| Name   | Type                                  | Mandatory| Description          |
77| --------- | -------------------------------------- | ---- | -------------- |
78| effect    | [VibrateEffect](#vibrateeffect9)       | Yes  | Vibration effect.|
79| attribute | [VibrateAttribute](#vibrateattribute9) | Yes  | Vibration attribute.|
80
81**Return value**
82
83| Type               | Description                                  |
84| ------------------- | -------------------------------------- |
85| Promise&lt;void&gt; | Promise that returns no value.|
86
87**Error codes**
88
89For details about the error codes, see [Vibrator Error Codes](../errorcodes/errorcode-vibrator.md).
90
91| ID| Error Message                |
92| -------- | ------------------------ |
93| 14600101 | Device operation failed. |
94
95**Example**
96
97  ```js
98try {
99    vibrator.startVibration({
100        type: 'time',
101        duration: 1000
102    }, {
103        id: 0,
104        usage: 'alarm'
105    }).then(() => {
106        console.log('Promise returned to indicate a successful vibration');
107    }, (error) => {
108        console.error('error.code' + error.code + 'error.message' + error.message);
109    });
110} catch (err) {
111    console.error('errCode: ' + err.code + ' ,msg: ' + err.message);
112}
113  ```
114
115## vibrator.stopVibration<sup>9+</sup>
116
117stopVibration(stopMode: VibratorStopMode, callback: AsyncCallback&lt;void&gt;): void
118
119Stops vibration in the specified mode. This API uses an asynchronous callback to return the result.
120
121**Required permissions**: ohos.permission.VIBRATE
122
123**System capability**: SystemCapability.Sensors.MiscDevice
124
125**Parameters**
126
127| Name  | Type                                 | Mandatory| Description                                                        |
128| -------- | ------------------------------------- | ---- | ------------------------------------------------------------ |
129| stopMode | [VibratorStopMode](#vibratorstopmode) | Yes  | Mode to stop the vibration.                                    |
130| callback | AsyncCallback&lt;void&gt;             | Yes  | Callback used to return the result. If the vibration stops, **err** is **undefined**; otherwise, **err** is an error object.|
131
132**Example**
133
134  ```js
135try {
136    // Start vibration at a fixed duration.
137    vibrator.startVibration({
138        type: 'time',
139        duration: 1000,
140    }, {
141        id: 0,
142        usage: 'alarm'
143    }, (error) => {
144        if (error) {
145            console.error('vibrate fail, error.code: ' + error.code + 'error.message: ', + error.message);
146            return;
147        }
148        console.log('Callback returned to indicate a successful vibration.');
149    });
150} catch (err) {
151    console.error('errCode: ' + err.code + ' ,msg: ' + err.message);
152}
153
154try {
155    // Stop vibration in VIBRATOR_STOP_MODE_TIME mode.
156    vibrator.stopVibration(vibrator.VibratorStopMode.VIBRATOR_STOP_MODE_TIME, function (error) {
157        if (error) {
158            console.log('error.code' + error.code + 'error.message' + error.message);
159            return;
160        }
161        console.log('Callback returned to indicate successful.');
162    })
163} catch (err) {
164    console.info('errCode: ' + err.code + ' ,msg: ' + err.message);
165}
166  ```
167
168## vibrator.stopVibration<sup>9+</sup>
169
170stopVibration(stopMode: VibratorStopMode): Promise&lt;void&gt;
171
172Stops vibration in the specified mode. This API uses a promise to return the result.
173
174**Required permissions**: ohos.permission.VIBRATE
175
176**System capability**: SystemCapability.Sensors.MiscDevice
177
178**Parameters**
179
180| Name  | Type                                 | Mandatory| Description                    |
181| -------- | ------------------------------------- | ---- | ------------------------ |
182| stopMode | [VibratorStopMode](#vibratorstopmode) | Yes  | Mode to stop the vibration.|
183
184**Return value**
185
186| Type               | Description                                  |
187| ------------------- | -------------------------------------- |
188| Promise&lt;void&gt; | Promise that returns no value.|
189
190**Example**
191
192  ```js
193try {
194    // Start vibration at a fixed duration.
195    vibrator.startVibration({
196        type: 'time',
197        duration: 1000
198    }, {
199        id: 0,
200        usage: 'alarm'
201    }).then(() => {
202        console.log('Promise returned to indicate a successful vibration');
203    }, (error) => {
204        console.error('error.code' + error.code + 'error.message' + error.message);
205    });
206} catch (err) {
207    console.error('errCode: ' + err.code + ' ,msg: ' + err.message);
208}
209
210try {
211    // Stop vibration in VIBRATOR_STOP_MODE_TIME mode.
212    vibrator.stopVibration(vibrator.VibratorStopMode.VIBRATOR_STOP_MODE_PRESET).then(() => {
213        console.log('Promise returned to indicate a successful vibration.');
214    }, (error) => {
215        console.log('error.code' + error.code + 'error.message' + error.message);
216    });
217} catch (err) {
218    console.info('errCode: ' + err.code + ' ,msg: ' + err.message);
219}
220  ```
221
222## EffectId
223
224Describes the preset vibration effect ID.
225
226**System capability**: SystemCapability.Sensors.MiscDevice
227
228| Name              | Value                  | Description                            |
229| ------------------ | -------------------- | -------------------------------- |
230| EFFECT_CLOCK_TIMER | "haptic.clock.timer" | Vibration effect of the vibrator when a user adjusts the timer.|
231
232
233## VibratorStopMode
234
235Enumerates the modes available to stop the vibration.
236
237**System capability**: SystemCapability.Sensors.MiscDevice
238
239| Name                     | Value      | Description                          |
240| ------------------------- | -------- | ------------------------------ |
241| VIBRATOR_STOP_MODE_TIME   | "time"   | The vibration to stop is in **duration** mode.|
242| VIBRATOR_STOP_MODE_PRESET | "preset" | The vibration to stop is in **EffectId** mode.|
243
244## VibrateEffect<sup>9+</sup>
245
246Describes the vibration effect.
247
248**System capability**: SystemCapability.Sensors.MiscDevice
249
250| Type                            | Description                          |
251| -------------------------------- | ------------------------------ |
252| [VibrateTime](#vibratetime9)     | Triggers vibration with the specified duration. This API uses a promise to return the result.|
253| [VibratePreset](#vibratepreset9) | Vibration with a preset effect.|
254
255## VibrateTime<sup>9+</sup>
256
257Describes the vibration with the specified duration.
258
259**System capability**: SystemCapability.Sensors.MiscDevice
260
261| Name    | Value| Description                          |
262| -------- | ------ | ------------------------------ |
263| type     | "time" | Vibration with the specified duration.|
264| duration | -      | Vibration duration, in ms.        |
265
266## VibratePreset<sup>9+</sup>
267
268Describes the vibration with a preset effect.
269
270**System capability**: SystemCapability.Sensors.MiscDevice
271
272| Name    | Value      | Description                          |
273| -------- | -------- | ------------------------------ |
274| type     | "preset" | Vibration with the specified effect.|
275| effectId | -        | Preset vibration effect ID.            |
276| count    | -        | Number of vibrations to repeat.              |
277
278## VibrateAttribute<sup>9+</sup>
279
280Describes the vibration attribute.
281
282**System capability**: SystemCapability.Sensors.MiscDevice
283
284| Name | Value| Description          |
285| ----- | ------ | -------------- |
286| id    | 0      | Vibrator ID.    |
287| usage | -      | Vibration scenario.|
288
289## Usage<sup>9+</sup>
290
291Enumerates the vibration scenarios.
292
293**System capability**: SystemCapability.Sensors.MiscDevice
294
295| Name            | Type  | Description                          |
296| ---------------- | ------ | ------------------------------ |
297| unknown          | string | Unknown scenario, with the lowest priority.|
298| alarm            | string | Vibration for alarms.          |
299| ring             | string | Vibration for incoming calls.          |
300| notification     | string | Vibration for notifications.          |
301| communication    | string | Vibration for communication.          |
302| touch            | string | Touch vibration scenario.          |
303| media            | string | Multimedia vibration scenario.        |
304| physicalFeedback | string | Physical feedback vibration scenario.      |
305| simulateReality  | string | Simulated reality vibration scenario.      |
306
307## vibrator.vibrate<sup>(deprecated)</sup>
308
309vibrate(duration: number): Promise&lt;void&gt;
310
311Triggers vibration with the specified duration. This API uses a promise to return the result.
312
313This API is deprecated since API version 9. You are advised to use [vibrator.startVibration](#vibratorstartvibration9-1) instead.
314
315**Required permissions**: ohos.permission.VIBRATE
316
317**System capability**: SystemCapability.Sensors.MiscDevice
318
319**Parameters**
320
321| Name  | Type  | Mandatory| Description                  |
322| -------- | ------ | ---- | ---------------------- |
323| duration | number | Yes  | Vibration duration, in ms.|
324
325**Return value**
326
327| Type               | Description                                  |
328| ------------------- | -------------------------------------- |
329| Promise&lt;void&gt; | Promise that returns no value.|
330
331**Example**
332
333  ```js
334vibrator.vibrate(1000).then(() => {
335    console.log('Promise returned to indicate a successful vibration.');
336}, (error) => {
337    console.log('error.code' + error.code + 'error.message' + error.message);
338});
339  ```
340
341## vibrator.vibrate<sup>(deprecated)</sup>
342
343vibrate(duration: number, callback?: AsyncCallback&lt;void&gt;): void
344
345Triggers vibration with the specified duration. This API uses an asynchronous callback to return the result.
346
347This API is deprecated since API version 9. You are advised to use [vibrator.startVibration](#vibratorstartvibration9) instead.
348
349**Required permissions**: ohos.permission.VIBRATE
350
351**System capability**: SystemCapability.Sensors.MiscDevice
352
353**Parameters**
354
355| Name  | Type                     | Mandatory| Description                                                      |
356| -------- | ------------------------- | ---- | ---------------------------------------------------------- |
357| duration | number                    | Yes  | Vibration duration, in ms.                                    |
358| callback | AsyncCallback&lt;void&gt; | No  | Callback used to return the result. If the vibration starts, **err** is **undefined**; otherwise, **err** is an error object.|
359
360**Example**
361
362  ```js
363vibrator.vibrate(1000, function (error) {
364    if (error) {
365        console.log('error.code' + error.code + 'error.message' + error.message);
366    } else {
367        console.log('Callback returned to indicate a successful vibration.');
368    }
369})
370  ```
371
372
373## vibrator.vibrate<sup>(deprecated)</sup>
374
375vibrate(effectId: EffectId): Promise&lt;void&gt;
376
377Triggers vibration with the specified effect. This API uses a promise to return the result.
378
379This API is deprecated since API version 9. You are advised to use [vibrator.startVibration](#vibratorstartvibration9-1) instead.
380
381**Required permissions**: ohos.permission.VIBRATE
382
383**System capability**: SystemCapability.Sensors.MiscDevice
384
385**Parameters**
386
387| Name  | Type                 | Mandatory| Description              |
388| -------- | --------------------- | ---- | ------------------ |
389| effectId | [EffectId](#effectid) | Yes  | Preset vibration effect ID.|
390
391**Return value**
392
393| Type               | Description                                  |
394| ------------------- | -------------------------------------- |
395| Promise&lt;void&gt; | Promise that returns no value.|
396
397**Example**
398
399  ```js
400vibrator.vibrate(vibrator.EffectId.EFFECT_CLOCK_TIMER).then(() => {
401    console.log('Promise returned to indicate a successful vibration.');
402}, (error) => {
403    console.log('error.code' + error.code + 'error.message' + error.message);
404});
405  ```
406
407
408## vibrator.vibrate<sup>(deprecated)</sup>
409
410vibrate(effectId: EffectId, callback?: AsyncCallback&lt;void&gt;): void
411
412Triggers vibration with the specified effect. This API uses an asynchronous callback to return the result.
413
414This API is deprecated since API version 9. You are advised to use [vibrator.startVibration](#vibratorstartvibration9) instead.
415
416**Required permissions**: ohos.permission.VIBRATE
417
418**System capability**: SystemCapability.Sensors.MiscDevice
419
420**Parameters**
421
422| Name  | Type                     | Mandatory| Description                                                      |
423| -------- | ------------------------- | ---- | ---------------------------------------------------------- |
424| effectId | [EffectId](#effectid)     | Yes  | Preset vibration effect ID.                                        |
425| callback | AsyncCallback&lt;void&gt; | No  | Callback used to return the result. If the vibration starts, **err** is **undefined**; otherwise, **err** is an error object.|
426
427**Example**
428
429  ```js
430vibrator.vibrate(vibrator.EffectId.EFFECT_CLOCK_TIMER, function (error) {
431    if (error) {
432        console.log('error.code' + error.code + 'error.message' + error.message);
433    } else {
434        console.log('Callback returned to indicate a successful vibration.');
435    }
436})
437  ```
438
439## vibrator.stop<sup>(deprecated)</sup>
440
441stop(stopMode: VibratorStopMode): Promise&lt;void&gt;
442
443Stops vibration in the specified mode. This API uses a promise to return the result.
444
445This API is deprecated since API version 9. You are advised to use [vibrator.stopVibration](#vibratorstopvibration9-1) instead.
446
447**Required permissions**: ohos.permission.VIBRATE
448
449**System capability**: SystemCapability.Sensors.MiscDevice
450
451**Parameters**
452
453| Name  | Type                                 | Mandatory| Description                    |
454| -------- | ------------------------------------- | ---- | ------------------------ |
455| stopMode | [VibratorStopMode](#vibratorstopmode) | Yes  | Mode to stop the vibration.|
456
457**Return value**
458
459| Type               | Description                                  |
460| ------------------- | -------------------------------------- |
461| Promise&lt;void&gt; | Promise that returns no value.|
462
463**Example**
464
465  ```js
466// Start vibration based on the specified effect ID.
467vibrator.vibrate(vibrator.EffectId.EFFECT_CLOCK_TIMER, function (error) {
468    if (error) {
469        console.log('error.code' + error.code + 'error.message' + error.message);
470    } else {
471        console.log('Callback returned to indicate a successful vibration.');
472    }
473})
474// Stop vibration in VIBRATOR_STOP_MODE_PRESET mode.
475vibrator.stop(vibrator.VibratorStopMode.VIBRATOR_STOP_MODE_PRESET).then(() => {
476    console.log('Promise returned to indicate a successful vibration.');
477}, (error) => {
478    console.log('error.code' + error.code + 'error.message' + error.message);
479});
480  ```
481
482
483## vibrator.stop<sup>(deprecated)</sup>
484
485stop(stopMode: VibratorStopMode, callback?: AsyncCallback&lt;void&gt;): void
486
487Stops vibration in the specified mode. This API uses an asynchronous callback to return the result.
488
489This API is deprecated since API version 9. You are advised to use [vibrator.stopVibration](#vibratorstopvibration9) instead.
490
491**Required permissions**: ohos.permission.VIBRATE
492
493**System capability**: SystemCapability.Sensors.MiscDevice
494
495**Parameters**
496
497| Name  | Type                                 | Mandatory| Description                                                        |
498| -------- | ------------------------------------- | ---- | ------------------------------------------------------------ |
499| stopMode | [VibratorStopMode](#vibratorstopmode) | Yes  | Mode to stop the vibration.                                    |
500| callback | AsyncCallback&lt;void&gt;             | No  | Callback used to return the result. If the vibration stops, **err** is **undefined**; otherwise, **err** is an error object.|
501
502**Example**
503
504  ```js
505// Start vibration based on the specified effect ID.
506vibrator.vibrate(vibrator.EffectId.EFFECT_CLOCK_TIMER, function (error) {
507    if (error) {
508        console.log('error.code' + error.code + 'error.message' + error.message);
509    } else {
510        console.log('Callback returned to indicate a successful vibration.');
511    }
512})
513// Stop vibration in VIBRATOR_STOP_MODE_PRESET mode.
514vibrator.stop(vibrator.VibratorStopMode.VIBRATOR_STOP_MODE_PRESET, function (error) {
515    if (error) {
516        console.log('error.code' + error.code + 'error.message' + error.message);
517    } else {
518        console.log('Callback returned to indicate successful.');
519    }
520})
521  ```
522