4d430a95创建于 2025年3月4日历史提交

systemTonePlayer (系统提示音播放器)(系统接口)

系统提示音播放器提供了短信提示音、通知提示音的播放、配置、获取信息等功能。

systemTonePlayer需要和@ohos.multimedia.systemSoundManager配合使用，才能完成管理系统提示音的功能。

说明：

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

本模块接口为系统接口。

导入模块

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

SystemToneOptions

提示音参数选项。

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

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

名称	类型	必填	说明
muteAudio	boolean	否	是否静音，true表示静音，false表示正常发声。
muteHaptics	boolean	否	是否震动，true表示无振动，false表示正常振动。

SystemTonePlayer

系统提示音播放器提供了短信提示音、通知提示音的播放、配置、获取信息等功能。在调用SystemTonePlayer的接口前，需要先通过getSystemTonePlayer创建实例。

getTitle

getTitle(): Promise<string>

获取提示音标题，使用Promise方式异步返回结果。

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

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

返回值：

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

错误码：

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

错误码ID	错误信息
202	Caller is not a system application.
5400103	I/O error.

示例：

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

systemTonePlayer.getTitle().then((value: string) => {
  console.info(`Promise returned to indicate that the value of the system tone player title is obtained ${value}.`);
}).catch ((err: BusinessError) => {
  console.error(`Failed to get the system tone player title ${err}`);
});

prepare

prepare(): Promise<void>

准备播放提示音，使用Promise方式异步返回结果。

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

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

返回值：

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

错误码：

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

错误码ID	错误信息
202	Caller is not a system application.
5400102	Operation not allowed.
5400103	I/O error.

示例：

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

systemTonePlayer.prepare().then(() => {
  console.info(`Promise returned to indicate a successful prepareing of system tone player.`);
}).catch ((err: BusinessError) => {
  console.error(`Failed to prepareing system tone player. ${err}`);
});

start

start(toneOptions?: SystemToneOptions): Promise<number>

开始播放提示音，使用Promise方式异步返回结果。

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

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

需要权限： ohos.permission.VIBRATE

参数：

参数名	类型	必填	说明
toneOptions	SystemToneOptions	否	系统提示音选项。

返回值：

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

错误码：

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

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

示例：

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

class SystemToneOptions {
  muteAudio: boolean = false;
  muteHaptics: boolean = false;
}
let systemToneOptions: SystemToneOptions = {muteAudio: true, muteHaptics: false};

systemTonePlayer.start(systemToneOptions).then((value: number) => {
  console.info(`Promise returned to indicate that the value of the system tone player streamID is obtained ${value}.`);
}).catch ((err: BusinessError) => {
  console.error(`Failed to start system tone player. ${err}`);
});

stop

stop(id: number): Promise<void>

停止播放提示音，使用Promise方式异步返回结果。

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

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

参数：

参数名	类型	必填	说明
id	number	是	start方法返回的streamID。

返回值：

类型	说明
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.
5400102	Operation not allowed.

示例：

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

let streamID: number = 0; //streamID为start方法返回的streamID,此处只做初始化。
systemTonePlayer.stop(streamID).then(() => {
  console.info(`Promise returned to indicate a successful stopping of system tone player.`);
}).catch ((err: BusinessError) => {
  console.error(`Failed to stop system tone player. ${err}`);
});

release

release(): Promise<void>

释放提示音播放器，使用Promise方式异步返回结果。

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

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

返回值：

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

错误码：

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

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

示例：

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

systemTonePlayer.release().then(() => {
  console.info(`Promise returned to indicate a successful releasing of system tone player.`);
}).catch ((err: BusinessError) => {
  console.error(`Failed to release system tone player. ${err}`);
});

setAudioVolumeScale¹³⁺

setAudioVolumeScale(scale: number): void

设置音频音量大小，无返回结果。

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

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

参数：

参数名	类型	必填	说明
scale	number	是	音频音量大小，必须在[0, 1]之间取值。

错误码：

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

错误码ID	错误信息
202	Caller is not a system application.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types.
5400102	Operation not allowed.
20700002	Parameter check error, For example, value is out side [0, 1]

示例：

let scale: number = 0.5;
try {
  systemTonePlayer.setAudioVolumeScale(scale);
} catch (err) {
  console.error(`Failed to set audio volume scale. ${err}`);
}

getAudioVolumeScale¹³⁺

getAudioVolumeScale(): number;

获取当前音频音量大小，同步返回当前音量。

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

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

返回值：

类型	说明
number	当前音频音量。

错误码：

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

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

示例：

try {
  let scale: number = systemTonePlayer.getAudioVolumeScale();
  console.info(` get audio volume scale. ${scale}`);
} catch (err) {
  console.error(`Failed to get audio volume scale. ${err}`);
}

getSupportedHapticsFeatures¹³⁺

getSupportedHapticsFeatures(): Promise<Array<systemSoundManager.ToneHapticsFeature>>

获取当前支持的振动风格，使用Promise方式异步返回支持的振动风格列表。

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

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

返回值：

类型	说明
Promise<Array<systemSoundManager.ToneHapticsFeature>>	Promise回调返回当前支持的振动风格。

错误码：

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

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

示例：

try {
  let features: Array<systemSoundManager.ToneHapticsFeature> = await systemTonePlayer.getSupportedHapticsFeatures();
  console.info(` get supported haptics features. ${features}`);
} catch (err) {
  console.error(`Failed to get supported haptics features. ${err}`);
}

setHapticsFeature¹³⁺

setHapticsFeature(hapticsFeature: systemSoundManager.ToneHapticsFeature): void

设置播放铃音时的振动风格。

调用本接口前，应该先调用getSupportedHapticsFeatures查询支持的振动风格，如果设置不支持的振动风格，则设置失败。

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

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

参数名	类型	必填	说明
hapticsFeature	systemSoundManager.ToneHapticsFeature	是	振动风格。

错误码：

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

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

示例：

try {
  let features: Array<systemSoundManager.ToneHapticsFeature> = await systemTonePlayer.getSupportedHapticsFeatures();
  if (features.lenght == 0) {
    return;
  }
  let feature: systemSoundManager.ToneHapticsFeature = features[0];
  systemTonePlayer.setHapticsFeature(feature);
  console.info(` set haptics feature success`);
} catch (err) {
  console.error(`Failed to set haptics feature. ${err}`);
}

getHapticsFeature¹³⁺

getHapticsFeature(): systemSoundManager.ToneHapticsFeature

获取播放铃音时的振动风格，同步返回振动风格枚举值。

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

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

返回值：

类型	说明
systemSoundManager.ToneHapticsFeature	振动风格

错误码：

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

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

示例：

try {
  let feature: systemSoundManager.ToneHapticsFeature = systemTonePlayer.getHapticsFeature();
  console.info(` get haptics feature success. ${features}`);
} catch (err) {
  console.error(`Failed to get haptics feature. ${err}`);
}

on('playFinished')¹⁸⁺

on(type: 'playFinished', streamId: number, callback: Callback<number>): void

铃音播放完成监听，监听对象为传入的streamId对应音频流。当streamId传入0时，监听本播放器对应的所有音频流。

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

参数：

参数名	类型	必填	说明
type	string	是	支持事件：'playFinished'。音频流播放完成会触发此回调，需要传入监听的音频流的streamId。
streamId	number	是	监听对象为指定streamId对应的音频流，streamId通过start获取。当streamId传入0时，可监听当前播放器对应的所有音频流。
callback	Callback<number>	是	'playFinished'的回调方法。返回播放完成的音频流的streamId。

错误码：

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

错误码ID	错误信息
202	Not system App.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types.
20700002	Parameter check error.

示例：

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

// 监听所有音频流的结束事件。
systemTonePlayer.on('playFinished', 0, (streamId: number) => {
  console.info(`Receive the callback of playFinished, streamId: ${streamId}.`);
});

// 监听指定音频流的结束事件。
systemTonePlayer.start().then((value: number) => {
  systemTonePlayer.on('playFinished', value, (streamId: number) => {
    console.info(`Receive the callback of playFinished, streamId: ${streamId}.`);
  });
}).catch((err: BusinessError) => {
  console.error(`Failed to start system tone player. ${err}`);
});

off('playFinished')¹⁸⁺

off(type: 'playFinished', callback?: Callback<number>): void

取消铃音播放完成监听。

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

参数：

参数名	类型	必填	说明
type	string	是	要取消监听事件的类型。支持事件为：'playFinished'。
callback	Callback<number>	否	回调函数，返回结束事件的音频流的streamId。不填入此参数时，会取消该事件的所有监听。

错误码：

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

错误码ID	错误信息
202	Not system App.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types.
20700002	Parameter check error.

示例：

// 取消该事件的所有监听。
systemTonePlayer.off('playFinished');

// 同一监听事件中，on方法和off方法传入callback参数一致，off方法取消对应on方法订阅的监听。
let playFinishedCallback = (streamId: number) => {
  console.info(`Receive the callback of playFinished, streamId: ${streamId}.`);
};

systemTonePlayer.on('playFinished', 0, playFinishedCallback);

systemTonePlayer.off('playFinished', playFinishedCallback);

on('error')¹⁸⁺

on(type: 'error', callback: ErrorCallback): void

铃音播放播放过程中的错误事件监听。

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

参数：

参数名	类型	必填	说明
type	string	是	监听的事件类型。支持事件为：error事件。
callback	ErrorCallback	是	回调函数，返回错误码和错误信息。错误码请参考AVPlayer的on('error')。

错误码：

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

错误码ID	错误信息
202	Not system App.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types.
20700002	Parameter check error.

示例：

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

systemTonePlayer.on('error', (err: BusinessError) => {
  console.log("on error, err:" + JSON.stringify(err));
});

off('error')¹⁸⁺

off(type: 'error', callback?: ErrorCallback): void

取消铃音播放播放过程中的错误事件监听。

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

参数：

参数名	类型	必填	说明
type	string	是	要取消监听事件的类型。支持的事件为：error事件。
callback	ErrorCallback	否	回调函数，返回错误码和错误信息。不填入此参数时，会取消该事件的所有监听。

错误码：

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

错误码ID	错误信息
202	Not system App.
401	Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types.
20700002	Parameter check error.

示例：

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

// 取消该事件的所有监听。
systemTonePlayer.off('error');

// 同一监听事件中，on方法和off方法传入callback参数一致，off方法取消对应on方法订阅的监听。
let callback = (err: BusinessError) => {
  console.log("on error, err:" + JSON.stringify(err));
};

systemTonePlayer.on('error', callback);

systemTonePlayer.off('error', callback);

systemTonePlayer (系统提示音播放器)(系统接口)

导入模块

SystemToneOptions

SystemTonePlayer

getTitle

prepare

start

stop

release

setAudioVolumeScale13+

getAudioVolumeScale13+

getSupportedHapticsFeatures13+

setHapticsFeature13+

getHapticsFeature13+

on('playFinished')18+

off('playFinished')18+

on('error')18+

off('error')18+

setAudioVolumeScale¹³⁺

getAudioVolumeScale¹³⁺

getSupportedHapticsFeatures¹³⁺

setHapticsFeature¹³⁺

getHapticsFeature¹³⁺

on('playFinished')¹⁸⁺

off('playFinished')¹⁸⁺

on('error')¹⁸⁺

off('error')¹⁸⁺