@ohos.multimedia.systemSoundManager (系统声音管理)(系统接口)

系统声音管理提供管理系统声音的一些基础能力，包括对系统铃声的资源设置与读取、获取系统铃声播放器等。

说明：

• 本模块首批接口从API version 10开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
• 本模块接口为系统接口。

导入模块

import { systemSoundManager } from '@kit.AudioKit';

常量

系统接口： 该接口为系统接口。

系统能力： SystemCapability.Multimedia.SystemSound.Core

名称	值	说明
TONE_CATEGORY_RINGTONE12+	1	铃声类别。
TONE_CATEGORY_TEXT_MESSAGE12+	2	短信铃声类别。
TONE_CATEGORY_NOTIFICATION12+	4	通知铃声类别。
TONE_CATEGORY_ALARM12+	8	闹钟铃声类别。

RingtoneType

枚举，铃声类型。

系统接口： 该接口为系统接口。

系统能力： SystemCapability.Multimedia.SystemSound.Core

名称	值	说明
RINGTONE_TYPE_DEFAULT(deprecated)	0	默认铃声类型。 从 API version 11 开始废弃。建议使用该枚举中的RINGTONE_TYPE_SIM_CARD_0替代。
RINGTONE_TYPE_SIM_CARD_011+	0	sim卡1的铃声。
RINGTONE_TYPE_MULTISIM(deprecated)	1	多SIM卡铃声类型。 从 API version 11 开始废弃。建议使用该枚举中的RINGTONE_TYPE_SIM_CARD_1替代。
RINGTONE_TYPE_SIM_CARD_111+	1	sim卡2的铃声。

SystemToneType¹¹⁺

枚举，系统铃声类型。

系统接口： 该接口为系统接口。

系统能力： SystemCapability.Multimedia.SystemSound.Core

名称	值	说明
SYSTEM_TONE_TYPE_SIM_CARD_0	0	sim卡1的短信提示音。
SYSTEM_TONE_TYPE_SIM_CARD_1	1	sim卡2的短信提示音。
SYSTEM_TONE_TYPE_NOTIFICATION	32	通知提示音。

ToneCustomizedType¹²⁺

枚举，铃声自定义类型。

系统接口： 该接口为系统接口。

系统能力： SystemCapability.Multimedia.SystemSound.Core

名称	值	说明
PRE_INSTALLED12+	0	预安装铃声类型。
CUSTOMIZED12+	1	自定义铃声类型。

ToneAttrs¹²⁺

管理铃声属性。在调用ToneAttrs¹²⁺的接口前，需要先通过createCustomizedToneAttrs或getDefaultRingtoneAttrs、getRingtoneAttrList等方法获取实例。

getTitle¹²⁺

getTitle(): string

获取铃声标题。

系统接口： 该接口为系统接口。

系统能力： SystemCapability.Multimedia.SystemSound.Core

返回值：

类型	说明
string	标题。

错误码：

错误码ID	错误信息
202	Caller is not a system application.

示例：

toneAttrs.getTitle();

setTitle¹²⁺

setTitle(title: string): void

设置铃声标题。

系统接口： 该接口为系统接口。

系统能力： SystemCapability.Multimedia.SystemSound.Core

参数：

参数名	类型	必填	说明
title	string	是	铃声的标题。

错误码：

错误码ID	错误信息
202	Caller is not a system application.
401	The parameters check failed.

示例：

let toneAttrs = systemSoundManager.createCustomizedToneAttrs();
let title = 'text';
toneAttrs.setTitle(title);

getFileName¹²⁺

getFileName(): string

获取铃声文件名。

系统接口： 该接口为系统接口。

系统能力： SystemCapability.Multimedia.SystemSound.Core

返回值：

类型	说明
string	文件名。

错误码：

错误码ID	错误信息
202	Caller is not a system application.

示例：

toneAttrs.getFileName();

setFileName¹²⁺

setFileName(name: string): void

设置铃声文件名。

系统接口： 该接口为系统接口。

系统能力： SystemCapability.Multimedia.SystemSound.Core

参数：

参数名	类型	必填	说明
name	string	是	铃声的文件名。

错误码：

错误码ID	错误信息
202	Caller is not a system application.
401	The parameters check failed.

示例：

let toneAttrs = systemSoundManager.createCustomizedToneAttrs();
let fileName = 'textFileName';
toneAttrs.setFileName(fileName);

getUri¹²⁺

getUri(): string

获取铃声资源路径。

系统接口： 该接口为系统接口。

系统能力： SystemCapability.Multimedia.SystemSound.Core

返回值：

类型	说明
string	uri（如：'/data/storage/el2/base/RingTone/alarms/test.ogg'）。

错误码：

错误码ID	错误信息
202	Caller is not a system application.

示例：

toneAttrs.getUri();

getCustomizedType¹²⁺

getCustomizedType(): string

获取铃声自定义类型。

系统接口： 该接口为系统接口。

系统能力： SystemCapability.Multimedia.SystemSound.Core

返回值：

类型	说明
ToneCustomizedType	定制铃音类型。

错误码：

错误码ID	错误信息
202	Caller is not a system application.

示例：

toneAttrs.getCustomizedType();

setCategory¹²⁺

setCategory(category: number): void

设置铃声类别。

系统接口： 该接口为系统接口。

系统能力： SystemCapability.Multimedia.SystemSound.Core

参数：

参数名	类型	必填	说明
category	number	是	铃声类别，取值参考铃声类别的常量。

错误码：

错误码ID	错误信息
202	Caller is not a system application.
401	The parameters check failed.

示例：

let toneAttrs = systemSoundManager.createCustomizedToneAttrs();
let categoryValue = systemSoundManager.TONE_CATEGORY_ALARM; // 需更改为实际所需类型常量。
toneAttrs.setCategory(categoryValue);

getCategory¹²⁺

getCategory(): string

获取铃声类别。

系统接口： 该接口为系统接口。

系统能力： SystemCapability.Multimedia.SystemSound.Core

返回值：

类型	说明
number	铃声类别，取值参考铃声类别的常量。

错误码：

错误码ID	错误信息
202	Caller is not a system application.

示例：

toneAttrs.getCategory();

ToneAttrsArray¹²⁺

type ToneAttrsArray = Array<ToneAttrs>

铃音属性数组。

系统能力： SystemCapability.Multimedia.SystemSound.Core

类型	说明
Array<ToneAttrs>	铃音属性数组。

systemSoundManager.createCustomizedToneAttrs¹²⁺

createCustomizedToneAttrs(): ToneAttrs

创建自定义铃声属性。

系统接口： 该接口为系统接口。

系统能力： SystemCapability.Multimedia.SystemSound.Core

返回值：

类型	说明
ToneAttrs	铃声属性类。

错误码：

以下错误码的详细介绍请参见媒体服务错误码。

错误码ID	错误信息
202	Caller is not a system application.

示例：

let toneAttrs: systemSoundManager.ToneAttrs = systemSoundManager.createCustomizedToneAttrs();

ToneHapticsFeature¹³⁺

枚举，系统振动风格定义。

系统接口： 该接口为系统接口。

系统能力： SystemCapability.Multimedia.SystemSound.Core

名称	值	说明
STANDARD	0	标准振动风格。
GENTLE	1	轻柔振动风格。

ToneHapticsType¹⁴⁺

枚举，系统铃音的振动类型。

系统接口： 该接口为系统接口。

系统能力： SystemCapability.Multimedia.SystemSound.Core

名称	值	说明
CALL_SIM_CARD_0	0	sim卡1的来电铃声的振动。
CALL_SIM_CARD_1	1	sim卡2的来电铃声的振动。
TEXT_MESSAGE_SIM_CARD_0	20	sim卡1的短信提示音的振动。
TEXT_MESSAGE_SIM_CARD_1	21	sim卡2的短信提示音的振动。
NOTIFICATION	40	通知提示音的振动。

ToneHapticsMode¹⁴⁺

枚举，系统铃音场景的振动模式。

系统接口： 该接口为系统接口。

系统能力： SystemCapability.Multimedia.SystemSound.Core

名称	值	说明
NONE	0	无振动模式。
SYNC	1	与铃音同步模式。
NON_SYNC	2	非同步模式。

ToneHapticsSettings¹⁴⁺

系统铃音的振动设置。

系统接口： 该接口为系统接口。

系统能力： SystemCapability.Multimedia.SystemSound.Core

名称	类型	只读	可选	说明
mode	ToneHapticsMode	否	否	系统铃音的振动模式。
hapticsUri	string	否	是	系统铃音的振动路径，当振动模式不是非同步振动应该被忽略，振动的路径可通过getToneHapticsList获取。

ToneHapticsAttrs¹⁴⁺

系统铃音的振动属性。在调用ToneHapticsAttrs¹⁴⁺的接口前，需要先通过getToneHapticsList或getHapticsAttrsSyncedWithTone方法获取实例。

getUri¹⁴⁺

getUri(): string

获取振动资源路径。

系统接口： 该接口为系统接口。

系统能力： SystemCapability.Multimedia.SystemSound.Core

返回值：

类型	说明
string	uri（如：'/data/storage/el2/base/haptics/synchronized/alarms/test.json'）。

错误码：

错误码ID	错误信息
202	Caller is not a system application.

示例：

toneHapticsAttrs.getUri();

getTitle¹⁴⁺

getTitle(): string

获取振动标题。

系统接口： 该接口为系统接口。

系统能力： SystemCapability.Multimedia.SystemSound.Core

返回值：

类型	说明
string	标题。

错误码：

错误码ID	错误信息
202	Caller is not a system application.

示例：

toneHapticsAttrs.getTitle();

getFileName¹⁴⁺

getFileName(): string

获取振动文件名。

系统接口： 该接口为系统接口。

系统能力： SystemCapability.Multimedia.SystemSound.Core

返回值：

类型	说明
string	文件名。

错误码：

错误码ID	错误信息
202	Caller is not a system application.

示例：

toneHapticsAttrs.getFileName();

ToneHapticsAttrsArray¹⁴⁺

type ToneHapticsAttrsArray = Array<ToneHapticsAttrs>

系统铃音的振动属性数组。

系统能力： SystemCapability.Multimedia.SystemSound.Core

类型	说明
Array<ToneHapticsAttrs>	系统铃音的振动属性数组。

systemSoundManager.getSystemSoundManager

getSystemSoundManager(): SystemSoundManager

获取系统声音管理器。

系统接口： 该接口为系统接口。

系统能力： SystemCapability.Multimedia.SystemSound.Core

返回值：

类型	说明
SystemSoundManager	系统声音管理类。

示例：

let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager();

SystemSoundManager

管理系统声音。在调用SystemSoundManager的接口前，需要先通过getSystemSoundManager创建实例。

setSystemRingtoneUri^(deprecated)

setSystemRingtoneUri(context: Context, uri: string, type: RingtoneType, callback: AsyncCallback<void>): void

设置系统铃声uri，使用callback方式异步返回结果。

说明： 从 API version 10 开始支持，从 API version 11 开始废弃，建议使用setRingtoneUri替代。

系统接口： 该接口为系统接口。

系统能力： SystemCapability.Multimedia.SystemSound.Core

参数：

参数名	类型	必填	说明
context	Context	是	当前应用的上下文。
uri	string	是	被设置的系统铃声的uri，资源支持可参考media.AVPlayer。
type	RingtoneType	是	被设置的系统铃声的类型。
callback	AsyncCallback<void>	是	回调返回设置成功或失败。

示例：

import { BusinessError } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';

let context: Context = getContext(this);
let uri = 'file://data/test.wav'; // 需更改为目标铃声文件的uri。
let type: systemSoundManager.RingtoneType = systemSoundManager.RingtoneType.RINGTONE_TYPE_DEFAULT;

let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager();
systemSoundManagerInstance.setSystemRingtoneUri(context, uri, type, (err: BusinessError) => {
  if (err) {
    console.error(`Failed to set system ringtone uri. ${err}`);
    return;
  }
  console.info(`Callback invoked to indicate a successful setting of the system ringtone uri.`);
});

setSystemRingtoneUri^(deprecated)

setSystemRingtoneUri(context: Context, uri: string, type: RingtoneType): Promise<void>

设置系统铃声uri，使用Promise方式异步返回结果。

说明： 从 API version 10 开始支持，从 API version 11 开始废弃，建议使用setRingtoneUri替代。

系统接口： 该接口为系统接口。

系统能力： SystemCapability.Multimedia.SystemSound.Core

参数：

参数名	类型	必填	说明
context	Context	是	当前应用的上下文。
uri	string	是	被设置的系统铃声的uri，资源支持可参考media.AVPlayer。
type	RingtoneType	是	被设置的系统铃声的类型。

返回值：

类型	说明
Promise<void>	Promise回调返回设置成功或失败。

示例：

import { BusinessError } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';

let context: Context = getContext(this);
let uri = 'file://data/test.wav'; // 需更改为目标铃声文件的uri。
let type: systemSoundManager.RingtoneType = systemSoundManager.RingtoneType.RINGTONE_TYPE_DEFAULT;

let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager();
systemSoundManagerInstance.setSystemRingtoneUri(context, uri, type).then(() => {
  console.info(`Promise returned to indicate a successful setting of the system ringtone uri.`);
}).catch ((err: BusinessError) => {
  console.error(`Failed to set the system ringtone uri ${err}`);
});

getSystemRingtoneUri^(deprecated)

getSystemRingtoneUri(context: Context, type: RingtoneType, callback: AsyncCallback<string>): void

获取系统铃声uri，使用callback方式异步返回结果。

说明： 从 API version 10 开始支持，从 API version 11 开始废弃，建议使用getRingtoneUri替代。

系统接口： 该接口为系统接口。

系统能力： SystemCapability.Multimedia.SystemSound.Core

参数：

参数名	类型	必填	说明
context	Context	是	当前应用的上下文。
type	RingtoneType	是	待获取的系统铃声的类型。
callback	AsyncCallback<string>	是	回调返回获取的系统铃声uri。

示例：

import { BusinessError } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';

let context: Context = getContext(this);
let type: systemSoundManager.RingtoneType = systemSoundManager.RingtoneType.RINGTONE_TYPE_DEFAULT;

let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager();
systemSoundManagerInstance.getSystemRingtoneUri(context, type, (err: BusinessError, value: string) => {
  if (err) {
    console.error(`Failed to get system ringtone uri. ${err}`);
    return;
  }
  console.info(`Callback invoked to indicate the value of the system ringtone uri is obtained ${value}.`);
});

getSystemRingtoneUri^(deprecated)

getSystemRingtoneUri(context: Context, type: RingtoneType): Promise<string>

获取系统铃声uri，使用Promise方式异步返回结果。

说明： 从 API version 10 开始支持，从 API version 11 开始废弃，建议使用getRingtoneUri替代。

系统接口： 该接口为系统接口。

系统能力： SystemCapability.Multimedia.SystemSound.Core

参数：

参数名	类型	必填	说明
context	Context	是	当前应用的上下文。
type	RingtoneType	是	被设置的系统铃声的类型。

返回值：

类型	说明
Promise<string>	Promise回调返回获取的系统铃声uri。

示例：

import { BusinessError } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';

let context: Context = getContext(this);
let type: systemSoundManager.RingtoneType = systemSoundManager.RingtoneType.RINGTONE_TYPE_DEFAULT;

let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager();
systemSoundManagerInstance.getSystemRingtoneUri(context, type).then((value: string) => {
  console.info(`Promise returned to indicate that the value of the system ringtone uri is obtained ${value}.`);
}).catch ((err: BusinessError) => {
  console.error(`Failed to get the system ringtone uri ${err}`);
});

getSystemRingtonePlayer^(deprecated)

getSystemRingtonePlayer(context: Context, type: RingtoneType, callback: AsyncCallback<RingtonePlayer>): void

获取系统铃声播放器，使用callback方式异步返回结果。

说明： 从 API version 10 开始支持，从 API version 11 开始废弃，建议使用getRingtonePlayer替代。

系统接口： 该接口为系统接口。

系统能力： SystemCapability.Multimedia.SystemSound.Core

参数：

参数名	类型	必填	说明
context	Context	是	当前应用的上下文。
type	RingtoneType	是	待获取播放器的系统铃声的类型。
callback	AsyncCallback<RingtonePlayer>	是	回调返回获取的系统铃声播放器。

示例：

import { BusinessError } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';

let context: Context = getContext(this);
let type: systemSoundManager.RingtoneType = systemSoundManager.RingtoneType.RINGTONE_TYPE_DEFAULT;
let systemRingtonePlayer: systemSoundManager.RingtonePlayer | undefined = undefined;

let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager();
systemSoundManagerInstance.getSystemRingtonePlayer(context, type, (err: BusinessError, value: systemSoundManager.RingtonePlayer) => {
  if (err) {
    console.error(`Failed to get system ringtone player. ${err}`);
    return;
  }
  console.info(`Callback invoked to indicate the value of the system ringtone player is obtained.`);
  systemRingtonePlayer = value;
});

getSystemRingtonePlayer^(deprecated)

getSystemRingtonePlayer(context: Context, type: RingtoneType): Promise<RingtonePlayer>

获取系统铃声播放器，使用Promise方式异步返回结果。

说明： 从 API version 10 开始支持，从 API version 11 开始废弃，建议使用getRingtonePlayer替代。

系统接口： 该接口为系统接口。

系统能力： SystemCapability.Multimedia.SystemSound.Core

参数：

参数名	类型	必填	说明
context	Context	是	当前应用的上下文。
type	RingtoneType	是	待获取播放器的系统铃声的类型。

返回值：

类型	说明
Promise<RingtonePlayer>	Promise回调返回获取的系统铃声播放器。

示例：

import { BusinessError } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';

let context: Context = getContext(this);
let type: systemSoundManager.RingtoneType = systemSoundManager.RingtoneType.RINGTONE_TYPE_DEFAULT;
let systemRingtonePlayer: systemSoundManager.RingtonePlayer | undefined = undefined;

let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager();
systemSoundManagerInstance.getSystemRingtonePlayer(context, type).then((value: systemSoundManager.RingtonePlayer) => {
  console.info(`Promise returned to indicate that the value of the system ringtone player is obtained.`);
  systemRingtonePlayer = value;
}).catch ((err: BusinessError) => {
  console.error(`Failed to get the system ringtone player ${err}`);
});

setRingtoneUri¹¹⁺

setRingtoneUri(context: BaseContext, uri: string, type: RingtoneType): Promise<void>

设置系统铃声uri，使用Promise方式异步返回结果。

系统接口： 该接口为系统接口。

系统能力： SystemCapability.Multimedia.SystemSound.Core

参数：

参数名	类型	必填	说明
context	BaseContext	是	当前应用的上下文。
uri	string	是	被设置的系统铃声的uri，资源支持可参考media.AVPlayer。
type	RingtoneType	是	被设置的系统铃声的类型。

返回值：

类型	说明
Promise<void>	Promise回调返回设置成功或失败。

错误码：

以下错误码的详细介绍请参见媒体服务错误码。

错误码ID	错误信息
202	Caller is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types.
5400103	I/O error.

示例：

import { BusinessError } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';

let context: common.BaseContext = getContext(this);
let uri = 'file://data/test.wav'; // 需更改为目标铃声文件的uri。
let type: systemSoundManager.RingtoneType = systemSoundManager.RingtoneType.RINGTONE_TYPE_SIM_CARD_0;

let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager();
systemSoundManagerInstance.setRingtoneUri(context, uri, type).then(() => {
  console.info(`Promise returned to indicate a successful setting of the system ringtone uri.`);
}).catch ((err: BusinessError) => {
  console.error(`Failed to set the system ringtone uri ${err}`);
});

getRingtoneUri¹¹⁺

getRingtoneUri(context: BaseContext, type: RingtoneType): Promise<string>

获取系统铃声uri，使用Promise方式异步返回结果。

系统接口： 该接口为系统接口。

系统能力： SystemCapability.Multimedia.SystemSound.Core

参数：

参数名	类型	必填	说明
context	BaseContext	是	当前应用的上下文。
type	RingtoneType	是	被设置的系统铃声的类型。

返回值：

类型	说明
Promise<string>	Promise回调返回获取的系统铃声uri。

错误码：

以下错误码的详细介绍请参见媒体服务错误码。

错误码ID	错误信息
202	Caller is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types.
5400103	I/O error.

示例：

import { BusinessError } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';

let context: common.BaseContext = getContext(this);
let type: systemSoundManager.RingtoneType = systemSoundManager.RingtoneType.RINGTONE_TYPE_SIM_CARD_0;

let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager();
systemSoundManagerInstance.getRingtoneUri(context, type).then((value: string) => {
  console.info(`Promise returned to indicate that the value of the system ringtone uri is obtained ${value}.`);
}).catch ((err: BusinessError) => {
  console.error(`Failed to get the system ringtone uri ${err}`);
});

getRingtonePlayer¹¹⁺

getRingtonePlayer(context: BaseContext, type: RingtoneType): Promise<RingtonePlayer>

获取系统铃声播放器，使用Promise方式异步返回结果。

系统接口： 该接口为系统接口。

系统能力： SystemCapability.Multimedia.SystemSound.Core

参数：

参数名	类型	必填	说明
context	BaseContext	是	当前应用的上下文。
type	RingtoneType	是	待获取播放器的系统铃声的类型。

返回值：

类型	说明
Promise<RingtonePlayer>	Promise回调返回获取的系统铃声播放器。

错误码：

以下错误码的详细介绍请参见媒体服务错误码。

错误码ID	错误信息
202	Caller is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types.

示例：

import { BusinessError } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';

let context: common.BaseContext = getContext(this);
let type: systemSoundManager.RingtoneType = systemSoundManager.RingtoneType.RINGTONE_TYPE_SIM_CARD_0;
let systemRingtonePlayer: systemSoundManager.RingtonePlayer | undefined = undefined;

let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager();
systemSoundManagerInstance.getRingtonePlayer(context, type).then((value: systemSoundManager.RingtonePlayer) => {
  console.info(`Promise returned to indicate that the value of the system ringtone player is obtained.`);
  systemRingtonePlayer = value;
}).catch ((err: BusinessError) => {
  console.error(`Failed to get the system ringtone player ${err}`);
});

setSystemToneUri¹¹⁺

setSystemToneUri(context: BaseContext, uri: string, type: SystemToneType): Promise<void>

设置系统提示音uri，使用Promise方式异步返回结果。

系统接口： 该接口为系统接口。

系统能力： SystemCapability.Multimedia.SystemSound.Core

参数：

参数名	类型	必填	说明
context	BaseContext	是	当前应用的上下文。
uri	string	是	被设置的系统提示音的uri，资源支持可参考media.AVPlayer。
type	SystemToneType	是	被设置的系统提示音的类型。

返回值：

类型	说明
Promise<void>	Promise回调返回设置成功或失败。

错误码：

以下错误码的详细介绍请参见媒体服务错误码。

错误码ID	错误信息
202	Caller is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types.
5400103	I/O error.

示例：

import { BusinessError } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';

let context: common.BaseContext = getContext(this);
let uri = 'file://data/test.wav'; // 需更改为目标铃声文件的uri。
let type: systemSoundManager.SystemToneType = systemSoundManager.SystemToneType.SYSTEM_TONE_TYPE_SIM_CARD_0;

let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager();
systemSoundManagerInstance.setSystemToneUri(context, uri, type).then(() => {
  console.info(`Promise returned to indicate a successful setting of the system tone uri.`);
}).catch ((err: BusinessError) => {
  console.error(`Failed to set the system tone uri ${err}`);
});

getSystemToneUri¹¹⁺

getSystemToneUri(context: BaseContext, type: SystemToneType): Promise<string>

获取系统提示音uri，使用Promise方式异步返回结果。

系统接口： 该接口为系统接口。

系统能力： SystemCapability.Multimedia.SystemSound.Core

参数：

参数名	类型	必填	说明
context	BaseContext	是	当前应用的上下文。
type	SystemToneType	是	被设置的系统提示音的类型。

返回值：

类型	说明
Promise<string>	Promise回调返回获取的系统提示音uri。

错误码：

以下错误码的详细介绍请参见媒体服务错误码。

错误码ID	错误信息
202	Caller is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types.
5400103	I/O error.

示例：

import { BusinessError } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';

let context: common.BaseContext = getContext(this);
let type: systemSoundManager.SystemToneType = systemSoundManager.SystemToneType.SYSTEM_TONE_TYPE_SIM_CARD_0;

let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager();
systemSoundManagerInstance.getSystemToneUri(context, type).then((value: string) => {
  console.info(`Promise returned to indicate that the value of the system tone uri is obtained ${value}.`);
}).catch ((err: BusinessError) => {
  console.error(`Failed to get the system tone uri ${err}`);
});

getSystemTonePlayer¹¹⁺

getSystemTonePlayer(context: BaseContext, type: SystemToneType): Promise<SystemTonePlayer>

获取系统提示音播放器，使用Promise方式异步返回结果。

系统接口： 该接口为系统接口。

系统能力： SystemCapability.Multimedia.SystemSound.Core

参数：

参数名	类型	必填	说明
context	BaseContext	是	当前应用的上下文。
type	SystemToneType	是	待获取播放器的系统提示音的类型。

返回值：

类型	说明
Promise<SystemTonePlayer>	Promise回调返回获取的系统提示音播放器。

错误码：

以下错误码的详细介绍请参见媒体服务错误码。

错误码ID	错误信息
202	Caller is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types.

示例：

import { BusinessError } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';

let context: common.BaseContext = getContext(this);
let type: systemSoundManager.SystemToneType = systemSoundManager.SystemToneType.SYSTEM_TONE_TYPE_SIM_CARD_0;
let systemTonePlayer: systemSoundManager.SystemTonePlayer | undefined = undefined;

let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager();
systemSoundManagerInstance.getSystemTonePlayer(context, type).then((value: systemSoundManager.SystemTonePlayer) => {
  console.info(`Promise returned to indicate that the value of the system tone player is obtained.`);
    systemTonePlayer = value;
}).catch ((err: BusinessError) => {
  console.error(`Failed to get the system tone player ${err}`);
});

getDefaultRingtoneAttrs¹²⁺

getDefaultRingtoneAttrs(context: BaseContext, type: RingtoneType): Promise<ToneAttrs>

获取系统铃声的属性，使用Promise方式异步返回结果。

系统接口： 该接口为系统接口。

系统能力： SystemCapability.Multimedia.SystemSound.Core

参数：

参数名	类型	必填	说明
context	BaseContext	是	当前应用的上下文。
type	RingtoneType	是	被设置的系统铃声的类型。

返回值：

类型	说明
Promise<ToneAttrs>	Promise回调返回系统铃声的属性。

错误码：

以下错误码的详细介绍请参见媒体服务错误码。

错误码ID	错误信息
202	Caller is not a system application.
401	The parameters check failed.
5400103	I/O error.

示例：

import { BusinessError } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';

let context: common.BaseContext = getContext(this);
let type: systemSoundManager.RingtoneType = systemSoundManager.RingtoneType.RINGTONE_TYPE_SIM_CARD_0;

let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager();
systemSoundManagerInstance.getDefaultRingtoneAttrs(context, type).then((value: systemSoundManager.ToneAttrs) => {
  console.info(`Promise returned to indicate that the value of the attributes of the default ringtone is obtained.`);
}).catch ((err: BusinessError) => {
  console.error(`Failed to get the default ring tone attrs ${err}`);
});

getRingtoneAttrList¹²⁺

getRingtoneAttrList(context: BaseContext, type: RingtoneType): Promise<ToneAttrsArray>

获取系统铃声的属性列表，使用Promise方式异步返回结果。

系统接口： 该接口为系统接口。

系统能力： SystemCapability.Multimedia.SystemSound.Core

参数：

参数名	类型	必填	说明
context	BaseContext	是	当前应用的上下文。
type	RingtoneType	是	被设置的系统铃声的类型。

返回值：

类型	说明
Promise<ToneAttrsArray>	Promise回调返回系统铃声的属性列表。

错误码：

以下错误码的详细介绍请参见媒体服务错误码。

错误码ID	错误信息
202	Caller is not a system application.
401	The parameters check failed.
5400103	I/O error.

示例：

import { BusinessError } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';

let context: common.BaseContext = getContext(this);
let type: systemSoundManager.RingtoneType = systemSoundManager.RingtoneType.RINGTONE_TYPE_SIM_CARD_0;

let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager();
systemSoundManagerInstance.getRingtoneAttrList(context, type).then((value: systemSoundManager.ToneAttrsArray) => {
  console.info(`Promise returned to indicate that the value of the attribute list of ringtone is obtained.`);
}).catch ((err: BusinessError) => {
  console.error(`Failed to get the attribute list of ringtone ${err}`);
});

getDefaultSystemToneAttrs¹²⁺

getDefaultSystemToneAttrs(context: BaseContext, type: SystemToneType): Promise<ToneAttrs>

获取系统提示音的属性，使用Promise方式异步返回结果。

系统接口： 该接口为系统接口。

系统能力： SystemCapability.Multimedia.SystemSound.Core

参数：

参数名	类型	必填	说明
context	BaseContext	是	当前应用的上下文。
type	SystemToneType	是	待获取播放器的系统提示音的类型。

返回值：

类型	说明
Promise<ToneAttrs>	Promise回调返回系统提示音的属性。

错误码：

以下错误码的详细介绍请参见媒体服务错误码。

错误码ID	错误信息
202	Caller is not a system application.
401	The parameters check failed.
5400103	I/O error.

示例：

import { BusinessError } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';

let context: common.BaseContext = getContext(this);
let type: systemSoundManager.SystemToneType = systemSoundManager.SystemToneType.SYSTEM_TONE_TYPE_SIM_CARD_0;

let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager();
systemSoundManagerInstance.getDefaultSystemToneAttrs(context, type).then((value: systemSoundManager.ToneAttrs) => {
  console.info(`Promise returned to indicate that the value of the attributes of the system ringtone is obtained.`);
}).catch ((err: BusinessError) => {
  console.error(`Failed to get the system tone attrs ${err}`);
});

getSystemToneAttrList¹²⁺

getSystemToneAttrList(context: BaseContext, type: SystemToneType): Promise<ToneAttrsArray>

获取系统提示音的属性列表，使用Promise方式异步返回结果。

系统接口： 该接口为系统接口。

系统能力： SystemCapability.Multimedia.SystemSound.Core

参数：

参数名	类型	必填	说明
context	BaseContext	是	当前应用的上下文。
type	SystemToneType	是	待获取播放器的系统提示音的类型。

返回值：

类型	说明
Promise<ToneAttrsArray>	Promise回调返回系统提示音的属性列表。

错误码：

以下错误码的详细介绍请参见媒体服务错误码。

错误码ID	错误信息
202	Caller is not a system application.
401	The parameters check failed.
5400103	I/O error.

示例：

import { BusinessError } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';

let context: common.BaseContext = getContext(this);
let type: systemSoundManager.SystemToneType = systemSoundManager.SystemToneType.SYSTEM_TONE_TYPE_SIM_CARD_0;

let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager();
systemSoundManagerInstance.getSystemToneAttrList(context, type).then((value: systemSoundManager.ToneAttrsArray) => {
  console.info(`Promise returned to indicate that the value of the attribute list of system tone is obtained.`);
}).catch ((err: BusinessError) => {
  console.error(`Failed to get the attribute list of system tone ${err}`);
});

getDefaultAlarmToneAttrs¹²⁺

getDefaultAlarmToneAttrs(context: BaseContext): Promise<ToneAttrs>

获取系统闹铃的属性，使用Promise方式异步返回结果。

系统接口： 该接口为系统接口。

系统能力： SystemCapability.Multimedia.SystemSound.Core

参数：

参数名	类型	必填	说明
context	BaseContext	是	当前应用的上下文。

返回值：

类型	说明
Promise<ToneAttrs>	Promise回调返回系统闹铃的属性。

错误码：

以下错误码的详细介绍请参见媒体服务错误码。

错误码ID	错误信息
202	Caller is not a system application.
401	The parameters check failed.
5400103	I/O error.

示例：

import { BusinessError } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';

let context: common.BaseContext = getContext(this);

let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager();
systemSoundManagerInstance.getDefaultAlarmToneAttrs(context).then((value: systemSoundManager.ToneAttrs) => {
  console.info(`Promise returned to indicate that the value of the attributes of the default alarm tone is obtained.`);
}).catch ((err: BusinessError) => {
  console.error(`Failed to get the default alarm tone attrs ${err}`);
});

setAlarmToneUri¹²⁺

setAlarmToneUri(context: Context, uri: string): Promise<void>

设置系统闹铃uri，使用Promise方式异步返回结果。

系统接口： 该接口为系统接口。

系统能力： SystemCapability.Multimedia.SystemSound.Core

参数：

参数名	类型	必填	说明
context	Context	是	当前应用的上下文。
uri	string	是	被设置的系统闹铃的uri，资源支持可参考media.AVPlayer。

返回值：

类型	说明
Promise<void>	Promise回调返回设置成功或失败。

示例：

import { BusinessError } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';

let context: Context = getContext(this);
let uri = 'file://data/test.wav'; // 需更改为目标铃声文件的uri。

let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager();
systemSoundManagerInstance.setAlarmToneUri(context, uri).then(() => {
  console.info(`Promise returned to indicate a successful setting of the alarm tone uri.`);
}).catch ((err: BusinessError) => {
  console.error(`Failed to set the alarm tone uri ${err}`);
});

getAlarmToneUri¹²⁺

getAlarmToneUri(context: Context): Promise<string>

获取系统当前闹铃uri，使用Promise方式异步返回结果。

系统接口： 该接口为系统接口。

系统能力： SystemCapability.Multimedia.SystemSound.Core

参数：

参数名	类型	必填	说明
context	Context	是	当前应用的上下文。

返回值：

类型	说明
Promise<string>	Promise回调返回系统当前闹铃uri。

示例：

import { BusinessError } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';

let context: Context = getContext(this);

let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager();
systemSoundManagerInstance.getAlarmToneUri(context).then((value: string) => {
  console.info(`Promise returned to indicate that the value of alarm tone uri.`);
}).catch ((err: BusinessError) => {
  console.error(`Failed to get the alarm tone uri ${err}`);
});

getAlarmToneAttrList¹²⁺

getAlarmToneAttrList(context: BaseContext): Promise<ToneAttrsArray>

获取全部闹铃属性列表，使用Promise方式异步返回结果。

系统接口： 该接口为系统接口。

系统能力： SystemCapability.Multimedia.SystemSound.Core

参数：

参数名	类型	必填	说明
context	BaseContext	是	当前应用的上下文。

返回值：

类型	说明
Promise<ToneAttrsArray>	Promise回调返回全部闹铃属性列表。

错误码：

以下错误码的详细介绍请参见媒体服务错误码。

错误码ID	错误信息
202	Caller is not a system application.
401	The parameters check failed.
5400103	I/O error.

示例：

import { BusinessError } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';

let context: common.BaseContext = getContext(this);

let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager();
systemSoundManagerInstance.getAlarmToneAttrList(context).then((value: systemSoundManager.ToneAttrsArray) => {
  console.info(`Promise returned to indicate that the value of the attribute list of alarm tone is obtained.`);
}).catch ((err: BusinessError) => {
  console.error(`Failed to get the attribute list of alarm tone ${err}`);
});

openAlarmTone¹²⁺

openAlarmTone(context: Context, uri: string): Promise<number>

打开闹铃文件，使用Promise方式异步返回结果。

系统接口： 该接口为系统接口。

系统能力： SystemCapability.Multimedia.SystemSound.Core

参数：

参数名	类型	必填	说明
context	Context	是	当前应用的上下文。
uri	string	是	被设置的系统闹铃的uri，资源支持可参考media.AVPlayer。

返回值：

类型	说明
Promise<number>	Promise回调返回fd。

错误码：

以下错误码的详细介绍请参见媒体服务错误码。

错误码ID	错误信息
202	Caller is not a system application.
401	The parameters check failed.
5400103	I/O error.
20700001	Tone type mismatch, e.g. tone of uri is notification instead of alarm.

示例：

import { BusinessError } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';

let context: Context = getContext(this);
let uri = 'file://data/test.wav'; // 需更改为目标铃声文件的uri。

let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager();
systemSoundManagerInstance.openAlarmTone(context, uri).then((value: number) => {
  console.info(`Promise returned to indicate the value of fd.`);
}).catch ((err: BusinessError) => {
  console.error(`Failed to open alarm tone ${err}`);
});

close¹²⁺

close(fd: number): Promise<void>

关闭闹铃文件，使用Promise方式异步返回结果。

系统接口： 该接口为系统接口

系统能力： SystemCapability.Multimedia.SystemSound.Core

参数：

参数名	类型	必填	说明
fd	number	是	文件描述符，通过openAlarmTone获取。

返回值：

类型	说明
Promise<void>	Promise回调返回设置成功或失败。

错误码：

以下错误码的详细介绍请参见媒体服务错误码。

错误码ID	错误信息
202	Caller is not a system application.
401	The parameters check failed.
5400103	I/O error.

示例：

import { BusinessError } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';

let context: Context = getContext(this);
let fd = 50; // 需更改为目标铃声的fd。

let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager();
systemSoundManagerInstance.close(fd).then(() => {
  console.info(`Promise returned to indicate that the fd has been close.`);
}).catch ((err: BusinessError) => {
  console.error(`Failed to close fd ${err}`);
});

addCustomizedTone¹²⁺

addCustomizedTone(context: BaseContext, toneAttr: ToneAttrs, externalUri: string): Promise<string>

通过铃音uri将自定义铃音添加到铃音库，使用Promise方式异步返回结果。

系统接口： 该接口为系统接口。

系统能力： SystemCapability.Multimedia.SystemSound.Core

参数：

参数名	类型	必填	说明
context	Context	是	当前应用的上下文。
toneAttr	ToneAttrs	是	铃音属性。
externalUri	string	是	外部存储器中的铃音uri。

返回值：

类型	说明
Promise<string>	Promise回调返回铃音在铃音库中的uri。

错误码：

以下错误码的详细介绍请参见媒体服务错误码。

错误码ID	错误信息
201	Permission denied.
202	Caller is not a system application.
401	The parameters check failed.
5400102	Operation is not allowed, e.g. ringtone to add is not customized.
5400103	I/O error.

示例：

import { BusinessError } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';

let context: Context = getContext(this);
let title = 'test'; // 需更改为实际名称。
let fileName = 'displayName_test'; // 需更改为实际文件名。
let categoryValue = systemSoundManager.TONE_CATEGORY_ALARM;

let toneAttrs = systemSoundManager.createCustomizedToneAttrs();
toneAttrs.setTitle(title);
toneAttrs.setFileName(fileName);
toneAttrs.setCategory(categoryValue);

let path = 'file://data/test.ogg'; // 需更改为实际铃音uri。

let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager();
systemSoundManagerInstance.addCustomizedTone(context, toneAttrs, path).then((value: string) => {
  console.info(`Promise returned to indicate that the value of tone uri in ringtone library.`);
}).catch ((err: BusinessError) => {
  console.error(`Failed to add customized tone ${err}`);
});

addCustomizedTone¹²⁺

addCustomizedTone(context: BaseContext, toneAttr: ToneAttrs, fd: number, offset?: number, length?: number): Promise<string>

通过文件描述符fd将自定义铃音添加到铃音库，使用Promise方式异步返回结果。

系统接口： 该接口为系统接口。

系统能力： SystemCapability.Multimedia.SystemSound.Core

参数：

参数名	类型	必填	说明
context	Context	是	当前应用的上下文。
toneAttr	ToneAttrs	是	铃音属性。
fd	number	是	文件描述符，可通过fs.open获取。
offset	number	否	读取数据的偏移量（以字节为单位）。默认情况下为0。
length	number	否	读取的数据的长度（以字节为单位）。默认情况下，长度为偏移后的剩余全部字节数。

返回值：

类型	说明
Promise<string>	Promise回调返回铃音在铃音库中的uri。

错误码：

以下错误码的详细介绍请参见媒体服务错误码。

错误码ID	错误信息
201	Permission denied.
202	Caller is not a system application.
401	The parameters check failed.
5400102	Operation is not allowed, e.g. ringtone to add is not customized.
5400103	I/O error.

示例：

import { BusinessError } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';

let context: Context = getContext(this);
let title = 'test'; // 需更改为实际名称。
let fileName = 'displayName_test'; // 需更改为实际文件名。
let categoryValue = systemSoundManager.TONE_CATEGORY_ALARM;

let toneAttrs = systemSoundManager.createCustomizedToneAttrs();
toneAttrs.setTitle(title);
toneAttrs.setFileName(fileName);
toneAttrs.setCategory(categoryValue);

let fd = 10; // 需更改为实际铃音fd。
let offset = 0; // 需更改为实际所需偏移量。
let length = 50; // 需更改为实际所需数据长度。

let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager();
systemSoundManagerInstance.addCustomizedTone(context, toneAttrs, fd, offset, length).then((value: string) => {
  console.info(`Promise returned to indicate that the value of tone uri in ringtone library.`);
}).catch ((err: BusinessError) => {
  console.error(`Failed to add customized tone ${err}`);
});

removeCustomizedTone¹²⁺

removeCustomizedTone(context: BaseContext, uri: string): Promise<void>

从铃音库中删除自定义铃音，使用Promise方式异步返回结果。

系统接口： 该接口为系统接口。

系统能力： SystemCapability.Multimedia.SystemSound.Core

参数：

参数名	类型	必填	说明
context	Context	是	当前应用的上下文。
uri	string	是	铃音uri，可通过addCustomizedTone或getAlarmToneAttrList等方法获取。

返回值：

类型	说明
Promise<void>	Promise回调返回设置成功或失败。

错误码：

以下错误码的详细介绍请参见媒体服务错误码。

错误码ID	错误信息
201	Permission denied.
202	Caller is not a system application.
401	The parameters check failed.
5400102	Operation is not allowed, e.g. ringtone to add is not customized.
5400103	I/O error.

示例：

import { BusinessError } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';

let context: Context = getContext(this);
let uri = 'file://data/test.wav'; // 需更改为目标铃声文件的uri。

let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager();
systemSoundManagerInstance.removeCustomizedTone(context, uri).then(() => {
  console.info(`Promise returned to indicate that the customized tone has been deleted.`);
}).catch ((err: BusinessError) => {
  console.error(`Failed to delete customized tone ${err}`);
});

getToneHapticsSettings¹⁴⁺

getToneHapticsSettings(context: BaseContext, type: ToneHapticsType): Promise<ToneHapticsSettings>

获取系统铃音的振动设置，使用Promise方式异步返回结果。

系统接口： 该接口为系统接口。

系统能力： SystemCapability.Multimedia.SystemSound.Core

参数：

参数名	类型	必填	说明
context	Context	是	当前应用的上下文。
type	ToneHapticsType	是	待获取系统铃音的振动类型。

返回值：

类型	说明
Promise<ToneHapticsSettings>	Promise回调返回铃声的振动设置。

错误码：

以下错误码的详细介绍请参见媒体服务错误码。

错误码ID	错误信息
202	Caller is not a system application.
401	The parameters check failed.
5400103	I/O error.
20700003	Unsupported operation.

示例：

import { BusinessError } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';

let context: common.BaseContext = getContext(this);
let type: systemSoundManager.ToneHapticsType = systemSoundManager.ToneHapticsType.CALL_SIM_CARD_0;

let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager();
systemSoundManagerInstance.getToneHapticsSettings(context, type).then((value: systemSoundManager.ToneHapticsSettings) => {
  console.info(`Promise returned to indicate that the value of the tone haptics settings is obtained.`);
}).catch ((err: BusinessError) => {
  console.error(`Failed to get the tone haptics settings ${err}`);
});

setToneHapticsSettings¹⁴⁺

setToneHapticsSettings(context: BaseContext, type: ToneHapticsType, settings: ToneHapticsSettings): Promise<void>

设置系统铃音的振动，使用Promise方式异步返回结果。

系统接口： 该接口为系统接口。

系统能力： SystemCapability.Multimedia.SystemSound.Core

参数：

参数名	类型	必填	说明
context	Context	是	当前应用的上下文。
type	ToneHapticsType	是	被设置的系统铃音的振动类型。
settings	ToneHapticsSettings	是	被设置的系统铃音的振动设置。

返回值：

类型	说明
Promise<void>	Promise回调返回设置成功或失败。

错误码：

以下错误码的详细介绍请参见媒体服务错误码。

错误码ID	错误信息
202	Caller is not a system application.
401	The parameters check failed.
5400102	Operation is not allowed, e.g. ringtone to add is not customized.
5400103	I/O error.
20700003	Unsupported operation.

示例：

import { BusinessError } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';

let context: common.BaseContext = getContext(this);
let type: systemSoundManager.ToneHapticsType = systemSoundManager.ToneHapticsType.CALL_SIM_CARD_0;
let toneHapticsSettings: systemSoundManager.ToneHapticsSettings = {
  mode: systemSoundManager.ToneHapticsMode.NON_SYNC,
  hapticsUri: '/data/storage/el2/base/haptics/synchronized/alarms/test.json', // 需更改为通过getToneHapticsList获取的Uri。
}

let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager();
systemSoundManagerInstance.setToneHapticsSettings(context, type, toneHapticsSettings).then(() => {
  console.info(`Promise returned to indicate a successful setting of the tone haptics.`);
}).catch ((err: BusinessError) => {
  console.error(`Failed to set the tone haptics settings ${err}`);
});

getToneHapticsList¹⁴⁺

getToneHapticsList(context: BaseContext, isSynced: boolean): Promise<ToneHapticsAttrsArray>

获取同步或者非同步的系统铃音的振动属性列表，使用Promise方式异步返回结果。

系统接口： 该接口为系统接口。

系统能力： SystemCapability.Multimedia.SystemSound.Core

参数：

参数名	类型	必填	说明
context	Context	是	当前应用的上下文。
isSynced	boolean	是	待获取的振动是否与某个铃音同步。

返回值：

类型	说明
Promise<ToneHapticsAttrsArray>	Promise回调返回同步或者非同步的系统铃音的振动属性列表。

错误码：

以下错误码的详细介绍请参见媒体服务错误码。

错误码ID	错误信息
202	Caller is not a system application.
401	The parameters check failed.
5400103	I/O error.
20700003	Unsupported operation.

示例：

import { BusinessError } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';

let context: common.BaseContext = getContext(this);

let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager();
systemSoundManagerInstance.getToneHapticsList(context, false).then((value: systemSoundManager.ToneHapticsAttrsArray) => {
  console.info(`Promise returned to indicate that the value of the attribute list of tone haptics is obtained.`);
}).catch ((err: BusinessError) => {
  console.error(`Failed to get the attribute list of tone haptics ${err}`);
});

getHapticsAttrsSyncedWithTone¹⁴⁺

getHapticsAttrsSyncedWithTone(context: BaseContext, toneUri: string): Promise<ToneHapticsAttrs>

获取与指定铃音同步的振动属性，使用Promise方式异步返回结果。

系统接口： 该接口为系统接口。

系统能力： SystemCapability.Multimedia.SystemSound.Core

参数：

参数名	类型	必填	说明
context	Context	是	当前应用的上下文。
toneUri	string	是	待获取同步振动的系统铃声Uri,可通过getRingtoneAttrList或getSystemToneAttrList等获取。

返回值：

类型	说明
Promise<ToneHapticsAttrs>	Promise回调返回与指定铃音同步的振动属性。

错误码：

以下错误码的详细介绍请参见媒体服务错误码。

错误码ID	错误信息
202	Caller is not a system application.
401	The parameters check failed.
5400102	Operation is not allowed, e.g. ringtone to add is not customized.
5400103	I/O error.
20700003	Unsupported operation.

示例：

import { BusinessError } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';

let context: common.BaseContext = getContext(this);
let toneUri: string = '/data/storage/el2/base/RingTone/alarms/test.ogg'; // 需更改为实际铃音uri。

let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager();
systemSoundManagerInstance.getHapticsAttrsSyncedWithTone(context, toneUri).then((value: systemSoundManager.ToneHapticsAttrs) => {
  console.info(`Promise returned to indicate that the value of the attribute of tone haptics is obtained.`);
}).catch ((err: BusinessError) => {
  console.error(`Failed to get the attribute of tone haptics ${err}`);
});

openToneHaptics¹⁴⁺

openToneHaptics(context: Context, hapticsUri: string): Promise<number>

打开系统铃音的振动，使用Promise方式异步返回结果。

系统接口： 该接口为系统接口。

系统能力： SystemCapability.Multimedia.SystemSound.Core

参数：

参数名	类型	必填	说明
context	Context	是	当前应用的上下文。
hapticsUri	string	是	待打开系统铃音的振动的uri，资源支持可参考media.AVPlayer。

返回值：

类型	说明
Promise<number>	Promise回调返回fd。

错误码：

以下错误码的详细介绍请参见媒体服务错误码。

错误码ID	错误信息
202	Caller is not a system application.
401	The parameters check failed.
5400102	Operation is not allowed, e.g. ringtone to add is not customized.
5400103	I/O error.
20700003	Unsupported operation.

示例：

import { BusinessError } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';

let context: Context = getContext(this);
let hapticsUri = '/data/storage/el2/base/haptics/synchronized/alarms/test.json'; // 需更改为目标统铃音的振动的uri。

let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager();
systemSoundManagerInstance.openToneHaptics(context, hapticsUri).then((value: number) => {
  console.info(`Promise returned to indicate the value of fd.`);
}).catch ((err: BusinessError) => {
  console.error(`Failed to open haptics ${err}`);
});

RingtonePlayer¹⁰⁺

type RingtonePlayer = _RingtonePlayer;

系统铃音播放器对象。

系统能力： SystemCapability.Multimedia.SystemSound.Core

类型	说明
_RingtonePlayer	系统铃音播放器。

SystemTonePlayer¹¹⁺

type SystemTonePlayer = _SystemTonePlayer;

系统提示音播放器对象。

系统能力： SystemCapability.Multimedia.SystemSound.Core

类型	说明
_SystemTonePlayer	系统提示音播放器。

RingtoneOptions¹⁰⁺

type RingtoneOptions = _RingtoneOptions;

系统铃音播放器配置项。

系统能力： SystemCapability.Multimedia.SystemSound.Core

类型	说明
_RingtoneOptions	系统铃音播放器配置项。

SystemToneOptions¹¹⁺

type SystemToneOptions = _SystemToneOptions;

系统提示音播放器配置项。

系统能力： SystemCapability.Multimedia.SystemSound.Core

类型	说明
_SystemToneOptions	系统提示音音播放器配置项。