UIAlbumSelector

立即使用

概述

UIAlbumSelector 是一个本地媒体资源扫描器,在 Android 平台上可扫描整个设备的资源,iOS 仅扫描相册内的资源。本模块仅支持对本地图片资源的浏览、读取,目前尚不支持编辑。注意本模块在iPhone设备上仅支持 iOS8.0 及以上版本。

由于系统平台差异,iOS 上和 android 上相册分组策略有所不同。

iOS 上系统相册分组策略如下:
相机胶卷(All组):  a,b,c,d,e,f,g
A组:a
B组:b,c
C组:f,g

android 上系统相册分组策略如下:
A组:a
B组:b,c
C组:d,e,f,g

因此,若要在 android 平台上显示 All 组,开发者需自行组合。

本模块封装了三种方案。

方案一:

通过 open 接口打开一个自带 UI 界面的媒体资源浏览页面,相当于打开了一个 window 。当用户选择指定媒体资源,可返回绝对路径给前端开发者。前端开发者可通过此绝对路径读取指定媒体资源文件。注意:在 iOS 平台上需要先调用 transPaths、transVideoPath 接口将路径转换之后才能读取目标资源媒体文件。

open接口UI open接口UI

方案二:

通过 scan 接口扫描指定数量的媒体资源文件,本接口是纯功能类接口,不带界面。开发者可根据此接口扫描到的文件自行开发展示页面,极大的提高了自定义性。注意展示页面要做成赖加载模式,以免占用内存过高导致 app 假死。懒加载模式可通过 fetch 接口实现持续向下加载更多功能。

方案三:

先通过 scanGroups 接口,获取一共有多少分组,然后用 scanByGroupId、fetchGroup 接口按组读取资源信息,接下来的逻辑流程类似方案二。

注意:使用本模块前需在云编译页面添加勾选访问相册权限,否则会有崩溃闪退现象

模块接口

authorizationStatus

判断当前 App 访问系统相册权限

authorizationStatus(callback(ret))

callback(ret)

ret:

  • 类型:JSON 对象
  • 内部字段:
{
    details: ''      //字符串类型;权限详情,取值范围如下:
                     //notDetermined: 用户从未选择过权限
                     //restricted:无法访问手机相册,该状态用户无法改变
                     //denied:户拒绝该应用访问手机相册,或是访问手机相册服务总开关处于关闭状态
                     //authorized:用户允许该程序可以访问手机相册
}

示例代码

var UIAlbumSelector = api.require('UIAlbumSelector');
UIAlbumSelector.authorizationStatus({
}, function(ret) {
    if (ret) {
        api.alert({msg:JSON.stringify(ret)});
    } 
});

可用性

iOS 系统

可提供的 1.0.0 及更高版本

open

打开多媒体资源选择器,打开后会全屏显示

注意:iOS 平台上获取的path、gifPath、videoPath需要用 transPaths、transVideoPath 接口转换之后才可读取资源

open({params}, callback(ret))

params

maxAlert:

  • 类型:JSON对象
  • 描述:(可选项)超出设置的最大选取数时的提示
  • 内部字段:
{
    max:,           //(可选项)数字类型;最多选择几张图片/视频,超出时模块弹出提示框,当为1时则为单选模式,自动取消上次选中项;默认:9
    prompt:'',      //(可选项)字符串类型;提示语;默认:你最多只能选*张照片,其中*号会自动匹配 max
    pColor:'',      //(可选项)字符串类型;提示语文字颜色,支持rgb、rgba、#;默认:
    pSize:,         //(可选项)数字类型;提示语字体大小;默认:12
    btnTitle:'',    //(可选项)字符串类型;提示框关闭按钮标题;默认:我知道了
    btnColor:'',    //(可选项)字符串类型;关闭按钮文字颜色,支持rgb、rgba、#;默认:
    btnSize:,       //(可选项)数字类型;关闭按钮字体大小;默认:14
    bg:'',          //(可选项)字符串类型;弹框背景色,支持rgb、rgba、#;默认:
    corner:         //(可选项)数字类型;弹框圆角大小;默认:3
}

type:

  • 类型:字符串
  • 描述:(可选项)显示图片或视频
  • 取值范围:
    • all(图片和视频)
    • image(图片)
    • video(视频)

selectedAll:

  • 类型:布尔
  • 描述:(可选项)当type为all时,视频和图片能不能同时选中,仅当type为all时本参数有意义。若为false则非首选资源类型元素上置有遮罩层变为不可选状态
  • 默认:true

styles:

  • 类型:JSON 对象
  • 描述:(可选项)模块各部分的样式配置
  • 内部字段:
{
    bg: '#FFFFFF',              //(可选项)字符串类型;资源选择器背景,支持 rgb,rgba,#;默认:'#FFFFFF'
    mark: {                     //(可选项)JSON对象;选中图标的样式
        unselected:'',          //(可选项)字符串类型;未选中图标路径(本地路径,支持fs://、widget://);默认:圆形灰色对勾图标
        selected: '',           //(可选项)字符串类型;选中图标路径(本地路径,支持fs://、widget://);默认:圆形绿色对勾图标                      

        position: ' ',          //(可选项)字符串类型;图标的位置,默认:'bottom_left'
                                // 取值范围:
                                // top_left(左上角)
                                // bottom_left(左下角)
                                // top_right(右上角)
                                // bottom_right(右下角)
        size: 20                //(可选项)数字类型;图标的大小;默认:显示的缩略图的宽度的三分之一
    },
    nav: {                      //(可选项)JSON对象;导航栏样式
        bg: '#eee',             //(可选项)字符串类型;导航栏背景,支持 rgb,rgba,#;默认:'rgba(0,0,0,0.6)'
        title:'',               //(可选项)字符串类型;标题;默认:选择图片
        titleColor: '#fff',     //(可选项)字符串类型;标题文字颜色,支持 rgb,rgba,#;默认:'#fff'
        titleSize: 18,          //(可选项)数字类型;标题文字大小,默认:18 
    },
       confirmButton: {         //(可选项)JSON对象;底部确定按钮样式 
        width:,                 //(可选项)数字类型;宽度;默认:屏幕宽度-20
        height:,                //(可选项)数字类型;高度 ;默认:44
        corner:,                //(可选项)数字类型;按钮圆角大小;默认:22
        bg: ' ',                //(可选项)字符串类型;按钮背景,支持 rgb,rgba,#;默认:
        selected:' ',           //(可选项)字符串类型;按钮选中背景色,支持 rgb,rgba,#;默认:
        title:'确定',            //(可选项)字符串类型;选择图片或视频的预览的文字;默认:'确定'
        titleColor: '#fff',      //(可选项)字符串类型;标题文字颜色,支持 rgb,rgba,#;默认:'#fff'
        titleSize: 14,           //(可选项)数字类型;标题文字大小,默认:14 
    }
}

callback(ret)

ret:

  • 类型:JSON 对象
  • 内部字段:
{
    eventType: cancel,               //字符串类型;交互事件类型,取值范围:
                                     //confirm 用户点击确定按钮事件
                                     //cancel 用户点击取消按钮事件
    list: [{                         //数组类型;返回选定的资源信息数组
        gifPath:'',                  //字符串类型;资源路径 注意: gifPath、path和videoPath互斥返回
        path: '',                    //字符串类型;资源路径,返回资源在本地的绝对路径,注意: gifPath、path和videoPath互斥返回
        thumbPath: '',               //字符串类型;缩略图路径,返回资源缩略图在本地的绝对路径
        suffix: '',                  //字符串类型;文件后缀名,如:png、jpg、 mp4
        size: 1048576,               //数字类型;资源大小,单位(Bytes)
        time: '1490580032000',       //字符串类型;资源修改时间,格式:时间戳,单位为毫秒。  
        videoPath:'',                 //字符串类型;视频路径,注意: gifPath、path和videoPath互斥返回
        longitude:116.3718,           //数字类型;资源的经度 ;注意确认一下相机的定位权限是否被开启,如果不开启的话经纬度为0,查看方式:设置-->隐私-->定位服务-->相机 (仅支持iOS)
        latitude:39.982',             //数字类型;资源的纬度度  (仅支持iOS)      
        mediaType:'',                 //字符串类型;所在相册的类型,   Image ,Video ,Audio。
        duration:50,                  //数字类型;视频时长,单位为毫秒,同videoPath参数同时存在
    }]
}

示例代码

var UIAlbumSelector = api.require('UIAlbumSelector');
UIAlbumSelector.open({

}, function(ret) {
    if (ret) {
        api.alert({msg:JSON.stringify(ret)});
    }
});

可用性

iOS 系统,android 系统

可提供的 1.0.0 及更高版本

scan

扫描系统多媒体资源,可以通过 Web 代码自定义多选界面。

页面展示的图片建议使用缩略图,一次显示的图片不宜过多(1至2屏)

注意:iOS 平台上获取的path、gifPath、videoPath需要用 transPaths、transVideoPath 接口转换之后才可读取资源

scan({params}, callback(ret))

params

type:

  • 类型:字符串
  • 描述:返回的资源种类;默认:'all'
  • 取值范围:
    • all(图片和视频)
    • image(图片)
    • video(视频)

count:

  • 类型:数字
  • 描述:(可选项)每次返回的资源数量,剩余资源可用 fetch 接口遍历
  • 默认:全部资源数量(不建议使用默认值)

sort:

  • 类型:JSON 对象
  • 描述:(可选项)图片排序方式
  • 内部字段:
{
    key: 'time',    //(可选项)字符串类型;排序方式;默认:'time'
                    //取值范围:
                    //time(按图片创建时间排序)
    order: 'desc'   //(可选项)字符串类型;排列顺序;默认:'desc'
                    //取值范围:
                    //asc(旧->新)
                    //desc(新->旧)
}

thumbnail:

  • 类型:JSON 对象
  • 描述:(可选项)返回的缩略图配置,建议本图片不要设置过大 若已有缩略图,则使用已有的缩略图。若要重新生成缩略图,可先调用清除缓存接口 clearCache()。
  • 内部字段:
{
      w: 100,     //(可选项)数字类型;返回的缩略图的宽;默认:100
      h: 100      //(可选项)数字类型;返回的缩略图的宽;默认:100
}

callback(ret)

ret:

  • 类型:JSON 对象
  • 内部字段:
{
    total: 100,                      //数字类型;媒体资源总数
     list: [{                         //数组类型;返回选定的资源信息数组
        gifPath:'',                  //字符串类型;资源路径 注意: gifPath、path和videoPath互斥返回
        path: '',                    //字符串类型;资源路径,返回资源在本地的绝对路径,注意: gifPath、path和videoPath互斥返回
        thumbPath: '',               //字符串类型;缩略图路径,返回资源缩略图在本地的绝对路径
        suffix: '',                  //字符串类型;文件后缀名,如:png、jpg、 mp4
        size: 1048576,               //数字类型;资源大小,单位(Bytes)
        time: '1490580032000',       //字符串类型;资源修改时间,格式:时间戳,单位为毫秒。  
        videoPath:'',                 //字符串类型;视频路径,注意: gifPath、path和videoPath互斥返回
        longitude:116.3718,           //数字类型;资源的经度 ;注意确认一下相机的定位权限是否被开启,如果不开启的话经纬度为0,查看方式:设置-->隐私-->定位服务-->相机 (仅支持iOS)
        latitude:39.982',             //数字类型;资源的纬度度  (仅支持iOS)      
        mediaType:'',                 //字符串类型;所在相册的类型,   Image ,Video ,Audio。
        duration:50,                  //数字类型;视频时长,单位为毫秒,同videoPath参数同时存在
    }]
}

示例代码

var UIAlbumSelector = api.require('UIAlbumSelector');
UIAlbumSelector.scan({
    type: 'all',
    count: 10,
    sort: {
        key: 'time',
        order: 'desc'
    },
    thumbnail: {
        w: 100,
        h: 100
    }
}, function(ret) {
    if (ret) {
        alert(JSON.stringify(ret));
    }
});

可用性

iOS 系统,Android 系统

可提供的 1.0.0 及更高版本

fetch

获取指定数量的多媒体资源,没有更多资源则返回空数组,

必须配合 scan 接口的 count 参数一起使用。

注意:iOS 平台上获取的path、gifPath、videoPath需要用 transPaths、transVideoPath 接口转换之后才可读取资源

fetch(callback(ret))

callback(ret)

ret:

  • 类型:JSON 对象
  • 内部字段:
{
    list: [{                          //数组类型;返回选定的资源信息数组
        gifPath:'',                  //字符串类型;资源路径 注意: gifPath、path和videoPath互斥返回
        path: '',                    //字符串类型;资源路径,返回资源在本地的绝对路径,注意: gifPath、path和videoPath互斥返回
        thumbPath: '',               //字符串类型;缩略图路径,返回资源缩略图在本地的绝对路径
        suffix: '',                  //字符串类型;文件后缀名,如:png、jpg、 mp4
        size: 1048576,               //数字类型;资源大小,单位(Bytes)
        time: '1490580032000',       //字符串类型;资源修改时间,格式:时间戳,单位为毫秒。  
        videoPath:'',                 //字符串类型;视频路径,注意: gifPath、path和videoPath互斥返回
        longitude:116.3718,           //数字类型;资源的经度 ;注意确认一下相机的定位权限是否被开启,如果不开启的话经纬度为0,查看方式:设置-->隐私-->定位服务-->相机 (仅支持iOS)
        latitude:39.982',             //数字类型;资源的纬度度  (仅支持iOS)      
        mediaType:'',                 //字符串类型;所在相册的类型,   Image ,Video ,Audio。
        duration:50,                  //数字类型;视频时长,单位为毫秒,同videoPath参数同时存在
       }]
}

示例代码

var UIAlbumSelector = api.require('UIAlbumSelector');
UIAlbumSelector.fetch(function(ret, err) {
    if (ret) {
        alert(JSON.stringify(ret));
    } else {
        alert(JSON.stringify(err));
    }
});

可用性

iOS 系统,Android 系统

可提供的 1.0.0 及更高版本

scanGroups

获取系统多媒体资源的分组

scanGroups({params}, callback(ret))

params

type:

  • 类型:字符串
  • 描述:返回的资源种类;默认:'all'
  • 取值范围:
    • all(图片和视频)
    • image(图片)
    • video(视频)

thumbnail:

  • 类型:JSON 对象
  • 描述:(可选项)返回的分组的缩略图配置,建议本图片不要设置过大 若已有缩略图,则使用已有的缩略图。若要重新生成缩略图,可先调用清除缓存接口 clearCache()。
  • 内部字段:
{
      w: 100,     //(可选项)数字类型;返回的缩略图的宽;默认:100
      h: 100      //(可选项)数字类型;返回的缩略图的宽;默认:100
}

callback(ret)

ret:

  • 类型:JSON 对象
  • 内部字段:
{
    total: 10,                      //数字类型;媒体资源分组总数
    list: [{                        //数组类型;返回指定的资源信息数组
        thumbPath: '',              //字符串类型;缩略图路径,返回资源缩略图在本地的绝对路径  (安卓上返回的是第一张,iOS返回的是最后一张)
        groupName: '',              //字符串类型;分组名称
        groupId: '',                //字符串类型;分组名称
        groupType:'',               //字符串类型;分组类型:image图片,video视频
        imgCount:23                    //数字类型;分组中图片数量
    }]
}

示例代码

var UIAlbumSelector = api.require('UIAlbumSelector');
UIAlbumSelector.scanGroups({
    type: 'all',
    thumbnail: {
        w: 100,
        h: 100
    }
}, function(ret) {
    if (ret) {
        alert(JSON.stringify(ret));
    }
});

可用性

iOS 系统,Android 系统

可提供的 1.0.0 及更高版本

scanByGroupId

根据分组id,扫描系统多媒体资源

页面展示的图片建议使用缩略图,一次显示的图片不宜过多(1至2屏)

注意:iOS 平台上获取的path、gifPath、videoPath需要用 transPaths、transVideoPath 接口转换之后才可读取资源

scanByGroupId({params}, callback(ret))

params

groupId:

  • 类型:字符串
  • 描述:分组id

type:

  • 类型:字符串
  • 描述:分组类型;默认:'all'
  • 取值范围:
    • image(图片)
    • video(视频)
    • all(图片,视频)

count:

  • 类型:数字
  • 描述:(可选项)每次返回的资源数量,剩余资源可用 fetchGroup 接口遍历
  • 默认:全部资源数量(不建议使用默认值)

sort:

  • 类型:JSON 对象
  • 描述:(可选项)图片排序方式
  • 内部字段:
{
    key: 'time',    //(可选项)字符串类型;排序方式;默认:'time'
                    //取值范围:
                    //time(按图片创建时间排序)
    order: 'desc'   //(可选项)字符串类型;排列顺序;默认:'desc'
                    //取值范围:
                    //asc(旧->新)
                    //desc(新->旧)
}

thumbnail:

  • 类型:JSON 对象
  • 描述:(可选项)返回的缩略图配置,建议本图片不要设置过大 若已有缩略图,则使用已有的缩略图。若要重新生成缩略图,可先调用清除缓存接口 clearCache()。
  • 内部字段:
{
      w: 100,     //(可选项)数字类型;返回的缩略图的宽;默认:100
      h: 100      //(可选项)数字类型;返回的缩略图的宽;默认:100
}

callback(ret)

ret:

  • 类型:JSON 对象
  • 内部字段:
{
    total: 100,                       //数字类型;媒体资源总数
    list: [{                          //数组类型;返回指定的资源信息数组
        gifPath:'',                  //字符串类型;资源路径 注意: gifPath、path和videoPath互斥返回
        path: '',                    //字符串类型;资源路径,返回资源在本地的绝对路径,注意: gifPath、path和videoPath互斥返回
        thumbPath: '',               //字符串类型;缩略图路径,返回资源缩略图在本地的绝对路径
        suffix: '',                  //字符串类型;文件后缀名,如:png、jpg、 mp4
        size: 1048576,               //数字类型;资源大小,单位(Bytes)
        time: '1490580032000',       //字符串类型;资源修改时间,格式:时间戳,单位为毫秒。  
        videoPath:'',                 //字符串类型;视频路径,注意: gifPath、path和videoPath互斥返回
        longitude:116.3718,           //数字类型;资源的经度 ;注意确认一下相机的定位权限是否被开启,如果不开启的话经纬度为0,查看方式:设置-->隐私-->定位服务-->相机 (仅支持iOS)
        latitude:39.982',             //数字类型;资源的纬度度  (仅支持iOS)      
        mediaType:'',                 //字符串类型;所在相册的类型,   Image ,Video ,Audio。
        duration:50,                  //数字类型;视频时长,单位为毫秒,同videoPath参数同时存在
       }]
}

示例代码

var UIAlbumSelector = api.require('UIAlbumSelector');
UIAlbumSelector.scanByGroupId({
    groupId : 123456,
    type: 'image',
    count: 10,
    sort: {
        key: 'time',
        order: 'desc'
    },
    thumbnail: {
        w: 100,
        h: 100
    }
}, function(ret) {
    if (ret) {
        alert(JSON.stringify(ret));
    }
});

可用性

iOS 系统,Android 系统

可提供的 1.0.0 及更高版本

fetchGroup

从分组中获取指定数量的多媒体资源,没有更多资源则返回空数组,

必须配合 scanByGroupId 接口的 count 参数一起使用。

注意:iOS 平台上获取的path、gifPath、videoPath需要用 transPaths、transVideoPath 接口转换之后才可读取资源

fetchGroup(callback(ret))

callback(ret)

ret:

  • 类型:JSON 对象
  • 内部字段:
{
    list: [{                         //数组类型;返回指定的资源信息数组
        gifPath:'',                  //字符串类型;资源路径 注意: gifPath、path和videoPath互斥返回
        path: '',                    //字符串类型;资源路径,返回资源在本地的绝对路径,注意: gifPath、path和videoPath互斥返回
        thumbPath: '',               //字符串类型;缩略图路径,返回资源缩略图在本地的绝对路径
        suffix: '',                  //字符串类型;文件后缀名,如:png、jpg、 mp4
        size: 1048576,               //数字类型;资源大小,单位(Bytes)
        time: '1490580032000',       //字符串类型;资源修改时间,格式:时间戳,单位为毫秒。  
        videoPath:'',                 //字符串类型;视频路径,注意: gifPath、path和videoPath互斥返回
        longitude:116.3718,           //数字类型;资源的经度 ;注意确认一下相机的定位权限是否被开启,如果不开启的话经纬度为0,查看方式:设置-->隐私-->定位服务-->相机 (仅支持iOS)
        latitude:39.982',             //数字类型;资源的纬度度  (仅支持iOS)      
        mediaType:'',                 //字符串类型;所在相册的类型,   Image ,Video ,Audio。
        duration:50,                  //数字类型;视频时长,单位为毫秒,同videoPath参数同时存在
    }]
}

示例代码

var UIAlbumSelector = api.require('UIAlbumSelector');
UIAlbumSelector.fetchGroup(function(ret, err) {
    if (ret) {
        alert(JSON.stringify(ret));
    } else {
        alert(JSON.stringify(err));
    }
});

可用性

iOS 系统,Android 系统

可提供的 1.0.0 及更高版本

transPaths

将相册图片地址转换为可以直接使用的本地路径地址(临时文件夹的绝对路径),相册图片会被拷贝到临时文件夹,调用 clearCache 接口可清除该临时图片文件

transPaths({params}, callback(ret))

params

paths:

  • 类型:数组
  • 描述:要转换的图片路径(在相册库的绝对路径)组成的数组

scale:

  • 类型:数字
  • 描述:图片质量
  • 默认:1.0
  • 取值范围:0~1.0

callback(ret)

ret:

  • 类型:JSON 对象
  • 内部字段:
{ 
   paths: []      //数组类型;相册内图片被拷贝到临时文件夹,返回已拷贝图片的绝对路径。出现error的元素返回空字符串,本数组与传入数组资源一一对应
}

示例代码

var UIAlbumSelector = api.require('UIAlbumSelector');
UIAlbumSelector.transPaths({
    paths: ''
}, function(ret) {
    if (ret) {
        api.alert({msg:JSON.stringify(ret)});
    }
});

可用性

iOS 系统,Android 系统

可提供的 1.0.0 及更高版本

transVideoPath

视频路径转化

在iOS端直接获取的视频路径需经本接口转换后才能使用(播放、上传等)

transVideoPath({params}, callback(ret))

params

path:

  • 类型:字符串
  • 描述:要转换的视频路径

callback(ret)

ret:

  • 类型:JSON 对象
  • 内部字段:
{
   status: true,     //布尔类型 
   path:''           //字符串类型;视频保存的沙河路径;可用此路径进行播放、上传等操作;
   fileSize: 3819599 //视频文件大小;byte为单位
   duration: 4       //视频时长;单位为秒
}

err:

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

示例代码

var UIAlbumSelector = api.require('UIAlbumSelector');
UIAlbumSelector.transVideoPath({
    path: ''
}, function(ret, err) {
    if (ret.status) {
        alert(JSON.stringify(ret));
    } else {
        alert(JSON.stringify(err));
    }
});

可用性

iOS 系统

可提供的 1.0.0 及更高版本

clearCache

清除本模块缓存到沙盒的图片、视频,本接口只清除本模块缓存的数据,若要清除本 app 缓存的所有数据则调用 api.clearCache

clearCache()

示例代码

var UIAlbumBrowser = api.require('UIAlbumBrowser');
UIAlbumBrowser.clearCache();

可用性

iOS 系统,Android 系统

可提供的 1.0.0 及更高版本