UIAlbumBrowser

来自于：官方立即使用

open imagePicker closePicker requestAlbumPermissions scan fetch scanGroups scanByGroupId fetchGroup transPath transVideoPath getVideoDuration openGroup closeGroup changeGroup openAlbum closeAlbum batchTransPath getImgInfo

论坛示例

为帮助用户更好更快的使用模块，论坛维护了一个示例，示例中包含示例代码、知识点讲解、注意事项等，供您参考。

概述

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

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

  1. iOS 上系统相册分组策略如下：
  2. 相机胶卷（All组）:  a,b,c,d,e,f,g
  3. A组：a
  4. B组：b,c
  5. C组：f,g
  7. android 上系统相册分组策略如下：
  8. A组：a
  9. B组：b,c
  10. C组：d,e,f,g
  12. 因此，若要在 android 平台上显示 All 组，开发者需自行组合。

本模块封装了两种方案。

方案一：

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

方案二：

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

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

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

本模块源码已开源https://github.com/apicloudcom/APICloud-Modules/tree/master/UIAlbumBrowser

iOS只支持中文,英文,繁体中文三种语言

模块接口

open

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

open({params}, callback(ret))

params

max：

  • 类型：数字
  • 描述：（可选项）最多选择几张图片
  • 默认值：9

type：

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

isOpenPreview：

  • 类型：布尔
  • 描述：（可选项）显是否打开预览界面
  • 默认：true

classify：

  • 类型：布尔
  • 描述：（可选项）是否将图片分类显示，为 true 时，会首先跳转到相册分类列表页面，false时打开第一个分组的详情。(仅对iOS有效) 注意:iOS把所有照片或相机胶卷调整为第一个分组，此调整借鉴微信朋友圈的相册选择
  • 默认：true

selectedAll：

  • 类型：布尔
  • 描述：（可选项）当type为all时，视频和图片能不能同时选中，参考微信，仅当type为all时本参数有意义
  • 默认：true

styles：

  • 类型：JSON 对象
  • 描述：（可选项）模块各部分的样式
  • 内部字段：
  1. {
  2.     bg: '#FFFFFF',                  //（可选项）字符串类型；资源选择器背景，支持 rgb，rgba，#；默认：'#FFFFFF'
  3.     mark: {                         //（可选项）JSON对象；选中图标的样式
  4.         unSelectedIcon:'',          //（可选项）字符串类型；未选中图标路径（本地路径，支持fs://、widget://）；默认：圆形灰色对勾图标
  5.         icon: '',                   //（可选项）字符串类型；选中图标路径（本地路径，支持fs://、widget://）；默认：圆形绿色对勾图标                      
  7.         position: 'bottom_left',    //（可选项）字符串类型；图标的位置，默认：'bottom_left'
  8.       // 取值范围：
  9.                 // top_left（左上角）
  10.                 // bottom_left（左下角）
  11.                 // top_right（右上角）
  12.                 // bottom_right（右下角）
  13.         size: 20                    //（可选项）数字类型；图标的大小；默认：显示的缩略图的宽度的三分之一
  14.     },
  15.     nav: {                          //（可选项）JSON对象；导航栏样式
  16.         bg: '#eee',                 //（可选项）字符串类型；导航栏背景，支持 rgb，rgba，#；默认：'rgba(0,0,0,0.6)'
  17.         titleText:'',              //（可选项）字符串类型；标题 (仅支持安卓)
  18.         titleColor: '#fff',         //（可选项）字符串类型；标题文字颜色，支持 rgb，rgba，#；默认：'#fff'
  19.         titleSize: 18,              //（可选项）数字类型；标题文字大小，默认：18
  20.         cancelColor: '#fff',        //（可选项）字符串类型；取消按钮的文字颜色；支持 rgb，rgba，#；默认：'#fff'
  21.         cancelSize: 16,            //（可选项）数字类型；取消按钮的文字大小；默认：18
  22.         cancelText: '中国',             //（可选项）字符串类型；取消按钮文字内容；默认：'取消'
  23.         finishText: '嗯嗯',             //（可选项）字符串类型；完成按钮文字内容；默认：'完成'
  24.         finishColor: '#fff',       //（可选项）字符串类型；完成按钮的文字颜色，支持 rgb，rgba，#；默认：'#fff'
  25.         finishWidth: 50,             //（可选项）数字类型；完成按钮的宽度；默认：50 (仅支持iOS)
  27.         unFinishColor: 'rgba(64,224,208,0.25)',          //（可选项）字符串类型；打开页面还未选择图片或视频的完成按钮的文字颜色，支持 rgb，rgba，#；默认：'rgba(64,224,208,0.25)'
  28.         finishSize: 16,           //（可选项）数字类型；完成按钮的文字大小；默认：16
  29.         numberSize: 20,           //（可选项）数字类型；数字显示的大小；默认：20  **仅支持iOS**
  30.         numberFontSize:14,        //（可选项）数字类型；数字显示文字的大小；默认：14    **仅支持iOS**
  31.         numberTextColor:'#fff',   //（可选项）字符串类型；数字显示的文字颜色，支持 rgb，rgba，#；默认：'#fff' **仅支持iOS**
  32.         numberBgColor:'#00FA9A',  //（可选项）字符串类型；数字显示的背景颜色，支持 rgb，rgba，#；默认：'#00FA9A' **仅支持iOS**
  33.         numberCorner:10,          //（可选项）字符串类型；数字显示的圆角度，#；默认：10 **仅支持iOS**
  35.     },
  36.        bottomTabBar: {          //（可选项）JSON对象；底部导航栏样式  **该项参数仅支持iOS**
  37.         bg: 'rgba(0,0,0,0.6)',  //（可选项）字符串类型；底部导航栏背景，支持 rgb，rgba，#；默认：'rgba(0,0,0,0.6)'
  38.         unPreviewTitleColor:'rgba(0,0,0,0.25)',//（可选项）字符串类型；打开页面还未选择图片或视频的预览的文字颜色，支持 rgb，rgba，#；默认：'rgba(0,0,0,0.25)'
  39.         previewTitleColor: '#000000',         //（可选项）字符串类型；选择图片或视频的预览的文字颜色，支持 rgb，rgba，#；默认：'#000000'
  40.          previewTitle:'预览',                  //（可选项）字符串类型；选择图片或视频的预览的文字；默认：'预览'
  41.         previewTitleSize: 15,                 //（可选项）数字类型；标题文字大小，默认：15
  42.     }
  43. }

rotation：

  • 类型：布尔
  • 描述：屏幕是否旋转（横屏），为 true 时可以横竖屏旋转，false 时禁止横屏
  • 默认值：false

alertTitle：

  • 类型：字符串类型
  • 描述：（可选项）超过设置的选中图片的数量时的提示框内容

alertBtnTitle：

  • 类型：字符串类型
  • 描述：（可选项）超过设置的选中图片的数量时的提示框按钮名称（仅iOS支持）
  • 默认值：我知道了

videoTimeFilter：

  • 类型：数字类型
  • 单位:秒
  • 描述：（可选项）视频时间长度超过此参数,禁止选取
  • 默认值：无

callback(ret)

ret：

  • 类型：JSON 对象
  • 内部字段：
  1. {
  2.     eventType: cancel,               //字符串类型；按钮点击事件，取值范围
  3.                                      //confirm 用户点击确定按钮事件
  4.                                      //cancel 用户点击取消按钮事件
  5.     list: [{                         //数组类型；返回选定的资源信息数组
  6.         gifImagePath:'',             //字符串类型；gif图路径，返回gif图在本地的绝对路径，可直接使用 注意:当gifImagePath存在，则不返回path和thumbPath路径
  7.         path: '',                    //字符串类型；资源路径，返回资源在本地的绝对路径，注意：iOS 平台上需要用 transPath 接口转换之后才可读取原图
  8.         thumbPath: '',               //字符串类型；缩略图路径，返回资源缩略图在本地的绝对路径
  9.         suffix: '',                  //字符串类型；文件后缀名，如：png、jpg、 mp4(iOS不支持)
  10.         size: 1048576,               //数字类型；资源大小，单位（Bytes）
  11.         time: '1490580032000',       //字符串类型；资源修改时间，格式：时间戳，单位为毫秒。  
  12.         videoPath:'',                 //字符串类型；视频路径
  13.         longitude:116.3718,           //数字类型；资源的经度 ；注意确认一下相机的定位权限是否被开启，如果不开启的话经纬度为0，查看方式:设置-->隐私-->定位服务-->相机 (仅支持iOS)
  14.         latitude:39.982',             //数字类型；资源的纬度度  (仅支持iOS)      
  15.     }]
  16. }

示例代码

  1. var UIAlbumBrowser = api.require('UIAlbumBrowser');
  2. UIAlbumBrowser.open({
  3.     max: 9,
  4.     styles: {
  5.         bg: '#fff',
  6.         mark: {
  7.             icon: '',
  8.             position: 'bottom_left',
  9.             size: 20
  10.         },
  11.         nav: {
  12.             bg: 'rgba(0,0,0,0.6)',
  13.             titleColor: '#fff',
  14.             titleSize: 18,
  15.             cancelColor: '#fff',
  16.             cancelSize: 16,
  17.             finishColor: '#fff',
  18.             finishSize: 16
  19.         }
  20.     },
  21.     rotation: true
  22. }, function(ret) {
  23.     if (ret) {
  24.         alert(JSON.stringify(ret));
  25.     }
  26. });

可用性

iOS系统，android系统

可提供的1.0.0及更高版本

imagePicker

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

imagePicker({params}, callback(ret))

params

max：

  • 类型：数字
  • 描述：（可选项）最多选择几张图片
  • 默认值：9

showCamera:

  • 类型：布尔
  • 描述：是否显示相机
  • 默认：true

selectedPaths：

  • 类型：数组
  • 描述：（可选项）默认选中图片的路径组成的数组 (需传入path参数，用相机拍照后需传入assetPath参数)

styles：

  • 类型：JSON 对象
  • 描述：（可选项）模块各部分的样式
  • 内部字段：
  1. {
  2.     bg: '#FFFFFF',                      //（可选项）字符串类型；资源选择器背景，支持 rgb，rgba，#；默认：'#FFFFFF'
  3.     cameraImg:'widget://res/cameraImg.png',
  4.                                         //(可选项）字符串类型；相机图片路径（本地路径，支持fs://、widget://）；默认：相机图片
  5.     mark: {                             //（可选项）JSON对象；选中图标的样式
  6.         icon: '',                       //（可选项）字符串类型；图标路径（本地路径，支持fs://、widget://）；默认：对勾图标
  7.         position: 'bottom_left',        //（可选项）字符串类型；图标的位置，默认：'bottom_left'
  8.                                         // 取值范围：
  9.                                         // top_left（左上角）
  10.                                         // bottom_left（左下角）
  11.                                         // top_right（右上角）
  12.                                         // bottom_right（右下角）
  13.         size: 20                        //（可选项）数字类型；图标的大小；默认：显示的缩略图的宽度的三分之一
  14.     },
  15.     nav: {                              //（可选项）JSON对象；导航栏样式
  16.         bg: '#eee',                     //（可选项）字符串类型；导航栏背景，支持 rgb，rgba，#；默认：'rgba(0,0,0,0.6)'
  17.         cancelColor: '#fff',            //（可选项）字符串类型；取消按钮的文字颜色；支持 rgb，rgba，#；默认：'#fff'
  18.         cancelSize: 16,                 //（可选项）数字类型；取消按钮的文字大小；默认：18
  19.         nextStepColor: '#fff',            //（可选项）字符串类型；下一步按钮的文字颜色，支持 rgb，rgba，#；默认：'#fff'
  20.         nextStepSize: 16                  //（可选项）数字类型；下一步按钮的文字大小；默认：18
  21.         cancelText: '中国',             //（可选项）字符串类型；取消按钮文字内容；默认：'取消'
  22.         finishText: '嗯嗯',             //（可选项）字符串类型；完成按钮文字内容；默认：'下一步'
  23.     },
  24.   thumbnail:{      //（可选项）返回的缩略图配置，**建议本图片不要设置过大** 若已有缩略图，则使用已有的缩略图。若要重新生成缩略图，可先调用清除缓存接口api.clearCache()。  
  25.       w: 100,     //（可选项）数字类型；返回的缩略图的宽；默认：原图的宽度
  26.       h: 100      //（可选项）数字类型；返回的缩略图的宽；默认：原图的高度
  27. }  
  29. }

isSystemCamera：

  • 类型：布尔
  • 描述：（可选项）拍照时是否调用系统相机
  • 默认：true

animation：

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

callback(ret)

ret：

  • 类型：JSON 对象
  • 内部字段：
  1. {
  2.     eventType: cancel,               //字符串类型；按钮点击事件，取值范围
  3.                                      //nextStep 用户点击下一步按钮事件
  4.                                      //cancel 用户点击取消按钮事件
  5.                                      //clickCamera 点击相机事件；当isSystemCamera为false时,此参数有值
  6.     originalPath: ''                 //字符串类型；拍照结束后把原图的图片路径  (仅在拍照后返回)
  7.     assetPath:''                     //字符串类型；拍照结束后的资源路径，返回资源在本地的绝对路径，注意：iOS 平台上需要用 transPath 接口转换之后才可读取原图  (仅在拍照后返回;仅支持iOS)
  8.     list: [{                         //数组类型；返回选定的资源信息数组
  9.         path: '',                    //字符串类型；资源路径，返回资源在本地的绝对路径，注意：iOS 平台上需要用 transPath 接口转换之后才可读取原图
  10.         thumbPath: '',               //字符串类型；缩略图路径，返回资源缩略图在本地的绝对路径                      
  11.     }]
  12. }

示例代码

  1. var UIAlbumBrowser = api.require('UIAlbumBrowser');
  2. UIAlbumBrowser.imagePicker({
  3.     max: 9,
  4.     styles: {
  5.     bg: '#FFFFFF',                   
  6.     cameraImg:'widget://res/cameraImg.png',
  7.     mark: {                             
  8.         icon: '',                       
  9.         position: 'bottom_left',      
  10.         size: 20                        
  11.     },
  12.     nav: {                              
  13.         bg: '#eee',                     
  14.         cancelColor: '#fff',            
  15.         cancelSize: 16,  
  16.         nextStepColor: '#fff',
  17.         nextStepSize: 16                 
  18.     }
  19.     },
  20.     animation:true,    
  21. }, function(ret) {
  22.    if (ret.eventType == 'nextStep') {
  23.   var UIAlbumBrowser = api.require('UIAlbumBrowser');
  24.    UIAlbumBrowser.closePicker();
  25.    }
  26. });

可用性

iOS系统，安卓系统

可提供的1.0.0及更高版本

closePicker

针对imagePicker接口关闭

closePicker()

示例代码

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

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

requestAlbumPermissions

请求相册权限

requestAlbumPermissions( callback(ret))

callback(ret)

ret：

  • 类型：JSON 对象
  • 内部字段：
  1. {
  2.   isAccessPermissions: ture    //布尔类型；是否有相册权限
  3. }

示例代码

  1. var UIAlbumBrowser = api.require('UIAlbumBrowser');
  2. UIAlbumBrowser.requestAlbumPermissions({
  3. }, function(ret, err) {
  4.     if (ret) {
  5.         alert(JSON.stringify(ret));
  6.     } else {
  7.         alert(JSON.stringify(err));
  8.     }
  9. });

可用性

iOS系统

可提供的1.0.0及更高版本

scan

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

scan({params}, callback(ret))

params

type：

  • 类型：字符串
  • 描述：返回的资源种类；默认：’all’
  • 取值范围：
    • all（图片和视频）
    • image（图片）
    • video（视频）

count：

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

sort：

  • 类型：JSON 对象
  • 描述：（可选项）图片排序方式
  • 内部字段：
  1. {
  2.     key: 'time',    //（可选项）字符串类型；排序方式；默认：'time'
  3.                     //取值范围：
  4.                     //time（按图片创建时间排序）
  5.     order: 'desc'   //（可选项）字符串类型；排列顺序；默认：'desc'
  6.                     //取值范围：
  7.                     //asc（旧->新）
  8.                     //desc（新->旧）
  9. }

thumbnail：

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

callback(ret)

ret：

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

示例代码

  1. var UIAlbumBrowser = api.require('UIAlbumBrowser');
  2. UIAlbumBrowser.scan({
  3.     type: 'all',
  4.     count: 10,
  5.     sort: {
  6.         key: 'time',
  7.         order: 'desc'
  8.     },
  9.     thumbnail: {
  10.         w: 100,
  11.         h: 100
  12.     }
  13. }, function(ret) {
  14.     if (ret) {
  15.         alert(JSON.stringify(ret));
  16.     }
  17. });

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

fetch

获取指定数量的多媒体资源，没有更多资源则返回空数组，必须配合 scan 接口的 count 参数一起使用。

fetch(callback(ret))

callback(ret)

ret：

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

示例代码

  1. var UIAlbumBrowser = api.require('UIAlbumBrowser');
  2. UIAlbumBrowser.fetch(function(ret, err) {
  3.     if (ret) {
  4.         alert(JSON.stringify(ret));
  5.     } else {
  6.         alert(JSON.stringify(err));
  7.     }
  8. });

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

scanGroups

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

scanGroups({params}, callback(ret))

params

type：

  • 类型：字符串
  • 描述：返回的资源种类；默认：’all’(iOS不支持)
  • 取值范围：
    • all（图片和视频）
    • image（图片）
    • video（视频）

thumbnail：

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

callback(ret)

ret：

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

示例代码

  1. var UIAlbumBrowser = api.require('UIAlbumBrowser');
  2. UIAlbumBrowser.scanGroups({
  3.     type: 'all',
  4.     thumbnail: {
  5.         w: 100,
  6.         h: 100
  7.     }
  8. }, function(ret) {
  9.     if (ret) {
  10.         alert(JSON.stringify(ret));
  11.     }
  12. });

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

scanByGroupId

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

scanByGroupId({params}, callback(ret))

params

groupId：

  • 类型：字符串
  • 描述：分组id；

type：

  • 类型：字符串
  • 描述：分组类型；默认：’all’
  • 取值范围：
    • image（图片）
    • video（视频）
    • all(图片,视频)

count：

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

sort：

  • 类型：JSON 对象
  • 描述：（可选项）图片排序方式
  • 内部字段：
  1. {
  2.     key: 'time',    //（可选项）字符串类型；排序方式；默认：'time'
  3.                     //取值范围：
  4.                     //time（按图片创建时间排序）
  5.     order: 'desc'   //（可选项）字符串类型；排列顺序；默认：'desc'
  6.                     //取值范围：
  7.                     //asc（旧->新）
  8.                     //desc（新->旧）
  9. }

thumbnail：

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

callback(ret)

ret：

  • 类型：JSON 对象
  • 内部字段：
  1. {
  2.     total: 100,                       //数字类型；媒体资源总数
  3.     list: [{                           //数组类型；返回指定的资源信息数组
  4.          gifImagePath:'',              //字符串类型；gif图路径，返回gif图在本地的绝对路径，可直接使用 注意:当gifImagePath存在，则不返回path和thumbPath路径
  5.           path: '',                    //字符串类型；资源路径，返回资源在本地的绝对路径。注意：在 iOS 平台上需要先调用 transPath 接口将路径转换之后才能读取目标资源媒体文件
  6.         thumbPath: '',                //字符串类型；缩略图路径，返回资源缩略图在本地的绝对路径
  7.         suffix: '',                   //字符串类型；文件后缀名，如：png，jpg, mp4  (iOS不支持)
  8.         size: 1048576,                //数字类型；资源大小，单位（Bytes）
  9.         time: '1490580032000',        //字符串类型；资源修改时间，格式：时间戳，单位为毫秒。
  10.         mediaType:'',                 //字符串类型;所在相册的类型,   image ,video.
  11.     }]
  12. }

示例代码

  1. var UIAlbumBrowser = api.require('UIAlbumBrowser');
  2. UIAlbumBrowser.scanByGroupId({
  3.     groupId : 123456,
  4.     type: 'image',
  5.     count: 10,
  6.     sort: {
  7.         key: 'time',
  8.         order: 'desc'
  9.     },
  10.     thumbnail: {
  11.         w: 100,
  12.         h: 100
  13.     }
  14. }, function(ret) {
  15.     if (ret) {
  16.         alert(JSON.stringify(ret));
  17.     }
  18. });

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

fetchGroup

从分组中获取指定数量的多媒体资源，没有更多资源则返回空数组，必须配合 scanByGroupId 接口的 count 参数一起使用。

fetchGroup(callback(ret))

callback(ret)

ret：

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

示例代码

  1. var UIAlbumBrowser = api.require('UIAlbumBrowser');
  2. UIAlbumBrowser.fetchGroup(function(ret, err) {
  3.     if (ret) {
  4.         alert(JSON.stringify(ret));
  5.     } else {
  6.         alert(JSON.stringify(err));
  7.     }
  8. });

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

transPath

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

transPath({params}, callback(ret))

params

path：

  • 类型：字符串
  • 描述：要转换的图片路径（在相册库的绝对路径）

quality：

  • 类型：字符串
  • 描述：视频质量（android此参数为图片的quality，不支持视频）(iOS不支持)
  • 默认：medium
  • 取值范围：
    • highest
    • medium
    • low

scale：

  • 类型：数字
  • 描述：图片质量 (iOS不支持)
  • 默认：1.0
  • 取值范围：0~1.0

callback(ret)

ret：

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

err：

  • 类型：JSON 对象
  • 内部字段：
  1. {
  2.   status: false     //转化失败
  3. }

示例代码

  1. var UIAlbumBrowser = api.require('UIAlbumBrowser');
  2. UIAlbumBrowser.transPath({
  3.     path: ''
  4. }, function(ret, err) {
  5.     if (ret) {
  6.         alert(JSON.stringify(ret));
  7.     } else {
  8.         alert(JSON.stringify(err));
  9.     }
  10. });

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

transVideoPath

视频路径转化，直接获取的路径需经本接口转换后才能使用（播放、上传等）

transVideoPath({params}, callback(ret))

params

path：

  • 类型：字符串
  • 描述：要转换的视频路径（在相册库的绝对路径）

isSave：

  • 类型：布尔类型
  • 描述：是否保存在沙盒 （仅支持iOS）
  • 默认：false

callback(ret)

ret：

  • 类型：JSON 对象
  • 内部字段：
  1. {
  2.    status: true,     //布尔类型
  3.    albumVideoPath:'' //字符串类型；视频在相册的绝对路径，可用此路径播放该视频
  4.    fileSize: 3819599 //视频文件大小；byte为单位
  5.    duration: 4       //视频时长；单位为秒
  6.    savePath:''        //字符串类型；视频保存的沙河路径；可用此路径进行播放、上传等操作；仅在isSave为true时返回 （仅支持iOS）
  7. }

err：

  • 类型：JSON 对象
  • 内部字段：
  1. {
  2.  code:-1
  3. }

示例代码

  1. var UIAlbumBrowser = api.require('UIAlbumBrowser');
  2. UIAlbumBrowser.transVideoPath({
  3.     path: ''
  4. }, function(ret, err) {
  5.     if (ret) {
  6.         alert(JSON.stringify(ret));
  7.     } else {
  8.         alert(JSON.stringify(err));
  9.     }
  10. });

可用性

iOS系统

可提供的1.0.0及更高版本

getVideoDuration

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

params

path：

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

callback(ret)

ret：

  • 类型：JSON 对象
  • 内部字段：
  1. {
  2.    duration: 60    //数字类型；视频时长,单位为毫秒
  3. }

示例代码

  1. var UIAlbumBrowser = api.require('UIAlbumBrowser');
  2. UIAlbumBrowser.getVideoDuration({
  3.     path: ''
  4. }, function(ret, err) {
  5.     if (ret) {
  6.         alert(JSON.stringify(ret));
  7.     } else {
  8.         alert(JSON.stringify(err));
  9.     }
  10. });

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

openGroup

openGroup({params}, callback(ret))

以 frame 形式打开一个图片预览区域

params

rect：

  • 类型：JSON 对象
  • 描述：（可选项）模块的位置及尺寸
  • 内部字段：
  1. {
  2.     x: 0,   //（可选项）数字类型；模块左上角的 x 坐标（相对于所属的 Window 或 Frame）；默认：0
  3.     y: 0,   //（可选项）数字类型；模块左上角的 y 坐标（相对于所属的 Window 或 Frame）；默认：0
  4.     w: 320, //（可选项）数字类型；模块的宽度；默认：屏幕宽度
  5.     h: 200  //（可选项）数字类型；模块的高度；默认：w 
  6. }

groupId:

注意:若groupId为空,则会默认打开相机胶卷(所有照片)的相册分类

  • 类型：字符串
  • 描述：(可选项)要打开的相册分组 ID

selectedPaths：

  • 类型：数组
  • 描述：（可选项）图片预览区域默认选中图片的路径组成的数组

fixedOn：

  • 类型：字符串类型
  • 描述：（可选项）模块视图添加到指定 frame 的名字（只指 frame，传 window 无效）
  • 默认：模块依附于当前 window

fixed:

  • 类型：布尔
  • 描述：（可选项）模块是否随所属 window 或 frame 滚动
  • 默认值：true（不随之滚动）

callback(ret)

ret：

  • 类型：JSON 对象
  • 内部字段：
  1. {
  2.    groupName:''                      //字符串类型；分组名称当'groupId'为空时,会返回
  3.    eventType: 'camera',              //字符串类型；交互事件类型，取值范围如下：
  4.                                      //camera：点击拍照按钮
  5.                                      //select：选中图片事件
  6.                                      //cancel：取消选中图片事件
  7.                                      //show：打开预览区域成功事件
  8.                                      //change：改变显示分组成功事件
  9.    groupId: '',                      //字符串类型；当前分组 ID                                  
  10.    target:{                          //JSON对象；返回所操作的资源信息
  11.         gifImagePath:'',             //字符串类型（Android 暂不支持gif图片格式）；gif图路径，返回gif图在本地的绝对路径，可直接使用 
  12.         path: '',                    //字符串类型；资源路径，返回资源在本地的绝对路径，注意：iOS 平台上需要用 transPath 接口转换之后才可读取原图
  13.         thumbPath: '',               //字符串类型；缩略图路径，返回资源缩略图在本地的绝对路径
  14.     }
  15. }

示例代码

  1. var UIAlbumBrowser = api.require('UIAlbumBrowser');
  2. UIAlbumBrowser.openGroup({
  3.     groupId:''
  4. }, function(ret) {
  5.     alert(JSON.stringify(ret));
  6. });

可用性

iOS系统，Android系统

可提供的1.0.3及更高版本

changeGroup

通过分组ID改变预览区域显示的分组图片

changeGroup({params})

params

groupId:

  • 类型：字符串
  • 描述：要改变的相册分组 ID

selectedPaths：

  • 类型：数组
  • 描述：（可选项）图片预览区域默认选中图片的路径组成的数组

示例代码

  1. var UIAlbumBrowser = api.require('UIAlbumBrowser');
  2. UIAlbumBrowser.changeGroup({
  3.     groupId:''
  4. });

可用性

iOS系统，Android系统

可提供的1.0.3及更高版本

closeGroup

关闭打开的相册分组预览区域

closeGroup()

示例代码

  1. var UIAlbumBrowser = api.require('UIAlbumBrowser');
  2. UIAlbumBrowser.close();

可用性

iOS系统，Android系统

可提供的1.0.3及更高版本

openAlbum

以 frame 形式打开一个图片预览区域

openAlbum({params}, callback(ret))

params

rect：

  • 类型：JSON 对象
  • 描述：（可选项）模块的位置及尺寸
  • 内部字段：
  1. {
  2.     x: 0,   //（可选项）数字类型；模块左上角的 x 坐标（相对于所属的 Window 或 Frame）；默认：0
  3.     y: 0,   //（可选项）数字类型；模块左上角的 y 坐标（相对于所属的 Window 或 Frame）；默认：0
  4.     w: 320, //（可选项）数字类型；模块的宽度；默认：屏幕宽度
  5.     h: 200  //（可选项）数字类型；模块的高度；默认：w 
  6. }

groupId:

注意:若groupId为空,则会默认打开相机胶卷(所有照片)的相册分类

  • 类型：字符串
  • 描述：(可选项)要打开的相册分组 ID

max：

  • 类型：数字
  • 描述：（可选项）最多选择几张图片，超过max则用户点击选中按钮只返回eventType为max的事件回调，不会执行选中操作（点击的图片还是未选中状态）
  • 默认值：9

type：

  • 类型：字符串
  • 描述：（可选项）显示图片或显示图片和视频
  • 取值范围：
    • all：展示图片和视频（视频资源缩略图区域左下角有视频小标签）
    • image：只展示图片
    • video：只展示视频（视频资源缩略图区域左下角有视频小标签）
  • 注意：type为all时，视频和图片不能同时选中（否则会提示错误）。且max参数只对图片有效。若选择视频时模块视为一次选择行为完结。

styles：

  • 类型：JSON对象
  • 描述：
  • 内部字段：
  1. {
  2.       column:3,      //（可选项）数字类型；列数；默认：3
  3.       interval: ,    //（可选项）数字类型；每列和每行之间的间距；默认：5
  4.       selector: {    //（可选项）JSON类型；选择器样式配置
  5.          normal: ‘’, //（可选项）字符串类型；选择器常态图标，要求本地路径（fs、widget协议）；默认：默认图标
  6.          active: ‘’, //（可选项）字符串类型；选择器选中图标，要求本地路径（fs、widget协议）；默认：默认图标
  7.          size:   ,   //（可选项）数字类型；选择器大小（正方形边长）；默认：20
  9.       }
  10. }

videoPreview：

  • 类型：布尔
  • 描述：（可选项）选中视频资源时，是否进入预览页面，若为false则直接callback相关信息
  • 默认值：true

fixedOn：

  • 类型：字符串类型
  • 描述：（可选项）模块视图添加到指定 frame 的名字（只指 frame，传 window 无效）
  • 默认：模块依附于当前 window

fixed:

  • 类型：布尔
  • 描述：（可选项）模块是否随所属 window 或 frame 滚动
  • 默认值：true（不随之滚动）

callback(ret)

ret：

  • 类型：JSON 对象
  • 内部字段：
  1. {
  2.    groupName:''                      //字符串类型；分组名称当'groupId'为空时,会返回
  3.    eventType: 'show',                //字符串类型；交互事件类型，取值范围如下：
  4.                                      //select：选中事件
  5.                                      //cancel：取消选中图片事件
  6.                                      //show：打开预览区域成功事件
  7.                                      //max：超过最大选中图片数事件
  8.    groupId: '',                      //字符串类型；当前分组 ID                                  
  9.    target:{                          //JSON对象；返回所操作的资源信息，仅当 eventType 为 select 时返回值
  10.         type:'image',                //字符串类型；资源类型，image：图片，video：视频
  11.         gifImagePath:'',             //字符串类型（Android 暂不支持gif图片格式）；gif图路径，返回gif图在本地的绝对路径，可直接使用 注意:当gifImagePath存在，则不返回path和thumbPath路径
  12.         path: '',                    //字符串类型；资源路径，返回资源在本地的绝对路径，注意：iOS 平台上需要用 transPath 接口转换之后才可读取原图
  13.         thumbPath: '',               //字符串类型；缩略图路径，返回资源缩略图在本地的绝对路径
  14.     }
  15. }

示例代码

  1. var UIAlbumBrowser = api.require('UIAlbumBrowser');
  2. UIAlbumBrowser.openAlbum({
  3.     groupId:''
  4. }, function(ret) {
  5.     alert(JSON.stringify(ret));
  6. });

可用性

iOS系统，Android系统

可提供的1.0.3及更高版本

closeAlbum

关闭 openAlbum 打开的相册预览区域

closeAlbum()

示例代码

  1. var UIAlbumBrowser = api.require('UIAlbumBrowser');
  2. UIAlbumBrowser.closeAlbum();

可用性

iOS系统，Android系统

可提供的1.0.3及更高版本

batchTransPath

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

batchTransPath({params}, callback(ret))

params

path：

  • 类型：数组
  • 描述：要转换的图片路径（在相册库的绝对路径）

callback(ret)

ret：

  • 类型：JSON 对象
  • 内部字段：
  1. {
  2.    path: ''          //数组类型；相册内图片被拷贝到临时文件夹，返回已拷贝图片的绝对路径 
  3. }

err：

  • 类型：JSON 对象
  • 内部字段：
  1. {
  2.   status: false     //转化失败
  3. }

示例代码

  1. var UIAlbumBrowser = api.require('UIAlbumBrowser');
  2. UIAlbumBrowser.batchTransPath({
  3.     path: ['','','']
  4. }, function(ret, err) {
  5.     if (ret) {
  6.         alert(JSON.stringify(ret));
  7.     } else {
  8.         alert(JSON.stringify(err));
  9.     }
  10. });

可用性

iOS系统，Android系统

可提供的1.0.9及更高版本

getImgInfo

getImgInfo({params}, callback(ret))

获取图片信息

params

imagePath:

  • 类型：字符串
  • 描述：图片路径支持fs://,widget://;

callback(ret，err)

ret：

  • 类型：JSON 对象
  • 内部字段：Android
  1. {
  3.     status: true,           //布尔型；是否成功获取图片信息
  4.     info:{                        //JSON对象类型；照片信息,以下字段有值则正差返回该值，没有该字段信息则返回‘’
  5.      aperture:              //字符串类型；光圈值
  6.      dateTime:              //字符串类型；拍摄时间
  7.      exposureTime:       //字符串类型；曝光时间
  8.      flash:                         //字符串类型；闪光灯
  9.      focalLength:             //字符串类型；焦距
  10.      height:                       //字符串类型；图片高度
  11.      width:                        //字符串类型；图片宽度
  12.      device:                        //字符串类型；设备品牌
  13.      deviceModel:             //字符串类型；设备型号
  14.      orientation:                 //字符串类型；旋转角度
  15.      longitude:                     //字符串类型；经度
  16.      latitude:                        //字符串类型；纬度
  17.     }          
  18. }
  • 内部字段：iOS
  1. {
  2.     status: true,           //布尔型；是否成功获取图片信息
  3.     info:{                        //JSON对象类型；照片信息，以下字段有值则正差返回该值，没有该字段信息则返回undefined
  5.         ColorModel:'',                                  //字符串类型；图像的颜色模式
  6.         DPIHeight:'',                                   //字符串类型；DPI高度
  7.         DPIWidth:'',                                    //字符串类型；DPI宽度
  8.         Depth:'',                                       //字符串类型；颜色位数
  9.         Orientation:'',                                 //字符串类型；图片的显示方向；取值如下：
  10.                                                                 // 1  =  左上到右下.  
  11.                                                                 // 2  =  右上到左下.  
  12.                                                                 // 3  =  右下到左上.
  13.                                                                 // 4  =  左下到右上.  
  14.                                                                 // 5  =  行列置换 左上到右下.  
  15.                                                                 // 6  =  行列置换 右上到左下.  
  16.                                                                 // 7  =  行列置换 右下到左上.  
  17.                                                                 // 8  =  行列置换 左下到右上.                                                           
  18.         PixelHeight:'',                                  //字符串类型；像素高度
  19.         PixelWidth:'',                                   //字符串类型；像素宽度
  20.         ProfileName:'sRGB IEC61966-2.1',                 //字符串类型；嵌入图片的ICC配置文件名称
  21.         "{Exif}":    {
  22.             ApertureValue:'2.275007124536905',           //字符串类型；孔径值
  24.             BrightnessValue:'3.086726998491705',         //字符串类型；亮度值
  25.             ColorSpace:'',                               //字符串类型；色彩空间
  26.             ComponentsConfiguration:[],                  //数组类型；压缩配置
  27.             DateTimeDigitized:'2018:11:03 17:10:11',     //字符串类型；数字化日期时间
  28.             DateTimeOriginal:'2018:11:03 17:10:11',      //字符串类型；原始日期时间
  29.             ExifVersion:[],                              //数组类型；Exif版本
  30.             ExposureBiasValue:'',                        //字符串类型；曝光偏差值
  31.             ExposureMode:'',                             //字符串类型；曝光模式
  32.             ExposureProgram:'',                          //字符串类型；曝光程序
  33.             ExposureTime:'0.05882352941176471',          //字符串类型；曝光时间
  34.             FNumber:'2.2',                               //字符串类型；ExifNumber
  35.             Flash:'',                                    //字符串类型；拍摄时的闪光状态
  36.             FlashPixVersion:[];                          //数组类型；FlashPix版本信息
  37.             FocalLenIn35mmFilm:'',                       //字符串类型；35毫米胶片的等效焦距
  38.             FocalLength:'4.15',                          //字符串类型；焦距
  39.             ISOSpeedRatings:[],                          //数组类型；ISO速度等级
  40.             LensMake:'',                                 //字符串类型；透镜制造商名称
  41.             LensModel:'',                                //字符串类型；透镜模式
  42.             LensSpecification:[],                        //数组类型；透镜规格信息
  43.             MeteringMode:'',                             //字符串类型；测量模式
  44.             PixelXDimension:'',                          //字符串类型；X方向像素
  45.             PixelYDimension:'',                          //字符串类型；Y方向像素
  46.             SceneCaptureType:'',                         //字符串类型；场景捕捉类型（标准，景观，肖像，夜晚）
  47.             SceneType:'',                                //字符串类型；场景类型
  48.             SensingMethod:'',                            //字符串类型；传感器类型
  49.             ShutterSpeedValue:'4.059158134243458',       //字符串类型；快门速度值
  50.             SubjectArea:[],                              //数组类型；主体区域
  51.             SubsecTimeDigitized:'',                      //字符串类型；数字时间
  52.             SubsecTimeOriginal:'',                       //字符串类型；原始时间
  53.             WhiteBalance:'',                             //字符串类型；白平衡模式
  54.         };
  55.         "{GPS}":    {
  56.             DateStamp:'2018:11:03',                      //字符串类型；日期时间
  57.             DestBearing:'',                              //字符串类型；地理方位
  58.             DestBearingRef:'',                           //字符串类型；方位参照
  59.             HPositioningError:'',                        //字符串类型；错误信息
  60.             ImgDirection:'',                             //字符串类型；位置方向
  61.             ImgDirectionRef:'',                          //字符串类型；位置方向参考
  62.             Latitude:'',                                 //字符串类型；地理纬度
  63.             LatitudeRef:'',                              //字符串类型；地理纬度南纬或北纬
  64.             Longitude:'',                                //字符串类型；地理经度
  65.             LongitudeRef:'',                             //字符串类型；地理经度 东经或西经
  66.             Speed:'',                                    //字符串类型；速度            SpeedRef:'',                                 //字符串类型；速度标准
  67.             TimeStamp:'',                                //字符串类型；时间戳
  68.         },
  69.         "{MakerApple}":{},                               //json对象；Apple相机信息
  70.         "{TIFF}":    {
  71.             DateTime:'',                                 //字符串类型；日期时间
  72.             Make:'',                                     //相机设备名
  73.             Model:'',                                    //相机设备模式
  74.             Orientation:'',                              //图片方向
  75.             ResolutionUnit:'',                           //字符串类型；分辨率单位
  76.             Software:'',                                 //字符串类型；创建图像的软件名称和版本
  77.             XResolution:'',                              //字符串类型；横向每个分辨位的像素数
  78.             YResolution:'',                              //字符串类型；纵向每个分辨位的像素数
  79.         },
  80.         {JFIF}":{
  81.         DensityUnit:'',                                 //字符串类型；像素密度单元
  82.         JFIFVersion:[],                                 //数组类型；JFIF版本
  83.         XDensity:'',                                    //字符串类型；横向像素密度
  84.         YDensity:'',                                    //字符串类型；纵向像素密度
  86.     }
  88.     }   
  89. }

示例代码

  1. var UIAlbumBrowser = api.require('UIAlbumBrowser');
  2. UIAlbumBrowser.getImgInfo({
  4.     imagePath:''
  5. }, function(ret, err) {
  6.     if (ret) {
  7.         alert(JSON.stringify(ret));
  8.     } else {
  9.         alert(JSON.stringify(err));
  10.     }
  11. });

可用性

iOS系统，Android系统

可提供的1.0.3及更高版本

论坛示例

为帮助用户更好更快的使用模块，论坛维护了一个示例，示例中包含示例代码、知识点讲解、注意事项等，供您参考。