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以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[媒体服务错误码](../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以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[媒体服务错误码](../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以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[媒体服务错误码](../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以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[媒体服务错误码](../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以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.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以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[媒体服务错误码](../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以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 302 303| 错误码ID | 错误信息 | 304| -------- | ----------------------------------- | 305| 202 | Caller is not a system application. | 306 307**示例：** 308 309```ts 310try { 311 let scale: number = systemTonePlayer.getAudioVolumeScale(); 312 console.info(` get audio volume scale. ${scale}`); 313} catch (err) { 314 console.error(`Failed to get audio volume scale. ${err}`); 315} 316``` 317 318### getSupportedHapticsFeatures<sup>13+</sup> 319 320getSupportedHapticsFeatures(): Promise<Array<systemSoundManager.ToneHapticsFeature>> 321 322获取当前支持的振动风格，使用Promise方式异步返回支持的振动风格列表。 323 324**系统接口：** 该接口为系统接口 325 326**系统能力：** SystemCapability.Multimedia.SystemSound.Core 327 328**返回值：** 329 330 331| 类型 | 说明 | 332|-----------------------------------------------------------------------------------------------------------------------------| --------------------------------------------------------------------------------------------------------------------- | 333| Promise<Array<[systemSoundManager.ToneHapticsFeature](js-apis-systemSoundManager-sys.md#tonehapticsfeature13)>> | Promise回调返回当前支持的振动风格。 | 334 335**错误码：** 336 337以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[媒体服务错误码](../apis-media-kit/errorcode-media.md)。 338 339| 错误码ID | 错误信息 | 340| -------- | ----------------------------------- | 341| 202 | Caller is not a system application. | 342| 20700003 | Unsupported operation. | 343 344**示例：** 345 346```ts 347try { 348 let features: Array<systemSoundManager.ToneHapticsFeature> = await systemTonePlayer.getSupportedHapticsFeatures(); 349 console.info(` get supported haptics features. ${features}`); 350} catch (err) { 351 console.error(`Failed to get supported haptics features. ${err}`); 352} 353``` 354 355### setHapticsFeature<sup>13+</sup> 356 357setHapticsFeature(hapticsFeature: systemSoundManager.ToneHapticsFeature): void 358 359设置播放铃音时的振动风格。 360 361调用本接口前，应该先调用[getSupportedHapticsFeatures](#getsupportedhapticsfeatures13)查询支持的振动风格，如果设置不支持的振动风格，则设置失败。 362 363**系统接口：** 该接口为系统接口 364 365**系统能力：** SystemCapability.Multimedia.SystemSound.Core 366**参数：** 367 368 369| 参数名 | 类型 | 必填 | 说明 | 370| -------------- |-------------------------------------------------------------------------------------------------| ---- | ---------------- | 371| hapticsFeature | [systemSoundManager.ToneHapticsFeature](js-apis-systemSoundManager-sys.md#tonehapticsfeature13) | 是 | 振动风格。 | 372 373**错误码：** 374 375以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[媒体服务错误码](../apis-media-kit/errorcode-media.md)。 376 377| 错误码ID | 错误信息 | 378| -------- | ----------------------------------------------------------------------------------------------------------- | 379| 202 | Caller is not a system application. | 380| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 381| 5400102 | Operation not allowed. | 382| 20700003 | Unsupported operation. | 383 384**示例：** 385 386```ts 387try { 388 let features: Array<systemSoundManager.ToneHapticsFeature> = await systemTonePlayer.getSupportedHapticsFeatures(); 389 if (features.lenght == 0) { 390 return; 391 } 392 let feature: systemSoundManager.ToneHapticsFeature = features[0]; 393 systemTonePlayer.setHapticsFeature(feature); 394 console.info(` set haptics feature success`); 395} catch (err) { 396 console.error(`Failed to set haptics feature. ${err}`); 397} 398``` 399 400### getHapticsFeature<sup>13+</sup> 401 402getHapticsFeature(): systemSoundManager.ToneHapticsFeature 403 404获取播放铃音时的振动风格，同步返回振动风格枚举值。 405 406**系统接口：** 该接口为系统接口 407 408**系统能力：** SystemCapability.Multimedia.SystemSound.Core 409 410**返回值：** 411 412 413| 类型 | 说明 | 414|-------------------------------------------------------------------------------------------------| -------- | 415| [systemSoundManager.ToneHapticsFeature](js-apis-systemSoundManager-sys.md#tonehapticsfeature13) | 振动风格。 | 416 417**错误码：** 418 419以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[媒体服务错误码](../apis-media-kit/errorcode-media.md)。 420 421| 错误码ID | 错误信息 | 422| -------- | ----------------------------------- | 423| 202 | Caller is not a system application. | 424| 20700003 | Unsupported operation. | 425 426**示例：** 427 428```ts 429try { 430 let feature: systemSoundManager.ToneHapticsFeature = systemTonePlayer.getHapticsFeature(); 431 console.info(` get haptics feature success. ${features}`); 432} catch (err) { 433 console.error(`Failed to get haptics feature. ${err}`); 434} 435``` 436 437### on('playFinished')<sup>18+</sup> 438 439on(type: 'playFinished', streamId: number, callback: Callback\<number>): void 440 441铃音播放完成监听，监听对象为传入的streamId对应音频流。当streamId传入0时，监听本播放器对应的所有音频流。 442 443**系统能力：** SystemCapability.Multimedia.SystemSound.Core 444 445**参数：** 446 447| 参数名 | 类型 | 必填 | 说明 | 448| -------- | ----------------------- | ---- | --------------------------------------------------------------- | 449| type | string | 是 | 支持事件：'playFinished'。音频流播放完成会触发此回调，需要传入监听的音频流的streamId。 | 450| streamId | number | 是 | 监听对象为指定streamId对应的音频流，streamId通过[start](#start)获取。当streamId传入0时，可监听当前播放器对应的所有音频流。 | 451| callback | Callback\<number> | 是 | 'playFinished'的回调方法。返回播放完成的音频流的streamId。 | 452 453**错误码：** 454 455以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[铃声错误码说明文档](./errorcode-ringtone.md)。 456 457| 错误码ID | 错误信息 | 458| ------- | --------------------------------------------| 459| 202 | Not system App. | 460| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 461| 20700002 | Parameter check error. | 462 463**示例：** 464 465```ts 466import { BusinessError } from '@kit.BasicServicesKit'; 467 468// 监听所有音频流的结束事件。 469systemTonePlayer.on('playFinished', 0, (streamId: number) => { 470 console.info(`Receive the callback of playFinished, streamId: ${streamId}.`); 471}); 472 473// 监听指定音频流的结束事件。 474systemTonePlayer.start().then((value: number) => { 475 systemTonePlayer.on('playFinished', value, (streamId: number) => { 476 console.info(`Receive the callback of playFinished, streamId: ${streamId}.`); 477 }); 478}).catch((err: BusinessError) => { 479 console.error(`Failed to start system tone player. ${err}`); 480}); 481``` 482 483### off('playFinished')<sup>18+</sup> 484 485off(type: 'playFinished', callback?: Callback\<number>): void 486 487取消铃音播放完成监听。 488 489**系统能力：** SystemCapability.Multimedia.SystemSound.Core 490 491**参数：** 492 493| 参数名 | 类型 | 必填 | 说明 | 494| ----- | ----- | ---- | ------------------------------------------------ | 495| type | string | 是 | 要取消监听事件的类型。支持事件为：'playFinished'。 | 496| callback | Callback\<number> | 否 | 回调函数，返回结束事件的音频流的streamId。不填入此参数时，会取消该事件的所有监听。 | 497 498**错误码：** 499 500以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[铃声错误码说明文档](./errorcode-ringtone.md)。 501 502| 错误码ID | 错误信息 | 503| ------- | --------------------------------------------| 504| 202 | Not system App. | 505| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 506| 20700002 | Parameter check error. | 507 508**示例：** 509 510```ts 511// 取消该事件的所有监听。 512systemTonePlayer.off('playFinished'); 513 514// 同一监听事件中，on方法和off方法传入callback参数一致，off方法取消对应on方法订阅的监听。 515let playFinishedCallback = (streamId: number) => { 516 console.info(`Receive the callback of playFinished, streamId: ${streamId}.`); 517}; 518 519systemTonePlayer.on('playFinished', 0, playFinishedCallback); 520 521systemTonePlayer.off('playFinished', playFinishedCallback); 522``` 523 524### on('error')<sup>18+</sup> 525 526on(type: 'error', callback: ErrorCallback): void 527 528铃音播放播放过程中的错误事件监听。 529 530**系统能力**：SystemCapability.Multimedia.SystemSound.Core 531 532**参数：** 533 534| 参数名 | 类型 | 必填 | 说明 | 535| -------- | ------------- | ---- | ------------------------------------ | 536| type | string | 是 | 监听的事件类型。支持事件为：error事件。 | 537| callback | ErrorCallback | 是 | 回调函数，返回错误码和错误信息。错误码请参考AVPlayer的[on('error')](../apis-media-kit/js-apis-media.md#onerror9)。 | 538 539**错误码：** 540 541以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[铃声错误码说明文档](./errorcode-ringtone.md)。 542 543| 错误码ID | 错误信息 | 544| ------- | --------------------------------------------| 545| 202 | Not system App. | 546| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 547| 20700002 | Parameter check error. | 548 549**示例：** 550 551```ts 552import { BusinessError } from '@kit.BasicServicesKit'; 553 554systemTonePlayer.on('error', (err: BusinessError) => { 555 console.log("on error, err:" + JSON.stringify(err)); 556}); 557``` 558 559### off('error')<sup>18+</sup> 560 561off(type: 'error', callback?: ErrorCallback): void 562 563取消铃音播放播放过程中的错误事件监听。 564 565**系统能力**：SystemCapability.Multimedia.SystemSound.Core 566 567**参数：** 568 569| 参数名 | 类型 | 必填 | 说明 | 570| -------- | ------------- | ---- | ------------------------------------ | 571| type | string | 是 | 要取消监听事件的类型。支持的事件为：error事件。 | 572| callback | ErrorCallback | 否 | 回调函数，返回错误码和错误信息。不填入此参数时，会取消该事件的所有监听。 | 573 574**错误码：** 575 576以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[铃声错误码说明文档](./errorcode-ringtone.md)。 577 578| 错误码ID | 错误信息 | 579| ------- | --------------------------------------------| 580| 202 | Not system App. | 581| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 582| 20700002 | Parameter check error. | 583 584**示例：** 585 586```ts 587import { BusinessError } from '@kit.BasicServicesKit'; 588 589// 取消该事件的所有监听。 590systemTonePlayer.off('error'); 591 592// 同一监听事件中，on方法和off方法传入callback参数一致，off方法取消对应on方法订阅的监听。 593let callback = (err: BusinessError) => { 594 console.log("on error, err:" + JSON.stringify(err)); 595}; 596 597systemTonePlayer.on('error', callback); 598 599systemTonePlayer.off('error', callback); 600``` 601