# 振动开发指导(ArkTS)

## 场景介绍

当设备需要设置不同的振动效果时，可以调用Vibrator模块，例如：设备的按键可以设置不同强度和不同时长的振动，闹钟和来电可以设置不同强度和时长的单次或周期振动。

详细的接口介绍请参考[@ohos.vibrator (振动)](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-vibrator)。

## 接口说明

|名称|描述|
|:------------------------------------------------------------------------------------------------------|:--------------------------------------------------------------------------|
|startVibration(effect: VibrateEffect, attribute: VibrateAttribute): Promise<void>|根据指定振动效果和振动属性触发马达振动，使用Promise异步回调。|
|startVibration(effect: VibrateEffect, attribute: VibrateAttribute, callback: AsyncCallback<void>): void|根据指定振动效果和振动属性触发马达振动，使用Callback异步回调。|
|stopVibration(stopMode: VibratorStopMode): Promise<void>|按照指定模式停止马达的振动，使用Promise异步回调。|
|stopVibration(stopMode: VibratorStopMode, callback: AsyncCallback<void>): void|按照指定模式停止马达的振动，使用Callback异步回调。|
|stopVibration(): Promise<void>|停止所有模式的马达振动，使用Promise异步回调。|
|stopVibration(param?: VibratorInfoParam): Promise<void>|不传参则停止本地设备所有马达的振动，也可传参停止指定马达振动，使用Promise异步回调。|
|stopVibration(callback: AsyncCallback<void>): void|停止所有模式的马达振动，使用Callback异步回调。|
|isSupportEffect(effectId: string): Promise<boolean>|查询是否支持传入的参数effectId。返回true则表示支持，否则不支持，使用Promise异步回调。|
|isSupportEffect(effectId: string, callback: AsyncCallback<boolean>): void|查询是否支持传入的参数effectId。返回true则表示支持，否则不支持，使用Callback异步回调。|
|getEffectInfoSync(effectId: string, param?: VibratorInfoParam): EffectInfo|同步查询是否支持传入的参数effectId，param可指定具体马达。返回EffectInfo中isEffectSupported字段可判断是否支持。|
|getVibratorInfoSync(param?: VibratorInfoParam): Array<VibratorInfo>|同步查询一个或所有设备的马达信息列表。返回VibratorInfo包含设备ID、马达ID、设备名称、是否支持高清振动、是否本地设备等信息。|
|on(type: 'vibratorStateChange', callback: Callback<VibratorStatusEvent>): void|注册马达设备上下线状态变化的监听。callback参数VibratorStatusEvent可返回事件时间戳、设备ID、马达数量、上线或下线等信息。|
|off(type: 'vibratorStateChange', callback?: Callback<VibratorStatusEvent>): void|注销马达设备上下线状态变化的监听。|
|isHdHapticSupported(): boolean|查询是否支持高清振动。|

## 振动效果说明

目前支持三类振动效果，如下所示：

|名称|说明|
|:-----|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|固定时长振动|传入一个固定时长，马达按照默认强度和频率触发振动，振动效果描述请参考[VibrateTime](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-vibrator#vibratetime9)。|
|预置振动|系统中的[EffectId](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-vibrator#effectid)，这些效果适用于某些固定场景，比如效果"haptic.clock.timer"通常用于用户调整计时器时的振感反馈，振动效果描述请参考[VibratePreset](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-vibrator#vibratepreset9)。|
|自定义振动|自定义振动提供给用户设计自己所需振动效果的能力，用户可通过自定义振动配置文件，并遵循相应规则编排所需振动形式，使能更加开放的振感交互体验，效果描述请参考[VibrateFromFile](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-vibrator#vibratefromfile10)。|

自定义振动配置文件为Json格式，在形式上如下所示：

```json
{
    "MetaData": {
        "Create": "2023-01-09",
        "Description": "a haptic case",
        "Version": 1.0,
        "ChannelNumber": 1
    },
    "Channels": [
        {
            "Parameters": {
                "Index": 0
            },
            "Pattern": [
                {
                    "Event": {
                        "Type": "transient",
                        "StartTime": 0,
                        "Parameters": {
                            "Frequency": 31,
                            "Intensity": 100
                        }
                    }
                },
                {
                    "Event": {
                        "Type": "continuous",
                        "StartTime": 40,
                        "Duration": 54,
                        "Parameters": {
                            "Frequency": 30,
                            "Intensity": 38,
                            "Curve": [
                                {
                                    "Time": 0,
                                    "Frequency": 0,
                                    "Intensity": 0
                                },
                                {
                                    "Time": 1,
                                    "Frequency": 15,
                                    "Intensity": 0.5
                                },
                                {
                                    "Time": 40,
                                    "Frequency": -8,
                                    "Intensity": 1.0
                                },
                                {
                                    "Time": 54,
                                    "Frequency": 0,
                                    "Intensity": 0
                                }
                            ]
                        }
                    }
                }
            ]
        }
    ]
}
```

JSON文件共包含3个属性。

1. "MetaData"属性中为文件头信息，可在如下属性中添加描述：

   |名称|必填项|说明|
   |:------------|:--|:-----------------------|
   |Version|是|文件格式的版本号，向前兼容，目前支持版本1.0。|
   |ChannelNumber|是|表示马达振动的通道数，最大支持双马达通道。|
   |Create|否|可记录文件创作时间。|
   |Description|否|可指明振动效果、创建信息等附加说明。|

2. "Channels"属性中为马达振动通道的相关信息。

   "Channels"是Json数组，表示各个通道的信息，包含2个属性。

   |名称|必填项|说明|
   |:---------|:--|:-------------------------------------------------------------|
   |Parameters|是|为通道参数。其中"Index"表示通道编号，0表示全通道发送，1、2分别对应左右马达。0不能与其他通道编号同时作为配置参数。|
   |Pattern|否|马达振动序列。|

   "Pattern"是Json数组，包含振动事件序列，每个"Event"属性代表1个振动事件，支持添加2种振动类型。

   |振动类型|说明|
   |:---------|:----------------------|
   |transient|瞬态短振动，干脆有力。|
   |continuous|稳态长振动，具备长时间输出强劲有力振动的能力。|

   "Event"表示一个振动事件，包含如下属性：

   |名称|必填项|说明|
   |:--------|:--|:-----------------------------------------------|
   |Type|是|振动事件类型，为"transient" 或"continuous"。|
   |StartTime|是|振动的起始时间，单位ms，有效范围为[0, 1800,000]。|
   |Duration|是|振动持续时间，仅当类型为"continuous"时有效，单位ms，有效范围为[0, 5000]。|

3. "Parameters"表示振动事件参数设置，必填项，可设置以下属性参数：

   |名称|必填项|说明|
   |:--------|:--|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
   |Intensity|是|振动事件强度，有效范围为[0, 100]，数字大小代表最大振动量的xx%。|
   |Frequency|是|振动事件频率，有效范围为[0, 100]，一般支持频率调节的马达设置为55时为器件的谐振频率，此时振动量最大，越靠近谐振频率的振动，同强度设置的振动量越大。|
   |Curve|否|振动曲线，当振动事件类型为"continuous"时有效，为Json数组，支持设置一组调节点，调节点数量最大支持16个，最小为4个，每个调节点需包含如下属性： "Time"：相对事件起始时间的偏移，最小为0，最大不能超过事件振动时长； "Intensity"：相对事件振动强度的增益，范围为[0, 1]，此值乘上振动事件强度为对应时间点调节后的强度； "Frequency"：相对事件振动频率的变化，范围为[-100, 100]，此值加上振动事件频率为对应时间点调节后的频率。|

其他要求：

|参数|要求|
|:-------------|:--------|
|振动事件(event)的数量|不得超过128个。|
|振动配置文件长度|不得超过64KB。|

## 开发步骤

1. 新建一个工程。

   ![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/92/v3/GIDi3t_ITwWjIdcEmC8MEg/zh-cn_image_0000002779092139.png?HW-CC-KV=V1&HW-CC-Date=20260929T121702Z&HW-CC-Expire=31536000000&HW-CC-Sign=2988561E97817E4290333CA0E49DF87985DFC058B9A19BCFFE941FB4BD8B5AF8)
2. 配置权限，具体配置方式请参考[声明权限](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/declare-permissions)。

   ```JSON5
   "requestPermissions": [
     {
       "name": "ohos.permission.VIBRATE"
     }
   ],
   ```

3. 导入模块。

   ```TypeScript
   import { vibrator } from '@kit.SensorServiceKit';
   import { resourceManager } from '@kit.LocalizationKit';
   import { BusinessError } from '@kit.BasicServicesKit';
   import { hilog } from '@kit.PerformanceAnalysisKit';
   ```

4. 定义常量。

   ```TypeScript
   const fileName: string = 'vibrator.json';
   let TAG = 'vibrator:';
   ```

5. 振动器查询。

   **情形一** 查询所有马达信息：

   ```TypeScript
   try {
     const vibratorInfoList: vibrator.VibratorInfo[] = vibrator.getVibratorInfoSync();
     console.info(`vibratorInfoList: ${JSON.stringify(vibratorInfoList)}`);
     // ...
   } catch (error) {
     let e: BusinessError = error as BusinessError;
     console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`);
   }
   ```

   **情形二** 查询指定设备的一个或多个马达信息：

   ```TypeScript
   try {
     const vibratorParam: vibrator.VibratorInfoParam = {
       deviceId: -1    // deviceId 需要是查询出来真实存在的设备
     }
     const vibratorInfoList: vibrator.VibratorInfo[] = vibrator.getVibratorInfoSync(vibratorParam);
     console.info(`vibratorInfoList: ${JSON.stringify(vibratorInfoList)}`);
     // ...
   } catch (error) {
     let e: BusinessError = error as BusinessError;
     console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`);
   }
   ```

6. 根据指定振动效果和振动属性触发马达振动。

   **情形一** 按照指定持续时间触发马达振动：

   ```TypeScript
   try {
     // 触发马达振动
     vibrator.startVibration({
       type: 'time',
       duration: 1000,
     }, {
       id: 0,
       usage: 'alarm'
     }, (error: BusinessError) => {
       if (error) {
         console.error(`Failed to start vibration. Code: ${error.code}, message: ${error.message}`);
         return;
       }
       console.info('Succeed in starting vibration');
     });
   } catch (err) {
     let e: BusinessError = err as BusinessError;
     console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`);
   }
   ```

   **情形二** 按照预置振动效果触发马达振动，可先查询振动效果是否被支持，再调用振动接口：

   ```TypeScript
   try {
     vibrator.isSupportEffect(this.realEffectId, (err: BusinessError, state: boolean) => {
       if (err) {
         console.error(`Failed to query effect. Code: ${err.code}, message: ${err.message}`);
         return;
       }
       console.info('Succeed in querying effect');
       if (state) {
         try {
           // 触发马达振动
           vibrator.startVibration({
             type: 'preset',
             effectId: this.realEffectId,
             count: 1,
             intensity: 50,
           }, {
             usage: 'unknown'
           }, (error: BusinessError) => {
             if (error) {
               console.error(`Failed to start vibration. Code: ${error.code}, message: ${error.message}`);
             } else {
               console.info('Succeed in starting vibration');
             }
           });
         } catch (error) {
           let e: BusinessError = error as BusinessError;
           console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`);
         }
       }
     })
   } catch (error) {
     let e: BusinessError = error as BusinessError;
     console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`);
   }
   ```

   **情形三** 按照自定义振动配置文件触发马达振动：

   ```TypeScript
   // 获取文件资源描述符
   let rawFd: resourceManager.RawFileDescriptor | undefined = this.uiContext.getHostContext()?.resourceManager.getRawFdSync(fileName);
   if (rawFd != undefined) {
     // 触发马达振动
     try {
       vibrator.startVibration({
         type: "file",
         hapticFd: { fd: rawFd.fd, offset: rawFd.offset, length: rawFd.length }
       }, {
         id: 0,
         usage: 'alarm' // 根据实际选择类型归属不同的开关管控
       }, (error: BusinessError) => {
         if (error) {
           console.error(`Failed to start vibration. Code: ${error.code}, message: ${error.message}`);
           return;
         }
         console.info('Succeed in starting vibration');
       });
     } catch (err) {
       let e: BusinessError = err as BusinessError;
       console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`);
     } finally {
       vibrator.stopVibration();
       this.uiContext.getHostContext()?.resourceManager.closeRawFdSync(fileName);
     }
   }
   ```

   **情形四** Pattern类型的马达振动：

   添加短振事件的方式获取Pattern，并触发振动：

   ```TypeScript
   let builder: vibrator.VibratorPatternBuilder = new vibrator.VibratorPatternBuilder();
   try {
     let param: vibrator.TransientParam = {
       intensity: 80,
       frequency: 70,
       index: 0
     }
     builder.addTransientEvent(0, param);
     console.info(`addTransientEvent builder is ${builder.build()}`);
   } catch (error) {
     let e: BusinessError = error as BusinessError;
     console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`);
   }
   try {
     vibrator.startVibration({
       type: "pattern",
       pattern: builder.build()
     }, {
       id: 1,
       deviceId: -1,
       // 根据实际选择类型归属不同的开关管控
       usage: "alarm"
     }, (error: BusinessError) => {
       if (error) {
         let e: BusinessError = error as BusinessError;
         console.error(`Vibrate fail. Code: ${e.code}, message: ${e.message}`);
       } else {
         console.info(`vibrate success`);
       }
     });
   } catch (error) {
     let e: BusinessError = error as BusinessError;
     console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`);
   }
   ```

   添加长振事件的方式获取Pattern，并触发振动：

   ```TypeScript
   let builder: vibrator.VibratorPatternBuilder = new vibrator.VibratorPatternBuilder();
   try {
     // VibratorCurvePoint参数最少设置4个，最大设置16个
     let pointsMe: vibrator.VibratorCurvePoint[] = [
       { time: 0, intensity: 0, frequency: -7 },
       { time: 42, intensity: 1, frequency: -6 },
       { time: 128, intensity: 0.94, frequency: -4 },
       { time: 217, intensity: 0.63, frequency: -14 },
       { time: 763, intensity: 0.48, frequency: -14 },
       { time: 1125, intensity: 0.53, frequency: -10 },
       { time: 1503, intensity: 0.42, frequency: -14 },
       { time: 1858, intensity: 0.39, frequency: -14 },
       { time: 2295, intensity: 0.34, frequency: -17 },
       { time: 2448, intensity: 0.21, frequency: -14 },
       { time: 2468, intensity: 0, frequency: -21 }
     ]
     let param: vibrator.ContinuousParam = {
       intensity: 97,
       frequency: 34,
       points: pointsMe,
       index: 0
     }
     builder.addContinuousEvent(0, 2468, param);
     console.info(`addContinuousEvent builder is ${builder.build()}`);
   } catch (error) {
     let e: BusinessError = error as BusinessError;
     console.error(`Exception. Code ${e.code}`);
   }
   try {
     vibrator.startVibration({
       type: 'pattern',
       pattern: builder.build()
     }, {
       id: 1,
       deviceId: -1,
       usage:"alarm",
     }, (error: BusinessError) => {
       if (error) {
         let e: BusinessError = error as BusinessError;
         console.error(`Vibrate fail. Code: ${e.code}, message: ${e.message}`);
       } else {
         console.info(`vibrate success`);
       }
     });
   } catch (error) {
     let e: BusinessError = error as BusinessError;
     console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`);
   }
   ```

7. 停止马达的振动。

   **方式一** 按照指定模式停止对应的马达振动，自定义振动不支持此类停止方式：

   ​停止固定时长振动：

   ```TypeScript
   try {
     // 按照VIBRATOR_STOP_MODE_TIME模式停止振动
     vibrator.stopVibration(vibrator.VibratorStopMode.VIBRATOR_STOP_MODE_TIME, (error: BusinessError) => {
       if (error) {
         console.error(`Failed to stop vibration. Code: ${error.code}, message: ${error.message}`);
         return;
       }
       console.info('Succeed in stopping vibration');
     })
   } catch (err) {
     let e: BusinessError = err as BusinessError;
     console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`);
   }
   ```

   ​停止预置振动：

   ```TypeScript
   try {
     // 按照VIBRATOR_STOP_MODE_PRESET模式停止振动
     vibrator.stopVibration(vibrator.VibratorStopMode.VIBRATOR_STOP_MODE_PRESET, (error: BusinessError) => {
       if (error) {
         console.error(`Failed to stop vibration. Code: ${error.code}, message: ${error.message}`);
         return;
       }
       console.info('Succeed in stopping vibration');
     })
   } catch (err) {
     let e: BusinessError = err as BusinessError;
     console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`);
   }
   ```

   **方式二** 停止所有模式的马达振动，包括自定义振动：

   ```TypeScript
   try {
     // 停止所有模式的马达振动
     vibrator.stopVibration((error: BusinessError) => {
       if (error) {
         console.error(`Failed to stop vibration. Code: ${error.code}, message: ${error.message}`);
         return;
       }
       console.info('Succeed in stopping vibration');
     })
   } catch (error) {
     let e: BusinessError = error as BusinessError;
     console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`);
   }
   ```

   **方式三** 停止指定设备的振动：

   ```TypeScript
   const vibratorInfoParam: vibrator.VibratorInfoParam = {
     deviceId: -1   // deviceId 需要是查询出来真实存在的设备
   }
   try {
     vibrator.stopVibration(vibratorInfoParam).then(() => {
       console.info('Succeed in stopping vibration');
     }, (error: BusinessError) => {
       console.error(`Failed to stop vibration. Code: ${error.code}, message: ${error.message}`);
     });
   } catch (error) {
     let e: BusinessError = error as BusinessError;
     console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`);
   }
   ```

8. 动态马达状态变化监听。

   注册监听。

   ```TypeScript
   // 回调函数
   vibratorStateChangeCallback = (data: vibrator.VibratorStatusEvent) => {
     console.info('vibrator state callback info:', JSON.stringify(data));
     // ...
   }
   // ...
               try {
                 // 订阅 vibratorStateChange事件
                 vibrator.on('vibratorStateChange', this.vibratorStateChangeCallback);
               } catch (error) {
                 let e: BusinessError = error as BusinessError;
                 console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`);
               }
   ```

   取消监听，取消传入的callback需与注册的一致。

   ```TypeScript
   // 回调函数
   vibratorStateChangeCallback = (data: vibrator.VibratorStatusEvent) => {
     console.info('vibrator state callback info:', JSON.stringify(data));
     // ...
   }
   // ...
               try {
                 // 取消订阅 vibratorStateChange事件
                 vibrator.off('vibratorStateChange', this.vibratorStateChangeCallback);
                 // 取消订阅所有 vibratorStateChange事件
                 // vibrator.off('vibratorStateChange');
               } catch (error) {
                 let e: BusinessError = error as BusinessError;
                 console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`);
               }
   ```

9. 通过设备ID和马达ID获取预置振动效果信息。

   ```TypeScript
   try {
     const effectInfo: vibrator.EffectInfo = vibrator.getEffectInfoSync('haptic.clock.timer', { deviceId: -1, vibratorId: 1});
     console.info(`isEffectSupported: ${effectInfo.isEffectSupported}`);
     // ...
   } catch (error) {
     let e: BusinessError = error as BusinessError;
     console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`);
   }
   ```

10. 查询是否支持高清振动。

    ```TypeScript
    try {
      // 查询是否支持高清振动
      let ret = vibrator.isHdHapticSupported();
      console.info(`The query result is ${ret}`);
      // ...
    } catch (error) {
      let e: BusinessError = error as BusinessError;
      console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`);
    }
    ```