music

基础类

概述

在 iOS 端,系统自带有音乐播放的 App ,名字叫 Music。用户可以删除该 App,也可以在 Apple Store 搜索下载该 App。music 原生插件封装了 iOS 平台上访问音乐库的相关接口。通过本原生插件可以判断当前 App 访问音乐权限,并支持扫描并获取 Music 里的被授权的音频文件。注意,由于知识产权原因,并不是所有 Music 内的音频文件都能获取,从苹果音乐服务器下载的音频文件获取不到,只能获取通过电脑同步到 Music 这个 App 里的音频文件。

使用本原生插件,需在云编译时申请访问音乐库权限。否则调用本原生插件接口会闪退,上传 App Store 也会被拒。

** authorizationForMusic**

判断是否有访问音乐库权限

authorizationForMusic(callback(ret))

callback(ret)

ret:

  • 类型:JSON 对象
  • 内部字段:
{ 
    status: ''      //字符串类型;权限详情,取值范围如下:
                     //notDetermined: 用户从未选择过权限
                     //restricted:无法使用音乐库服务,该状态用户无法改变
                     //denied:户拒绝该应用使用音乐库服务
                     //authorized:用户允许该程序访问音乐库
}

示例代码

var music = api.require('music');
music.authorizationForMusic(function(ret) {
    if (ret) {
        api.alert({
            msg: JSON.stringify(ret)
        })
    }
});

可用性

iOS 系统

可提供的 1.0.0 及更高版本

** requestAuthorization**

请求访问音乐库权限

requestAuthorization(callback(ret))

callback(ret)

ret:

  • 类型:JSON 对象
  • 内部字段:
{ 
    status: ''      //字符串类型;权限详情,取值范围如下:
                     //notDetermined: 用户从未选择过权限
                     //restricted:无法使用音乐库服务,该状态用户无法改变
                     //denied:户拒绝该应用使用音乐库服务
                     //authorized:用户允许该程序访问音乐库
}

示例代码

var music = api.require('music');
music.requestAuthorization(function(ret) {
    if (ret) {
        api.alert({
            msg: JSON.stringify(ret)
        })
    }
});

可用性

iOS 系统

可提供的 1.0.0 及更高版本

scanMusic

扫描 Music 内的音频文件

scanMusic({params},callback(ret, err))

params

thumbnail:

  • 类型:JSON 对象
  • 描述:返回的缩略图(若不存在则返回空)大小,若不传本参数则不返回缩略图,注意返回缩略图会降低读取速度
  • 内部字段:
{
   width: ,      //(可选项)缩略图宽度;默认:72
   height:       //(可选项)缩略图高度;默认:72
}

iCloud:

  • 类型:布尔
  • 描述:是否包含 iCloud 音乐
  • 默认:false

callback(ret, err)

ret:

  • 类型:JSON 对象
  • 内部字段:
{
     status: true,        //布尔型;是否获取成功 
     audios:[{           //数组类型;获取的音频资源信息组成的数组
       artist: '',       //字符串类型;音频作者
       title: '',        //字符串类型;音频标题
       url: '',          //字符串类型;音频地址
       albumTitle: ''    //字符串类型;音频专辑
       duration:,        //数字类型;音频时长;单位:毫秒
       thumbnail:        //字符串类型;缩略图路径
    }]
}

err:

  • 类型:JSON 对象
  • 内部字段:
{
    code:1    //数字类型;错误码:
              //1:无访问音乐库权限 
}

示例代码

var music = api.require('music');
music.scanMusic({
    thumbnail:{
       width:72,
       height:72
    },
    iCloud:false
},function(ret, err) {
    if (ret.status) {
        api.alert({msg:JSON.stringify(ret)});
    } else {
        api.alert({msg:JSON.stringify(err)});
    }
});

可用性

iOS 系统

可提供的 1.0.0 及更高版本

copyToSandbox

将音乐库的音频文件拷贝到沙盒

copyToSandbox({params},callback(ret, err))

params

url:

  • 类型:字符串
  • 描述:音乐库音频文件路径,如:ipod-library://item/item.mp3?id=4559289265963493915

savePath:

  • 类型:字符串
  • 描述:(可选项)保存路径,要求本地路径(fs://),如:fs://music/m1.mp3
  • 默认:默认缓存路径

callback(ret, err)

ret:

  • 类型:JSON 对象
  • 内部字段:
{
     status: true,       //布尔型;是否拷贝成功 
     realPath:           //字符串类型;路径类型 
}

err:

  • 类型:JSON 对象
  • 内部字段:
{
    code:1    //数字类型;错误码:
              //1:url为空
              //2:资源初始化失败 
              //3:资源读取失败 
}

示例代码

var music = api.require('music');
music.copyToSandbox({ 
    url:'ipod-library://item/item.mp3?id=4559289265963493915'
},function(ret, err) {
    if (ret.status) {
        api.alert({msg:JSON.stringify(ret)});
    } else {
        api.alert({msg:JSON.stringify(err)});
    }
});

可用性

iOS 系统

可提供的 1.0.0 及更高版本

cancelCopyToSandbox

取消音乐库的音频文件拷贝到沙盒

cancelCopyToSandbox(callback(ret, err))

callback(ret, err)

ret:

  • 类型:JSON 对象
  • 内部字段:
{
     status: true   //布尔型;true:取消成功,false:当前未有拷贝中的音频  
}

示例代码

var music = api.require('music');
music.cancelCopyToSandbox(function(ret) {
    if (ret.status) {
        api.alert({msg:'取消成功'});
    } else {
        api.alert({msg:'当前未有拷贝中的音频'});
    }
});

可用性

iOS 系统

可提供的 1.0.0 及更高版本

cleanCach

清空缓存

cleanCach({params},callback(ret, err))

params

url:

  • 类型:字符串
  • 描述:清空的缓存的目标
  • 默认:all
  • 取值范围:
    • all:音频和缩略图
    • thumbnail:缩略图
    • audio:音频

callback(ret, err)

ret:

  • 类型:JSON 对象
  • 内部字段:
{
     status: true,       //布尔型;是否清除成功  
}

err:

  • 类型:JSON 对象
  • 内部字段:
{
    code:1    //数字类型;错误码: 
    userInfo:'' //字符串类型;错误信息
}

示例代码

var music = api.require('music');
music.cleanCach({ 
    target:'all'
},function(ret, err) {
    if (ret.status) {
        api.alert({msg:'清除成功'});
    } else {
        api.alert({msg:JSON.stringify(err)});
    }
});

可用性

iOS 系统

可提供的 1.0.0 及更高版本

presentMusic

弹出系统自带选择音频页面

presentMusic({params},callback(ret, err))

params

multiple:

  • 类型:字符串
  • 描述:是否多选
  • 默认:true

showsCloudItems:

  • 类型:字符串
  • 描述:是否显示云端资源
  • 默认:true

thumbnail:

  • 类型:JSON 对象
  • 描述:返回的缩略图(若不存在则返回空)大小,若不传本参数则不返回缩略图,注意返回缩略图会降低读取速度
  • 内部字段:
{
   width: ,      //(可选项)缩略图宽度;默认:72
   height:       //(可选项)缩略图高度;默认:72
}

callback(ret)

ret:

  • 类型:JSON 对象
  • 内部字段:
{
      eventType:'show',   //字符串类型;交互事件类型
                          //show:弹出选择界面
                          //cancel:用户取消
                          //selected:用户选择完成
      audios:[{           //数组类型;获取的音频资源信息组成的数组,仅当 eventType 为 selected 时有值
       artist: '',       //字符串类型;音频作者
       title: '',        //字符串类型;音频标题
       url: '',          //字符串类型;音频地址
       albumTitle: ''    //字符串类型;音频专辑
       duration:,        //数字类型;音频时长;单位:毫秒
       thumbnail:        //字符串类型;缩略图路径
    }]
}

示例代码

var music = api.require('music');
music.presentMusic({ 
    multiple:true,
    showsCloudItems:true
},function(ret) {
    if (ret) {
        api.alert({msg:JSON.stringify(ret)});
    } 
});

可用性

iOS 系统

可提供的 1.0.0 及更高版本

是否仍需要帮助? 请保持联络!
最后更新于 2024/10/10