has.playBackgroundAudio(Object object)
使用后台播放器播放音乐。
返回桌面,仍保持播放;当遇到其他应用/元服务的音视频源,将暂停播放原有播放的音视频源。
起始版本: 1.0.9
需要权限: 开启后台音频播放,需要如下配置:
module.json5:
"module": {
"abilities": [
{
"backgroundModes": [
"audioPlayback"
]
}
]
} app.json:
"requiredBackgroundModes": ["audio"]
参数:
参数为Object对象,包括以下字段。
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
| dataUrl | string | 是 | 音乐链接,目前支持的格式有m4a、aac、mp3、ogg、wav、flac、amr,支持网络音频链接和本地音频文件路径(internal://开头)。 |
| title | string | 否 | 音乐标题。 |
| coverImgUrl | string | 否 | 封面URL。 |
| success | function | 否 | 接口调用成功的回调函数。 |
| fail | function | 否 | 接口调用失败的回调函数。 |
| complete | function | 否 | 接口调用结束的回调函数(调用成功、失败都会执行)。 |
| 错误码 | 错误信息 |
|---|---|
| 101 | AVPlayer is not initialized. |
| 102 | dataUrl is invalid or inaccessible. |
| 70002205 | state is not play. |
| 70002202 | AVPlayer play error. |
| 70002206 | AVPlayer can not reset. |
| 70002203 | AVPlayer reset error. |
| 70002201 | playBackgroundAudio error. 更多错误信息参考:Media错误码 |
示例:
has.playBackgroundAudio({
dataUrl: 'https://www.example.com/test.mp3', // 此处仅为样例,请开发者更换为可用的网址
title: '音乐标题',
coverImgUrl: 'https://www.example.com/test.png', // 此处仅为样例,请开发者更换为可用的网址
success: () => {
console.info('playBackgroundAudio success');
},
fail: (err) => {
console.error('playBackgroundAudio fail', err);
},
complete: (res) => {
console.info('playBackgroundAudio complete', res);
}
}); has.pauseBackgroundAudio(Object object)
暂停播放音乐。
起始版本: 1.0.9
参数:
参数为Object对象,包括以下字段。
| 属性 | 类型 | 必填 | 描述 |
|---|---|---|---|
| success | function | 否 | 接口调用成功的回调函数。 |
| fail | function | 否 | 接口调用失败的回调函数。 |
| complete | function | 否 | 接口调用结束的回调函数(调用成功、失败都会执行)。 |
错误码信息:
| 错误码 | 错误信息 |
|---|---|
| 101 | AVPlayer is not initialized. |
| 102 | AVPlayer can not be paused. |
| 70002402 | AVPlayer pause error. |
| 70002401 | pauseBackgroundAudio error. 更多错误信息参考:Media错误码 |
示例:
has.pauseBackgroundAudio({
success: () => {
console.info('pauseBackgroundAudio success');
},
fail: (err) => {
console.error('pauseBackgroundAudio fail', err);
},
complete: (res) => {
console.info('pauseBackgroundAudio complete', res);
}
}); has.seekBackgroundAudio(Object object)
控制音乐播放进度。
起始版本: 1.0.9
参数:
参数为Object对象,包括以下字段。
| 属性 | 类型 | 必填 | 描述 |
|---|---|---|---|
| position | number | 是 | 音乐跳转的位置,单位:s。精确到小数点后3位,支持ms级别精确度。 |
| success | function | 否 | 接口调用成功的回调函数。 |
| fail | function | 否 | 接口调用失败的回调函数。 |
| complete | function | 否 | 接口调用结束的回调函数(调用成功、失败都会执行)。 |
错误码信息:
| 错误码 | 错误信息 |
|---|---|
| 101 | AVPlayer is not initialized. |
| 70002302 | state is not seek. |
| 70002301 | seekBackgroundAudio error. 更多错误信息参考:Media错误码 |
示例:
has.seekBackgroundAudio({
position: 30,
success: () => {
console.info('seekBackgroundAudio success');
},
fail: (err) => {
console.error('seekBackgroundAudio fail', err);
},
complete: (res) => {
console.info('seekBackgroundAudio complete', res);
}
}); has.stopBackgroundAudio(Object object)
停止播放音乐。
起始版本: 1.0.9
参数:
参数为Object对象,包括以下字段。
| 属性 | 类型 | 必填 | 描述 |
|---|---|---|---|
| success | function | 否 | 接口调用成功的回调函数。 |
| fail | function | 否 | 接口调用失败的回调函数。 |
| complete | function | 否 | 接口调用结束的回调函数(调用成功、失败都会执行)。 |
错误码信息:
| 错误码 | 错误信息 |
|---|---|
| 101 | AVPlayer is not initialized. |
| 102 | AVPlayer can not be stop. |
| 70002502 | AVPlayer stop error. |
| 70002501 | stopBackgroundAudio error. 更多错误信息参考:Media错误码 |
示例:
has.stopBackgroundAudio({
success: () => {
console.info('stopBackgroundAudio success');
},
fail: (err) => {
console.error('stopBackgroundAudio fail', err);
},
complete: (res) => {
console.info('stopBackgroundAudio complete', res);
}
}); has.getBackgroundAudioPlayerState(Object object)
获取后台音乐播放状态。
起始版本: 1.0.9
参数:
参数为Object对象,包括以下字段。
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
| success | function | 否 | 接口调用成功的回调函数。 |
| fail | function | 否 | 接口调用失败的回调函数。 |
| complete | function | 否 | 接口调用结束的回调函数(调用成功、失败都会执行)。 |
success返回值:
| 参数 | 类型 | 描述 |
|---|---|---|
| duration | number | 选定音频的长度,单位:s。只有在音乐播放中时返回。 |
| currentPosition | number | 选定音频的播放位置,单位:s。只有在音乐播放中时返回。 |
| status | number | 播放状态。 0:暂停。 1:播放中。 2:没有音乐播放。 |
| downloadPercent | number | 音频的下载进度百分比,只有在音乐播放中时返回。 |
| dataUrl | string | 歌曲数据链接,只有在音乐播放中时返回。 |
错误码信息:
| 错误码 | 错误信息 |
|---|---|
| 101 | AVPlayer is not initialized. |
| 70002101 | getBackgroundAudioPlayerState error. |
示例:
has.getBackgroundAudioPlayerState({
success: (res) => {
console.info('getBackgroundAudioPlayerState success', res);
},
fail: (err) => {
console.error('getBackgroundAudioPlayerState fail', err);
},
complete: (res) => {
console.info('getBackgroundAudioPlayerState complete', res);
}
}); has.onBackgroundAudioPlay(function callback)
监听音乐播放事件。
起始版本: 1.0.9
参数:
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
| callback | function | 是 | 音乐播放事件的监听函数。 |
示例:
has.onBackgroundAudioPlay(() => {
console.info('onBackgroundAudioPlay callback triggered');
}); has.onBackgroundAudioPause(function callback)
监听音乐暂停事件。
起始版本: 1.0.9
参数:
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
| callback | function | 是 | 音乐暂停事件的监听函数。 |
示例:
has.onBackgroundAudioPause(() => {
console.info('onBackgroundAudioPause callback triggered');
}); has.onBackgroundAudioStop(function callback)
监听音乐停止事件。
起始版本: 1.0.9
参数:
| 参数 | 类型 | 必填 | 描述 |
|---|---|---|---|
| callback | function | 是 | 音乐停止事件的监听函数。 |
示例:
has.onBackgroundAudioStop(() => {
console.info('onBackgroundAudioStop callback triggered');
}); has.getBackgroundAudioManager(): BackgroundAudioManager
获取全局唯一的背景音频管理器。支持后台音频播放,元服务切入后台,如果音频处于播放状态,可以继续播放。
起始版本: 1.0.9
需要权限: 开启后台音频播放,需要如下配置:
module.json5:
"module": {
"abilities": [
{
"backgroundModes": [
"audioPlayback"
]
}
]
} 在app.json中配置requiredBackgroundModes属性。
app.json:
"requiredBackgroundModes": ["audio"]
返回值:
示例:
const backgroundAudioManager = has.getBackgroundAudioManager();