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