1# systemTonePlayer (系统提示音播放器)(系统接口) 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 11systemTonePlayer需要和[@ohos.multimedia.systemSoundManager](js-apis-systemSoundManager-sys.md)配合使用，才能完成管理系统提示音的功能。 12 13> **说明：** 14> 15> - 本模块首批接口从API version 11开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 16> - 本模块接口为系统接口。 17 18## 导入模块 19 20```ts 21import { systemSoundManager } from '@kit.AudioKit'; 22``` 23 24## SystemToneOptions 25 26提示音参数选项。 27 28**系统接口：** 该接口为系统接口 29 30**系统能力：** SystemCapability.Multimedia.SystemSound.Core 31 32| 名称 | 类型 | 必填 | 说明 | 33| ----------- | ------- | ---- | --------------------------------------------- | 34| muteAudio | boolean | 否 | 是否静音，true表示静音，false表示正常发声。 | 35| muteHaptics | boolean | 否 | 是否震动，true表示无振动，false表示正常振动。 | 36 37## SystemTonePlayer 38 39系统提示音播放器提供了短信提示音、通知提示音的播放、配置、获取信息等功能。在调用SystemTonePlayer的接口前，需要先通过[getSystemTonePlayer](js-apis-systemSoundManager-sys.md#getsystemtoneplayer11)创建实例。 40 41### getTitle 42 43getTitle(): Promise<string> 44 45获取提示音标题。使用Promise异步回调。 46 47**系统接口：** 该接口为系统接口 48 49**系统能力：** SystemCapability.Multimedia.SystemSound.Core 50 51**返回值：** 52 53| 类型 | 说明 | 54| ------- | ------------------------------------- | 55| Promise<string> | Promise对象，返回获取的系统提示音标题。 | 56 57**错误码：** 58 59以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[媒体服务错误码](../apis-media-kit/errorcode-media.md)。 60 61| 错误码ID | 错误信息 | 62| -------- | ----------------------------------- | 63| 202 | Caller is not a system application. | 64| 5400103 | I/O error. | 65 66**示例：** 67 68```ts 69import { BusinessError } from '@kit.BasicServicesKit'; 70 71systemTonePlayer.getTitle().then((value: string) => { 72 console.info('Succeeded in doing getTitle.'); 73}).catch((err: BusinessError) => { 74 console.error(`Failed to getTitle. Code: ${err.code}, message: ${err.message}`); 75}); 76``` 77 78### prepare 79 80prepare(): Promise<void> 81 82准备播放提示音。使用Promise异步回调。 83 84**系统接口：** 该接口为系统接口 85 86**系统能力：** SystemCapability.Multimedia.SystemSound.Core 87 88**返回值：** 89 90| 类型 | 说明 | 91| ------- | ------------------------------- | 92| Promise<void> | Promise对象。无返回结果的Promise对象。 | 93 94**错误码：** 95 96以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[媒体服务错误码](../apis-media-kit/errorcode-media.md)。 97 98| 错误码ID | 错误信息 | 99| -------- | ----------------------------------- | 100| 202 | Caller is not a system application. | 101| 5400102 | Operation not allowed. | 102| 5400103 | I/O error. | 103 104**示例：** 105 106```ts 107import { BusinessError } from '@kit.BasicServicesKit'; 108 109systemTonePlayer.prepare().then(() => { 110 console.info('Succeeded in doing prepare.'); 111}).catch((err: BusinessError) => { 112 console.error(`Failed to prepare. Code: ${err.code}, message: ${err.message}`); 113}); 114``` 115 116### start 117 118start(toneOptions?: SystemToneOptions): Promise<number> 119 120开始播放提示音。使用Promise异步回调。 121 122**系统接口：** 该接口为系统接口 123 124**系统能力：** SystemCapability.Multimedia.SystemSound.Core 125 126**需要权限：** ohos.permission.VIBRATE 127 128**参数：** 129 130| 参数名 | 类型 | 必填 | 说明 | 131| ----------- | --------------------------------------- | ---- | ---------------- | 132| toneOptions | [SystemToneOptions](#systemtoneoptions) | 否 | 系统提示音选项。 | 133 134**返回值：** 135 136| 类型 | 说明 | 137| ------- | ------------------------- | 138| Promise<number> | Promise对象，返回streamID。 | 139 140**错误码：** 141 142以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[媒体服务错误码](../apis-media-kit/errorcode-media.md)。 143 144| 错误码ID | 错误信息 | 145| -------- | ----------------------------------------------------------------------------------------------------------- | 146| 201 | Permission denied. | 147| 202 | Caller is not a system application. | 148| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 149| 5400102 | Operation not allowed. | 150 151**示例：** 152 153```ts 154import { BusinessError } from '@kit.BasicServicesKit'; 155 156class SystemToneOptions { 157 muteAudio: boolean = false; 158 muteHaptics: boolean = false; 159} 160let systemToneOptions: SystemToneOptions = {muteAudio: true, muteHaptics: false}; 161 162systemTonePlayer.start(systemToneOptions).then((value: number) => { 163 console.info('Succeeded in doing start.'); 164}).catch((err: BusinessError) => { 165 console.error(`Failed to start. Code: ${err.code}, message: ${err.message}`); 166}); 167``` 168 169### stop 170 171stop(id: number): Promise<void> 172 173停止播放提示音。使用Promise异步回调。 174 175**系统接口：** 该接口为系统接口 176 177**系统能力：** SystemCapability.Multimedia.SystemSound.Core 178 179**参数：** 180 181| 参数名 | 类型 | 必填 | 说明 | 182| ------ | ------ | ---- | ------------------------- | 183| id | number | 是 | Promise对象，返回streamID。 | 184 185**返回值：** 186 187| 类型 | 说明 | 188| ------- | ----------------------------------- | 189| Promise<void> | Promise回调返回停止播放成功或失败。 | 190 191**错误码：** 192 193以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[媒体服务错误码](../apis-media-kit/errorcode-media.md)。 194 195| 错误码ID | 错误信息 | 196| -------- | ----------------------------------------------------------------------------------------------------------- | 197| 202 | Caller is not a system application. | 198| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 199| 5400102 | Operation not allowed. | 200 201**示例：** 202 203```ts 204import { BusinessError } from '@kit.BasicServicesKit'; 205 206let streamID: number = 0; //streamID为start方法返回的streamID,此处只做初始化。 207systemTonePlayer.stop(streamID).then(() => { 208 console.info('Succeeded in doing stop.'); 209}).catch((err: BusinessError) => { 210 console.error(`Failed to stop. Code: ${err.code}, message: ${err.message}`); 211}); 212``` 213 214### release 215 216release(): Promise<void> 217 218释放提示音播放器。使用Promise异步回调。 219 220**系统接口：** 该接口为系统接口 221 222**系统能力：** SystemCapability.Multimedia.SystemSound.Core 223 224**返回值：** 225 226| 类型 | 说明 | 227| ------- | ------------------------------- | 228| Promise<void> | Promise对象。无返回结果的Promise对象。 | 229 230**错误码：** 231 232以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 233 234| 错误码ID | 错误信息 | 235| -------- | ----------------------------------- | 236| 202 | Caller is not a system application. | 237 238**示例：** 239 240```ts 241import { BusinessError } from '@kit.BasicServicesKit'; 242 243systemTonePlayer.release().then(() => { 244 console.info('Succeeded in doing release.'); 245}).catch((err: BusinessError) => { 246 console.error(`Failed to release. Code: ${err.code}, message: ${err.message}`); 247}); 248``` 249 250### setAudioVolumeScale<sup>13+</sup> 251 252setAudioVolumeScale(scale: number): void 253 254设置音频音量大小，无返回结果。 255 256**系统接口：** 该接口为系统接口 257 258**系统能力：** SystemCapability.Multimedia.SystemSound.Core 259 260**参数：** 261 262| 参数名 | 类型 | 必填 | 说明 | 263| ------ | ------ | ---- | ------------------------------------ | 264| scale | number | 是 | 音频音量大小，必须在[0, 1]之间取值。 | 265 266**错误码：** 267 268以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)、[媒体服务错误码](../apis-media-kit/errorcode-media.md)和[铃声错误码说明文档](./errorcode-ringtone.md)。 269 270| 错误码ID | 错误信息 | 271| -------- | ----------------------------------------------------------------------------------------------------------- | 272| 202 | Caller is not a system application. | 273| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 274| 5400102 | Operation not allowed. | 275| 20700002 | Parameter check error, For example, value is out side [0, 1]. | 276 277**示例：** 278 279```ts 280import { BusinessError } from '@kit.BasicServicesKit'; 281 282let scale: number = 0.5; 283try { 284 systemTonePlayer.setAudioVolumeScale(scale); 285 console.info('Succeeded in doing setAudioVolumeScale.'); 286} catch (err) { 287 let error = err as BusinessError; 288 console.error(`Failed to setAudioVolumeScale. Code: ${error.code}, message: ${error.message}`); 289} 290``` 291 292### getAudioVolumeScale<sup>13+</sup> 293 294getAudioVolumeScale(): number 295 296获取当前音频音量大小，同步返回当前音量。 297 298**系统接口：** 该接口为系统接口 299 300**系统能力：** SystemCapability.Multimedia.SystemSound.Core 301 302**返回值：** 303 304 305| 类型 | 说明 | 306| ------ | ------------ | 307| number | 当前音频音量。 | 308 309**错误码：** 310 311以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 312 313| 错误码ID | 错误信息 | 314| -------- | ----------------------------------- | 315| 202 | Caller is not a system application. | 316 317**示例：** 318 319```ts 320import { BusinessError } from '@kit.BasicServicesKit'; 321 322try { 323 let scale: number = systemTonePlayer.getAudioVolumeScale(); 324 console.info('Succeeded in doing getAudioVolumeScale.'); 325} catch (err) { 326 let error = err as BusinessError; 327 console.error(`Failed to getAudioVolumeScale. Code: ${error.code}, message: ${error.message}`); 328} 329``` 330 331### getSupportedHapticsFeatures<sup>13+</sup> 332 333getSupportedHapticsFeatures(): Promise<Array<systemSoundManager.ToneHapticsFeature>> 334 335获取当前支持的振动风格。使用Promise异步回调。 336 337**系统接口：** 该接口为系统接口 338 339**系统能力：** SystemCapability.Multimedia.SystemSound.Core 340 341**返回值：** 342 343| 类型 | 说明 | 344|-----------------------------------------------------------------------------------------------------------------------------| --------------------------------------------------------------------------------------------------------------------- | 345| Promise<Array<[systemSoundManager.ToneHapticsFeature](js-apis-systemSoundManager-sys.md#tonehapticsfeature13)>> | Promise对象，返回当前支持的振动风格。 | 346 347**错误码：** 348 349以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[铃声错误码说明文档](./errorcode-ringtone.md)。 350 351| 错误码ID | 错误信息 | 352| -------- | ----------------------------------- | 353| 202 | Caller is not a system application. | 354| 20700003 | Unsupported operation. | 355 356**示例：** 357 358```ts 359systemTonePlayer.getSupportedHapticsFeatures().then((features: Array<systemSoundManager.ToneHapticsFeature>) => { 360 console.info('Succeeded in doing getSupportedHapticsFeatures.'); 361}).catch((err: BusinessError) => { 362 console.error(`Failed to getSupportedHapticsFeatures. Code: ${err.code}, message: ${err.message}`); 363}); 364``` 365 366### setHapticsFeature<sup>13+</sup> 367 368setHapticsFeature(hapticsFeature: systemSoundManager.ToneHapticsFeature): void 369 370设置播放铃音时的振动风格。 371 372调用本接口前，应该先调用[getSupportedHapticsFeatures](#getsupportedhapticsfeatures13)查询支持的振动风格，如果设置不支持的振动风格，则设置失败。 373 374**系统接口：** 该接口为系统接口 375 376**系统能力：** SystemCapability.Multimedia.SystemSound.Core 377 378**参数：** 379 380| 参数名 | 类型 | 必填 | 说明 | 381| -------------- |-------------------------------------------------------------------------------------------------| ---- | ---------------- | 382| hapticsFeature | [systemSoundManager.ToneHapticsFeature](js-apis-systemSoundManager-sys.md#tonehapticsfeature13) | 是 | 振动风格。 | 383 384**错误码：** 385 386以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)、[媒体服务错误码](../apis-media-kit/errorcode-media.md)和[铃声错误码说明文档](./errorcode-ringtone.md)。 387 388| 错误码ID | 错误信息 | 389| -------- | ----------------------------------------------------------------------------------------------------------- | 390| 202 | Caller is not a system application. | 391| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 392| 5400102 | Operation not allowed. | 393| 20700003 | Unsupported operation. | 394 395**示例：** 396 397```ts 398systemTonePlayer.getSupportedHapticsFeatures().then((features: Array<systemSoundManager.ToneHapticsFeature>) => { 399 console.info('Succeeded in doing getSupportedHapticsFeatures.'); 400 if (features.length > 0) { 401 let feature: systemSoundManager.ToneHapticsFeature = features[0]; 402 systemTonePlayer.setHapticsFeature(feature); 403 console.info('Succeeded in doing setHapticsFeature.'); 404 } 405}).catch((err: BusinessError) => { 406 console.error(`Failed to getSupportedHapticsFeatures. Code: ${err.code}, message: ${err.message}`); 407}); 408``` 409 410### getHapticsFeature<sup>13+</sup> 411 412getHapticsFeature(): systemSoundManager.ToneHapticsFeature 413 414获取播放铃音时的振动风格，同步返回振动风格枚举值。 415 416**系统接口：** 该接口为系统接口 417 418**系统能力：** SystemCapability.Multimedia.SystemSound.Core 419 420**返回值：** 421 422| 类型 | 说明 | 423|-------------------------------------------------------------------------------------------------| -------- | 424| [systemSoundManager.ToneHapticsFeature](js-apis-systemSoundManager-sys.md#tonehapticsfeature13) | 振动风格。 | 425 426**错误码：** 427 428以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[铃声错误码说明文档](./errorcode-ringtone.md)。 429 430 431| 错误码ID | 错误信息 | 432| -------- | ----------------------------------- | 433| 202 | Caller is not a system application. | 434| 20700003 | Unsupported operation. | 435 436**示例：** 437 438```ts 439import { BusinessError } from '@kit.BasicServicesKit'; 440 441try { 442 let feature: systemSoundManager.ToneHapticsFeature = systemTonePlayer.getHapticsFeature(); 443 console.info('Succeeded in doing getHapticsFeature.'); 444} catch (err) { 445 let error = err as BusinessError; 446 console.error(`Failed to getHapticsFeature. Code: ${error.code}, message: ${error.message}`); 447} 448``` 449 450### on('playFinished')<sup>18+</sup> 451 452on(type: 'playFinished', streamId: number, callback: Callback\<number>): void 453 454监听铃音播放完成事件（当铃音播放完成时触发）。使用callback异步回调。 455 456监听对象为传入的streamId对应音频流。当streamId传入0时，监听本播放器对应的所有音频流。 457 458**系统能力：** SystemCapability.Multimedia.SystemSound.Core 459 460**参数：** 461 462| 参数名 | 类型 | 必填 | 说明 | 463| -------- | ----------------------- | ---- | --------------------------------------------------------------- | 464| type | string | 是 | 事件回调类型，支持的事件为'playFinished'，当铃音播放完成时，触发该事件。 | 465| streamId | number | 是 | 监听对象为指定streamId对应的音频流，streamId通过[start](#start)获取。当streamId传入0时，可监听当前播放器对应的所有音频流。 | 466| callback | Callback\<number> | 是 | 'playFinished'的回调方法。返回播放完成的音频流的streamId。 | 467 468**错误码：** 469 470以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[铃声错误码说明文档](./errorcode-ringtone.md)。 471 472| 错误码ID | 错误信息 | 473| ------- | --------------------------------------------| 474| 202 | Not system App. | 475| 20700002 | Parameter check error. | 476 477**示例：** 478 479```ts 480import { BusinessError } from '@kit.BasicServicesKit'; 481 482// 监听所有音频流的结束事件。 483systemTonePlayer.on('playFinished', 0, (streamId: number) => { 484 console.info(`Receive the callback of playFinished, streamId: ${streamId}.`); 485}); 486 487// 监听指定音频流的结束事件。 488systemTonePlayer.start().then((value: number) => { 489 systemTonePlayer.on('playFinished', value, (streamId: number) => { 490 console.info(`Receive the callback of playFinished, streamId: ${streamId}.`); 491 }); 492}).catch((err: BusinessError) => { 493 console.error(`Failed to start system tone player. ${err}`); 494}); 495``` 496 497### off('playFinished')<sup>18+</sup> 498 499off(type: 'playFinished', callback?: Callback\<number>): void 500 501取消监听铃音播放完成事件。使用callback异步回调。 502 503**系统能力：** SystemCapability.Multimedia.SystemSound.Core 504 505**参数：** 506 507| 参数名 | 类型 | 必填 | 说明 | 508| ----- | ----- | ---- | ------------------------------------------------ | 509| type | string | 是 | 事件回调类型，支持的事件为'playFinished'，当取消监听铃音播放完成事件时，触发该事件。 | 510| callback | Callback\<number> | 否 | 回调函数，返回结束事件的音频流的streamId。不填入此参数时，会取消该事件的所有监听。 | 511 512**错误码：** 513 514以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[铃声错误码说明文档](./errorcode-ringtone.md)。 515 516| 错误码ID | 错误信息 | 517| ------- | --------------------------------------------| 518| 202 | Not system App. | 519| 20700002 | Parameter check error. | 520 521**示例：** 522 523```ts 524// 取消该事件的所有监听。 525systemTonePlayer.off('playFinished'); 526 527// 同一监听事件中，on方法和off方法传入callback参数一致，off方法取消对应on方法订阅的监听。 528let playFinishedCallback = (streamId: number) => { 529 console.info(`Receive the callback of playFinished, streamId: ${streamId}.`); 530}; 531 532systemTonePlayer.on('playFinished', 0, playFinishedCallback); 533 534systemTonePlayer.off('playFinished', playFinishedCallback); 535``` 536 537### on('error')<sup>18+</sup> 538 539on(type: 'error', callback: ErrorCallback): void 540 541监听铃音播放过程中的错误事件（当铃音播放过程中发生错误时触发）。使用callback异步回调。 542 543**系统能力**：SystemCapability.Multimedia.SystemSound.Core 544 545**参数：** 546 547| 参数名 | 类型 | 必填 | 说明 | 548| -------- | ------------- | ---- | ------------------------------------ | 549| type | string | 是 | 事件回调类型，支持的事件为'error'，当铃音播放过程中发生错误时，触发该事件。 | 550| callback | ErrorCallback | 是 | 回调函数，返回错误码和错误信息。错误码请参考AVPlayer的[on('error')](../apis-media-kit/arkts-apis-media-AVPlayer.md#onerror9)。 | 551 552**错误码：** 553 554以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[铃声错误码说明文档](./errorcode-ringtone.md)。 555 556| 错误码ID | 错误信息 | 557| ------- | --------------------------------------------| 558| 202 | Not system App. | 559| 20700002 | Parameter check error. | 560 561**示例：** 562 563```ts 564import { BusinessError } from '@kit.BasicServicesKit'; 565 566systemTonePlayer.on('error', (err: BusinessError) => { 567 console.log("on error, err:" + JSON.stringify(err)); 568}); 569``` 570 571### off('error')<sup>18+</sup> 572 573off(type: 'error', callback?: ErrorCallback): void 574 575取消监听铃音播放过程中的错误事件。使用callback异步回调。 576 577**系统能力**：SystemCapability.Multimedia.SystemSound.Core 578 579**参数：** 580 581| 参数名 | 类型 | 必填 | 说明 | 582| -------- | ------------- | ---- | ------------------------------------ | 583| type | string | 是 | 事件回调类型，支持的事件为'error'，当取消监听铃音播放过程中的错误事件时，触发该事件。 | 584| callback | ErrorCallback | 否 | 回调函数，返回错误码和错误信息。不填入此参数时，会取消该事件的所有监听。 | 585 586**错误码：** 587 588以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[铃声错误码说明文档](./errorcode-ringtone.md)。 589 590| 错误码ID | 错误信息 | 591| ------- | --------------------------------------------| 592| 202 | Not system App. | 593| 20700002 | Parameter check error. | 594 595**示例：** 596 597```ts 598import { BusinessError } from '@kit.BasicServicesKit'; 599 600// 取消该事件的所有监听。 601systemTonePlayer.off('error'); 602 603// 同一监听事件中，on方法和off方法传入callback参数一致，off方法取消对应on方法订阅的监听。 604let callback = (err: BusinessError) => { 605 console.log("on error, err:" + JSON.stringify(err)); 606}; 607 608systemTonePlayer.on('error', callback); 609 610systemTonePlayer.off('error', callback); 611``` 612