UIAlbumBrowser

来自于:官方立即使用

概述

UIAlbumBrowser 是一个本地媒体资源扫描器,在 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 组,开发者需自行组合。

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

UIAlbumBrowser 模块是 UIMediaScanner 模块的优化升级版。

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

模块接口

open

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

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

params

max:

  • 类型:数字
  • 描述:(可选项)最多选择几张图片
  • 默认值:9

styles:

  • 类型:JSON 对象
  • 描述:(可选项)模块各部分的样式
  • 内部字段:
{
    bg: '#FFFFFF',                      //(可选项)字符串类型;资源选择器背景,支持 rgb,rgba,#;默认:'#FFFFFF'
    mark: {                             //(可选项)JSON对象;选中图标的样式
        icon: '',                       //(可选项)字符串类型;图标路径(本地路径,支持fs://、widget://);默认:对勾图标
        position: 'bottom_left',        //(可选项)字符串类型;图标的位置,默认:'bottom_left'
                                        // 取值范围:
                                        // top_left(左上角)
                                        // bottom_left(左下角)
                                        // top_right(右上角)
                                        // bottom_right(右下角)
        size: 20                        //(可选项)数字类型;图标的大小;默认:显示的缩略图的宽度的三分之一
    },
    nav: {                              //(可选项)JSON对象;导航栏样式
        bg: '#eee',                     //(可选项)字符串类型;导航栏背景,支持 rgb,rgba,#;默认:'rgba(0,0,0,0.6)'
        titleColor: '#fff',             //(可选项)字符串类型;标题文字颜色,支持 rgb,rgba,#;默认:'#fff'
        titleSize: 18,                  //(可选项)数字类型;标题文字大小,默认:18
        cancelColor: '#fff',            //(可选项)字符串类型;取消按钮的文字颜色;支持 rgb,rgba,#;默认:'#fff'
        cancelSize: 16,                 //(可选项)数字类型;取消按钮的文字大小;默认:18
        finishColor: '#fff',            //(可选项)字符串类型;完成按钮的文字颜色,支持 rgb,rgba,#;默认:'#fff'
        finishSize: 16                  //(可选项)数字类型;完成按钮的文字大小;默认:18
    }
}

rotation:

  • 类型:布尔
  • 描述:屏幕是否旋转(横屏),为 true 时可以横竖屏旋转,false 时禁止横屏
  • 默认值:false

callback(ret, err)

ret:

  • 类型:JSON 对象
  • 内部字段:
{
    eventType: cancel,               //字符串类型;按钮点击事件,取值范围
                                     //confirm 用户点击确定按钮事件
                                     //cancel 用户点击取消按钮事件
    list: [{                         //数组类型;返回选定的资源信息数组
        path: '',                    //字符串类型;资源路径,返回资源在本地的绝对路径,注意:iOS 平台上需要用 transPath 接口转换之后才可读取原图
        thumbPath: '',               //字符串类型;缩略图路径,返回资源缩略图在本地的绝对路径
        suffix: '',                  //字符串类型;文件后缀名,如:png、jpg、 mp4(iOS不支持)
        size: 1048576,               //数字类型;资源大小,单位(Bytes)(iOS不支持)
        time: '1490580032000',       //字符串类型;资源修改时间,格式:时间戳,单位为毫秒。                       
    }]
}

示例代码

var UIAlbumBrowser = api.require('UIAlbumBrowser');
UIAlbumBrowser.open({
    max: 9,
    styles: {
        bg: '#fff',
        mark: {
            icon: '',
            position: 'bottom_left',
            size: 20
        },
        nav: {
            bg: 'rgba(0,0,0,0.6)',
            titleColor: '#fff',
            titleSize: 18,
            cancelColor: '#fff',
            cancelSize: 16,
            finishColor: '#fff',
            finishSize: 16
        }
    },
    rotation: true
}, function(ret) {
    if (ret) {
        alert(JSON.stringify(ret));
    }
});

可用性

iOS系统

可提供的1.0.0及更高版本

imagePicker

打开图片选择器,打开后会全屏显示

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

params

max:

  • 类型:数字
  • 描述:(可选项)最多选择几张图片
  • 默认值:9

styles:

  • 类型:JSON 对象
  • 描述:(可选项)模块各部分的样式
  • 内部字段:
{
    bg: '#FFFFFF',                      //(可选项)字符串类型;资源选择器背景,支持 rgb,rgba,#;默认:'#FFFFFF'
    cameraImg:'widget://res/cameraImg.png',
                                        //(可选项)字符串类型;相机图片路径(本地路径,支持fs://、widget://);默认:相机图片
    mark: {                             //(可选项)JSON对象;选中图标的样式
        icon: '',                       //(可选项)字符串类型;图标路径(本地路径,支持fs://、widget://);默认:对勾图标
        position: 'bottom_left',        //(可选项)字符串类型;图标的位置,默认:'bottom_left'
                                        // 取值范围:
                                        // top_left(左上角)
                                        // bottom_left(左下角)
                                        // top_right(右上角)
                                        // bottom_right(右下角)
        size: 20                        //(可选项)数字类型;图标的大小;默认:显示的缩略图的宽度的三分之一
    },
    nav: {                              //(可选项)JSON对象;导航栏样式
        bg: '#eee',                     //(可选项)字符串类型;导航栏背景,支持 rgb,rgba,#;默认:'rgba(0,0,0,0.6)'
        cancelColor: '#fff',            //(可选项)字符串类型;取消按钮的文字颜色;支持 rgb,rgba,#;默认:'#fff'
        cancelSize: 16,                 //(可选项)数字类型;取消按钮的文字大小;默认:18
        nextStepColor: '#fff',            //(可选项)字符串类型;下一步按钮的文字颜色,支持 rgb,rgba,#;默认:'#fff'
        nextStepSize: 16                  //(可选项)数字类型;下一步按钮的文字大小;默认:18
    }
}

animation:

  • 类型:布尔
  • 描述:(可选项)点击下一步按钮时是否有动画
  • 默认:true

callback(ret, err)

ret:

  • 类型:JSON 对象
  • 内部字段:
{
    eventType: cancel,               //字符串类型;按钮点击事件,取值范围
                                     //nextStep 用户点击下一步按钮事件
                                     //cancel 用户点击取消按钮事件
    originalPath: ''                 //字符串类型;拍照结束后把原图的图片路径
    list: [{                         //数组类型;返回选定的资源信息数组
        path: '',                    //字符串类型;资源路径,返回资源在本地的绝对路径,注意:iOS 平台上需要用 transPath 接口转换之后才可读取原图
        thumbPath: '',               //字符串类型;缩略图路径,返回资源缩略图在本地的绝对路径                      
    }]
}

示例代码

var UIAlbumBrowser = api.require('UIAlbumBrowser');
UIAlbumBrowser.imagePicker({
    max: 9,
    styles: {
    bg: '#FFFFFF',                   
    cameraImg:'widget://res/cameraImg.png',
    mark: {                             
        icon: '',                       
        position: 'bottom_left',      
        size: 20                        
    },
    nav: {                              
        bg: '#eee',                     
        cancelColor: '#fff',            
        cancelSize: 16,  
        nextStepColor: '#fff',
        nextStepSize: 16                 
    }
    },
    animation:true,    
}, function(ret) {
   if (ret.eventType == 'nextStep') {
  var UIAlbumBrowser = api.require('UIAlbumBrowser');
   UIAlbumBrowser.closePicker();
   }
});

可用性

iOS系统,安卓系统

可提供的1.0.0及更高版本

closePicker

针对imagePicker接口关闭

closePicker()

示例代码

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

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

requestAlbumPermissions

请求相册权限

CheckAlbumPermissions( callback(ret, err))

callback(ret, err)

ret:

  • 类型:JSON 对象
  • 内部字段:
{
  isAccessPermissions: ture    //布尔类型;是否有相册权限
}

示例代码

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

可用性

iOS系统

可提供的1.0.0及更高版本

scan

扫描系统多媒体资源,可以通过 Web 代码自定义多选界面。注意:页面展示的图片建议使用缩略图,一次显示的图片不宜过多(1至2屏)

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

params

type:

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

count:

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

sort:

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

thumbnail:

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

callback(ret, err)

ret:

  • 类型:JSON 对象
  • 内部字段:
{
    total: 100,                      //数字类型;媒体资源总数
    list: [{                          //数组类型;返回指定的资源信息数组
          path: '',                    //字符串类型;资源路径,返回资源在本地的绝对路径。注意:在 iOS 平台上需要先调用 transPath 接口将路径转换之后才能读取目标资源媒体文件
        thumbPath: '',                //字符串类型;缩略图路径,返回资源缩略图在本地的绝对路径
        suffix: '',                   //字符串类型;文件后缀名,如:png,jpg, mp4(iOS不支持)
        size: 1048576,                //数字类型;资源大小,单位(Bytes)(ios不支持)
        time: '1490580032000',        //字符串类型;资源修改时间,格式:时间戳,单位为毫秒。
        mediaType:'',                 //字符串类型;所在相册的类型,   Image ,Video ,Audio。
        duration:50,                  //数字类型;视频时长,单位为毫秒
    }]
}

示例代码

var UIAlbumBrowser = api.require('UIAlbumBrowser');
UIAlbumBrowser.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 参数一起使用

fetch(callback(ret, err))

callback(ret, err)

ret:

  • 类型:JSON 对象
  • 内部字段:
{
    list: [{                          //数组类型;返回指定的资源信息数组
          path: '',                    //字符串类型;资源路径,返回资源在本地的绝对路径。注意:在 iOS 平台上需要先调用 transPath 接口将路径转换之后才能读取目标资源媒体文件
        thumbPath: '',                //字符串类型;缩略图路径,返回资源缩略图在本地的绝对路径
        suffix: '',                   //字符串类型;文件后缀名,如:png,jpg, mp4(iOS不支持)
        size: 1048576,                //数字类型;资源大小,单位(Bytes)(ios不支持)
        time: '1490580032000',        //字符串类型;资源修改时间,格式:时间戳,单位为毫秒。
        mediaType:'',                 //字符串类型;所在相册的类型,   Image ,Video ,Audio.
        duration:50                   //数字类型;视频时长,单位为毫秒
    }]
}

示例代码

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

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

scanGroups

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

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

params

type:

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

thumbnail:

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

callback(ret, err)

ret:

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

示例代码

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

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

scanByGroupId

根据分组id,扫描系统多媒体资源,可以通过 Web 代码自定义多选界面。注意:页面展示的图片建议使用缩略图,一次显示的图片不宜过多(1至2屏)

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

params

groupId:

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

type:

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

count:

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

sort:

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

thumbnail:

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

callback(ret, err)

ret:

  • 类型:JSON 对象
  • 内部字段:
{
    total: 100,                       //数字类型;媒体资源总数
    list: [{                           //数组类型;返回指定的资源信息数组
          path: '',                     //字符串类型;资源路径,返回资源在本地的绝对路径。注意:在 iOS 平台上需要先调用 transPath 接口将路径转换之后才能读取目标资源媒体文件
        thumbPath: '',                 //字符串类型;缩略图路径,返回资源缩略图在本地的绝对路径
        suffix: '',                    //字符串类型;文件后缀名,如:png,jpg, mp4
        size: 1048576,                 //数字类型;资源大小,单位(Bytes)
        time: '1490580032000',         //字符串类型;资源修改时间,格式:时间戳,单位为毫秒。
    }]
}

示例代码

var UIAlbumBrowser = api.require('UIAlbumBrowser');
UIAlbumBrowser.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 参数一起使用

fetchGroup(callback(ret, err))

callback(ret, err)

ret:

  • 类型:JSON 对象
  • 内部字段:
{
    list: [{                         //数组类型;返回指定的资源信息数组
          path: '',                   //字符串类型;资源路径,返回资源在本地的绝对路径。注意:在 iOS 平台上需要先调用 transPath 接口将路径转换之后才能读取目标资源媒体文件
        thumbPath: '',               //字符串类型;缩略图路径,返回资源缩略图在本地的绝对路径
        suffix: '',                  //字符串类型;文件后缀名,如:png,jpg, mp4(iOS不支持)
        size: 1048576,               //数字类型;资源大小,单位(Bytes)(iOS不支持)
        time: '1490580032000',       //字符串类型;资源修改时间,格式:时间戳,单位为毫秒。
        mediaType:'',                //字符串类型;所在相册的类型,   Image ,Video ,Audio.
        duration:50                  //数字类型;视频时长,单位为毫秒
    }]
}

示例代码

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

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

transPath

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

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

params

path:

  • 类型:字符串
  • 描述:要转换的图片路径(在相册库的绝对路径)

callback(ret, err)

ret:

  • 类型:JSON 对象
  • 内部字段:
{
   path: ''     //字符串类型;相册内图片被拷贝到临时文件夹,返回已拷贝图片的绝对路径
}

示例代码

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

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本

getVideoDuration

iOS在scan接口里面可以获取到时长.所以可以不用管. getVideoDuration({params}, callback(ret, err))

params

path:

  • 类型:字符串
  • 描述:视频资源路径(在相册库的绝对路径,另外支持 fs:// widget://路径)

callback(ret, err)

ret:

  • 类型:JSON 对象
  • 内部字段:
{
   duration: 60    //数字类型;视频时长,单位为毫秒
}

示例代码

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

可用性

iOS系统,Android系统

可提供的1.0.0及更高版本