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

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

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

说明：

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

导入模块

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

SystemToneOptions

提示音参数选项。

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

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

SystemTonePlayer

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

getTitle

getTitle(): Promise<string>

获取提示音标题。使用Promise异步回调。

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

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

返回值：

错误码：

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

示例：

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

返回值：

错误码：

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

示例：

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

参数：

返回值：

错误码：

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

示例：

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

参数：

返回值：

错误码：

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

示例：

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

返回值：

错误码：

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

示例：

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

参数：

错误码：

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

示例：

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

返回值：

错误码：

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

示例：

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

返回值：

错误码：

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

示例：

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

参数：

错误码：

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

示例：

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

返回值：

错误码：

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

示例：

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

监听铃音播放完成事件（当铃音播放完成时触发）。使用callback异步回调。

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

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

参数：

错误码：

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

示例：

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

取消监听铃音播放完成事件。使用callback异步回调。

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

参数：

错误码：

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

示例：

// 取消该事件的所有监听。
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

监听铃音播放过程中的错误事件（当铃音播放过程中发生错误时触发）。使用callback异步回调。

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

参数：

错误码：

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

示例：

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

取消监听铃音播放过程中的错误事件。使用callback异步回调。

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

参数：

错误码：

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

示例：

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

你可能感兴趣的鸿蒙文章

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)