1# systemTonePlayer (系统提示音播放器)(系统接口) 2 3系统提示音播放器提供了短信提示音、通知提示音的播放、配置、获取信息等功能。 4 5systemTonePlayer需要和[@ohos.multimedia.systemSoundManager](js-apis-systemSoundManager-sys.md)配合使用，才能完成管理系统提示音的功能。 6 7> **说明：** 8> 9> - 本模块首批接口从API version 11开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 10> - 本模块接口为系统接口。 11 12## 导入模块 13 14```ts 15import { systemSoundManager } from '@kit.AudioKit'; 16``` 17 18## SystemToneOptions 19 20提示音参数选项。 21 22**系统接口：** 该接口为系统接口 23 24**系统能力：** SystemCapability.Multimedia.SystemSound.Core 25 26| 名称 | 类型 | 必填 | 说明 | 27| --------- | -------------- |---|---------------------------| 28| muteAudio | boolean | 否 | 是否静音，true表示静音，false表示正常发声。 | 29| muteHaptics | boolean | 否 | 是否震动，true表示无振动，false表示正常振动。 | 30 31## SystemTonePlayer 32 33系统提示音播放器提供了短信提示音、通知提示音的播放、配置、获取信息等功能。在调用SystemTonePlayer的接口前，需要先通过[getSystemTonePlayer](js-apis-systemSoundManager-sys.md#getsystemtoneplayer11)创建实例。 34 35### getTitle 36 37getTitle(): Promise<string> 38 39获取提示音标题，使用Promise方式异步返回结果。 40 41**系统接口：** 该接口为系统接口 42 43**系统能力：** SystemCapability.Multimedia.SystemSound.Core 44 45**返回值：** 46 47| 类型 | 说明 | 48| --------------------- | -------------------------------- | 49| Promise<string> | Promise回调返回获取的系统提示音标题。 | 50 51**错误码：** 52 53以下错误码的详细介绍请参见[媒体服务错误码](../apis-media-kit/errorcode-media.md)。 54 55| 错误码ID | 错误信息 | 56| ------- | --------------------- | 57| 202 | Caller is not a system application. | 58| 5400103 | I/O error. | 59 60**示例：** 61 62```ts 63import { BusinessError } from '@kit.BasicServicesKit'; 64 65systemTonePlayer.getTitle().then((value: string) => { 66 console.info(`Promise returned to indicate that the value of the system tone player title is obtained ${value}.`); 67}).catch ((err: BusinessError) => { 68 console.error(`Failed to get the system tone player title ${err}`); 69}); 70``` 71 72### prepare 73 74prepare(): Promise<void> 75 76准备播放提示音，使用Promise方式异步返回结果。 77 78**系统接口：** 该接口为系统接口 79 80**系统能力：** SystemCapability.Multimedia.SystemSound.Core 81 82**返回值：** 83 84| 类型 | 说明 | 85| ------------------- | -------------------------------- | 86| Promise<void> | Promise回调返回准备成功或失败。 | 87 88**错误码：** 89 90以下错误码的详细介绍请参见[媒体服务错误码](../apis-media-kit/errorcode-media.md)。 91 92| 错误码ID | 错误信息 | 93| ------- | --------------------- | 94| 202 | Caller is not a system application. | 95| 5400102 | Operation not allowed. | 96| 5400103 | I/O error. | 97 98**示例：** 99 100```ts 101import { BusinessError } from '@kit.BasicServicesKit'; 102 103systemTonePlayer.prepare().then(() => { 104 console.info(`Promise returned to indicate a successful prepareing of system tone player.`); 105}).catch ((err: BusinessError) => { 106 console.error(`Failed to prepareing system tone player. ${err}`); 107}); 108``` 109 110### start 111 112start(toneOptions?: SystemToneOptions): Promise<number> 113 114开始播放提示音，使用Promise方式异步返回结果。 115 116**系统接口：** 该接口为系统接口 117 118**系统能力：** SystemCapability.Multimedia.SystemSound.Core 119 120**需要权限：** ohos.permission.VIBRATE 121 122**参数：** 123 124| 参数名 | 类型 | 必填 | 说明 | 125| -------- |-----------------------------------------|--| ------------------------- | 126| toneOptions | [SystemToneOptions](#systemtoneoptions) | 否 | 系统提示音选项。 | 127 128**返回值：** 129 130| 类型 | 说明 | 131| ------------------- | ------------------------------- | 132| Promise<number> | Promise回调返回streamID。 | 133 134**错误码：** 135 136以下错误码的详细介绍请参见[媒体服务错误码](../apis-media-kit/errorcode-media.md)。 137 138| 错误码ID | 错误信息 | 139| ------- | --------------------- | 140| 201 | Permission denied. | 141| 202 | Caller is not a system application. | 142| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 143| 5400102 | Operation not allowed. | 144 145**示例：** 146 147```ts 148import { BusinessError } from '@kit.BasicServicesKit'; 149 150class SystemToneOptions { 151 muteAudio: boolean = false; 152 muteHaptics: boolean = false; 153} 154let systemToneOptions: SystemToneOptions = {muteAudio: true, muteHaptics: false}; 155 156systemTonePlayer.start(systemToneOptions).then((value: number) => { 157 console.info(`Promise returned to indicate that the value of the system tone player streamID is obtained ${value}.`); 158}).catch ((err: BusinessError) => { 159 console.error(`Failed to start system tone player. ${err}`); 160}); 161``` 162 163### stop 164 165stop(id: number): Promise<void> 166 167停止播放提示音，使用Promise方式异步返回结果。 168 169**系统接口：** 该接口为系统接口 170 171**系统能力：** SystemCapability.Multimedia.SystemSound.Core 172 173**参数：** 174 175| 参数名 | 类型 | 必填 | 说明 | 176| -------- |-----------------------------------------|--| ------------------------- | 177| id | number | 是 | start方法返回的streamID。 | 178 179**返回值：** 180 181| 类型 | 说明 | 182| ------------------- | -------------------------------- | 183| Promise<void> | Promise回调返回停止播放成功或失败。 | 184 185**错误码：** 186 187以下错误码的详细介绍请参见[媒体服务错误码](../apis-media-kit/errorcode-media.md)。 188 189| 错误码ID | 错误信息 | 190| ------- | --------------------- | 191| 202 | Caller is not a system application. | 192| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 193| 5400102 | Operation not allowed. | 194 195**示例：** 196 197```ts 198import { BusinessError } from '@kit.BasicServicesKit'; 199 200let streamID: number = 0; //streamID为start方法返回的streamID,此处只做初始化。 201systemTonePlayer.stop(streamID).then(() => { 202 console.info(`Promise returned to indicate a successful stopping of system tone player.`); 203}).catch ((err: BusinessError) => { 204 console.error(`Failed to stop system tone player. ${err}`); 205}); 206``` 207 208### release 209 210release(): Promise<void> 211 212释放提示音播放器，使用Promise方式异步返回结果。 213 214**系统接口：** 该接口为系统接口 215 216**系统能力：** SystemCapability.Multimedia.SystemSound.Core 217 218**返回值：** 219 220| 类型 | 说明 | 221| ------------------- | ------------------------------- | 222| Promise<void> | Promise回调返回释放成功或失败。 | 223 224**错误码：** 225 226以下错误码的详细介绍请参见[媒体服务错误码](../apis-media-kit/errorcode-media.md)。 227 228| 错误码ID | 错误信息 | 229| ------- | --------------------- | 230| 202 | Caller is not a system application. | 231 232**示例：** 233 234```ts 235import { BusinessError } from '@kit.BasicServicesKit'; 236 237systemTonePlayer.release().then(() => { 238 console.info(`Promise returned to indicate a successful releasing of system tone player.`); 239}).catch ((err: BusinessError) => { 240 console.error(`Failed to release system tone player. ${err}`); 241}); 242```