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

  • 2025-06-12
  • 浏览 (5)

@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的铃声。

SystemToneType11+

枚举，系统铃声类型。

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

系统能力： 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 通知提示音。

ToneCustomizedType12+

枚举，铃声自定义类型。

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

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

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

ToneAttrs12+

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

getTitle12+

getTitle(): string

获取铃声标题。

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

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

返回值：

类型 说明
string 标题。

错误码：

以下错误码的详细介绍请参见通用错误码说明文档。

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

示例：

toneAttrs.getTitle();

setTitle12+

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);

getFileName12+

getFileName(): string

获取铃声文件名。

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

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

返回值：

类型 说明
string 文件名。

错误码：

以下错误码的详细介绍请参见通用错误码说明文档。

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

示例：

toneAttrs.getFileName();

setFileName12+

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);

getUri12+

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();

getCustomizedType12+

getCustomizedType(): ToneCustomizedType

获取铃声自定义类型。

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

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

返回值：

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

错误码：

以下错误码的详细介绍请参见通用错误码说明文档。

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

示例：

toneAttrs.getCustomizedType();

setCategory12+

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);

getCategory12+

getCategory(): number

获取铃声类别。

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

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

返回值：

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

错误码：

以下错误码的详细介绍请参见通用错误码说明文档。

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

示例：

toneAttrs.getCategory();

ToneAttrsArray12+

type ToneAttrsArray = Array<ToneAttrs>

铃音属性数组。

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

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

systemSoundManager.createCustomizedToneAttrs12+

createCustomizedToneAttrs(): ToneAttrs

创建自定义铃声属性。

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

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

返回值：

类型 说明
ToneAttrs 铃声属性类。

错误码：

以下错误码的详细介绍请参见通用错误码说明文档。

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

示例：

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

ToneHapticsFeature13+

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

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

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

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

ToneHapticsType14+

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

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

系统能力： 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 通知提示音的振动。

ToneHapticsMode14+

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

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

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

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

ToneHapticsSettings14+

系统铃音的振动设置。

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

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

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

ToneHapticsAttrs14+

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

getUri14+

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();

getTitle14+

getTitle(): string

获取振动标题。

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

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

返回值：

类型 说明
string 标题。

错误码：

以下错误码的详细介绍请参见通用错误码说明文档。

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

示例：

toneHapticsAttrs.getTitle();

getFileName14+

getFileName(): string

获取振动文件名。

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

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

返回值：

类型 说明
string 文件名。

错误码：

以下错误码的详细介绍请参见通用错误码说明文档。

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

示例：

toneHapticsAttrs.getFileName();

ToneHapticsAttrsArray14+

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> 是 回调函数。当设置系统铃声uri成功，err为undefined，否则为错误对象。

示例：

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

// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext。
let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
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对象。无返回结果的Promise对象。

示例：

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

// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext。
let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
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成功，err为undefined，data为获取到的系统铃声uri；否则为错误对象。

示例：

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

// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext。
let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
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';

// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext。
let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
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> 是 回调函数。当获取系统铃声播放器成功，err为undefined，data为获取到的系统铃声播放器；否则为错误对象。

示例：

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

// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext。
let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
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';

// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext。
let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
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}`);
});

setRingtoneUri11+

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对象。无返回结果的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';

// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext。
let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
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}`);
});

getRingtoneUri11+

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';

// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext。
let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
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}`);
});

getRingtonePlayer11+

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';

// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext。
let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
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}`);
});

setSystemToneUri11+

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对象。无返回结果的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';

// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext。
let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
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}`);
});

getSystemToneUri11+

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';

// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext。
let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
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}`);
});

getSystemTonePlayer11+

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';

// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext。
let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
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}`);
});

getDefaultRingtoneAttrs12+

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';

// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext。
let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
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}`);
});

getRingtoneAttrList12+

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';

// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext。
let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
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}`);
});

getDefaultSystemToneAttrs12+

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';

// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext。
let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
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}`);
});

getSystemToneAttrList12+

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';

// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext。
let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
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}`);
});

getDefaultAlarmToneAttrs12+

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';

// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext。
let context = this.getUIContext().getHostContext() as common.UIAbilityContext;

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}`);
});

setAlarmToneUri12+

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

设置系统闹铃uri。使用Promise异步回调。

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

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

参数：

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

返回值：

类型 说明
Promise<void> Promise对象。无返回结果的Promise对象。

示例：

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

// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext。
let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
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}`);
});

getAlarmToneUri12+

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';

// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext。
let context = this.getUIContext().getHostContext() as common.UIAbilityContext;

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}`);
});

getAlarmToneAttrList12+

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';

// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext。
let context = this.getUIContext().getHostContext() as common.UIAbilityContext;

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}`);
});

openAlarmTone12+

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';

// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext。
let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
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}`);
});

close12+

close(fd: number): Promise<void>

关闭闹铃文件。使用Promise异步回调。

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

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

参数：

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

返回值：

类型 说明
Promise<void> Promise对象。无返回结果的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';

// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext。
let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
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}`);
});

addCustomizedTone12+

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

通过铃音uri将自定义铃音添加到铃音库。使用Promise异步回调。

需要权限： ohos.permission.WRITE_RINGTONE

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

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

参数：

参数名 类型 必填 说明
context BaseContext 是 当前应用的上下文。
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';

// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext。
let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
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}`);
});

addCustomizedTone12+

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

通过文件描述符fd将自定义铃音添加到铃音库。使用Promise异步回调。

需要权限： ohos.permission.WRITE_RINGTONE

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

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

参数：

参数名 类型 必填 说明
context BaseContext 是 当前应用的上下文。
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';

// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext。
let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
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}`);
});

removeCustomizedTone12+

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

从铃音库中删除自定义铃音。使用Promise异步回调。

需要权限： ohos.permission.WRITE_RINGTONE

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

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

参数：

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

返回值：

类型 说明
Promise<void> Promise对象。无返回结果的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';

// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext。
let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
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}`);
});

getToneHapticsSettings14+

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

获取系统铃音的振动设置。使用Promise异步回调。

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

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

参数：

参数名 类型 必填 说明
context BaseContext 是 当前应用的上下文。
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';

// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext。
let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
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}`);
});

setToneHapticsSettings14+

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

设置系统铃音的振动。使用Promise异步回调。

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

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

参数：

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

返回值：

类型 说明
Promise<void> Promise对象。无返回结果的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';

// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext。
let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
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}`);
});

getToneHapticsList14+

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

获取同步或者非同步的系统铃音的振动属性列表。使用Promise异步回调。

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

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

参数：

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

返回值：

类型 说明
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';

// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext。
let context = this.getUIContext().getHostContext() as common.UIAbilityContext;

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}`);
});

getHapticsAttrsSyncedWithTone14+

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

获取与指定铃音同步的振动属性。使用Promise异步回调。

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

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

参数：

参数名 类型 必填 说明
context BaseContext 是 当前应用的上下文。
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';

// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext。
let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
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}`);
});

openToneHaptics14+

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';

// 请在组件内获取context，确保this.getUIContext().getHostContext()返回结果为UIAbilityContext。
let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
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}`);
});

RingtonePlayer10+

type RingtonePlayer = _RingtonePlayer;

系统铃音播放器对象。

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

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

SystemTonePlayer11+

type SystemTonePlayer = _SystemTonePlayer;

系统提示音播放器对象。

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

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

RingtoneOptions10+

type RingtoneOptions = _RingtoneOptions;

系统铃音播放器配置项。

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

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

SystemToneOptions11+

type SystemToneOptions = _SystemToneOptions;

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

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

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

你可能感兴趣的鸿蒙文章

harmony 鸿蒙Audio Kit（音频服务）

harmony 鸿蒙Interface (AudioCapturer)

harmony 鸿蒙Interface (AudioManager)

harmony 鸿蒙Interface (AudioRenderer)

harmony 鸿蒙Interface (AudioRoutingManager)

harmony 鸿蒙Interface (AudioSessionManager)

harmony 鸿蒙Interface (AudioSpatializationManager)

harmony 鸿蒙Interface (AudioStreamManager)

harmony 鸿蒙Interface (AudioVolumeGroupManager)

harmony 鸿蒙Interface (AudioVolumeManager)

0  赞
  • 所属分类： 后端技术
  • 本文标签：
  • 版权声明： 原创文章如转载，请注明本文链接: https://www.seaxiang.com/blog/kS9Dz9
热门推荐
标签云
Linux Java Spring Spring Boot docker 大数据 前端 生活 maven golang 软件 spring cloud fintech mac vscode 其他 区块链 以太坊 V神 开发者 技术 股票 git greenplum 分布式事务 chrome mysql flink kafka 设计模式 原理 鸿蒙 seo
最新文章
本文目录