1# @ohos.multimedia.audioHaptic (音振协同)(系统接口) 2<!--Kit: Audio Kit--> 3<!--Subsystem: Multimedia--> 4<!--Owner: @songshenke--> 5<!--Designer: @caixuejiang; @hao-liangfei; @zhanganxiang--> 6<!--Tester: @Filger--> 7<!--Adviser: @zengyawen--> 8 9音振协同，表示在播放声音时，同步发起振动。可用于来电通知、消息提醒等场景。 10 11> **说明：** 12> 13> 本模块首批接口从API version 11开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 14 15## 导入模块 16 17```ts 18import { audioHaptic } from '@kit.AudioKit'; 19``` 20 21## AudioHapticPlayer 22 23音振播放器，提供音振协同播放功能。在调用AudioHapticPlayer的接口前，需要先通过[createPlayer](./js-apis-audioHaptic.md#createplayer)创建实例。 24 25### isHapticsIntensityAdjustmentSupported<sup>20+</sup> 26 27isHapticsIntensityAdjustmentSupported(): boolean 28 29查询设备是否可以调整振动幅度。 30 31**系统接口：** 此接口为系统接口。 32 33**系统能力：** SystemCapability.Multimedia.AudioHaptic.Core 34 35**返回值：** 36 37| 类型 | 说明 | 38| ------------------- | ------------------------------- | 39| boolean | 设备是否可以调整振动幅度。true表示可以调整振动幅度，false表示不可以调整振动幅度。 | 40 41**错误码：** 42 43以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 44 45| 错误码ID | 错误信息 | 46|---------|-----------------------------------| 47| 202 | Caller is not a system application. | 48 49**示例：** 50 51```ts 52const result: boolean = audioHapticPlayerInstance.isHapticsIntensityAdjustmentSupported(); 53``` 54 55### isHapticsRampSupported<sup>20+</sup> 56 57isHapticsRampSupported(): boolean 58 59查询设备是否可以设置振动渐变。 60 61**系统接口：** 此接口为系统接口。 62 63**系统能力：** SystemCapability.Multimedia.AudioHaptic.Core 64 65**返回值：** 66 67| 类型 | 说明 | 68| ------------------- | ------------------------------- | 69| boolean | 设备是否可以设置振动渐变。true表示设备可以设置振动渐变，false表示设备不可以设置振动渐变。| 70 71**错误码：** 72 73以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 74 75| 错误码ID | 错误信息 | 76|---------|-----------------------------------| 77| 202 | Caller is not a system application. | 78 79**示例：** 80 81```ts 82const result: boolean = audioHapticPlayerInstance.isHapticsRampSupported(); 83``` 84 85### enableHapticsInSilentMode<sup>20+</sup> 86 87enableHapticsInSilentMode(enable: boolean): void 88 89静音模式下，音振播放器可以振动。 90 91> **注意：** 92> 93> 该方法必须在释放音振播放器前使用，不能在播放中调用。 94 95**系统接口：** 此接口为系统接口。 96 97**系统能力：** SystemCapability.Multimedia.AudioHaptic.Core 98 99**参数** 100 101| 参数名 | 类型 | 必填| 说明 | 102| -------- | ---------------------------------------- | ---- | ------------------------ | 103| enable | boolean | 是 | 是否在静音模式下开启振动。true表示在静音模式下开启振动，false表示在静音模式下不开启振动。| 104 105**错误码：** 106 107以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[媒体服务错误码](../apis-media-kit/errorcode-media.md)。 108 109| 错误码ID | 错误信息 | 110|---------|-----------------------------------| 111| 202 | Caller is not a system application. | 112| 5400102 | Operate not permit in current state. | 113 114**示例：** 115 116```ts 117audioHapticPlayerInstance.enableHapticsInSilentMode(true); 118``` 119 120### setHapticsIntensity<sup>20+</sup> 121 122setHapticsIntensity(intensity: number): Promise<void> 123 124设置音振播放器的振幅。使用Promise异步回调。 125 126> **注意：** 127> 128>该方法需在音振播放器释放前调用，且单次播放过程中仅调用一次。 129 130**系统接口：** 此接口为系统接口。 131 132**系统能力：** SystemCapability.Multimedia.AudioHaptic.Core 133 134**参数** 135 136| 参数名 | 类型 | 必填| 说明 | 137| -------- | ---------------------------------------- | ---- | ------------------------ | 138| intensity | number | 是 | 取值范围为[0.00, 1.00]，其中1.00表示最大振幅（100%）。| 139 140**返回值：** 141 142| 类型 | 说明 | 143| ------------------- | ------------------------------- | 144| Promise&lt;void&gt; | Promise对象，无返回结果。 | 145 146**错误码：** 147 148以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[媒体服务错误码](../apis-media-kit/errorcode-media.md)。 149 150| 错误码ID | 错误信息 | 151|---------|-----------------------------------| 152| 202 | Caller is not a system application. | 153| 801 | Function is not supported in current device. | 154| 5400102 | Operate not permit in current state. | 155| 5400108 | Parameter out of range. | 156 157**示例：** 158 159```ts 160import { BusinessError } from '@kit.BasicServicesKit'; 161 162audioHapticPlayerInstance.setHapticsIntensity(0.5).then(() => { 163 console.info('Promise returned to indicate that set intensity successfully.'); 164}).catch ((err: BusinessError) => { 165 console.error(`Failed to set intensity. ${err}`); 166}); 167``` 168 169### setHapticsRamp<sup>20+</sup> 170 171setHapticsRamp(duration: number, startIntensity: number, endIntensity: number): Promise<void> 172 173设置音振播放器渐变播放。使用Promise异步回调。 174 175> **注意：** 176> 177>- 该方法需在音振协同播放器播放前后和销毁前使用。 178>- 该方法仅能调用一次。 179 180**系统接口：** 此接口为系统接口。 181 182**系统能力：** SystemCapability.Multimedia.AudioHaptic.Core 183 184**参数** 185 186| 参数名 | 类型 | 必填| 说明 | 187| -------- | ---------------------------------------- | ---- | ------------------------ | 188| duration | number | 是 | 渐变时间段，单位为毫秒（ms），值必须为整数，且不能小于100ms。 | 189| startIntensity | number | 是 | 起始振动幅度，取值范围为[0.00, 1.00]，其中1.00表示最大振幅（100%）。| 190| endIntensity | number | 是 | 结束振动幅度，取值范围为[0.00, 1.00]，其中1.00表示最大振幅（100%）。| 191 192**返回值：** 193 194| 类型 | 说明 | 195| ------------------- | ------------------------------- | 196| Promise&lt;void&gt; | Promise对象，无返回结果。 | 197 198**错误码：** 199 200以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[媒体服务错误码](../apis-media-kit/errorcode-media.md)。 201 202| 错误码ID | 错误信息 | 203|---------|-----------------------------------| 204| 202 | Caller is not a system application. | 205| 801 | Function is not supported in current device. | 206| 5400102 | Operate not permit in current state. | 207| 5400108 | Parameter out of range. | 208 209**示例：** 210 211```ts 212import { BusinessError } from '@kit.BasicServicesKit'; 213 214const duration = 10000; 215const startIntensity = 0.5; 216const endIntensity = 1; 217 218audioHapticPlayerInstance.setHapticsRamp(duration, startIntensity, endIntensity).then(() => { 219 console.info('Promise returned to indicate that set haptics ramp successfully.'); 220}).catch ((err: BusinessError) => { 221 console.error(`Failed to set haptics ramp. ${err}`); 222}); 223```