1# systemTonePlayer (系统提示音播放器)(系统接口) 2 3系统提示音播放器提供了短信提示音、通知提示音的播放、配置、获取信息等功能。 4 5systemTonePlayer需要和[@ohos.multimedia.systemSoundManager](js-apis-systemSoundManager-sys.md)配合使用，才能完成管理系统提示音的功能。 6 7> **说明：** 8> 9> - 本模块首批接口从API version 11开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 10> - 本模块接口为系统接口。 11 12## 导入模块 13 14```ts 15import { systemSoundManager } from '@kit.AudioKit'; 16``` 17 18## SystemToneOptions 19 20提示音参数选项。 21 22**系统接口：** 该接口为系统接口 23 24**系统能力：** SystemCapability.Multimedia.SystemSound.Core 25 26| 名称 | 类型 | 必填 | 说明 | 27| ----------- | ------- | ---- | --------------------------------------------- | 28| muteAudio | boolean | 否 | 是否静音，true表示静音，false表示正常发声。 | 29| muteHaptics | boolean | 否 | 是否震动，true表示无振动，false表示正常振动。 | 30 31## SystemTonePlayer 32 33系统提示音播放器提供了短信提示音、通知提示音的播放、配置、获取信息等功能。在调用SystemTonePlayer的接口前，需要先通过[getSystemTonePlayer](js-apis-systemSoundManager-sys.md#getsystemtoneplayer11)创建实例。 34 35### getTitle 36 37getTitle(): Promise<string> 38 39获取提示音标题，使用Promise方式异步返回结果。 40 41**系统接口：** 该接口为系统接口 42 43**系统能力：** SystemCapability.Multimedia.SystemSound.Core 44 45**返回值：** 46 47| 类型 | 说明 | 48| ------- | ------------------------------------- | 49| Promise<string> | Promise回调返回获取的系统提示音标题。 | 50 51**错误码：** 52 53以下错误码的详细介绍请参见[媒体服务错误码](../apis-media-kit/errorcode-media.md)。 54 55| 错误码ID | 错误信息 | 56| -------- | ----------------------------------- | 57| 202 | Caller is not a system application. | 58| 5400103 | I/O error. | 59 60**示例：** 61 62```ts 63import { BusinessError } from '@kit.BasicServicesKit'; 64 65systemTonePlayer.getTitle().then((value: string) => { 66 console.info(`Promise returned to indicate that the value of the system tone player title is obtained ${value}.`); 67}).catch ((err: BusinessError) => { 68 console.error(`Failed to get the system tone player title ${err}`); 69}); 70``` 71 72### prepare 73 74prepare(): Promise<void> 75 76准备播放提示音，使用Promise方式异步返回结果。 77 78**系统接口：** 该接口为系统接口 79 80**系统能力：** SystemCapability.Multimedia.SystemSound.Core 81 82**返回值：** 83 84| 类型 | 说明 | 85| ------- | ------------------------------- | 86| Promise<void> | Promise回调返回准备成功或失败。 | 87 88**错误码：** 89 90以下错误码的详细介绍请参见[媒体服务错误码](../apis-media-kit/errorcode-media.md)。 91 92| 错误码ID | 错误信息 | 93| -------- | ----------------------------------- | 94| 202 | Caller is not a system application. | 95| 5400102 | Operation not allowed. | 96| 5400103 | I/O error. | 97 98**示例：** 99 100```ts 101import { BusinessError } from '@kit.BasicServicesKit'; 102 103systemTonePlayer.prepare().then(() => { 104 console.info(`Promise returned to indicate a successful prepareing of system tone player.`); 105}).catch ((err: BusinessError) => { 106 console.error(`Failed to prepareing system tone player. ${err}`); 107}); 108``` 109 110### start 111 112start(toneOptions?: SystemToneOptions): Promise<number> 113 114开始播放提示音，使用Promise方式异步返回结果。 115 116**系统接口：** 该接口为系统接口 117 118**系统能力：** SystemCapability.Multimedia.SystemSound.Core 119 120**需要权限：** ohos.permission.VIBRATE 121 122**参数：** 123 124| 参数名 | 类型 | 必填 | 说明 | 125| ----------- | --------------------------------------- | ---- | ---------------- | 126| toneOptions | [SystemToneOptions](#systemtoneoptions) | 否 | 系统提示音选项。 | 127 128**返回值：** 129 130| 类型 | 说明 | 131| ------- | ------------------------- | 132| Promise<number> | Promise回调返回streamID。 | 133 134**错误码：** 135 136以下错误码的详细介绍请参见[媒体服务错误码](../apis-media-kit/errorcode-media.md)。 137 138| 错误码ID | 错误信息 | 139| -------- | ----------------------------------------------------------------------------------------------------------- | 140| 201 | Permission denied. | 141| 202 | Caller is not a system application. | 142| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 143| 5400102 | Operation not allowed. | 144 145**示例：** 146 147```ts 148import { BusinessError } from '@kit.BasicServicesKit'; 149 150class SystemToneOptions { 151 muteAudio: boolean = false; 152 muteHaptics: boolean = false; 153} 154let systemToneOptions: SystemToneOptions = {muteAudio: true, muteHaptics: false}; 155 156systemTonePlayer.start(systemToneOptions).then((value: number) => { 157 console.info(`Promise returned to indicate that the value of the system tone player streamID is obtained ${value}.`); 158}).catch ((err: BusinessError) => { 159 console.error(`Failed to start system tone player. ${err}`); 160}); 161``` 162 163### stop 164 165stop(id: number): Promise<void> 166 167停止播放提示音，使用Promise方式异步返回结果。 168 169**系统接口：** 该接口为系统接口 170 171**系统能力：** SystemCapability.Multimedia.SystemSound.Core 172 173**参数：** 174 175| 参数名 | 类型 | 必填 | 说明 | 176| ------ | ------ | ---- | ------------------------- | 177| id | number | 是 | start方法返回的streamID。 | 178 179**返回值：** 180 181| 类型 | 说明 | 182| ------- | ----------------------------------- | 183| Promise<void> | Promise回调返回停止播放成功或失败。 | 184 185**错误码：** 186 187以下错误码的详细介绍请参见[媒体服务错误码](../apis-media-kit/errorcode-media.md)。 188 189| 错误码ID | 错误信息 | 190| -------- | ----------------------------------------------------------------------------------------------------------- | 191| 202 | Caller is not a system application. | 192| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 193| 5400102 | Operation not allowed. | 194 195**示例：** 196 197```ts 198import { BusinessError } from '@kit.BasicServicesKit'; 199 200let streamID: number = 0; //streamID为start方法返回的streamID,此处只做初始化。 201systemTonePlayer.stop(streamID).then(() => { 202 console.info(`Promise returned to indicate a successful stopping of system tone player.`); 203}).catch ((err: BusinessError) => { 204 console.error(`Failed to stop system tone player. ${err}`); 205}); 206``` 207 208### release 209 210release(): Promise<void> 211 212释放提示音播放器，使用Promise方式异步返回结果。 213 214**系统接口：** 该接口为系统接口 215 216**系统能力：** SystemCapability.Multimedia.SystemSound.Core 217 218**返回值：** 219 220| 类型 | 说明 | 221| ------- | ------------------------------- | 222| Promise<void> | Promise回调返回释放成功或失败。 | 223 224**错误码：** 225 226以下错误码的详细介绍请参见[媒体服务错误码](../apis-media-kit/errorcode-media.md)。 227 228| 错误码ID | 错误信息 | 229| -------- | ----------------------------------- | 230| 202 | Caller is not a system application. | 231 232**示例：** 233 234```ts 235import { BusinessError } from '@kit.BasicServicesKit'; 236 237systemTonePlayer.release().then(() => { 238 console.info(`Promise returned to indicate a successful releasing of system tone player.`); 239}).catch ((err: BusinessError) => { 240 console.error(`Failed to release system tone player. ${err}`); 241}); 242``` 243 244### setAudioVolumeScale<sup>13+</sup> 245 246setAudioVolumeScale(scale: number): void 247 248设置音频音量大小，无返回结果。 249 250**系统接口：** 该接口为系统接口 251 252**系统能力：** SystemCapability.Multimedia.SystemSound.Core 253 254**参数：** 255 256| 参数名 | 类型 | 必填 | 说明 | 257| ------ | ------ | ---- | ------------------------------------ | 258| scale | number | 是 | 音频音量大小，必须在[0, 1]之间取值。 | 259 260**错误码：** 261 262以下错误码的详细介绍请参见[媒体服务错误码](../apis-media-kit/errorcode-media.md)。 263 264| 错误码ID | 错误信息 | 265| -------- | ----------------------------------------------------------------------------------------------------------- | 266| 202 | Caller is not a system application. | 267| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 268| 5400102 | Operation not allowed. | 269| 20700002 | Parameter check error, For example, value is out side [0, 1] | 270 271**示例：** 272 273```ts 274let scale: number = 0.5; 275try { 276 systemTonePlayer.setAudioVolumeScale(scale); 277} catch (err) { 278 console.error(`Failed to set audio volume scale. ${err}`); 279} 280``` 281 282### getAudioVolumeScale<sup>13+</sup> 283 284getAudioVolumeScale(): number; 285 286获取当前音频音量大小，同步返回当前音量。 287 288**系统接口：** 该接口为系统接口 289 290**系统能力：** SystemCapability.Multimedia.SystemSound.Core 291 292**返回值：** 293 294 295| 类型 | 说明 | 296| ------ | ------------ | 297| number | 当前音频音量。 | 298 299**错误码：** 300 301以下错误码的详细介绍请参见[媒体服务错误码](../apis-media-kit/errorcode-media.md)。 302 303 304| 错误码ID | 错误信息 | 305| -------- | ----------------------------------- | 306| 202 | Caller is not a system application. | 307 308**示例：** 309 310```ts 311try { 312 let scale: number = systemTonePlayer.getAudioVolumeScale(); 313 console.info(` get audio volume scale. ${scale}`); 314} catch (err) { 315 console.error(`Failed to get audio volume scale. ${err}`); 316} 317``` 318 319### getSupportedHapticsFeatures<sup>13+</sup> 320 321getSupportedHapticsFeatures(): Promise<Array<systemSoundManager.ToneHapticsFeature>> 322 323获取当前支持的振动风格，使用Promise方式异步返回支持的振动风格列表。 324 325**系统接口：** 该接口为系统接口 326 327**系统能力：** SystemCapability.Multimedia.SystemSound.Core 328 329**返回值：** 330 331 332| 类型 | 说明 | 333|-----------------------------------------------------------------------------------------------------------------------------| --------------------------------------------------------------------------------------------------------------------- | 334| Promise<Array<[systemSoundManager.ToneHapticsFeature](js-apis-systemSoundManager-sys.md#tonehapticsfeature13)>> | Promise回调返回当前支持的振动风格。 | 335 336**错误码：** 337 338以下错误码的详细介绍请参见[媒体服务错误码](../apis-media-kit/errorcode-media.md)。 339 340 341| 错误码ID | 错误信息 | 342| -------- | ----------------------------------- | 343| 202 | Caller is not a system application. | 344| 20700003 | Unsupported operation. | 345 346**示例：** 347 348```ts 349try { 350 let features: Array<systemSoundManager.ToneHapticsFeature> = await systemTonePlayer.getSupportedHapticsFeatures(); 351 console.info(` get supported haptics features. ${features}`); 352} catch (err) { 353 console.error(`Failed to get supported haptics features. ${err}`); 354} 355``` 356 357### setHapticsFeature<sup>13+</sup> 358 359setHapticsFeature(hapticsFeature: systemSoundManager.ToneHapticsFeature): void 360 361设置播放铃音时的振动风格。 362 363调用本接口前，应该先调用[getSupportedHapticsFeatures](#getsupportedhapticsfeatures13)查询支持的振动风格，如果设置不支持的振动风格，则设置失败。 364 365**系统接口：** 该接口为系统接口 366 367**系统能力：** SystemCapability.Multimedia.SystemSound.Core 368**参数：** 369 370 371| 参数名 | 类型 | 必填 | 说明 | 372| -------------- |-------------------------------------------------------------------------------------------------| ---- | ---------------- | 373| hapticsFeature | [systemSoundManager.ToneHapticsFeature](js-apis-systemSoundManager-sys.md#tonehapticsfeature13) | 是 | 振动风格。 | 374 375**错误码：** 376 377以下错误码的详细介绍请参见[媒体服务错误码](../apis-media-kit/errorcode-media.md)。 378 379 380| 错误码ID | 错误信息 | 381| -------- | ----------------------------------------------------------------------------------------------------------- | 382| 202 | Caller is not a system application. | 383| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 384| 5400102 | Operation not allowed. | 385| 20700003 | Unsupported operation. | 386 387**示例：** 388 389```ts 390try { 391 let features: Array<systemSoundManager.ToneHapticsFeature> = await systemTonePlayer.getSupportedHapticsFeatures(); 392 if (features.lenght == 0) { 393 return; 394 } 395 let feature: systemSoundManager.ToneHapticsFeature = features[0]; 396 systemTonePlayer.setHapticsFeature(feature); 397 console.info(` set haptics feature success`); 398} catch (err) { 399 console.error(`Failed to set haptics feature. ${err}`); 400} 401``` 402 403### getHapticsFeature<sup>13+</sup> 404 405getHapticsFeature(): systemSoundManager.ToneHapticsFeature 406 407获取播放铃音时的振动风格，同步返回振动风格枚举值。 408 409**系统接口：** 该接口为系统接口 410 411**系统能力：** SystemCapability.Multimedia.SystemSound.Core 412 413**返回值：** 414 415 416| 类型 | 说明 | 417|-------------------------------------------------------------------------------------------------| -------- | 418| [systemSoundManager.ToneHapticsFeature](js-apis-systemSoundManager-sys.md#tonehapticsfeature13) | 振动风格 | 419 420**错误码：** 421 422以下错误码的详细介绍请参见[媒体服务错误码](../apis-media-kit/errorcode-media.md)。 423 424 425| 错误码ID | 错误信息 | 426| -------- | ----------------------------------- | 427| 202 | Caller is not a system application. | 428| 20700003 | Unsupported operation. | 429 430**示例：** 431 432```ts 433try { 434 let feature: systemSoundManager.ToneHapticsFeature = systemTonePlayer.getHapticsFeature(); 435 console.info(` get haptics feature success. ${features}`); 436} catch (err) { 437 console.error(`Failed to get haptics feature. ${err}`); 438} 439``` 440