1# @ohos.multimedia.systemSoundManager (系统声音管理)(系统接口) 2 3系统声音管理提供管理系统声音的一些基础能力，包括对系统铃声的资源设置与读取、获取系统铃声播放器等。 4 5> **说明：** 6> 7> - 本模块首批接口从API version 10开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8> - 本模块接口为系统接口。 9 10## 导入模块 11 12```ts 13import { systemSoundManager } from '@kit.AudioKit'; 14``` 15 16## 常量 17 18**系统接口：** 该接口为系统接口。 19 20**系统能力：** SystemCapability.Multimedia.SystemSound.Core 21 22| 名称 | 值 | 说明 | 23|------------------------------------------|-----|---------| 24| TONE_CATEGORY_RINGTONE<sup>12+</sup> | 1 | 铃声类别。 | 25| TONE_CATEGORY_TEXT_MESSAGE<sup>12+</sup> | 2 | 短信铃声类别。 | 26| TONE_CATEGORY_NOTIFICATION<sup>12+</sup> | 4 | 通知铃声类别。 | 27| TONE_CATEGORY_ALARM<sup>12+</sup> | 8 | 闹钟铃声类别。 | 28 29## RingtoneType 30 31枚举，铃声类型。 32 33**系统接口：** 该接口为系统接口。 34 35**系统能力：** SystemCapability.Multimedia.SystemSound.Core 36 37| 名称 | 值 | 说明 | 38| ------------------------------- |----|------------------------------------------------------------------------| 39| RINGTONE_TYPE_DEFAULT<sup>(deprecated)</sup> | 0 | 默认铃声类型。<br/> 从 API version 11 开始废弃。建议使用该枚举中的RINGTONE_TYPE_SIM_CARD_0替代。 | 40| RINGTONE_TYPE_SIM_CARD_0<sup>11+</sup> | 0 | sim卡1的铃声。 | 41| RINGTONE_TYPE_MULTISIM<sup>(deprecated)</sup> | 1 | 多SIM卡铃声类型。<br/> 从 API version 11 开始废弃。建议使用该枚举中的RINGTONE_TYPE_SIM_CARD_1替代。 | 42| RINGTONE_TYPE_SIM_CARD_1<sup>11+</sup> | 1 | sim卡2的铃声。 | 43 44## SystemToneType<sup>11+</sup> 45 46枚举，系统铃声类型。 47 48**系统接口：** 该接口为系统接口。 49 50**系统能力：** SystemCapability.Multimedia.SystemSound.Core 51 52| 名称 | 值 | 说明 | 53| ------------------------------- |-----|------------| 54| SYSTEM_TONE_TYPE_SIM_CARD_0 | 0 | sim卡1的短信提示音。 | 55| SYSTEM_TONE_TYPE_SIM_CARD_1 | 1 | sim卡2的短信提示音。 | 56| SYSTEM_TONE_TYPE_NOTIFICATION | 32 | 通知提示音。 | 57 58 59## ToneCustomizedType<sup>12+</sup> 60 61枚举，铃声自定义类型。 62 63**系统接口：** 该接口为系统接口。 64 65**系统能力：** SystemCapability.Multimedia.SystemSound.Core 66 67| 名称 | 值 | 说明 | 68| ----------------------------|-----|------------| 69| PRE_INSTALLED<sup>12+</sup> | 0 | 预安装铃声类型。 | 70| CUSTOMIZED<sup>12+</sup> | 1 | 自定义铃声类型。 | 71 72## ToneAttrs<sup>12+</sup> 73 74管理铃声属性。在调用ToneAttrs<sup>12+</sup>的接口前，需要先通过[createCustomizedToneAttrs](#systemsoundmanagercreatecustomizedtoneattrs12)或[getDefaultRingtoneAttrs](#getdefaultringtoneattrs12)、[getRingtoneAttrList](#getringtoneattrlist12)等方法获取实例。 75 76### getTitle<sup>12+</sup> 77 78getTitle(): string 79 80获取铃声标题。 81 82**系统接口：** 该接口为系统接口。 83 84**系统能力：** SystemCapability.Multimedia.SystemSound.Core 85 86**返回值：** 87 88| 类型 | 说明 | 89|--------|-----| 90| string | 标题。 | 91 92**错误码：** 93 94以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 95 96| 错误码ID | 错误信息 | 97|---------| -------------------- | 98| 202 | Caller is not a system application. | 99 100**示例：** 101 102```ts 103toneAttrs.getTitle(); 104``` 105 106### setTitle<sup>12+</sup> 107 108setTitle(title: string): void 109 110设置铃声标题。 111 112**系统接口：** 该接口为系统接口。 113 114**系统能力：** SystemCapability.Multimedia.SystemSound.Core 115 116**参数：** 117 118| 参数名 | 类型 | 必填 | 说明 | 119| -------| -------| ---- | ------------| 120| title | string | 是 | 铃声的标题。 | 121 122**错误码：** 123 124以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 125 126| 错误码ID | 错误信息 | 127|-------| -------------------- | 128| 202 | Caller is not a system application. | 129| 401 | The parameters check failed. | 130 131**示例：** 132 133```ts 134let toneAttrs = systemSoundManager.createCustomizedToneAttrs(); 135let title = 'text'; 136toneAttrs.setTitle(title); 137``` 138 139### getFileName<sup>12+</sup> 140 141getFileName(): string 142 143获取铃声文件名。 144 145**系统接口：** 该接口为系统接口。 146 147**系统能力：** SystemCapability.Multimedia.SystemSound.Core 148 149**返回值：** 150 151| 类型 | 说明 | 152|--------|------| 153| string | 文件名。 | 154 155**错误码：** 156 157以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 158 159| 错误码ID | 错误信息 | 160|---------| -------------------- | 161| 202 | Caller is not a system application. | 162 163 164**示例：** 165 166```ts 167toneAttrs.getFileName(); 168``` 169 170### setFileName<sup>12+</sup> 171 172setFileName(name: string): void 173 174设置铃声文件名。 175 176**系统接口：** 该接口为系统接口。 177 178**系统能力：** SystemCapability.Multimedia.SystemSound.Core 179 180**参数：** 181 182| 参数名 | 类型 | 必填 | 说明 | 183| ------| -------|-----| ------------| 184| name | string | 是 | 铃声的文件名。 | 185 186**错误码：** 187 188以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 189 190| 错误码ID | 错误信息 | 191|-------| -------------------- | 192| 202 | Caller is not a system application. | 193| 401 | The parameters check failed. | 194 195**示例：** 196 197```ts 198let toneAttrs = systemSoundManager.createCustomizedToneAttrs(); 199let fileName = 'textFileName'; 200toneAttrs.setFileName(fileName); 201``` 202 203### getUri<sup>12+</sup> 204 205getUri(): string 206 207获取铃声资源路径。 208 209**系统接口：** 该接口为系统接口。 210 211**系统能力：** SystemCapability.Multimedia.SystemSound.Core 212 213**返回值：** 214 215| 类型 | 说明 | 216|--------|---------------------------------------------------------| 217| string | uri（如：'/data/storage/el2/base/RingTone/alarms/test.ogg'）。 | 218 219**错误码：** 220 221以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 222 223| 错误码ID | 错误信息 | 224|---------| -------------------- | 225| 202 | Caller is not a system application. | 226 227**示例：** 228 229```ts 230toneAttrs.getUri(); 231``` 232 233### getCustomizedType<sup>12+</sup> 234 235getCustomizedType(): string 236 237获取铃声自定义类型。 238 239**系统接口：** 该接口为系统接口。 240 241**系统能力：** SystemCapability.Multimedia.SystemSound.Core 242 243**返回值：** 244 245| 类型 | 说明 | 246|--------------------------------------------|---------| 247| [ToneCustomizedType](#tonecustomizedtype12) | 定制铃音类型。 | 248 249**错误码：** 250 251以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 252 253| 错误码ID | 错误信息 | 254|---------| -------------------- | 255| 202 | Caller is not a system application. | 256 257**示例：** 258 259```ts 260toneAttrs.getCustomizedType(); 261``` 262 263### setCategory<sup>12+</sup> 264 265setCategory(category: number): void 266 267设置铃声类别。 268 269**系统接口：** 该接口为系统接口。 270 271**系统能力：** SystemCapability.Multimedia.SystemSound.Core 272 273**参数：** 274 275| 参数名 | 类型 | 必填 | 说明 | 276|----------| ---------| ---- |----------| 277| category | number | 是 | 铃声类别，取值参考[铃声类别的常量](#常量)。 | 278 279**错误码：** 280 281以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 282 283| 错误码ID | 错误信息 | 284|-------| -------------------- | 285| 202 | Caller is not a system application. | 286| 401 | The parameters check failed. | 287 288**示例：** 289 290```ts 291let toneAttrs = systemSoundManager.createCustomizedToneAttrs(); 292let categoryValue = systemSoundManager.TONE_CATEGORY_ALARM; // 需更改为实际所需类型常量。 293toneAttrs.setCategory(categoryValue); 294``` 295 296### getCategory<sup>12+</sup> 297 298getCategory(): string 299 300获取铃声类别。 301 302**系统接口：** 该接口为系统接口。 303 304**系统能力：** SystemCapability.Multimedia.SystemSound.Core 305 306**返回值：** 307 308| 类型 | 说明 | 309|--------|--------| 310| number | 铃声类别，取值参考[铃声类别的常量](#常量)。 | 311 312**错误码：** 313 314以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 315 316| 错误码ID | 错误信息 | 317|---------| -------------------- | 318| 202 | Caller is not a system application. | 319 320 321**示例：** 322 323```ts 324toneAttrs.getCategory(); 325``` 326 327## ToneAttrsArray<sup>12+</sup> 328 329type ToneAttrsArray = Array<[ToneAttrs](#toneattrs12)> 330 331铃音属性数组。 332 333**系统能力：** SystemCapability.Multimedia.SystemSound.Core 334 335| 类型 | 说明 | 336|----------------------------------------|---------| 337| Array<[ToneAttrs](#toneattrs12)> | 铃音属性数组。 | 338 339## systemSoundManager.createCustomizedToneAttrs<sup>12+</sup> 340 341createCustomizedToneAttrs(): ToneAttrs 342 343创建自定义铃声属性。 344 345**系统接口：** 该接口为系统接口。 346 347**系统能力：** SystemCapability.Multimedia.SystemSound.Core 348 349**返回值：** 350 351| 类型 | 说明 | 352|---------------------------| ------------ | 353| [ToneAttrs](#toneattrs12) | 铃声属性类。 | 354 355**错误码：** 356 357以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 358 359| 错误码ID | 错误信息 | 360|---------| -------------------- | 361| 202 | Caller is not a system application. | 362 363**示例：** 364```ts 365let toneAttrs: systemSoundManager.ToneAttrs = systemSoundManager.createCustomizedToneAttrs(); 366``` 367## ToneHapticsFeature<sup>13+</sup> 368 369枚举，系统振动风格定义。 370 371**系统接口：** 该接口为系统接口。 372 373**系统能力：** SystemCapability.Multimedia.SystemSound.Core 374 375| 名称 | 值 | 说明 | 376| ----------------------------- | -- | -------------------- | 377| STANDARD| 0 | 标准振动风格。 | 378| GENTLE | 1 | 轻柔振动风格。 | 379 380## ToneHapticsType<sup>14+</sup> 381 382枚举，系统铃音的振动类型。 383 384**系统接口：** 该接口为系统接口。 385 386**系统能力：** SystemCapability.Multimedia.SystemSound.Core 387 388| 名称 | 值 | 说明 | 389| ------------------------|----|--------| 390| CALL_SIM_CARD_0 | 0 | sim卡1的来电铃声的振动。 | 391| CALL_SIM_CARD_1 | 1 | sim卡2的来电铃声的振动。 | 392| TEXT_MESSAGE_SIM_CARD_0 | 20 | sim卡1的短信提示音的振动。 | 393| TEXT_MESSAGE_SIM_CARD_1 | 21 | sim卡2的短信提示音的振动。 | 394| NOTIFICATION | 40 | 通知提示音的振动。 | 395 396## ToneHapticsMode<sup>14+</sup> 397 398枚举，系统铃音场景的振动模式。 399 400**系统接口：** 该接口为系统接口。 401 402**系统能力：** SystemCapability.Multimedia.SystemSound.Core 403 404| 名称 | 值 | 说明 | 405| ----------------------------- | -- | -------------------- | 406| NONE | 0 | 无振动模式。 | 407| SYNC | 1 | 与铃音同步模式。 | 408| NON_SYNC | 2 | 非同步模式。 | 409 410## ToneHapticsSettings<sup>14+</sup> 411 412系统铃音的振动设置。 413 414**系统接口：** 该接口为系统接口。 415 416**系统能力：** SystemCapability.Multimedia.SystemSound.Core 417 418| 名称 | 类型 | 只读 | 可选 | 说明 | 419| ------------ | -- | -- | -- | -------------------- | 420| mode | [ToneHapticsMode](#tonehapticsmode14) | 否 | 否 | 系统铃音的振动模式。 | 421| hapticsUri | string | 否 | 是 | 系统铃音的振动路径，当振动模式不是非同步振动应该被忽略，振动的路径可通过[getToneHapticsList](#gettonehapticslist14)获取。 | 422 423## ToneHapticsAttrs<sup>14+</sup> 424 425系统铃音的振动属性。在调用ToneHapticsAttrs<sup>14+</sup>的接口前，需要先通过[getToneHapticsList](#gettonehapticslist14)或[getHapticsAttrsSyncedWithTone](#gethapticsattrssyncedwithtone14)方法获取实例。 426 427### getUri<sup>14+</sup> 428 429getUri(): string 430 431获取振动资源路径。 432 433**系统接口：** 该接口为系统接口。 434 435**系统能力：** SystemCapability.Multimedia.SystemSound.Core 436 437**返回值：** 438 439| 类型 | 说明 | 440|--------|-----| 441| string | uri（如：'/data/storage/el2/base/haptics/synchronized/alarms/test.json'）。 | 442 443**错误码：** 444 445以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 446 447| 错误码ID | 错误信息 | 448|---------| -------------------- | 449| 202 | Caller is not a system application. | 450 451**示例：** 452 453```ts 454toneHapticsAttrs.getUri(); 455``` 456 457### getTitle<sup>14+</sup> 458 459getTitle(): string 460 461获取振动标题。 462 463**系统接口：** 该接口为系统接口。 464 465**系统能力：** SystemCapability.Multimedia.SystemSound.Core 466 467**返回值：** 468 469| 类型 | 说明 | 470|--------|-----| 471| string | 标题。 | 472 473**错误码：** 474 475以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 476 477| 错误码ID | 错误信息 | 478|---------| -------------------- | 479| 202 | Caller is not a system application. | 480 481**示例：** 482 483```ts 484toneHapticsAttrs.getTitle(); 485``` 486 487### getFileName<sup>14+</sup> 488 489getFileName(): string 490 491获取振动文件名。 492 493**系统接口：** 该接口为系统接口。 494 495**系统能力：** SystemCapability.Multimedia.SystemSound.Core 496 497**返回值：** 498 499| 类型 | 说明 | 500|--------|-----| 501| string | 文件名。 | 502 503**错误码：** 504 505以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 506 507| 错误码ID | 错误信息 | 508|---------| -------------------- | 509| 202 | Caller is not a system application. | 510 511**示例：** 512 513```ts 514toneHapticsAttrs.getFileName(); 515``` 516 517## ToneHapticsAttrsArray<sup>14+</sup> 518 519type ToneHapticsAttrsArray = Array<ToneHapticsAttrs> 520 521系统铃音的振动属性数组。 522 523**系统能力：** SystemCapability.Multimedia.SystemSound.Core 524 525| 类型 | 说明 | 526|----------------------------------------|---------| 527| Array<[ToneHapticsAttrs](#tonehapticsattrs14)> | 系统铃音的振动属性数组。 | 528 529## systemSoundManager.getSystemSoundManager 530 531getSystemSoundManager(): SystemSoundManager 532 533获取系统声音管理器。 534 535**系统接口：** 该接口为系统接口。 536 537**系统能力：** SystemCapability.Multimedia.SystemSound.Core 538 539**返回值：** 540 541| 类型 | 说明 | 542| ----------------------------- | ------------ | 543| [SystemSoundManager](#systemsoundmanager) | 系统声音管理类。 | 544 545**示例：** 546```ts 547let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 548``` 549 550## SystemSoundManager 551 552管理系统声音。在调用SystemSoundManager的接口前，需要先通过[getSystemSoundManager](#systemsoundmanagergetsystemsoundmanager)创建实例。 553 554### setSystemRingtoneUri<sup>(deprecated)</sup> 555 556setSystemRingtoneUri(context: Context, uri: string, type: RingtoneType, callback: AsyncCallback<void>): void 557 558设置系统铃声uri，使用callback方式异步返回结果。 559 560> **说明：** 561> 从 API version 10 开始支持，从 API version 11 开始废弃，建议使用[setRingtoneUri](#setringtoneuri11)替代。 562 563**系统接口：** 该接口为系统接口。 564 565**系统能力：** SystemCapability.Multimedia.SystemSound.Core 566 567**参数：** 568 569| 参数名 | 类型 | 必填 | 说明 | 570| -------- | ---------------------------------------- | ---- | ------------------------ | 571| context | [Context](../apis-ability-kit/js-apis-inner-application-context.md) | 是 | 当前应用的上下文。 | 572| uri | string | 是 | 被设置的系统铃声的uri，资源支持可参考[media.AVPlayer](../apis-media-kit/js-apis-media.md#avplayer9)。 | 573| type | [RingtoneType](#ringtonetype) | 是 | 被设置的系统铃声的类型。 | 574| callback | AsyncCallback<void> | 是 | 回调返回设置成功或失败。 | 575 576**示例：** 577 578```ts 579import { BusinessError } from '@kit.BasicServicesKit'; 580import { common } from '@kit.AbilityKit'; 581 582// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext。 583let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 584let uri = 'file://data/test.wav'; // 需更改为目标铃声文件的uri。 585let type: systemSoundManager.RingtoneType = systemSoundManager.RingtoneType.RINGTONE_TYPE_DEFAULT; 586 587let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 588systemSoundManagerInstance.setSystemRingtoneUri(context, uri, type, (err: BusinessError) => { 589 if (err) { 590 console.error(`Failed to set system ringtone uri. ${err}`); 591 return; 592 } 593 console.info(`Callback invoked to indicate a successful setting of the system ringtone uri.`); 594}); 595``` 596 597### setSystemRingtoneUri<sup>(deprecated)</sup> 598 599setSystemRingtoneUri(context: Context, uri: string, type: RingtoneType): Promise<void> 600 601设置系统铃声uri，使用Promise方式异步返回结果。 602 603> **说明：** 604> 从 API version 10 开始支持，从 API version 11 开始废弃，建议使用[setRingtoneUri](#setringtoneuri11)替代。 605 606**系统接口：** 该接口为系统接口。 607 608**系统能力：** SystemCapability.Multimedia.SystemSound.Core 609 610**参数：** 611 612| 参数名 | 类型 | 必填 | 说明 | 613| -------- | ---------------------------------------- | ---- | ------------------------ | 614| context | [Context](../apis-ability-kit/js-apis-inner-application-context.md) | 是 | 当前应用的上下文。 | 615| uri | string | 是 | 被设置的系统铃声的uri，资源支持可参考[media.AVPlayer](../apis-media-kit/js-apis-media.md#avplayer9)。 | 616| type | [RingtoneType](#ringtonetype) | 是 | 被设置的系统铃声的类型。 | 617 618**返回值：** 619 620| 类型 | 说明 | 621| ------------------- | ------------------------------- | 622| Promise<void> | Promise回调返回设置成功或失败。 | 623 624**示例：** 625 626```ts 627import { BusinessError } from '@kit.BasicServicesKit'; 628import { common } from '@kit.AbilityKit'; 629 630// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext。 631let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 632let uri = 'file://data/test.wav'; // 需更改为目标铃声文件的uri。 633let type: systemSoundManager.RingtoneType = systemSoundManager.RingtoneType.RINGTONE_TYPE_DEFAULT; 634 635let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 636systemSoundManagerInstance.setSystemRingtoneUri(context, uri, type).then(() => { 637 console.info(`Promise returned to indicate a successful setting of the system ringtone uri.`); 638}).catch ((err: BusinessError) => { 639 console.error(`Failed to set the system ringtone uri ${err}`); 640}); 641``` 642 643### getSystemRingtoneUri<sup>(deprecated)</sup> 644 645getSystemRingtoneUri(context: Context, type: RingtoneType, callback: AsyncCallback<string>): void 646 647获取系统铃声uri，使用callback方式异步返回结果。 648 649> **说明：** 650> 从 API version 10 开始支持，从 API version 11 开始废弃，建议使用[getRingtoneUri](#getringtoneuri11)替代。 651 652**系统接口：** 该接口为系统接口。 653 654**系统能力：** SystemCapability.Multimedia.SystemSound.Core 655 656**参数：** 657 658| 参数名 | 类型 | 必填 | 说明 | 659| -------- |-----------------------------------------------------------------------| ---- | ------------------------ | 660| context | [Context](../apis-ability-kit/js-apis-inner-application-context.md) | 是 | 当前应用的上下文。 | 661| type | [RingtoneType](#ringtonetype) | 是 | 待获取的系统铃声的类型。 | 662| callback | AsyncCallback<string> | 是 | 回调返回获取的系统铃声uri。 | 663 664**示例：** 665 666```ts 667import { BusinessError } from '@kit.BasicServicesKit'; 668import { common } from '@kit.AbilityKit'; 669 670// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext。 671let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 672let type: systemSoundManager.RingtoneType = systemSoundManager.RingtoneType.RINGTONE_TYPE_DEFAULT; 673 674let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 675systemSoundManagerInstance.getSystemRingtoneUri(context, type, (err: BusinessError, value: string) => { 676 if (err) { 677 console.error(`Failed to get system ringtone uri. ${err}`); 678 return; 679 } 680 console.info(`Callback invoked to indicate the value of the system ringtone uri is obtained ${value}.`); 681}); 682``` 683 684### getSystemRingtoneUri<sup>(deprecated)</sup> 685 686getSystemRingtoneUri(context: Context, type: RingtoneType): Promise<string> 687 688获取系统铃声uri，使用Promise方式异步返回结果。 689 690> **说明：** 691> 从 API version 10 开始支持，从 API version 11 开始废弃，建议使用[getRingtoneUri](#getringtoneuri11)替代。 692 693**系统接口：** 该接口为系统接口。 694 695**系统能力：** SystemCapability.Multimedia.SystemSound.Core 696 697**参数：** 698 699| 参数名 | 类型 | 必填 | 说明 | 700| -------- |----------------------------------------------------------------------| ---- | ------------------------ | 701| context | [Context](../apis-ability-kit/js-apis-inner-application-context.md) | 是 | 当前应用的上下文。 | 702| type | [RingtoneType](#ringtonetype) | 是 | 被设置的系统铃声的类型。 | 703 704**返回值：** 705 706| 类型 | 说明 | 707| ------------------- | ---------------------------------- | 708| Promise<string> | Promise回调返回获取的系统铃声uri。 | 709 710**示例：** 711 712```ts 713import { BusinessError } from '@kit.BasicServicesKit'; 714import { common } from '@kit.AbilityKit'; 715 716// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext。 717let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 718let type: systemSoundManager.RingtoneType = systemSoundManager.RingtoneType.RINGTONE_TYPE_DEFAULT; 719 720let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 721systemSoundManagerInstance.getSystemRingtoneUri(context, type).then((value: string) => { 722 console.info(`Promise returned to indicate that the value of the system ringtone uri is obtained ${value}.`); 723}).catch ((err: BusinessError) => { 724 console.error(`Failed to get the system ringtone uri ${err}`); 725}); 726``` 727 728### getSystemRingtonePlayer<sup>(deprecated)</sup> 729 730getSystemRingtonePlayer(context: Context, type: RingtoneType, callback: AsyncCallback<RingtonePlayer>): void 731 732获取系统铃声播放器，使用callback方式异步返回结果。 733 734> **说明：** 735> 从 API version 10 开始支持，从 API version 11 开始废弃，建议使用[getRingtonePlayer](#getringtoneplayer11)替代。 736 737**系统接口：** 该接口为系统接口。 738 739**系统能力：** SystemCapability.Multimedia.SystemSound.Core 740 741**参数：** 742 743| 参数名 | 类型 | 必填 | 说明 | 744| -------- | -----------------------------------------| ---- | --------------------------- | 745| context | [Context](../apis-ability-kit/js-apis-inner-application-context.md) | 是 | 当前应用的上下文。 | 746| type | [RingtoneType](#ringtonetype) | 是 | 待获取播放器的系统铃声的类型。 | 747| callback | AsyncCallback<[RingtonePlayer](js-apis-inner-multimedia-ringtonePlayer-sys.md#ringtoneplayer)> | 是 | 回调返回获取的系统铃声播放器。 | 748 749**示例：** 750 751```ts 752import { BusinessError } from '@kit.BasicServicesKit'; 753import { common } from '@kit.AbilityKit'; 754 755// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext。 756let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 757let type: systemSoundManager.RingtoneType = systemSoundManager.RingtoneType.RINGTONE_TYPE_DEFAULT; 758let systemRingtonePlayer: systemSoundManager.RingtonePlayer | undefined = undefined; 759 760let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 761systemSoundManagerInstance.getSystemRingtonePlayer(context, type, (err: BusinessError, value: systemSoundManager.RingtonePlayer) => { 762 if (err) { 763 console.error(`Failed to get system ringtone player. ${err}`); 764 return; 765 } 766 console.info(`Callback invoked to indicate the value of the system ringtone player is obtained.`); 767 systemRingtonePlayer = value; 768}); 769``` 770 771### getSystemRingtonePlayer<sup>(deprecated)</sup> 772 773getSystemRingtonePlayer(context: Context, type: RingtoneType): Promise<RingtonePlayer> 774 775获取系统铃声播放器，使用Promise方式异步返回结果。 776 777> **说明：** 778> 从 API version 10 开始支持，从 API version 11 开始废弃，建议使用[getRingtonePlayer](#getringtoneplayer11)替代。 779 780**系统接口：** 该接口为系统接口。 781 782**系统能力：** SystemCapability.Multimedia.SystemSound.Core 783 784**参数：** 785 786| 参数名 | 类型 | 必填 | 说明 | 787| -------- |---------------------------------------------------------------------| ---- | --------------------------- | 788| context | [Context](../apis-ability-kit/js-apis-inner-application-context.md) | 是 | 当前应用的上下文。 | 789| type | [RingtoneType](#ringtonetype) | 是 | 待获取播放器的系统铃声的类型。 | 790 791**返回值：** 792 793| 类型 | 说明 | 794| ------------------- | ------------------------------- | 795| Promise<[RingtonePlayer](js-apis-inner-multimedia-ringtonePlayer-sys.md#ringtoneplayer)> | Promise回调返回获取的系统铃声播放器。 | 796 797**示例：** 798 799```ts 800import { BusinessError } from '@kit.BasicServicesKit'; 801import { common } from '@kit.AbilityKit'; 802 803// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext。 804let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 805let type: systemSoundManager.RingtoneType = systemSoundManager.RingtoneType.RINGTONE_TYPE_DEFAULT; 806let systemRingtonePlayer: systemSoundManager.RingtonePlayer | undefined = undefined; 807 808let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 809systemSoundManagerInstance.getSystemRingtonePlayer(context, type).then((value: systemSoundManager.RingtonePlayer) => { 810 console.info(`Promise returned to indicate that the value of the system ringtone player is obtained.`); 811 systemRingtonePlayer = value; 812}).catch ((err: BusinessError) => { 813 console.error(`Failed to get the system ringtone player ${err}`); 814}); 815``` 816 817### setRingtoneUri<sup>11+</sup> 818 819setRingtoneUri(context: BaseContext, uri: string, type: RingtoneType): Promise<void> 820 821设置系统铃声uri，使用Promise方式异步返回结果。 822 823**系统接口：** 该接口为系统接口。 824 825**系统能力：** SystemCapability.Multimedia.SystemSound.Core 826 827**参数：** 828 829| 参数名 | 类型 | 必填 | 说明 | 830| -------- |-------------------------------| ---- | ------------------------ | 831| context | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | 是 | 当前应用的上下文。 | 832| uri | string | 是 | 被设置的系统铃声的uri，资源支持可参考[media.AVPlayer](../apis-media-kit/js-apis-media.md#avplayer9)。 | 833| type | [RingtoneType](#ringtonetype) | 是 | 被设置的系统铃声的类型。 | 834 835**返回值：** 836 837| 类型 | 说明 | 838| ------------------- | ------------------------------- | 839| Promise<void> | Promise回调返回设置成功或失败。 | 840 841**错误码：** 842 843以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[媒体服务错误码](../apis-media-kit/errorcode-media.md)。 844 845| 错误码ID | 错误信息 | 846| ------- | --------------------- | 847| 202 | Caller is not a system application. | 848| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 849| 5400103 | I/O error. | 850 851**示例：** 852 853```ts 854import { BusinessError } from '@kit.BasicServicesKit'; 855import { common } from '@kit.AbilityKit'; 856 857// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext。 858let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 859let uri = 'file://data/test.wav'; // 需更改为目标铃声文件的uri。 860let type: systemSoundManager.RingtoneType = systemSoundManager.RingtoneType.RINGTONE_TYPE_SIM_CARD_0; 861 862let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 863systemSoundManagerInstance.setRingtoneUri(context, uri, type).then(() => { 864 console.info(`Promise returned to indicate a successful setting of the system ringtone uri.`); 865}).catch ((err: BusinessError) => { 866 console.error(`Failed to set the system ringtone uri ${err}`); 867}); 868``` 869 870### getRingtoneUri<sup>11+</sup> 871 872getRingtoneUri(context: BaseContext, type: RingtoneType): Promise<string> 873 874获取系统铃声uri，使用Promise方式异步返回结果。 875 876**系统接口：** 该接口为系统接口。 877 878**系统能力：** SystemCapability.Multimedia.SystemSound.Core 879 880**参数：** 881 882| 参数名 | 类型 | 必填 | 说明 | 883| -------- | -------------------------------| ---- | ------------------------ | 884| context | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md)| 是 | 当前应用的上下文。 | 885| type | [RingtoneType](#ringtonetype) | 是 | 被设置的系统铃声的类型。 | 886 887**返回值：** 888 889| 类型 | 说明 | 890| ------------------- | ---------------------------------- | 891| Promise<string> | Promise回调返回获取的系统铃声uri。 | 892 893**错误码：** 894 895以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[媒体服务错误码](../apis-media-kit/errorcode-media.md)。 896 897| 错误码ID | 错误信息 | 898| -------- | --------------------- | 899| 202 | Caller is not a system application. | 900| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 901| 5400103 | I/O error. | 902 903**示例：** 904 905```ts 906import { BusinessError } from '@kit.BasicServicesKit'; 907import { common } from '@kit.AbilityKit'; 908 909// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext。 910let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 911let type: systemSoundManager.RingtoneType = systemSoundManager.RingtoneType.RINGTONE_TYPE_SIM_CARD_0; 912 913let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 914systemSoundManagerInstance.getRingtoneUri(context, type).then((value: string) => { 915 console.info(`Promise returned to indicate that the value of the system ringtone uri is obtained ${value}.`); 916}).catch ((err: BusinessError) => { 917 console.error(`Failed to get the system ringtone uri ${err}`); 918}); 919``` 920 921### getRingtonePlayer<sup>11+</sup> 922 923getRingtonePlayer(context: BaseContext, type: RingtoneType): Promise<RingtonePlayer> 924 925获取系统铃声播放器，使用Promise方式异步返回结果。 926 927**系统接口：** 该接口为系统接口。 928 929**系统能力：** SystemCapability.Multimedia.SystemSound.Core 930 931**参数：** 932 933| 参数名 | 类型 | 必填 | 说明 | 934| -------- | --------------------------------| ---- | --------------------------- | 935| context | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | 是 | 当前应用的上下文。 | 936| type | [RingtoneType](#ringtonetype) | 是 | 待获取播放器的系统铃声的类型。 | 937 938**返回值：** 939 940| 类型 | 说明 | 941| ------------------- | ------------------------------- | 942| Promise<[RingtonePlayer](js-apis-inner-multimedia-ringtonePlayer-sys.md#ringtoneplayer)> | Promise回调返回获取的系统铃声播放器。 | 943 944**错误码：** 945 946以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 947 948| 错误码ID | 错误信息 | 949| -------- | --------------------- | 950| 202 | Caller is not a system application. | 951| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 952 953**示例：** 954 955```ts 956import { BusinessError } from '@kit.BasicServicesKit'; 957import { common } from '@kit.AbilityKit'; 958 959// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext。 960let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 961let type: systemSoundManager.RingtoneType = systemSoundManager.RingtoneType.RINGTONE_TYPE_SIM_CARD_0; 962let systemRingtonePlayer: systemSoundManager.RingtonePlayer | undefined = undefined; 963 964let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 965systemSoundManagerInstance.getRingtonePlayer(context, type).then((value: systemSoundManager.RingtonePlayer) => { 966 console.info(`Promise returned to indicate that the value of the system ringtone player is obtained.`); 967 systemRingtonePlayer = value; 968}).catch ((err: BusinessError) => { 969 console.error(`Failed to get the system ringtone player ${err}`); 970}); 971``` 972 973### setSystemToneUri<sup>11+</sup> 974 975setSystemToneUri(context: BaseContext, uri: string, type: SystemToneType): Promise<void> 976 977设置系统提示音uri，使用Promise方式异步返回结果。 978 979**系统接口：** 该接口为系统接口。 980 981**系统能力：** SystemCapability.Multimedia.SystemSound.Core 982 983**参数：** 984 985| 参数名 | 类型 | 必填 | 说明 | 986| -------- |-------------------------------------| ---- | ------------------------ | 987| context | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | 是 | 当前应用的上下文。 | 988| uri | string | 是 | 被设置的系统提示音的uri，资源支持可参考[media.AVPlayer](../apis-media-kit/js-apis-media.md#avplayer9)。 | 989| type | [SystemToneType](#systemtonetype11) | 是 | 被设置的系统提示音的类型。 | 990 991**返回值：** 992 993| 类型 | 说明 | 994| ------------------- | ------------------------------- | 995| Promise<void> | Promise回调返回设置成功或失败。 | 996 997**错误码：** 998 999以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[媒体服务错误码](../apis-media-kit/errorcode-media.md)。 1000 1001| 错误码ID | 错误信息 | 1002| ------- | --------------------- | 1003| 202 | Caller is not a system application. | 1004| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 1005| 5400103 | I/O error. | 1006 1007**示例：** 1008 1009```ts 1010import { BusinessError } from '@kit.BasicServicesKit'; 1011import { common } from '@kit.AbilityKit'; 1012 1013// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext。 1014let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 1015let uri = 'file://data/test.wav'; // 需更改为目标铃声文件的uri。 1016let type: systemSoundManager.SystemToneType = systemSoundManager.SystemToneType.SYSTEM_TONE_TYPE_SIM_CARD_0; 1017 1018let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 1019systemSoundManagerInstance.setSystemToneUri(context, uri, type).then(() => { 1020 console.info(`Promise returned to indicate a successful setting of the system tone uri.`); 1021}).catch ((err: BusinessError) => { 1022 console.error(`Failed to set the system tone uri ${err}`); 1023}); 1024``` 1025 1026### getSystemToneUri<sup>11+</sup> 1027 1028getSystemToneUri(context: BaseContext, type: SystemToneType): Promise<string> 1029 1030获取系统提示音uri，使用Promise方式异步返回结果。 1031 1032**系统接口：** 该接口为系统接口。 1033 1034**系统能力：** SystemCapability.Multimedia.SystemSound.Core 1035 1036**参数：** 1037 1038| 参数名 | 类型 | 必填 | 说明 | 1039| -------- |-------------------------------------| ---- | ------------------------ | 1040| context | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | 是 | 当前应用的上下文。 | 1041| type | [SystemToneType](#systemtonetype11) | 是 | 被设置的系统提示音的类型。 | 1042 1043**返回值：** 1044 1045| 类型 | 说明 | 1046| ------------------- | ---------------------------------- | 1047| Promise<string> | Promise回调返回获取的系统提示音uri。 | 1048 1049**错误码：** 1050 1051以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[媒体服务错误码](../apis-media-kit/errorcode-media.md)。 1052 1053| 错误码ID | 错误信息 | 1054| ------- | --------------------- | 1055| 202 | Caller is not a system application. | 1056| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 1057| 5400103 | I/O error. | 1058 1059**示例：** 1060 1061```ts 1062import { BusinessError } from '@kit.BasicServicesKit'; 1063import { common } from '@kit.AbilityKit'; 1064 1065// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext。 1066let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 1067let type: systemSoundManager.SystemToneType = systemSoundManager.SystemToneType.SYSTEM_TONE_TYPE_SIM_CARD_0; 1068 1069let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 1070systemSoundManagerInstance.getSystemToneUri(context, type).then((value: string) => { 1071 console.info(`Promise returned to indicate that the value of the system tone uri is obtained ${value}.`); 1072}).catch ((err: BusinessError) => { 1073 console.error(`Failed to get the system tone uri ${err}`); 1074}); 1075``` 1076 1077### getSystemTonePlayer<sup>11+</sup> 1078 1079getSystemTonePlayer(context: BaseContext, type: SystemToneType): Promise<SystemTonePlayer> 1080 1081获取系统提示音播放器，使用Promise方式异步返回结果。 1082 1083**系统接口：** 该接口为系统接口。 1084 1085**系统能力：** SystemCapability.Multimedia.SystemSound.Core 1086 1087**参数：** 1088 1089| 参数名 | 类型 | 必填 | 说明 | 1090| -------- |-------------------------------------| ---- | --------------------------- | 1091| context | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | 是 | 当前应用的上下文。 | 1092| type | [SystemToneType](#systemtonetype11) | 是 | 待获取播放器的系统提示音的类型。 | 1093 1094**返回值：** 1095 1096| 类型 | 说明 | 1097|--------------------------------------------------------------------------------------------------| ------------------------------- | 1098| Promise<[SystemTonePlayer](js-apis-inner-multimedia-systemTonePlayer-sys.md#systemtoneplayer)> | Promise回调返回获取的系统提示音播放器。 | 1099 1100**错误码：** 1101 1102以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)。 1103 1104| 错误码ID | 错误信息 | 1105| ------- | --------------------- | 1106| 202 | Caller is not a system application. | 1107| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 1108 1109**示例：** 1110 1111```ts 1112import { BusinessError } from '@kit.BasicServicesKit'; 1113import { common } from '@kit.AbilityKit'; 1114 1115// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext。 1116let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 1117let type: systemSoundManager.SystemToneType = systemSoundManager.SystemToneType.SYSTEM_TONE_TYPE_SIM_CARD_0; 1118let systemTonePlayer: systemSoundManager.SystemTonePlayer | undefined = undefined; 1119 1120let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 1121systemSoundManagerInstance.getSystemTonePlayer(context, type).then((value: systemSoundManager.SystemTonePlayer) => { 1122 console.info(`Promise returned to indicate that the value of the system tone player is obtained.`); 1123 systemTonePlayer = value; 1124}).catch ((err: BusinessError) => { 1125 console.error(`Failed to get the system tone player ${err}`); 1126}); 1127``` 1128 1129### getDefaultRingtoneAttrs<sup>12+</sup> 1130 1131getDefaultRingtoneAttrs(context: BaseContext, type: RingtoneType): Promise<ToneAttrs> 1132 1133获取系统铃声的属性，使用Promise方式异步返回结果。 1134 1135**系统接口：** 该接口为系统接口。 1136 1137**系统能力：** SystemCapability.Multimedia.SystemSound.Core 1138 1139**参数：** 1140 1141| 参数名 | 类型 | 必填 | 说明 | 1142| -------- |-------------------------------------| ---- | --------------------------- | 1143| context |[BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | 是 | 当前应用的上下文。 | 1144| type |[RingtoneType](#ringtonetype) | 是 | 被设置的系统铃声的类型。 | 1145 1146**返回值：** 1147 1148| 类型 | 说明 | 1149|------------------------------------------|---------------------| 1150| Promise<[ToneAttrs](#toneattrs12)> | Promise回调返回系统铃声的属性。 | 1151 1152**错误码：** 1153 1154以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[媒体服务错误码](../apis-media-kit/errorcode-media.md)。 1155 1156| 错误码ID | 错误信息 | 1157| ------- | --------------------- | 1158| 202 | Caller is not a system application. | 1159| 401 | The parameters check failed. | 1160| 5400103 | I/O error. | 1161 1162**示例：** 1163 1164```ts 1165import { BusinessError } from '@kit.BasicServicesKit'; 1166import { common } from '@kit.AbilityKit'; 1167 1168// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext。 1169let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 1170let type: systemSoundManager.RingtoneType = systemSoundManager.RingtoneType.RINGTONE_TYPE_SIM_CARD_0; 1171 1172let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 1173systemSoundManagerInstance.getDefaultRingtoneAttrs(context, type).then((value: systemSoundManager.ToneAttrs) => { 1174 console.info(`Promise returned to indicate that the value of the attributes of the default ringtone is obtained.`); 1175}).catch ((err: BusinessError) => { 1176 console.error(`Failed to get the default ring tone attrs ${err}`); 1177}); 1178``` 1179 1180### getRingtoneAttrList<sup>12+</sup> 1181 1182getRingtoneAttrList(context: BaseContext, type: RingtoneType): Promise<ToneAttrsArray> 1183 1184获取系统铃声的属性列表，使用Promise方式异步返回结果。 1185 1186**系统接口：** 该接口为系统接口。 1187 1188**系统能力：** SystemCapability.Multimedia.SystemSound.Core 1189 1190**参数：** 1191 1192| 参数名 | 类型 | 必填 | 说明 | 1193| -------- |-------------------------------------| ---- | --------------------------- | 1194| context |[BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | 是 | 当前应用的上下文。 | 1195| type |[RingtoneType](#ringtonetype) | 是 | 被设置的系统铃声的类型。 | 1196 1197**返回值：** 1198 1199| 类型 | 说明 | 1200|----------------------------------------------------|-----------------------| 1201| Promise<[ToneAttrsArray](#toneattrsarray12)> | Promise回调返回系统铃声的属性列表。 | 1202 1203**错误码：** 1204 1205以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[媒体服务错误码](../apis-media-kit/errorcode-media.md)。 1206 1207| 错误码ID | 错误信息 | 1208| ------- | --------------------- | 1209| 202 | Caller is not a system application. | 1210| 401 | The parameters check failed. | 1211| 5400103 | I/O error. | 1212 1213**示例：** 1214 1215```ts 1216import { BusinessError } from '@kit.BasicServicesKit'; 1217import { common } from '@kit.AbilityKit'; 1218 1219// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext。 1220let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 1221let type: systemSoundManager.RingtoneType = systemSoundManager.RingtoneType.RINGTONE_TYPE_SIM_CARD_0; 1222 1223let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 1224systemSoundManagerInstance.getRingtoneAttrList(context, type).then((value: systemSoundManager.ToneAttrsArray) => { 1225 console.info(`Promise returned to indicate that the value of the attribute list of ringtone is obtained.`); 1226}).catch ((err: BusinessError) => { 1227 console.error(`Failed to get the attribute list of ringtone ${err}`); 1228}); 1229``` 1230 1231### getDefaultSystemToneAttrs<sup>12+</sup> 1232 1233getDefaultSystemToneAttrs(context: BaseContext, type: SystemToneType): Promise<ToneAttrs> 1234 1235获取系统提示音的属性，使用Promise方式异步返回结果。 1236 1237**系统接口：** 该接口为系统接口。 1238 1239**系统能力：** SystemCapability.Multimedia.SystemSound.Core 1240 1241**参数：** 1242 1243| 参数名 | 类型 | 必填 | 说明 | 1244| -------- |-----------------------------------------------------------------------------| ---- | --------------------------- | 1245| context | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | 是 | 当前应用的上下文。 | 1246| type | [SystemToneType](#systemtonetype11) | 是 | 待获取播放器的系统提示音的类型。 | 1247 1248**返回值：** 1249 1250| 类型 | 说明 | 1251|-----------------------------------------|----------------------| 1252| Promise<[ToneAttrs](#toneattrs12)> | Promise回调返回系统提示音的属性。 | 1253 1254**错误码：** 1255 1256以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[媒体服务错误码](../apis-media-kit/errorcode-media.md)。 1257 1258| 错误码ID | 错误信息 | 1259| ------- | --------------------- | 1260| 202 | Caller is not a system application. | 1261| 401 | The parameters check failed. | 1262| 5400103 | I/O error. | 1263 1264**示例：** 1265 1266```ts 1267import { BusinessError } from '@kit.BasicServicesKit'; 1268import { common } from '@kit.AbilityKit'; 1269 1270// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext。 1271let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 1272let type: systemSoundManager.SystemToneType = systemSoundManager.SystemToneType.SYSTEM_TONE_TYPE_SIM_CARD_0; 1273 1274let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 1275systemSoundManagerInstance.getDefaultSystemToneAttrs(context, type).then((value: systemSoundManager.ToneAttrs) => { 1276 console.info(`Promise returned to indicate that the value of the attributes of the system ringtone is obtained.`); 1277}).catch ((err: BusinessError) => { 1278 console.error(`Failed to get the system tone attrs ${err}`); 1279}); 1280``` 1281 1282### getSystemToneAttrList<sup>12+</sup> 1283 1284getSystemToneAttrList(context: BaseContext, type: SystemToneType): Promise<ToneAttrsArray> 1285 1286获取系统提示音的属性列表，使用Promise方式异步返回结果。 1287 1288**系统接口：** 该接口为系统接口。 1289 1290**系统能力：** SystemCapability.Multimedia.SystemSound.Core 1291 1292**参数：** 1293 1294| 参数名 | 类型 | 必填 | 说明 | 1295| -------- |-----------------------------------------------------------------------------| ---- | --------------------------- | 1296| context | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | 是 | 当前应用的上下文。 | 1297| type | [SystemToneType](#systemtonetype11) | 是 | 待获取播放器的系统提示音的类型。 | 1298 1299**返回值：** 1300 1301| 类型 | 说明 | 1302|---------------------------------------------------|------------------------| 1303| Promise<[ToneAttrsArray](#toneattrsarray12)> | Promise回调返回系统提示音的属性列表。 | 1304 1305**错误码：** 1306 1307以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[媒体服务错误码](../apis-media-kit/errorcode-media.md)。 1308 1309| 错误码ID | 错误信息 | 1310| ------- | --------------------- | 1311| 202 | Caller is not a system application. | 1312| 401 | The parameters check failed. | 1313| 5400103 | I/O error. | 1314 1315**示例：** 1316 1317```ts 1318import { BusinessError } from '@kit.BasicServicesKit'; 1319import { common } from '@kit.AbilityKit'; 1320 1321// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext。 1322let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 1323let type: systemSoundManager.SystemToneType = systemSoundManager.SystemToneType.SYSTEM_TONE_TYPE_SIM_CARD_0; 1324 1325let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 1326systemSoundManagerInstance.getSystemToneAttrList(context, type).then((value: systemSoundManager.ToneAttrsArray) => { 1327 console.info(`Promise returned to indicate that the value of the attribute list of system tone is obtained.`); 1328}).catch ((err: BusinessError) => { 1329 console.error(`Failed to get the attribute list of system tone ${err}`); 1330}); 1331``` 1332 1333### getDefaultAlarmToneAttrs<sup>12+</sup> 1334 1335getDefaultAlarmToneAttrs(context: BaseContext): Promise<ToneAttrs> 1336 1337获取系统闹铃的属性，使用Promise方式异步返回结果。 1338 1339**系统接口：** 该接口为系统接口。 1340 1341**系统能力：** SystemCapability.Multimedia.SystemSound.Core 1342 1343**参数：** 1344 1345| 参数名 | 类型 | 必填 | 说明 | 1346| --------|------------| ---- |-----------| 1347| context | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | 是 | 当前应用的上下文。 | 1348 1349**返回值：** 1350 1351| 类型 | 说明 | 1352|-----------------------------------------|---------------------| 1353| Promise<[ToneAttrs](#toneattrs12)> | Promise回调返回系统闹铃的属性。 | 1354 1355**错误码：** 1356 1357以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[媒体服务错误码](../apis-media-kit/errorcode-media.md)。 1358 1359| 错误码ID | 错误信息 | 1360| ------- | --------------------- | 1361| 202 | Caller is not a system application. | 1362| 401 | The parameters check failed. | 1363| 5400103 | I/O error. | 1364 1365**示例：** 1366 1367```ts 1368import { BusinessError } from '@kit.BasicServicesKit'; 1369import { common } from '@kit.AbilityKit'; 1370 1371// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext。 1372let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 1373 1374let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 1375systemSoundManagerInstance.getDefaultAlarmToneAttrs(context).then((value: systemSoundManager.ToneAttrs) => { 1376 console.info(`Promise returned to indicate that the value of the attributes of the default alarm tone is obtained.`); 1377}).catch ((err: BusinessError) => { 1378 console.error(`Failed to get the default alarm tone attrs ${err}`); 1379}); 1380``` 1381 1382### setAlarmToneUri<sup>12+</sup> 1383 1384setAlarmToneUri(context: Context, uri: string): Promise<void> 1385 1386设置系统闹铃uri，使用Promise方式异步返回结果。 1387 1388**系统接口：** 该接口为系统接口。 1389 1390**系统能力：** SystemCapability.Multimedia.SystemSound.Core 1391 1392**参数：** 1393 1394| 参数名 | 类型 | 必填 | 说明 | 1395| -------- | --------- | ---- |--------------------------| 1396| context | [Context](../apis-ability-kit/js-apis-inner-application-context.md) | 是 | 当前应用的上下文。 | 1397| uri | string | 是 | 被设置的系统闹铃的uri，资源支持可参考[media.AVPlayer](../apis-media-kit/js-apis-media.md#avplayer9)。 | 1398 1399**返回值：** 1400 1401| 类型 | 说明 | 1402| ------------------- |----------------------| 1403| Promise<void> | Promise回调返回设置成功或失败。 | 1404 1405**示例：** 1406 1407```ts 1408import { BusinessError } from '@kit.BasicServicesKit'; 1409import { common } from '@kit.AbilityKit'; 1410 1411// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext。 1412let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 1413let uri = 'file://data/test.wav'; // 需更改为目标铃声文件的uri。 1414 1415let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 1416systemSoundManagerInstance.setAlarmToneUri(context, uri).then(() => { 1417 console.info(`Promise returned to indicate a successful setting of the alarm tone uri.`); 1418}).catch ((err: BusinessError) => { 1419 console.error(`Failed to set the alarm tone uri ${err}`); 1420}); 1421``` 1422 1423### getAlarmToneUri<sup>12+</sup> 1424 1425getAlarmToneUri(context: Context): Promise<string> 1426 1427获取系统当前闹铃uri，使用Promise方式异步返回结果。 1428 1429**系统接口：** 该接口为系统接口。 1430 1431**系统能力：** SystemCapability.Multimedia.SystemSound.Core 1432 1433**参数：** 1434 1435| 参数名 | 类型 | 必填 | 说明 | 1436| -------- | --------| ---- |-----------------| 1437| context | [Context](../apis-ability-kit/js-apis-inner-application-context.md) | 是 | 当前应用的上下文。 | 1438 1439**返回值：** 1440 1441| 类型 | 说明 | 1442|-----------------------|-----------------------| 1443| Promise<string> | Promise回调返回系统当前闹铃uri。 | 1444 1445**示例：** 1446 1447```ts 1448import { BusinessError } from '@kit.BasicServicesKit'; 1449import { common } from '@kit.AbilityKit'; 1450 1451// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext。 1452let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 1453 1454let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 1455systemSoundManagerInstance.getAlarmToneUri(context).then((value: string) => { 1456 console.info(`Promise returned to indicate that the value of alarm tone uri.`); 1457}).catch ((err: BusinessError) => { 1458 console.error(`Failed to get the alarm tone uri ${err}`); 1459}); 1460``` 1461 1462### getAlarmToneAttrList<sup>12+</sup> 1463 1464getAlarmToneAttrList(context: BaseContext): Promise<ToneAttrsArray> 1465 1466获取全部闹铃属性列表，使用Promise方式异步返回结果。 1467 1468**系统接口：** 该接口为系统接口。 1469 1470**系统能力：** SystemCapability.Multimedia.SystemSound.Core 1471 1472**参数：** 1473 1474| 参数名 | 类型 | 必填 | 说明 | 1475| -------- |--------------| ---- | --------------------------- | 1476| context | [BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md) | 是 | 当前应用的上下文。 | 1477 1478**返回值：** 1479 1480| 类型 | 说明 | 1481|----------------------------------------------------|----------------------| 1482| Promise<[ToneAttrsArray](#toneattrsarray12)> | Promise回调返回全部闹铃属性列表。 | 1483 1484**错误码：** 1485 1486以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[媒体服务错误码](../apis-media-kit/errorcode-media.md)。 1487 1488| 错误码ID | 错误信息 | 1489| ------- | --------------------- | 1490| 202 | Caller is not a system application. | 1491| 401 | The parameters check failed. | 1492| 5400103 | I/O error. | 1493 1494**示例：** 1495 1496```ts 1497import { BusinessError } from '@kit.BasicServicesKit'; 1498import { common } from '@kit.AbilityKit'; 1499 1500// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext。 1501let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 1502 1503let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 1504systemSoundManagerInstance.getAlarmToneAttrList(context).then((value: systemSoundManager.ToneAttrsArray) => { 1505 console.info(`Promise returned to indicate that the value of the attribute list of alarm tone is obtained.`); 1506}).catch ((err: BusinessError) => { 1507 console.error(`Failed to get the attribute list of alarm tone ${err}`); 1508}); 1509``` 1510 1511### openAlarmTone<sup>12+</sup> 1512 1513openAlarmTone(context: Context, uri: string): Promise<number> 1514 1515打开闹铃文件，使用Promise方式异步返回结果。 1516 1517**系统接口：** 该接口为系统接口。 1518 1519**系统能力：** SystemCapability.Multimedia.SystemSound.Core 1520 1521**参数：** 1522 1523| 参数名 | 类型 | 必填 | 说明 | 1524| -------- | ---------| ---- |-------------------------------------------------------------------------------------| 1525| context | [Context](../apis-ability-kit/js-apis-inner-application-context.md) | 是 | 当前应用的上下文。 | 1526| uri | string | 是 | 被设置的系统闹铃的uri，资源支持可参考[media.AVPlayer](../apis-media-kit/js-apis-media.md#avplayer9)。 | 1527 1528**返回值：** 1529 1530| 类型 | 说明 | 1531|-----------------------|----------------| 1532| Promise<number> | Promise回调返回fd。 | 1533 1534**错误码：** 1535 1536以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[媒体服务错误码](../apis-media-kit/errorcode-media.md)。 1537 1538| 错误码ID | 错误信息 | 1539| ------- | --------------------- | 1540| 202 | Caller is not a system application. | 1541| 401 | The parameters check failed. | 1542| 5400103 | I/O error. | 1543| 20700001 | Tone type mismatch, e.g. tone of uri is notification instead of alarm. | 1544 1545**示例：** 1546 1547```ts 1548import { BusinessError } from '@kit.BasicServicesKit'; 1549import { common } from '@kit.AbilityKit'; 1550 1551// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext。 1552let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 1553let uri = 'file://data/test.wav'; // 需更改为目标铃声文件的uri。 1554 1555let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 1556systemSoundManagerInstance.openAlarmTone(context, uri).then((value: number) => { 1557 console.info(`Promise returned to indicate the value of fd.`); 1558}).catch ((err: BusinessError) => { 1559 console.error(`Failed to open alarm tone ${err}`); 1560}); 1561``` 1562 1563### close<sup>12+</sup> 1564 1565close(fd: number): Promise<void> 1566 1567关闭闹铃文件，使用Promise方式异步返回结果。 1568 1569**系统接口：** 该接口为系统接口 1570 1571**系统能力：** SystemCapability.Multimedia.SystemSound.Core 1572 1573**参数：** 1574 1575| 参数名 | 类型 | 必填 | 说明 | 1576|-----| --------| ---- |----------------------------------------------| 1577| fd | number | 是 | 文件描述符，通过[openAlarmTone](#openalarmtone12)获取。 | 1578 1579**返回值：** 1580 1581| 类型 | 说明 | 1582|---------------------|----------------| 1583| Promise<void> | Promise回调返回设置成功或失败。 | 1584 1585**错误码：** 1586 1587以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[媒体服务错误码](../apis-media-kit/errorcode-media.md)。 1588 1589| 错误码ID | 错误信息 | 1590| ------- | --------------------- | 1591| 202 | Caller is not a system application. | 1592| 401 | The parameters check failed. | 1593| 5400103 | I/O error. | 1594 1595**示例：** 1596 1597```ts 1598import { BusinessError } from '@kit.BasicServicesKit'; 1599import { common } from '@kit.AbilityKit'; 1600 1601// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext。 1602let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 1603let fd = 50; // 需更改为目标铃声的fd。 1604 1605let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 1606systemSoundManagerInstance.close(fd).then(() => { 1607 console.info(`Promise returned to indicate that the fd has been close.`); 1608}).catch ((err: BusinessError) => { 1609 console.error(`Failed to close fd ${err}`); 1610}); 1611``` 1612 1613### addCustomizedTone<sup>12+</sup> 1614 1615addCustomizedTone(context: BaseContext, toneAttr: ToneAttrs, externalUri: string): Promise<string> 1616 1617通过铃音uri将自定义铃音添加到铃音库，使用Promise方式异步返回结果。 1618 1619**系统接口：** 该接口为系统接口。 1620 1621**系统能力：** SystemCapability.Multimedia.SystemSound.Core 1622 1623**参数：** 1624 1625| 参数名 | 类型 | 必填 | 说明 | 1626|-----|-----------| ---- |---------------| 1627| context | [Context](../apis-ability-kit/js-apis-inner-application-context.md) | 是 | 当前应用的上下文。 | 1628| toneAttr | ToneAttrs | 是 | 铃音属性。 | 1629| externalUri | string | 是 | 外部存储器中的铃音uri。 | 1630 1631**返回值：** 1632 1633| 类型 | 说明 | 1634|-----------------------|-------------------------| 1635| Promise<string> | Promise回调返回铃音在铃音库中的uri。 | 1636 1637**错误码：** 1638 1639以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[媒体服务错误码](../apis-media-kit/errorcode-media.md)。 1640 1641| 错误码ID | 错误信息 | 1642|---------| -------------------- | 1643| 201 | Permission denied. | 1644| 202 | Caller is not a system application. | 1645| 401 | The parameters check failed. | 1646| 5400102 | Operation is not allowed, e.g. ringtone to add is not customized. | 1647| 5400103 | I/O error. | 1648 1649**示例：** 1650 1651```ts 1652import { BusinessError } from '@kit.BasicServicesKit'; 1653import { common } from '@kit.AbilityKit'; 1654 1655// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext。 1656let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 1657let title = 'test'; // 需更改为实际名称。 1658let fileName = 'displayName_test'; // 需更改为实际文件名。 1659let categoryValue = systemSoundManager.TONE_CATEGORY_ALARM; 1660 1661let toneAttrs = systemSoundManager.createCustomizedToneAttrs(); 1662toneAttrs.setTitle(title); 1663toneAttrs.setFileName(fileName); 1664toneAttrs.setCategory(categoryValue); 1665 1666let path = 'file://data/test.ogg'; // 需更改为实际铃音uri。 1667 1668let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 1669systemSoundManagerInstance.addCustomizedTone(context, toneAttrs, path).then((value: string) => { 1670 console.info(`Promise returned to indicate that the value of tone uri in ringtone library.`); 1671}).catch ((err: BusinessError) => { 1672 console.error(`Failed to add customized tone ${err}`); 1673}); 1674``` 1675 1676### addCustomizedTone<sup>12+</sup> 1677 1678addCustomizedTone(context: BaseContext, toneAttr: ToneAttrs, fd: number, offset?: number, length?: number): Promise<string> 1679 1680通过文件描述符fd将自定义铃音添加到铃音库，使用Promise方式异步返回结果。 1681 1682**系统接口：** 该接口为系统接口。 1683 1684**系统能力：** SystemCapability.Multimedia.SystemSound.Core 1685 1686**参数：** 1687 1688| 参数名 | 类型 | 必填 | 说明 | 1689|-----|-----------|----|------------------------------------------------------------------------| 1690| context | [Context](../apis-ability-kit/js-apis-inner-application-context.md) | 是 | 当前应用的上下文。 | 1691| toneAttr | [ToneAttrs](#toneattrs12) | 是 | 铃音属性。 | 1692| fd | number | 是 | 文件描述符，可通过[fs.open](../apis-core-file-kit/js-apis-file-fs.md#fsopen)获取。 | 1693| offset | number | 否 | 读取数据的偏移量（以字节为单位）。默认情况下为0。 | 1694| length | number | 否 | 读取的数据的长度（以字节为单位）。默认情况下，长度为偏移后的剩余全部字节数。 | 1695 1696**返回值：** 1697 1698| 类型 | 说明 | 1699|-----------------------|-------------------------| 1700| Promise<string> | Promise回调返回铃音在铃音库中的uri。 | 1701 1702**错误码：** 1703 1704以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[媒体服务错误码](../apis-media-kit/errorcode-media.md)。 1705 1706| 错误码ID | 错误信息 | 1707|---------| -------------------- | 1708| 201 | Permission denied. | 1709| 202 | Caller is not a system application. | 1710| 401 | The parameters check failed. | 1711| 5400102 | Operation is not allowed, e.g. ringtone to add is not customized. | 1712| 5400103 | I/O error. | 1713 1714**示例：** 1715 1716```ts 1717import { BusinessError } from '@kit.BasicServicesKit'; 1718import { common } from '@kit.AbilityKit'; 1719 1720// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext。 1721let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 1722let title = 'test'; // 需更改为实际名称。 1723let fileName = 'displayName_test'; // 需更改为实际文件名。 1724let categoryValue = systemSoundManager.TONE_CATEGORY_ALARM; 1725 1726let toneAttrs = systemSoundManager.createCustomizedToneAttrs(); 1727toneAttrs.setTitle(title); 1728toneAttrs.setFileName(fileName); 1729toneAttrs.setCategory(categoryValue); 1730 1731let fd = 10; // 需更改为实际铃音fd。 1732let offset = 0; // 需更改为实际所需偏移量。 1733let length = 50; // 需更改为实际所需数据长度。 1734 1735let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 1736systemSoundManagerInstance.addCustomizedTone(context, toneAttrs, fd, offset, length).then((value: string) => { 1737 console.info(`Promise returned to indicate that the value of tone uri in ringtone library.`); 1738}).catch ((err: BusinessError) => { 1739 console.error(`Failed to add customized tone ${err}`); 1740}); 1741``` 1742 1743### removeCustomizedTone<sup>12+</sup> 1744 1745removeCustomizedTone(context: BaseContext, uri: string): Promise<void> 1746 1747从铃音库中删除自定义铃音，使用Promise方式异步返回结果。 1748 1749**系统接口：** 该接口为系统接口。 1750 1751**系统能力：** SystemCapability.Multimedia.SystemSound.Core 1752 1753**参数：** 1754 1755| 参数名 | 类型 | 必填 | 说明 | 1756|-----|-----------| ---- |---------------------------------------------------------------------------------------------------------| 1757| context | [Context](../apis-ability-kit/js-apis-inner-application-context.md) | 是 | 当前应用的上下文。 | 1758| uri | string | 是 | 铃音uri，可通过[addCustomizedTone](#addcustomizedtone12)或[getAlarmToneAttrList](#getalarmtoneattrlist12)等方法获取。 | 1759 1760**返回值：** 1761 1762| 类型 | 说明 | 1763|---------------------|-----------------------| 1764| Promise<void> | Promise回调返回设置成功或失败。 | 1765 1766**错误码：** 1767 1768以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[媒体服务错误码](../apis-media-kit/errorcode-media.md)。 1769 1770| 错误码ID | 错误信息 | 1771|---------| -------------------- | 1772| 201 | Permission denied. | 1773| 202 | Caller is not a system application. | 1774| 401 | The parameters check failed. | 1775| 5400102 | Operation is not allowed, e.g. ringtone to add is not customized. | 1776| 5400103 | I/O error. | 1777 1778**示例：** 1779 1780```ts 1781import { BusinessError } from '@kit.BasicServicesKit'; 1782import { common } from '@kit.AbilityKit'; 1783 1784// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext。 1785let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 1786let uri = 'file://data/test.wav'; // 需更改为目标铃声文件的uri。 1787 1788let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 1789systemSoundManagerInstance.removeCustomizedTone(context, uri).then(() => { 1790 console.info(`Promise returned to indicate that the customized tone has been deleted.`); 1791}).catch ((err: BusinessError) => { 1792 console.error(`Failed to delete customized tone ${err}`); 1793}); 1794``` 1795 1796### getToneHapticsSettings<sup>14+</sup> 1797 1798getToneHapticsSettings(context: BaseContext, type: ToneHapticsType): Promise<ToneHapticsSettings> 1799 1800获取系统铃音的振动设置，使用Promise方式异步返回结果。 1801 1802**系统接口：** 该接口为系统接口。 1803 1804**系统能力：** SystemCapability.Multimedia.SystemSound.Core 1805 1806**参数：** 1807 1808| 参数名 | 类型 | 必填 | 说明 | 1809|-----|-----------| ---- |----------------------------------------------------------------------------------| 1810| context | [Context](../apis-ability-kit/js-apis-inner-application-context.md) | 是 | 当前应用的上下文。 | 1811| type | [ToneHapticsType](#tonehapticstype14) | 是 | 待获取系统铃音的振动类型。 | 1812 1813**返回值：** 1814 1815| 类型 | 说明 | 1816|---------------------|-----------------------| 1817| Promise<[ToneHapticsSettings](#tonehapticssettings14)> | Promise回调返回铃声的振动设置。 | 1818 1819**错误码：** 1820 1821以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[媒体服务错误码](../apis-media-kit/errorcode-media.md)。 1822 1823| 错误码ID | 错误信息 | 1824|---------| -------------------- | 1825| 202 | Caller is not a system application. | 1826| 401 | The parameters check failed. | 1827| 5400103 | I/O error. | 1828| 20700003 | Unsupported operation. | 1829 1830**示例：** 1831 1832```ts 1833import { BusinessError } from '@kit.BasicServicesKit'; 1834import { common } from '@kit.AbilityKit'; 1835 1836// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext。 1837let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 1838let type: systemSoundManager.ToneHapticsType = systemSoundManager.ToneHapticsType.CALL_SIM_CARD_0; 1839 1840let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 1841systemSoundManagerInstance.getToneHapticsSettings(context, type).then((value: systemSoundManager.ToneHapticsSettings) => { 1842 console.info(`Promise returned to indicate that the value of the tone haptics settings is obtained.`); 1843}).catch ((err: BusinessError) => { 1844 console.error(`Failed to get the tone haptics settings ${err}`); 1845}); 1846``` 1847 1848### setToneHapticsSettings<sup>14+</sup> 1849 1850setToneHapticsSettings(context: BaseContext, type: ToneHapticsType, settings: ToneHapticsSettings): Promise<void> 1851 1852设置系统铃音的振动，使用Promise方式异步返回结果。 1853 1854**系统接口：** 该接口为系统接口。 1855 1856**系统能力：** SystemCapability.Multimedia.SystemSound.Core 1857 1858**参数：** 1859 1860| 参数名 | 类型 | 必填 | 说明 | 1861|-----|-----------| ---- |----------------------------------------------------------------------------------| 1862| context | [Context](../apis-ability-kit/js-apis-inner-application-context.md) | 是 | 当前应用的上下文。 | 1863| type | [ToneHapticsType](#tonehapticstype14) | 是 | 被设置的系统铃音的振动类型。 | 1864| settings | [ToneHapticsSettings](#tonehapticssettings14) | 是 | 被设置的系统铃音的振动设置。 | 1865 1866**返回值：** 1867 1868| 类型 | 说明 | 1869|---------------------|-----------------------| 1870| Promise<void> | Promise回调返回设置成功或失败。 | 1871 1872**错误码：** 1873 1874以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[媒体服务错误码](../apis-media-kit/errorcode-media.md)。 1875 1876| 错误码ID | 错误信息 | 1877|---------| -------------------- | 1878| 202 | Caller is not a system application. | 1879| 401 | The parameters check failed. | 1880| 5400102 | Operation is not allowed, e.g. ringtone to add is not customized. | 1881| 5400103 | I/O error. | 1882| 20700003 | Unsupported operation. | 1883 1884**示例：** 1885 1886```ts 1887import { BusinessError } from '@kit.BasicServicesKit'; 1888import { common } from '@kit.AbilityKit'; 1889 1890// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext。 1891let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 1892let type: systemSoundManager.ToneHapticsType = systemSoundManager.ToneHapticsType.CALL_SIM_CARD_0; 1893let toneHapticsSettings: systemSoundManager.ToneHapticsSettings = { 1894 mode: systemSoundManager.ToneHapticsMode.NON_SYNC, 1895 hapticsUri: '/data/storage/el2/base/haptics/synchronized/alarms/test.json', // 需更改为通过getToneHapticsList获取的Uri。 1896} 1897 1898let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 1899systemSoundManagerInstance.setToneHapticsSettings(context, type, toneHapticsSettings).then(() => { 1900 console.info(`Promise returned to indicate a successful setting of the tone haptics.`); 1901}).catch ((err: BusinessError) => { 1902 console.error(`Failed to set the tone haptics settings ${err}`); 1903}); 1904``` 1905 1906### getToneHapticsList<sup>14+</sup> 1907 1908getToneHapticsList(context: BaseContext, isSynced: boolean): Promise<ToneHapticsAttrsArray> 1909 1910获取同步或者非同步的系统铃音的振动属性列表，使用Promise方式异步返回结果。 1911 1912**系统接口：** 该接口为系统接口。 1913 1914**系统能力：** SystemCapability.Multimedia.SystemSound.Core 1915 1916**参数：** 1917 1918| 参数名 | 类型 | 必填 | 说明 | 1919|-----|-----------| ---- |----------------------------------------------------------------------------------| 1920| context | [Context](../apis-ability-kit/js-apis-inner-application-context.md) | 是 | 当前应用的上下文。 | 1921| isSynced | boolean | 是 | 待获取的振动是否与某个铃音同步。 | 1922 1923**返回值：** 1924 1925| 类型 | 说明 | 1926|---------------------|-----------------------| 1927| Promise<[ToneHapticsAttrsArray](#tonehapticsattrsarray14)> | Promise回调返回同步或者非同步的系统铃音的振动属性列表。 | 1928 1929**错误码：** 1930 1931以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[媒体服务错误码](../apis-media-kit/errorcode-media.md)。 1932 1933| 错误码ID | 错误信息 | 1934|---------| -------------------- | 1935| 202 | Caller is not a system application. | 1936| 401 | The parameters check failed. | 1937| 5400103 | I/O error. | 1938| 20700003 | Unsupported operation. | 1939 1940**示例：** 1941 1942```ts 1943import { BusinessError } from '@kit.BasicServicesKit'; 1944import { common } from '@kit.AbilityKit'; 1945 1946// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext。 1947let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 1948 1949let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 1950systemSoundManagerInstance.getToneHapticsList(context, false).then((value: systemSoundManager.ToneHapticsAttrsArray) => { 1951 console.info(`Promise returned to indicate that the value of the attribute list of tone haptics is obtained.`); 1952}).catch ((err: BusinessError) => { 1953 console.error(`Failed to get the attribute list of tone haptics ${err}`); 1954}); 1955``` 1956 1957### getHapticsAttrsSyncedWithTone<sup>14+</sup> 1958 1959getHapticsAttrsSyncedWithTone(context: BaseContext, toneUri: string): Promise<ToneHapticsAttrs> 1960 1961获取与指定铃音同步的振动属性，使用Promise方式异步返回结果。 1962 1963**系统接口：** 该接口为系统接口。 1964 1965**系统能力：** SystemCapability.Multimedia.SystemSound.Core 1966 1967**参数：** 1968 1969| 参数名 | 类型 | 必填 | 说明 | 1970|-----|-----------| ---- |----------------------------------------------------------------------------------| 1971| context | [Context](../apis-ability-kit/js-apis-inner-application-context.md) | 是 | 当前应用的上下文。 | 1972| toneUri | string | 是 | 待获取同步振动的系统铃声Uri,可通过[getRingtoneAttrList](#getringtoneattrlist12)或[getSystemToneAttrList](#getsystemtoneattrlist12)等获取。 | 1973 1974**返回值：** 1975 1976| 类型 | 说明 | 1977|---------------------|-----------------------| 1978| Promise<[ToneHapticsAttrs](#tonehapticsattrs14)> | Promise回调返回与指定铃音同步的振动属性。 | 1979 1980**错误码：** 1981 1982以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[媒体服务错误码](../apis-media-kit/errorcode-media.md)。 1983 1984| 错误码ID | 错误信息 | 1985|---------| -------------------- | 1986| 202 | Caller is not a system application. | 1987| 401 | The parameters check failed. | 1988| 5400102 | Operation is not allowed, e.g. ringtone to add is not customized. | 1989| 5400103 | I/O error. | 1990| 20700003 | Unsupported operation. | 1991 1992**示例：** 1993 1994```ts 1995import { BusinessError } from '@kit.BasicServicesKit'; 1996import { common } from '@kit.AbilityKit'; 1997 1998// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext。 1999let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 2000let toneUri: string = '/data/storage/el2/base/RingTone/alarms/test.ogg'; // 需更改为实际铃音uri。 2001 2002let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 2003systemSoundManagerInstance.getHapticsAttrsSyncedWithTone(context, toneUri).then((value: systemSoundManager.ToneHapticsAttrs) => { 2004 console.info(`Promise returned to indicate that the value of the attribute of tone haptics is obtained.`); 2005}).catch ((err: BusinessError) => { 2006 console.error(`Failed to get the attribute of tone haptics ${err}`); 2007}); 2008``` 2009 2010### openToneHaptics<sup>14+</sup> 2011 2012openToneHaptics(context: Context, hapticsUri: string): Promise<number> 2013 2014打开系统铃音的振动，使用Promise方式异步返回结果。 2015 2016**系统接口：** 该接口为系统接口。 2017 2018**系统能力：** SystemCapability.Multimedia.SystemSound.Core 2019 2020**参数：** 2021 2022| 参数名 | 类型 | 必填 | 说明 | 2023| -------- | ---------| ---- |-------------------------------------------------------------------------------------| 2024| context | [Context](../apis-ability-kit/js-apis-inner-application-context.md) | 是 | 当前应用的上下文。 | 2025| hapticsUri | string | 是 | 待打开系统铃音的振动的uri，资源支持可参考[media.AVPlayer](../apis-media-kit/js-apis-media.md#avplayer9)。 | 2026 2027**返回值：** 2028 2029| 类型 | 说明 | 2030|-----------------------|----------------| 2031| Promise<number> | Promise回调返回fd。 | 2032 2033**错误码：** 2034 2035以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[媒体服务错误码](../apis-media-kit/errorcode-media.md)。 2036 2037| 错误码ID | 错误信息 | 2038| ------- | --------------------- | 2039| 202 | Caller is not a system application. | 2040| 401 | The parameters check failed. | 2041| 5400102 | Operation is not allowed, e.g. ringtone to add is not customized. | 2042| 5400103 | I/O error. | 2043| 20700003 | Unsupported operation. | 2044 2045**示例：** 2046 2047```ts 2048import { BusinessError } from '@kit.BasicServicesKit'; 2049import { common } from '@kit.AbilityKit'; 2050 2051// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext。 2052let context = this.getUIContext().getHostContext() as common.UIAbilityContext; 2053let hapticsUri = '/data/storage/el2/base/haptics/synchronized/alarms/test.json'; // 需更改为目标统铃音的振动的uri。 2054 2055let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager(); 2056systemSoundManagerInstance.openToneHaptics(context, hapticsUri).then((value: number) => { 2057 console.info(`Promise returned to indicate the value of fd.`); 2058}).catch ((err: BusinessError) => { 2059 console.error(`Failed to open haptics ${err}`); 2060}); 2061``` 2062 2063## RingtonePlayer<sup>10+</sup> 2064 2065type RingtonePlayer = _RingtonePlayer; 2066 2067系统铃音播放器对象。 2068 2069**系统能力：** SystemCapability.Multimedia.SystemSound.Core 2070 2071| 类型 |说明 | 2072|-----------------|-------| 2073| _RingtonePlayer | 系统铃音播放器。 | 2074 2075## SystemTonePlayer<sup>11+</sup> 2076 2077type SystemTonePlayer = _SystemTonePlayer; 2078 2079系统提示音播放器对象。 2080 2081**系统能力：** SystemCapability.Multimedia.SystemSound.Core 2082 2083| 类型 | 说明 | 2084|-----------------|-----------| 2085| _SystemTonePlayer | 系统提示音播放器。 | 2086 2087## RingtoneOptions<sup>10+</sup> 2088 2089type RingtoneOptions = _RingtoneOptions; 2090 2091系统铃音播放器配置项。 2092 2093**系统能力：** SystemCapability.Multimedia.SystemSound.Core 2094 2095| 类型 | 说明 | 2096|-----------------|-------------| 2097| _RingtoneOptions | 系统铃音播放器配置项。 | 2098 2099## SystemToneOptions<sup>11+</sup> 2100 2101type SystemToneOptions = _SystemToneOptions; 2102 2103系统提示音播放器配置项。 2104 2105**系统能力：** SystemCapability.Multimedia.SystemSound.Core 2106 2107| 类型 | 说明 | 2108|-----------------|---------------| 2109| _SystemToneOptions | 系统提示音音播放器配置项。 | 2110 2111 2112 2113