music

基础类

authorizationForMusic requestAuthorization scanMusic copyToSandbox cancelCopyToSandbox cleanCach presentMusic

概述

在 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/04/24