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
  6. android 上系统相册分组策略如下:
  7. A组:a
  8. B组:b,c
  9. C组:d,e,f,g
  10. 因此,若要在 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://);默认:圆形绿色对勾图标
  6. position: 'bottom_left', //(可选项)字符串类型;图标的位置,默认:'bottom_left'
  7. // 取值范围:
  8. // top_left(左上角)
  9. // bottom_left(左下角)
  10. // top_right(右上角)
  11. // bottom_right(右下角)
  12. size: 20 //(可选项)数字类型;图标的大小;默认:显示的缩略图的宽度的三分之一
  13. },
  14. nav: { //(可选项)JSON对象;导航栏样式
  15. bg: '#eee', //(可选项)字符串类型;导航栏背景,支持 rgb,rgba,#;默认:'rgba(0,0,0,0.6)'
  16. titleText:'', //(可选项)字符串类型;标题 (仅支持安卓)
  17. titleColor: '#fff', //(可选项)字符串类型;标题文字颜色,支持 rgb,rgba,#;默认:'#fff'
  18. titleSize: 18, //(可选项)数字类型;标题文字大小,默认:18
  19. cancelColor: '#fff', //(可选项)字符串类型;取消按钮的文字颜色;支持 rgb,rgba,#;默认:'#fff'
  20. cancelSize: 16, //(可选项)数字类型;取消按钮的文字大小;默认:18
  21. cancelText: '中国', //(可选项)字符串类型;取消按钮文字内容;默认:'取消'
  22. finishText: '嗯嗯', //(可选项)字符串类型;完成按钮文字内容;默认:'完成'
  23. finishColor: '#fff', //(可选项)字符串类型;完成按钮的文字颜色,支持 rgb,rgba,#;默认:'#fff'
  24. finishWidth: 50, //(可选项)数字类型;完成按钮的宽度;默认:50 (仅支持iOS)
  25. unFinishColor: 'rgba(64,224,208,0.25)', //(可选项)字符串类型;打开页面还未选择图片或视频的完成按钮的文字颜色,支持 rgb,rgba,#;默认:'rgba(64,224,208,0.25)'
  26. finishSize: 16, //(可选项)数字类型;完成按钮的文字大小;默认:16
  27. numberSize: 20, //(可选项)数字类型;数字显示的大小;默认:20 **仅支持iOS**
  28. numberFontSize:14, //(可选项)数字类型;数字显示文字的大小;默认:14 **仅支持iOS**
  29. numberTextColor:'#fff', //(可选项)字符串类型;数字显示的文字颜色,支持 rgb,rgba,#;默认:'#fff' **仅支持iOS**
  30. numberBgColor:'#00FA9A', //(可选项)字符串类型;数字显示的背景颜色,支持 rgb,rgba,#;默认:'#00FA9A' **仅支持iOS**
  31. numberCorner:10, //(可选项)字符串类型;数字显示的圆角度,#;默认:10 **仅支持iOS**
  32. },
  33. bottomTabBar: { //(可选项)JSON对象;底部导航栏样式 **该项参数仅支持iOS**
  34. bg: 'rgba(0,0,0,0.6)', //(可选项)字符串类型;底部导航栏背景,支持 rgb,rgba,#;默认:'rgba(0,0,0,0.6)'
  35. unPreviewTitleColor:'rgba(0,0,0,0.25)',//(可选项)字符串类型;打开页面还未选择图片或视频的预览的文字颜色,支持 rgb,rgba,#;默认:'rgba(0,0,0,0.25)'
  36. previewTitleColor: '#000000', //(可选项)字符串类型;选择图片或视频的预览的文字颜色,支持 rgb,rgba,#;默认:'#000000'
  37. previewTitle:'预览', //(可选项)字符串类型;选择图片或视频的预览的文字;默认:'预览'
  38. previewTitleSize: 15, //(可选项)数字类型;标题文字大小,默认:15
  39. }
  40. }

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. }
  28. }

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
  8. }
  9. }

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

示例代码

  1. var UIAlbumBrowser = api.require('UIAlbumBrowser');
  2. UIAlbumBrowser.getImgInfo({
  3. imagePath:''
  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.3及更高版本

论坛示例

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