1# @ohos.vibrator (振动) 2 3vibrator模块提供控制马达振动启、停的能力。 4 5> **说明：** 6> 7> 本模块首批接口从API version 8开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8 9 10## 导入模块 11 12```js 13import vibrator from '@ohos.vibrator'; 14``` 15 16## vibrator.startVibration<sup>9+</sup> 17 18startVibration(effect: VibrateEffect, attribute: VibrateAttribute, callback: AsyncCallback<void>): void 19 20根据指定振动效果和振动属性触发马达振动。 21 22**需要权限**：ohos.permission.VIBRATE 23 24**系统能力**：SystemCapability.Sensors.MiscDevice 25 26**参数：** 27 28| 参数名 | 类型 | 必填 | 说明 | 29| --------- | -------------------------------------- | ---- | :--------------------------------------------------------- | 30| effect | [VibrateEffect](#vibrateeffect9) | 是 | 马达振动效果。 | 31| attribute | [VibrateAttribute](#vibrateattribute9) | 是 | 马达振动属性。 | 32| callback | AsyncCallback<void> | 是 | 回调函数，当马达振动成功，err为undefined，否则为错误对象。 | 33 34**错误码**： 35 36以下错误码的详细介绍请参见 [ohos.vibrator错误码](../errorcodes/errorcode-vibrator.md) 37 38| 错误码ID | 错误信息 | 39| -------- | ------------------------ | 40| 14600101 | Device operation failed. | 41 42示例： 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<void> 67 68根据指定振动效果和振动属性触发马达振动。 69 70**需要权限**：ohos.permission.VIBRATE 71 72**系统能力**：SystemCapability.Sensors.MiscDevice 73 74**参数：** 75 76| 参数名 | 类型 | 必填 | 说明 | 77| --------- | -------------------------------------- | ---- | -------------- | 78| effect | [VibrateEffect](#vibrateeffect9) | 是 | 马达振动效果。 | 79| attribute | [VibrateAttribute](#vibrateattribute9) | 是 | 马达振动属性。 | 80 81**返回值：** 82 83| 类型 | 说明 | 84| ------------------- | -------------------------------------- | 85| Promise<void> | Promise对象。 | 86 87**错误码**： 88 89以下错误码的详细介绍请参见 [ohos.vibrator错误码](../errorcodes/errorcode-vibrator.md) 90 91| 错误码ID | 错误信息 | 92| -------- | ------------------------ | 93| 14600101 | Device operation failed. | 94 95**示例：** 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<void>): void 118 119按照指定模式停止马达的振动。 120 121**需要权限**：ohos.permission.VIBRATE 122 123**系统能力**：SystemCapability.Sensors.MiscDevice 124 125**参数：** 126 127| 参数名 | 类型 | 必填 | 说明 | 128| -------- | ------------------------------------- | ---- | ------------------------------------------------------------ | 129| stopMode | [VibratorStopMode](#vibratorstopmode) | 是 | 指定的停止振动模式。 | 130| callback | AsyncCallback<void> | 是 | 回调函数。当马达停止振动成功，err为undefined，否则为错误对象。 | 131 132**示例：** 133 134 ```js 135try { 136 // 按照固定时长振动 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 // 按照VIBRATOR_STOP_MODE_TIME模式停止振动 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<void> 171 172按照指定模式停止马达的振动。 173 174**需要权限**：ohos.permission.VIBRATE 175 176**系统能力**：SystemCapability.Sensors.MiscDevice 177 178**参数：** 179 180| 参数名 | 类型 | 必填 | 说明 | 181| -------- | ------------------------------------- | ---- | ------------------------ | 182| stopMode | [VibratorStopMode](#vibratorstopmode) | 是 | 马达停止指定的振动模式。 | 183 184**返回值：** 185 186| 类型 | 说明 | 187| ------------------- | -------------------------------------- | 188| Promise<void> | Promise对象。 | 189 190**示例：** 191 192 ```js 193try { 194 // 按照固定时长振动 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 // 按照VIBRATOR_STOP_MODE_TIME模式停止振动 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 224预置的振动效果。 225 226**系统能力**：以下各项对应的系统能力均为SystemCapability.Sensors.MiscDevice 227 228| 名称 | 值 | 说明 | 229| ------------------ | -------------------- | -------------------------------- | 230| EFFECT_CLOCK_TIMER | "haptic.clock.timer" | 描述用户调整计时器时的振动效果。 | 231 232 233## VibratorStopMode 234 235停止的振动模式。 236 237**系统能力**：以下各项对应的系统能力均为SystemCapability.Sensors.MiscDevice 238 239| 名称 | 值 | 说明 | 240| ------------------------- | -------- | ------------------------------ | 241| VIBRATOR_STOP_MODE_TIME | "time" | 停止模式为duration模式的振动。 | 242| VIBRATOR_STOP_MODE_PRESET | "preset" | 停止模式为预置EffectId的振动。 | 243 244## VibrateEffect<sup>9+</sup> 245 246马达振动效果。 247 248**系统能力**：以下各项对应的系统能力均为SystemCapability.Sensors.MiscDevice 249 250| 类型 | 说明 | 251| -------------------------------- | ------------------------------ | 252| [VibrateTime](#vibratetime9) | 按照指定持续时间触发马达振动。 | 253| [VibratePreset](#vibratepreset9) | 按照预置振动类型触发马达振动。 | 254 255## VibrateTime<sup>9+</sup> 256 257马达振动时长。 258 259**系统能力**：以下各项对应的系统能力均为SystemCapability.Sensors.MiscDevice 260 261| 名称 | 值 | 说明 | 262| -------- | ------ | ------------------------------ | 263| type | "time" | 按照指定持续时间触发马达振动。 | 264| duration | - | 马达持续振动时长, 单位ms。 | 265 266## VibratePreset<sup>9+</sup> 267 268马达预置振动类型。 269 270**系统能力**：以下各项对应的系统能力均为SystemCapability.Sensors.MiscDevice 271 272| 名称 | 值 | 说明 | 273| -------- | -------- | ------------------------------ | 274| type | "preset" | 按照预置振动效果触发马达振动。 | 275| effectId | - | 预置的振动效果ID。 | 276| count | - | 重复振动的次数。 | 277 278## VibrateAttribute<sup>9+</sup> 279 280马达振动属性。 281 282**系统能力**：以下各项对应的系统能力均为SystemCapability.Sensors.MiscDevice 283 284| 名称 | 值 | 说明 | 285| ----- | ------ | -------------- | 286| id | 0 | 振动器id。 | 287| usage | - | 马达振动的使用场景。 | 288 289## Usage<sup>9+</sup> 290 291振动使用场景。 292 293**系统能力**：以下各项对应的系统能力均为SystemCapability.Sensors.MiscDevice 294 295| 名称 | 类型 | 说明 | 296| ---------------- | ------ | ------------------------------ | 297| unknown | string | 没有明确使用场景，最低优先级。 | 298| alarm | string | 用于警报场景。 | 299| ring | string | 用于铃声场景。 | 300| notification | string | 用于通知场景。 | 301| communication | string | 用于通信场景。 | 302| touch | string | 用于触摸场景。 | 303| media | string | 用于多媒体场景。 | 304| physicalFeedback | string | 用于物理反馈场景。 | 305| simulateReality | string | 用于模拟现实场景。 | 306 307## vibrator.vibrate<sup>(deprecated)</sup> 308 309vibrate(duration: number): Promise<void> 310 311按照指定持续时间触发马达振动。 312 313从API version 9 开始不再维护，建议使用 [vibrator.startVibration](#vibratorstartvibration9-1) 代替。 314 315**需要权限**：ohos.permission.VIBRATE 316 317**系统能力**：SystemCapability.Sensors.MiscDevice 318 319**参数：** 320 321| 参数名 | 类型 | 必填 | 说明 | 322| -------- | ------ | ---- | ---------------------- | 323| duration | number | 是 | 马达振动时长, 单位ms。 | 324 325**返回值：** 326 327| 类型 | 说明 | 328| ------------------- | -------------------------------------- | 329| Promise<void> | Promise对象。 | 330 331**示例：** 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<void>): void 344 345按照指定持续时间触发马达振动。 346 347从API version 9 开始不再维护，建议使用 [vibrator.startVibration](#vibratorstartvibration9) 代替。 348 349**需要权限**：ohos.permission.VIBRATE 350 351**系统能力**：SystemCapability.Sensors.MiscDevice 352 353**参数：** 354 355| 参数名 | 类型 | 必填 | 说明 | 356| -------- | ------------------------- | ---- | ---------------------------------------------------------- | 357| duration | number | 是 | 马达振动时长, 单位ms。 | 358| callback | AsyncCallback<void> | 否 | 回调函数。当马达振动成功，err为undefined，否则为错误对象。 | 359 360**示例：** 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<void> 376 377按照预置振动效果触发马达振动。 378 379从API version 9 开始不再维护，建议使用 [vibrator.startVibration](#vibratorstartvibration9-1) 代替。 380 381**需要权限**：ohos.permission.VIBRATE 382 383**系统能力**：SystemCapability.Sensors.MiscDevice 384 385**参数：** 386 387| 参数名 | 类型 | 必填 | 说明 | 388| -------- | --------------------- | ---- | ------------------ | 389| effectId | [EffectId](#effectid) | 是 | 预置的振动效果ID。 | 390 391**返回值：** 392 393| 类型 | 说明 | 394| ------------------- | -------------------------------------- | 395| Promise<void> | Promise对象。 | 396 397**示例：** 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<void>): void 411 412按照指定振动效果触发马达振动。 413 414从API version 9 开始不再维护，建议使用 [vibrator.startVibration](#vibratorstartvibration9) 代替。 415 416**需要权限**：ohos.permission.VIBRATE 417 418**系统能力**：SystemCapability.Sensors.MiscDevice 419 420**参数：** 421 422| 参数名 | 类型 | 必填 | 说明 | 423| -------- | ------------------------- | ---- | ---------------------------------------------------------- | 424| effectId | [EffectId](#effectid) | 是 | 预置的振动效果ID。 | 425| callback | AsyncCallback<void> | 否 | 回调函数。当马达振动成功，err为undefined，否则为错误对象。 | 426 427**示例：** 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<void> 442 443按照指定模式停止马达的振动。 444 445从API version 9 开始不再维护，建议使用 [vibrator.stopVibration](#vibratorstopvibration9-1) 代替。 446 447**需要权限**：ohos.permission.VIBRATE 448 449**系统能力**：SystemCapability.Sensors.MiscDevice 450 451**参数：** 452 453| 参数名 | 类型 | 必填 | 说明 | 454| -------- | ------------------------------------- | ---- | ------------------------ | 455| stopMode | [VibratorStopMode](#vibratorstopmode) | 是 | 马达停止指定的振动模式。 | 456 457**返回值：** 458 459| 类型 | 说明 | 460| ------------------- | -------------------------------------- | 461| Promise<void> | Promise对象。 | 462 463**示例：** 464 465 ```js 466// 按照effectId类型启动振动 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// 使用VIBRATOR_STOP_MODE_PRESET模式停止振动 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<void>): void 486 487按照指定模式停止马达的振动。 488 489从API version 9 开始不再维护，建议使用 [vibrator.stopVibration](#vibratorstopvibration9) 代替。 490 491**需要权限**：ohos.permission.VIBRATE 492 493**系统能力**：SystemCapability.Sensors.MiscDevice 494 495**参数：** 496 497| 参数名 | 类型 | 必填 | 说明 | 498| -------- | ------------------------------------- | ---- | ------------------------------------------------------------ | 499| stopMode | [VibratorStopMode](#vibratorstopmode) | 是 | 马达停止指定的振动模式。 | 500| callback | AsyncCallback<void> | 否 | 回调函数。当马达停止振动成功，err为undefined，否则为错误对象。 | 501 502**示例：** 503 504 ```js 505// 按照effectId类型启动振动 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// 使用VIBRATOR_STOP_MODE_PRESET模式停止振动 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