Skip to content

D
Docs

OpenHarmony / Docs
1 年多 前同步成功

通知 159
Star 292
Fork 28
D
Docs
切换分支/标签
查找文件 普通视图历史永久链接Permalink
js-apis-systemSoundManager.md 10.0 KB
Newer Older
S
Add the apis reference for ringtone manager  
songshenke 已提交
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 
# @ohos.multimedia.systemSoundManager (系统声音管理)

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

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

## 导入模块

```js
import systemSoundManager from '@ohos.multimedia.systemSoundManager';
```

## RingtoneType

枚举，铃声类型。

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

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

| 名称                            |  值     | 说明                                         |
| ------------------------------- | ------ | -------------------------------------------- |
| RINGTONE_TYPE_DEFAULT           | 0      | 默认铃声类型。                                 |
| RINGTONE_TYPE_MULTISIM          | 1      | 多SIM卡铃声类型。                              |

## systemSoundManager.getSystemSoundManager

getSystemSoundManager(): SystemSoundManager

获取系统声音管理器。

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

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

**返回值：**

| 类型                          | 说明         |
| ----------------------------- | ------------ |
| [SystemSoundManager](#systemsoundmanager) | 系统声音管理类。 |

**示例：**
```js
let systemSoundManagerInstance = systemSoundManager.getSystemSoundManager();
```

## SystemSoundManager

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

### setSystemRingtoneUri

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

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

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

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

**参数：**

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

**示例：**

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

systemSoundManagerInstance.setSystemRingtoneUri(context, uri, type, (err) => {
  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

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

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

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

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

**参数：**

| 参数名   | 类型                                      | 必填 | 说明                     |
| -------- | ---------------------------------------- | ---- | ------------------------ |
| context  | Context                                  | 是   | 当前应用的上下文。         |
| uri      | string                                   | 是   | 被设置的系统铃声的uri，资源支持可参考[media.AVPlayer](js-apis-media.md#avplayer9)。 |
| type     | [RingtoneType](#ringtonetype)            | 是   | 被设置的系统铃声的类型。   |

**返回值：**

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

**示例：**

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

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

### getSystemRingtoneUri

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

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

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

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

**参数：**

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

**示例：**

```js
let context = this.context;
let type = systemSoundManager.RingtoneType.RINGTONE_TYPE_DEFAULT;

systemSoundManagerInstance.getSystemRingtoneUri(context, type, (err, value) => {
  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

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

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

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

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

**参数：**

| 参数名   | 类型                                      | 必填 | 说明                     |
| -------- | ---------------------------------------- | ---- | ------------------------ |
| context  | Context                                  | 是   | 当前应用的上下文。         |
| type     | [RingtoneType](#ringtonetype)            | 是   | 被设置的系统铃声的类型。   |

**返回值：**

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

**示例：**

```js
let context = this.context;
let type = systemSoundManager.RingtoneType.RINGTONE_TYPE_DEFAULT;

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

### getSystemRingtonePlayer

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

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

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

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

**参数：**

| 参数名   | 类型                                      | 必填 | 说明                         |
| -------- | -----------------------------------------| ---- | --------------------------- |
| context  | Context                                  | 是   | 当前应用的上下文。            |
| type     | [RingtoneType](#ringtonetype)            | 是   | 待获取播放器的系统铃声的类型。 |
| callback | AsyncCallback<[RingtonePlayer](js-apis-inner-multimedia-ringtonePlayer.md#ringtoneplayer)> | 是 | 回调返回获取的系统铃声播放器。 |

**示例：**

```js
let context = this.context;
let type = systemSoundManager.RingtoneType.RINGTONE_TYPE_DEFAULT;
let systemRingtonePlayer = null;

systemSoundManagerInstance.getSystemRingtonePlayer(context, type, (err, value) => {
  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

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

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

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

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

**参数：**

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

**返回值：**

| 类型                | 说明                            |
| ------------------- | ------------------------------- |
| Promise<[RingtonePlayer](js-apis-inner-multimedia-ringtonePlayer.md#ringtoneplayer)> | Promise回调返回获取的系统铃声播放器。 |

**示例：**

```js
let context = this.context;
let type = systemSoundManager.RingtoneType.RINGTONE_TYPE_DEFAULT;
let systemRingtonePlayer = null;

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