1/* 2 * Copyright (c) 2021 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16/** 17 * @file 18 * @kit SensorServiceKit 19 */ 20 21import { AsyncCallback, Callback } from './@ohos.base'; 22 23/** 24 * This module provides the capability to control motor vibration. 25 * 26 * @namespace vibrator 27 * @syscap SystemCapability.Sensors.MiscDevice 28 * @since 8 29 */ 30/** 31 * This module provides the capability to control motor vibration. 32 * 33 * @namespace vibrator 34 * @syscap SystemCapability.Sensors.MiscDevice 35 * @atomicservice 36 * @since arkts {'1.1':'11', '1.2':'20'} 37 * @arkts 1.1&1.2 38 */ 39declare namespace vibrator { 40 /** 41 * The trigger motor vibrates for a specified length of time. 42 * 43 * @permission ohos.permission.VIBRATE 44 * @param { number } duration Indicate the duration of the motor vibration. 45 * @param { AsyncCallback<void> } callback The callback of vibrate. 46 * @syscap SystemCapability.Sensors.MiscDevice 47 * @since 8 48 * @deprecated since 9 49 * @useinstead vibrator#startVibration 50 */ 51 function vibrate(duration: number, callback?: AsyncCallback<void>): void; 52 53 /** 54 * The trigger motor vibrates for a specified length of time. 55 * 56 * @permission ohos.permission.VIBRATE 57 * @param { number } duration Indicate the duration of the motor vibration. 58 * @returns { Promise<void> } Promise used to return the result. 59 * @syscap SystemCapability.Sensors.MiscDevice 60 * @since 8 61 * @deprecated since 9 62 * @useinstead vibrator#startVibration 63 */ 64 function vibrate(duration: number): Promise<void>; 65 66 /** 67 * The trigger motor vibrates for the specified effect of the preset. 68 * 69 * @permission ohos.permission.VIBRATE 70 * @param { EffectId } effectId Indicate the specified effect of the preset, {@code EffectId}. 71 * @returns { Promise<void> } Promise used to return the result. 72 * @syscap SystemCapability.Sensors.MiscDevice 73 * @since 8 74 * @deprecated since 9 75 * @useinstead vibrator#startVibration 76 */ 77 function vibrate(effectId: EffectId): Promise<void>; 78 79 /** 80 * The trigger motor vibrates for the specified effect of the preset. 81 * 82 * @permission ohos.permission.VIBRATE 83 * @param { EffectId } effectId Indicate the specified effect of the preset, {@code EffectId}. 84 * @param { AsyncCallback<void> } callback The callback of vibrate. 85 * @syscap SystemCapability.Sensors.MiscDevice 86 * @since 8 87 * @deprecated since 9 88 * @useinstead vibrator#startVibration 89 */ 90 function vibrate(effectId: EffectId, callback?: AsyncCallback<void>): void; 91 92 /** 93 * Trigger vibrator vibration. 94 * 95 * @permission ohos.permission.VIBRATE 96 * @param { VibrateEffect } effect - Indicate vibrate effect, {@code VibrateEffect}. 97 * @param { VibrateAttribute } attribute - Indicate vibrate attribute, {@code VibrateAttribute}. 98 * @param { AsyncCallback<void> } callback - The callback of startVibration. 99 * @throws { BusinessError } 201 - Permission denied. 100 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 101 * <br> 2. Incorrect parameter types; 3. Parameter verification failed. 102 * @throws { BusinessError } 801 - Capability not supported. 103 * @throws { BusinessError } 14600101 - Device operation failed. 104 * @syscap SystemCapability.Sensors.MiscDevice 105 * @since 9 106 */ 107 /** 108 * Trigger vibrator vibration. 109 * 110 * @permission ohos.permission.VIBRATE 111 * @param { VibrateEffect } effect - Indicate vibrate effect, {@code VibrateEffect} 112 * @param { VibrateAttribute } attribute - Indicate vibrate attribute, {@code VibrateAttribute} 113 * @param { AsyncCallback<void> } callback - The callback of startVibration 114 * @throws { BusinessError } 201 - Permission denied 115 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 116 * <br> 2. Incorrect parameter types; 3. Parameter verification failed. 117 * @throws { BusinessError } 801 - Capability not supported 118 * @throws { BusinessError } 14600101 - Device operation failed 119 * @syscap SystemCapability.Sensors.MiscDevice 120 * @atomicservice 121 * @since arkts {'1.1':'11', '1.2':'20'} 122 * @arkts 1.1&1.2 123 */ 124 function startVibration(effect: VibrateEffect, attribute: VibrateAttribute, callback: AsyncCallback<void>): void; 125 126 /** 127 * Trigger vibrator vibration. 128 * 129 * @permission ohos.permission.VIBRATE 130 * @param { VibrateEffect } effect - Indicate vibrate effect, {@code VibrateEffect}. 131 * @param { VibrateAttribute } attribute - Indicate vibrate attribute, {@code VibrateAttribute}. 132 * @returns { Promise<void> } Promise used to return the result. 133 * @throws { BusinessError } 201 - Permission denied. 134 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 135 * <br> 2. Incorrect parameter types; 3. Parameter verification failed. 136 * @throws { BusinessError } 801 - Capability not supported. 137 * @throws { BusinessError } 14600101 - Device operation failed. 138 * @syscap SystemCapability.Sensors.MiscDevice 139 * @since 9 140 */ 141 /** 142 * Trigger vibrator vibration. 143 * 144 * @permission ohos.permission.VIBRATE 145 * @param { VibrateEffect } effect - Indicate vibrate effect, {@code VibrateEffect}. 146 * @param { VibrateAttribute } attribute - Indicate vibrate attribute, {@code VibrateAttribute}. 147 * @returns { Promise<void> } Promise used to return the result. 148 * @throws { BusinessError } 201 - Permission denied. 149 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 150 * <br> 2. Incorrect parameter types; 3. Parameter verification failed. 151 * @throws { BusinessError } 801 - Capability not supported. 152 * @throws { BusinessError } 14600101 - Device operation failed. 153 * @syscap SystemCapability.Sensors.MiscDevice 154 * @atomicservice 155 * @since arkts {'1.1':'11', '1.2':'20'} 156 * @arkts 1.1&1.2 157 */ 158 function startVibration(effect: VibrateEffect, attribute: VibrateAttribute): Promise<void>; 159 160 /** 161 * Stop the vibrator from vibrating. 162 * 163 * @permission ohos.permission.VIBRATE 164 * @param { VibratorStopMode } stopMode - Indicate the stop mode in which the motor vibrates, {@code VibratorStopMode}. 165 * @returns { Promise<void> } Promise used to return the result. 166 * @throws { BusinessError } 201 - Permission denied. 167 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 168 * <br> 2. Incorrect parameter types; 3. Parameter verification failed. 169 * @syscap SystemCapability.Sensors.MiscDevice 170 * @since 9 171 */ 172 function stopVibration(stopMode: VibratorStopMode): Promise<void>; 173 174 /** 175 * Stop the vibrator from vibrating. 176 * 177 * @permission ohos.permission.VIBRATE 178 * @param { VibratorStopMode } stopMode - Indicate the stop mode in which the motor vibrates, {@code VibratorStopMode}. 179 * @param { AsyncCallback<void> } callback - The callback of stopVibration. 180 * @throws { BusinessError } 201 - Permission denied. 181 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 182 * <br> 2. Incorrect parameter types; 3. Parameter verification failed. 183 * @syscap SystemCapability.Sensors.MiscDevice 184 * @since 9 185 */ 186 function stopVibration(stopMode: VibratorStopMode, callback: AsyncCallback<void>): void; 187 188 /** 189 * Stop any type of vibration. 190 * 191 * @permission ohos.permission.VIBRATE 192 * @param { AsyncCallback<void> } callback - The callback of stopVibration. 193 * @throws { BusinessError } 201 - Permission denied. 194 * @syscap SystemCapability.Sensors.MiscDevice 195 * @since 10 196 */ 197 /** 198 * Stop any type of vibration. 199 * 200 * @permission ohos.permission.VIBRATE 201 * @param { AsyncCallback<void> } callback - The callback of stopVibration. 202 * @throws { BusinessError } 201 - Permission denied. 203 * @syscap SystemCapability.Sensors.MiscDevice 204 * @atomicservice 205 * @since 11 206 */ 207 function stopVibration(callback: AsyncCallback<void>): void; 208 209 /** 210 * Stop any type of vibration. 211 * 212 * @permission ohos.permission.VIBRATE 213 * @returns { Promise<void> } Promise used to return the result. 214 * @throws { BusinessError } 201 - Permission denied. 215 * @syscap SystemCapability.Sensors.MiscDevice 216 * @since 10 217 */ 218 /** 219 * Stop any type of vibration. 220 * 221 * @permission ohos.permission.VIBRATE 222 * @returns { Promise<void> } Promise used to return the result. 223 * @throws { BusinessError } 201 - Permission denied. 224 * @syscap SystemCapability.Sensors.MiscDevice 225 * @atomicservice 226 * @since 11 227 */ 228 function stopVibration(): Promise<void>; 229 230 /** 231 * Stop any type of vibration. 232 * 233 * @permission ohos.permission.VIBRATE 234 * @throws { BusinessError } 201 - Permission denied. 235 * @throws { BusinessError } 14600101 - Device operation failed. 236 * @syscap SystemCapability.Sensors.MiscDevice 237 * @atomicservice 238 * @since 12 239 */ 240 function stopVibrationSync(): void; 241 242 /** 243 * Stop the vibrator on the specified device. When all parameters are set to default, stop all local vibrators. 244 * 245 * @permission ohos.permission.VIBRATE 246 * @param { VibratorInfoParam } [param] - Indicate the device and vibrator information that needs to be controlled, 247 * <br> {@code VibratorInfoParam}. 248 * @returns { Promise<void> } Promise used to return the result. 249 * @throws { BusinessError } 201 - Permission denied. 250 * @throws { BusinessError } 14600101 - Device operation failed. 251 * @syscap SystemCapability.Sensors.MiscDevice 252 * @since 19 253 */ 254 function stopVibration(param?: VibratorInfoParam): Promise<void>; 255 256 /** 257 * Whether the preset vibration effect is supported. 258 * 259 * @param { string } effectId Indicate the specified effect of the preset, {@code EffectId}. 260 * @param { AsyncCallback<boolean> } callback The callback of isSupportEffect. 261 * @throws { BusinessError } 201 - Permission denied. 262 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 263 * <br> 2. Incorrect parameter types; 3. Parameter verification failed. 264 * @syscap SystemCapability.Sensors.MiscDevice 265 * @since arkts {'1.1':'10', '1.2':'20'} 266 * @arkts 1.1&1.2 267 */ 268 function isSupportEffect(effectId: string, callback: AsyncCallback<boolean>): void; 269 270 /** 271 * Whether the preset vibration effect is supported. 272 * 273 * @param { string } effectId Indicate the specified effect of the preset, {@code EffectId}. 274 * @returns { Promise<boolean> } Promise used to return the result. 275 * @throws { BusinessError } 201 - Permission denied. 276 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 277 * <br> 2. Incorrect parameter types; 3. Parameter verification failed. 278 * @syscap SystemCapability.Sensors.MiscDevice 279 * @since arkts {'1.1':'10', '1.2':'20'} 280 * @arkts 1.1&1.2 281 */ 282 function isSupportEffect(effectId: string): Promise<boolean>; 283 284 /** 285 * Whether the preset vibration effect is supported. 286 * 287 * @param { string } effectId Indicate the specified effect of the preset, {@code EffectId}. 288 * @returns { boolean } Returns whether the effect is supported. 289 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 290 * <br> 2. Incorrect parameter types; 3. Parameter verification failed. 291 * @throws { BusinessError } 14600101 - Device operation failed. 292 * @syscap SystemCapability.Sensors.MiscDevice 293 * @since 12 294 */ 295 function isSupportEffectSync(effectId: string): boolean; 296 297 /** 298 * Get effect information by device ID and vibrator ID. 299 * 300 * @param { string } effectId - The effect type to query. 301 * @param { VibratorInfoParam } [param] - Indicate the device and vibrator information that needs to be controlled, 302 * <br> {@code VibratorInfoParam}. By default, query local vibrators. 303 * @returns { EffectInfo } Returns information about the specified effect. 304 * @throws { BusinessError } 14600101 - Device operation failed. 305 * @syscap SystemCapability.Sensors.MiscDevice 306 * @since 19 307 */ 308 function getEffectInfoSync(effectId: string, param?: VibratorInfoParam): EffectInfo; 309 310 /** 311 * The information includes Indicates whether the effect is supported. 312 * 313 * @interface EffectInfo 314 * @syscap SystemCapability.Sensors.MiscDevice 315 * @since 19 316 */ 317 interface EffectInfo { 318 /** 319 * Indicates whether the effect is supported, true means supported, false means not supported. 320 * 321 * @type { boolean } 322 * @syscap SystemCapability.Sensors.MiscDevice 323 * @since 19 324 */ 325 isEffectSupported: boolean; 326 } 327 328 /** 329 * Stop the motor from vibrating. 330 * 331 * @permission ohos.permission.VIBRATE 332 * @param { VibratorStopMode } stopMode Indicate the stop mode in which the motor vibrates, {@code VibratorStopMode}. 333 * @returns { Promise<void> } Promise used to return the result. 334 * @syscap SystemCapability.Sensors.MiscDevice 335 * @since 8 336 * @deprecated since 9 337 * @useinstead vibrator#stopVibration 338 */ 339 function stop(stopMode: VibratorStopMode): Promise<void>; 340 341 /** 342 * Stop the motor from vibrating. 343 * 344 * @permission ohos.permission.VIBRATE 345 * @param { VibratorStopMode } stopMode Indicate the stop mode in which the motor vibrates, {@code VibratorStopMode}. 346 * @param { AsyncCallback<void> } callback The callback of stop. 347 * @syscap SystemCapability.Sensors.MiscDevice 348 * @since 8 349 * @deprecated since 9 350 * @useinstead vibrator#stopVibration 351 */ 352 function stop(stopMode: VibratorStopMode, callback?: AsyncCallback<void>): void; 353 354 /** 355 * Whether the high-definition haptic is supported. 356 * 357 * @returns { boolean } Returns whether the high-definition haptic is supported. 358 * @throws { BusinessError } 14600101 - Device operation failed. 359 * @syscap SystemCapability.Sensors.MiscDevice 360 * @since 12 361 */ 362 function isHdHapticSupported(): boolean; 363 364 /** 365 * Preset vibration effect string. 366 * 367 * @enum { string } 368 * @syscap SystemCapability.Sensors.MiscDevice 369 * @since 8 370 */ 371 enum EffectId { 372 /** 373 * Describes the vibration effect of the vibrator when a user adjusts the timer. 374 * 375 * @syscap SystemCapability.Sensors.MiscDevice 376 * @since 8 377 */ 378 EFFECT_CLOCK_TIMER = 'haptic.clock.timer' 379 } 380 381 /** 382 * Simple and universal vibration effects. 383 * 384 * @enum { string } 385 * @syscap SystemCapability.Sensors.MiscDevice 386 * @since 12 387 */ 388 enum HapticFeedback { 389 /** 390 * Describes the soft vibration effect of the vibrator. 391 * 392 * @syscap SystemCapability.Sensors.MiscDevice 393 * @since 12 394 */ 395 EFFECT_SOFT = 'haptic.effect.soft', 396 397 /** 398 * Describes the hard vibration effect of the vibrator. 399 * 400 * @syscap SystemCapability.Sensors.MiscDevice 401 * @since 12 402 */ 403 EFFECT_HARD = 'haptic.effect.hard', 404 405 /** 406 * Describes the sharp vibration effect of the vibrator. 407 * 408 * @syscap SystemCapability.Sensors.MiscDevice 409 * @since 12 410 */ 411 EFFECT_SHARP = 'haptic.effect.sharp', 412 413 /** 414 * Describes the vibration effect of the successful notice. 415 * 416 * @syscap SystemCapability.Sensors.MiscDevice 417 * @since 18 418 */ 419 EFFECT_NOTICE_SUCCESS = 'haptic.notice.success', 420 421 /** 422 * Describes the vibration effect of the failed notice. 423 * 424 * @syscap SystemCapability.Sensors.MiscDevice 425 * @since 18 426 */ 427 EFFECT_NOTICE_FAILURE = 'haptic.notice.fail', 428 429 /** 430 * Describes the vibration effect of the warning notice. 431 * 432 * @syscap SystemCapability.Sensors.MiscDevice 433 * @since 18 434 */ 435 EFFECT_NOTICE_WARNING = 'haptic.notice.warning' 436 } 437 438 /** 439 * Vibrator vibration stop mode. 440 * 441 * @enum { string } 442 * @syscap SystemCapability.Sensors.MiscDevice 443 * @since 8 444 */ 445 enum VibratorStopMode { 446 /** 447 * Indicates the mode of stopping a one-shot vibration effect. 448 * 449 * @syscap SystemCapability.Sensors.MiscDevice 450 * @since 8 451 */ 452 VIBRATOR_STOP_MODE_TIME = 'time', 453 454 /** 455 * Indicates the mode of stopping a preset vibration effect. 456 * 457 * @syscap SystemCapability.Sensors.MiscDevice 458 * @since 8 459 */ 460 VIBRATOR_STOP_MODE_PRESET = 'preset' 461 } 462 463 /** 464 * The use of vibration. 465 * 466 * @typedef {'unknown' | 'alarm' | 'ring' | 'notification' | 'communication' | 467 * 'touch' | 'media' | 'physicalFeedback' | 'simulateReality'} 468 * @syscap SystemCapability.Sensors.MiscDevice 469 * @since 9 470 */ 471 /** 472 * The use of vibration. 473 * 474 * @typedef {'unknown' | 'alarm' | 'ring' | 'notification' | 'communication' | 475 * 'touch' | 'media' | 'physicalFeedback' | 'simulateReality'} 476 * @syscap SystemCapability.Sensors.MiscDevice 477 * @atomicservice 478 * @since arkts {'1.1':'11', '1.2':'20'} 479 * @arkts 1.1&1.2 480 */ 481 type Usage = 'unknown' | 'alarm' | 'ring' | 'notification' | 'communication' | 482 'touch' | 'media' | 'physicalFeedback' | 'simulateReality'; 483 484 /** 485 * The attribute of vibration. 486 * 487 * @interface VibrateAttribute 488 * @syscap SystemCapability.Sensors.MiscDevice 489 * @since 9 490 */ 491 /** 492 * The attribute of vibration. 493 * 494 * @interface VibrateAttribute 495 * @syscap SystemCapability.Sensors.MiscDevice 496 * @atomicservice 497 * @since arkts {'1.1':'11', '1.2':'20'} 498 * @arkts 1.1&1.2 499 */ 500 interface VibrateAttribute { 501 /** 502 * Vibrator id, default is 0. 503 * 504 * @syscap SystemCapability.Sensors.MiscDevice 505 * @since 9 506 */ 507 /** 508 * Vibrator id, default is 0. 509 * 510 * @type { ?number } 511 * @syscap SystemCapability.Sensors.MiscDevice 512 * @atomicservice 513 * @since arkts {'1.1':'11', '1.2':'20'} 514 * @arkts 1.1&1.2 515 */ 516 id?: number; 517 518 /** 519 * Unique identifier for the device that contains one or multiple vibrators. 520 * By default, deviceId represents the local device. 521 * 522 * @type { ?number } 523 * @syscap SystemCapability.Sensors.MiscDevice 524 * @atomicservice 525 * @since 19 526 */ 527 deviceId?: number; 528 529 /** 530 * The use of vibration. 531 * 532 * @syscap SystemCapability.Sensors.MiscDevice 533 * @since 9 534 */ 535 /** 536 * The use of vibration. 537 * 538 * @type { Usage } 539 * @syscap SystemCapability.Sensors.MiscDevice 540 * @atomicservice 541 * @since arkts {'1.1':'11', '1.2':'20'} 542 * @arkts 1.1&1.2 543 */ 544 usage: Usage; 545 546 /** 547 * Indicates whether to bypass system management switches. 548 * 549 * @type { ?boolean } 550 * @syscap SystemCapability.Sensors.MiscDevice 551 * @systemapi 552 * @since arkts {'1.1':'12', '1.2':'20'} 553 * @arkts 1.1&1.2 554 */ 555 systemUsage?: boolean; 556 } 557 558 /** 559 * Describes the effect of vibration. 560 * 561 * @typedef { VibrateTime | VibratePreset } 562 * @syscap SystemCapability.Sensors.MiscDevice 563 * @since 9 564 */ 565 /** 566 * Describes the effect of vibration. 567 * 568 * @typedef { VibrateTime | VibratePreset | VibrateFromFile } 569 * @syscap SystemCapability.Sensors.MiscDevice 570 * @since 10 571 */ 572 /** 573 * Describes the effect of vibration. 574 * 575 * @typedef { VibrateTime | VibratePreset | VibrateFromFile } 576 * @syscap SystemCapability.Sensors.MiscDevice 577 * @atomicservice 578 * @since 11 579 */ 580 /** 581 * Describes the effect of vibration. 582 * 583 * @typedef { VibrateTime | VibratePreset | VibrateFromFile | VibrateFromPattern } 584 * @syscap SystemCapability.Sensors.MiscDevice 585 * @atomicservice 586 * @since arkts {'1.1':'18', '1.2':'20'} 587 * @arkts 1.1&1.2 588 */ 589 type VibrateEffect = VibrateTime | VibratePreset | VibrateFromFile | VibrateFromPattern; 590 591 /** 592 * Vibrate continuously for a period of time at the default intensity of the system. 593 * 594 * @interface VibrateTime 595 * @syscap SystemCapability.Sensors.MiscDevice 596 * @since 9 597 */ 598 /** 599 * Vibrate continuously for a period of time at the default intensity of the system. 600 * 601 * @interface VibrateTime 602 * @syscap SystemCapability.Sensors.MiscDevice 603 * @atomicservice 604 * @since arkts {'1.1':'11', '1.2':'20'} 605 * @arkts 1.1&1.2 606 */ 607 interface VibrateTime { 608 /** 609 * The value is "time", which triggers the motor vibration according to the specified duration. 610 * 611 * @syscap SystemCapability.Sensors.MiscDevice 612 * @since 9 613 */ 614 /** 615 * The value is "time", which triggers the motor vibration according to the specified duration. 616 * 617 * @type { 'time' } 618 * @syscap SystemCapability.Sensors.MiscDevice 619 * @atomicservice 620 * @since arkts {'1.1':'11', '1.2':'20'} 621 * @arkts 1.1&1.2 622 */ 623 type: 'time'; 624 625 /** 626 * The duration of the vibration, in ms. 627 * 628 * @syscap SystemCapability.Sensors.MiscDevice 629 * @since 9 630 */ 631 /** 632 * The duration of the vibration, in ms. 633 * 634 * @type { number } 635 * @syscap SystemCapability.Sensors.MiscDevice 636 * @atomicservice 637 * @since arkts {'1.1':'11', '1.2':'20'} 638 * @arkts 1.1&1.2 639 */ 640 duration: number; /** The duration of the vibration, in ms */ 641 } 642 643 /** 644 * Preset vibration type vibration effect. 645 * 646 * @interface VibratePreset 647 * @syscap SystemCapability.Sensors.MiscDevice 648 * @since arkts {'1.1':'9', '1.2':'20'} 649 * @arkts 1.1&1.2 650 */ 651 interface VibratePreset { 652 /** 653 * The value is "preset", which triggers motor vibration according to preset vibration effect. 654 * 655 * @type { 'preset' } 656 * @syscap SystemCapability.Sensors.MiscDevice 657 * @since arkts {'1.1':'9', '1.2':'20'} 658 * @arkts 1.1&1.2 659 */ 660 type: 'preset'; 661 662 /** 663 * Preset type vibration. 664 * 665 * @type { string } 666 * @syscap SystemCapability.Sensors.MiscDevice 667 * @since arkts {'1.1':'9', '1.2':'20'} 668 * @arkts 1.1&1.2 669 */ 670 effectId: string; 671 672 /** 673 * The number of vibration repetitions. 674 * 675 * @syscap SystemCapability.Sensors.MiscDevice 676 * @since 9 677 */ 678 /** 679 * The number of vibration repetitions. 680 * 681 * @type { ?number } 682 * @syscap SystemCapability.Sensors.MiscDevice 683 * @since arkts {'1.1':'12', '1.2':'20'} 684 * @arkts 1.1&1.2 685 */ 686 count?: number; 687 688 /** 689 * The intensity of vibration effect. 690 * 691 * @type { ?number } 692 * @syscap SystemCapability.Sensors.MiscDevice 693 * @since arkts {'1.1':'12', '1.2':'20'} 694 * @arkts 1.1&1.2 695 */ 696 intensity?: number; 697 } 698 699 /** 700 * Custom vibration, vibrate the effect from a haptic file. 701 * 702 * @interface VibrateFromFile 703 * @syscap SystemCapability.Sensors.MiscDevice 704 * @since arkts {'1.1':'10', '1.2':'20'} 705 * @arkts 1.1&1.2 706 */ 707 interface VibrateFromFile { 708 /** 709 * The value is "file", which triggers motor vibration according to the vibration profile. 710 * 711 * @type { 'file' } 712 * @syscap SystemCapability.Sensors.MiscDevice 713 * @since arkts {'1.1':'10', '1.2':'20'} 714 * @arkts 1.1&1.2 715 */ 716 type: 'file'; 717 718 /** 719 * Haptic file descriptor, some formats are supported. 720 * 721 * @type { HapticFileDescriptor } 722 * @syscap SystemCapability.Sensors.MiscDevice 723 * @since arkts {'1.1':'10', '1.2':'20'} 724 * @arkts 1.1&1.2 725 */ 726 hapticFd: HapticFileDescriptor; 727 } 728 729 /** 730 * Haptic file descriptor. The caller needs to ensure that the fd is valid and 731 * the offset and length are correct. 732 * 733 * @interface HapticFileDescriptor 734 * @syscap SystemCapability.Sensors.MiscDevice 735 * @since arkts {'1.1':'10', '1.2':'20'} 736 * @arkts 1.1&1.2 737 */ 738 interface HapticFileDescriptor { 739 /** 740 * The file descriptor of haptic effect source from file system. The caller 741 * is responsible to close the file descriptor. 742 * 743 * @type { number } 744 * @syscap SystemCapability.Sensors.MiscDevice 745 * @since arkts {'1.1':'10', '1.2':'20'} 746 * @arkts 1.1&1.2 747 */ 748 fd: number; 749 750 /** 751 * The offset into the file where the data to be read, in bytes. By default, 752 * the offset is zero. 753 * 754 * @type { ?number } 755 * @syscap SystemCapability.Sensors.MiscDevice 756 * @since arkts {'1.1':'10', '1.2':'20'} 757 * @arkts 1.1&1.2 758 */ 759 offset?: number; 760 761 /** 762 * The length in bytes of the data to be read. By default, the length is the 763 * rest of bytes in the file from the offset. 764 * 765 * @type { ?number } 766 * @syscap SystemCapability.Sensors.MiscDevice 767 * @since arkts {'1.1':'10', '1.2':'20'} 768 * @arkts 1.1&1.2 769 */ 770 length?: number; 771 } 772 773 /** 774 * Types of vibration events 775 * 776 * @enum { number } 777 * @syscap SystemCapability.Sensors.MiscDevice 778 * @since arkts {'1.1':'18', '1.2':'20'} 779 * @arkts 1.1&1.2 780 */ 781 enum VibratorEventType { 782 /** 783 * Steady state long vibration 784 * 785 * @syscap SystemCapability.Sensors.MiscDevice 786 * @since arkts {'1.1':'18', '1.2':'20'} 787 * @arkts 1.1&1.2 788 */ 789 CONTINUOUS = 0, 790 791 /** 792 * Transient short vibration 793 * 794 * @syscap SystemCapability.Sensors.MiscDevice 795 * @since arkts {'1.1':'18', '1.2':'20'} 796 * @arkts 1.1&1.2 797 */ 798 TRANSIENT = 1, 799 } 800 801 /** 802 * The vibration curve is valid when the vibration event type is 'continuous' 803 * 804 * @interface VibratorCurvePoint 805 * @syscap SystemCapability.Sensors.MiscDevice 806 * @since arkts {'1.1':'18', '1.2':'20'} 807 * @arkts 1.1&1.2 808 */ 809 interface VibratorCurvePoint { 810 /** 811 * The offset of the starting time of the relative event. 812 * 813 * @type { number } 814 * @syscap SystemCapability.Sensors.MiscDevice 815 * @since arkts {'1.1':'18', '1.2':'20'} 816 * @arkts 1.1&1.2 817 */ 818 time: number; 819 820 /** 821 * Gain in relative event vibration intensity 822 * 823 * @type { ?number } 824 * @syscap SystemCapability.Sensors.MiscDevice 825 * @since arkts {'1.1':'18', '1.2':'20'} 826 * @arkts 1.1&1.2 827 */ 828 intensity?: number; 829 /** 830 * Changes in relative event vibration frequency 831 * 832 * @type { ?number } 833 * @syscap SystemCapability.Sensors.MiscDevice 834 * @since arkts {'1.1':'18', '1.2':'20'} 835 * @arkts 1.1&1.2 836 */ 837 frequency?: number; 838 } 839 840 /** 841 * Vibration event. 842 * 843 * @interface VibratorEvent 844 * @syscap SystemCapability.Sensors.MiscDevice 845 * @since arkts {'1.1':'18', '1.2':'20'} 846 * @arkts 1.1&1.2 847 */ 848 interface VibratorEvent { 849 /** 850 * Types of vibration events 851 * 852 * @type { VibratorEventType } 853 * @syscap SystemCapability.Sensors.MiscDevice 854 * @since arkts {'1.1':'18', '1.2':'20'} 855 * @arkts 1.1&1.2 856 */ 857 eventType: VibratorEventType; 858 859 /** 860 * Relative starting time of vibration 861 * 862 * @type { number } 863 * @syscap SystemCapability.Sensors.MiscDevice 864 * @since arkts {'1.1':'18', '1.2':'20'} 865 * @arkts 1.1&1.2 866 */ 867 time: number; 868 869 /** 870 * The duration of vibration 871 * 872 * @type { ?number } 873 * @syscap SystemCapability.Sensors.MiscDevice 874 * @since arkts {'1.1':'18', '1.2':'20'} 875 * @arkts 1.1&1.2 876 */ 877 duration?: number; 878 879 /** 880 * Intensity of vibration events 881 * 882 * @type { ?number } 883 * @syscap SystemCapability.Sensors.MiscDevice 884 * @since arkts {'1.1':'18', '1.2':'20'} 885 * @arkts 1.1&1.2 886 */ 887 intensity?: number; 888 889 /** 890 * Vibration event frequency 891 * 892 * @type { ?number } 893 * @syscap SystemCapability.Sensors.MiscDevice 894 * @since arkts {'1.1':'18', '1.2':'20'} 895 * @arkts 1.1&1.2 896 */ 897 frequency?: number; 898 899 /** 900 * Channel number 901 * 902 * @type { ?number } 903 * @syscap SystemCapability.Sensors.MiscDevice 904 * @since arkts {'1.1':'18', '1.2':'20'} 905 * @arkts 1.1&1.2 906 */ 907 index?: number; 908 909 /** 910 * An array representing vibration adjustment curves. 911 * 912 * @type { ?Array<VibratorCurvePoint> } 913 * @syscap SystemCapability.Sensors.MiscDevice 914 * @since arkts {'1.1':'18', '1.2':'20'} 915 * @arkts 1.1&1.2 916 */ 917 points?: Array<VibratorCurvePoint>; 918 } 919 920 /** 921 * Each 'events' attribute in the vibration sequence represents one vibration event 922 * 923 * @interface VibratorPattern 924 * @syscap SystemCapability.Sensors.MiscDevice 925 * @since arkts {'1.1':'18', '1.2':'20'} 926 * @arkts 1.1&1.2 927 */ 928 interface VibratorPattern { 929 /** 930 * Absolute starting time of vibration 931 * 932 * @type { number } 933 * @syscap SystemCapability.Sensors.MiscDevice 934 * @since arkts {'1.1':'18', '1.2':'20'} 935 * @arkts 1.1&1.2 936 */ 937 time: number; 938 939 /** 940 * Vibration event array, where each 'events' attribute represents one vibration event. 941 * 942 * @type { Array<VibratorEvent> } 943 * @syscap SystemCapability.Sensors.MiscDevice 944 * @since arkts {'1.1':'18', '1.2':'20'} 945 * @arkts 1.1&1.2 946 */ 947 events: Array<VibratorEvent>; 948 } 949 950 /** 951 * The continuous vibration parameters 952 * 953 * @interface ContinuousParam 954 * @syscap SystemCapability.Sensors.MiscDevice 955 * @since 18 956 */ 957 interface ContinuousParam { 958 /** 959 * Intensity of vibration 960 * 961 * @type { ?number } 962 * @syscap SystemCapability.Sensors.MiscDevice 963 * @since 18 964 */ 965 intensity?: number; 966 967 /** 968 * Frequency of vibration 969 * 970 * @type { ?number } 971 * @syscap SystemCapability.Sensors.MiscDevice 972 * @since 18 973 */ 974 frequency?: number; 975 976 /** 977 * The points of vibration 978 * 979 * @type { ?VibratorCurvePoint[] } 980 * @syscap SystemCapability.Sensors.MiscDevice 981 * @since 18 982 */ 983 points?: VibratorCurvePoint[]; 984 985 /** 986 * Index of vibration 987 * 988 * @type { ?number } 989 * @syscap SystemCapability.Sensors.MiscDevice 990 * @since 18 991 */ 992 index?: number; 993 } 994 995 /** 996 * The transient vibration parameters 997 * 998 * @interface TransientParam 999 * @syscap SystemCapability.Sensors.MiscDevice 1000 * @since 18 1001 */ 1002 interface TransientParam { 1003 /** 1004 * Intensity of vibration 1005 * 1006 * @type { ?number } 1007 * @syscap SystemCapability.Sensors.MiscDevice 1008 * @since 18 1009 */ 1010 intensity?: number; 1011 1012 /** 1013 * Frequency of vibration 1014 * 1015 * @type { ?number } 1016 * @syscap SystemCapability.Sensors.MiscDevice 1017 * @since 18 1018 */ 1019 frequency?: number; 1020 1021 /** 1022 * Index of vibration 1023 * 1024 * @type { ?number } 1025 * @syscap SystemCapability.Sensors.MiscDevice 1026 * @since 18 1027 */ 1028 index?: number; 1029 } 1030 1031 /** 1032 * Provide methods for adding long or short vibration events and generate VibratorPattern objects. 1033 * 1034 * @name VibratorPatternBuilder 1035 * @syscap SystemCapability.Sensors.MiscDevice 1036 * @since 18 1037 */ 1038 class VibratorPatternBuilder { 1039 /** 1040 * Method for adding long vibration events 1041 * 1042 * @param { number } time Relative starting time of the long-term vibration event. 1043 * @param { number } duration The duration of the long-term vibration event 1044 * @param { ContinuousParam } options Optional parameter object 1045 * @returns { VibratorPatternBuilder } Return the current VibratorPatternBuilder object. 1046 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 1047 * <br> 2. Incorrect parameter types; 3. Parameter verification failed. 1048 * @syscap SystemCapability.Sensors.MiscDevice 1049 * @since 18 1050 */ 1051 addContinuousEvent(time: number, duration: number, options?: ContinuousParam): VibratorPatternBuilder; 1052 1053 /** 1054 * Method for adding short vibration events. 1055 * 1056 * @param { number } time Relative starting time of short oscillation events. 1057 * @param { TransientParam } options Optional parameter object 1058 * @returns { VibratorPatternBuilder } Return the current VibratorPatternBuilder object. 1059 * @throws { BusinessError } 401 - Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 1060 * <br> 2. Incorrect parameter types; 3. Parameter verification failed. 1061 * @syscap SystemCapability.Sensors.MiscDevice 1062 * @since 18 1063 */ 1064 addTransientEvent(time: number, options?: TransientParam): VibratorPatternBuilder; 1065 1066 /** 1067 * Method for constructing vibration sequences of combined short or long events. 1068 * 1069 * @returns { VibratorPattern } Return VibratorPattern object. 1070 * @syscap SystemCapability.Sensors.MiscDevice 1071 * @since 18 1072 */ 1073 build(): VibratorPattern; 1074 } 1075 1076 /** 1077 * Trigger motor vibration with custom vibration effects. 1078 * 1079 * @interface VibrateFromPattern 1080 * @syscap SystemCapability.Sensors.MiscDevice 1081 * @since arkts {'1.1':'18', '1.2':'20'} 1082 * @arkts 1.1&1.2 1083 */ 1084 interface VibrateFromPattern { 1085 /** 1086 * The value is "pattern", which triggers motor vibration based on the combination pattern. 1087 * 1088 * @type { 'pattern' } 1089 * @syscap SystemCapability.Sensors.MiscDevice 1090 * @since arkts {'1.1':'18', '1.2':'20'} 1091 * @arkts 1.1&1.2 1092 */ 1093 type: 'pattern'; 1094 1095 /** 1096 * Customize the sequence of motor vibration events, the VibratorPattern object returned by the build() method. 1097 * 1098 * @type { VibratorPattern } 1099 * @syscap SystemCapability.Sensors.MiscDevice 1100 * @since arkts {'1.1':'18', '1.2':'20'} 1101 * @arkts 1.1&1.2 1102 */ 1103 pattern: VibratorPattern; 1104 } 1105 1106 /** 1107 * Parameters of vibrator on the device. By default, VibratorInfoParam may default to querying or controlling 1108 * the local default vibrator. 1109 * @interface VibratorInfoParam 1110 * @syscap SystemCapability.Sensors.MiscDevice 1111 * @since 19 1112 */ 1113 interface VibratorInfoParam { 1114 /** 1115 * Unique identifier for the device that contains one or multiple vibrators. 1116 * By default, deviceId may default to querying or controlling the local default vibrator. 1117 * 1118 * @type { ?number } 1119 * @syscap SystemCapability.Sensors.MiscDevice 1120 * @since 19 1121 */ 1122 deviceId?: number; 1123 /** 1124 * Unique identifier for the vibrator itself within the device. 1125 * By default, vibratorId may default to querying or controlling all vibrators on the corresponding device. 1126 * 1127 * @type { ?number } 1128 * @syscap SystemCapability.Sensors.MiscDevice 1129 * @since 19 1130 */ 1131 vibratorId?: number; 1132 } 1133 1134 /** 1135 * Represents the information about a vibrator device in the system. 1136 * @interface VibratorInfo 1137 * @syscap SystemCapability.Sensors.MiscDevice 1138 * @since 19 1139 */ 1140 interface VibratorInfo { 1141 /** 1142 * Unique identifier for the device that contains one or multiple vibrators. 1143 * 1144 * @type { number } 1145 * @syscap SystemCapability.Sensors.MiscDevice 1146 * @since 19 1147 */ 1148 deviceId: number; 1149 1150 /** 1151 * Unique identifier for the vibrator itself within the device. 1152 * 1153 * @type { number } 1154 * @syscap SystemCapability.Sensors.MiscDevice 1155 * @since 19 1156 */ 1157 vibratorId: number; 1158 1159 /** 1160 * Name of the device. 1161 * 1162 * @type { string } 1163 * @syscap SystemCapability.Sensors.MiscDevice 1164 * @since 19 1165 */ 1166 deviceName: string; 1167 1168 /** 1169 * Indicates whether the vibrator device support HD haptic. 1170 * 1171 * @type { boolean } 1172 * @syscap SystemCapability.Sensors.MiscDevice 1173 * @since 19 1174 */ 1175 isHdHapticSupported: boolean; 1176 1177 /** 1178 * Indicates whether the vibrator is a local device or an external one. 1179 * If the value is true, it represents a local device; if false, it represents an external device. 1180 * 1181 * @type { boolean } 1182 * @syscap SystemCapability.Sensors.MiscDevice 1183 * @since 19 1184 */ 1185 isLocalVibrator: boolean; 1186 } 1187 1188 /** 1189 * Retrieve the list of vibrator information about one or all devices. 1190 * 1191 * @param { VibratorInfoParam } [param] - Indicate the device and vibrator information that needs to be controlled, 1192 * <br> {@code VibratorInfoParam}. By default, this returns all vibrators on all device when param is unspecified. 1193 * @returns { Array<VibratorInfo> } Promise used to return a list of vibrator IDs containing information 1194 * <br> about the vibrator device. 1195 * @syscap SystemCapability.Sensors.MiscDevice 1196 * @since 19 1197 */ 1198 function getVibratorInfoSync(param?: VibratorInfoParam): Array<VibratorInfo>; 1199 1200 /** 1201 * Register a callback function to be called when a vibrator plugin or unplug event occurs. 1202 * 1203 * @param { 'vibratorStateChange' } type - Event of the listening. 1204 * @param { Callback<VibratorStatusEvent> } callback - The callback function to be executed when 1205 * <br> the event is triggered. 1206 * @throws { BusinessError } 14600101 - Device operation failed. 1207 * @syscap SystemCapability.Sensors.MiscDevice 1208 * @since 19 1209 */ 1210 function on(type: 'vibratorStateChange', callback: Callback<VibratorStatusEvent>): void; 1211 1212 /** 1213 * Unregister a callback function for vibrator plugin or unplug events. 1214 * 1215 * @param { 'vibratorStateChange' } type - Event of the listening. 1216 * @param { Callback<VibratorStatusEvent> } [callback] - The callback function to be removed from the event listener. 1217 * @throws { BusinessError } 14600101 - Device operation failed. 1218 * @syscap SystemCapability.Sensors.MiscDevice 1219 * @since 19 1220 */ 1221 function off(type: 'vibratorStateChange', callback?: Callback<VibratorStatusEvent>): void; 1222 1223 /** 1224 * Indicates information about vibrator online or offline events. 1225 * 1226 * @interface 1227 * @syscap SystemCapability.Sensors.MiscDevice 1228 * @since 19 1229 */ 1230 interface VibratorStatusEvent { 1231 /** 1232 * The timestamp of the reported event. 1233 * @type { number } 1234 * @syscap SystemCapability.Sensors.MiscDevice 1235 * @since 19 1236 */ 1237 timestamp: number; 1238 1239 /** 1240 * Unique identifier for the device that contains one or multiple vibrators. 1241 * 1242 * @type { number } 1243 * @syscap SystemCapability.Sensors.MiscDevice 1244 * @since 19 1245 */ 1246 deviceId: number; 1247 1248 /** 1249 * Indicate the number of vibrators on the device. 1250 * 1251 * @type { number } 1252 * @syscap SystemCapability.Sensors.MiscDevice 1253 * @since 19 1254 */ 1255 vibratorCount: number; 1256 1257 /** 1258 * Indicates the device's online and offline status, true indicates online, false indicates offline. 1259 * 1260 * @type { boolean } 1261 * @syscap SystemCapability.Sensors.MiscDevice 1262 * @since 19 1263 */ 1264 isVibratorOnline: boolean; 1265 } 1266} 1267 1268export default vibrator; 1269