UIMediaScanner

来自于：官方立即使用

open scan fetch transPath getVideoDuration

模块概述

UIMediaScanner 模块是 mediaScanner 模块的优化升级版。同时本模块已有升级优化版：UIAlbumBrowser

注意：本模块已停止更新，建议使用 UIAlbumBrowser 代替

UIMediaScanner 是一个本地媒体资源扫描器，在 Android 平台上可扫描整个设备的资源，iOS 仅扫描相册内的资源。开发者可通过 open 内的 type 参数控制要扫描的资源类型。

本模块封装了两种方案。

方案一：

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

方案二：

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

以上两种方案详细功能，请参考接口说明。

图片说明

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

模块接口

本模块源码开源地址为：https://github.com/apicloudcom/UIMediaScanner

实例widget下载地址

open

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

open({params}, callback(ret))

params

type：

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

column：

  • 类型：数字
  • 描述：（可选项）图片显示的列数，须大于1
  • 默认值：4

classify：

  • 类型：布尔
  • 描述：（可选项）是否将图片分类显示（为 true 时，会首先跳转到相册分类列表页面）
  • 默认值：false

max：

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

sort：

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

texts：

  • 类型：JSON 对象
  • 描述：（可选项）模块各部分的文字内容
  • 内部字段：
  1. {
  2.     stateText: '已选择*项',         //（可选项）字符串类型；状态文字内容；*号会被替换为已选择个数；默认：'已选择*项'
  3.     cancelText: '取消',             //（可选项）字符串类型；取消按钮文字内容；默认：'取消'
  4.     finishText: '完成',             //（可选项）字符串类型；完成按钮文字内容；默认：'完成'
  5.     selectedMaxText: '超过*个了！',  //（可选项）字符串类型；最多显示提示语，*号会被替换为已选择个数;默认：'最多显示*个资源'
  6.     okBtnText: '我知道了',          //（可选项）字符串类型；确认按钮显示文本，默认：'我知道了'（仅支持ios，Android弹出Toast，无需确定按钮）
  7.     classifyTitle:'相簿'           //（可选项）字符串类型；分类列表的标题文字；默认：相簿。仅当 classify 为true时本参数有效
  8. }

styles：

  • 类型：JSON 对象
  • 描述：（可选项）模块各部分的样式
  • 内部字段：
  1. {
  2.     bg: '#FFFFFF',                      //（可选项）字符串类型；资源选择器背景，支持 rgb，rgba，#；默认：'#FFFFFF'
  3.     mark: {                             //（可选项）JSON对象；选中图标的样式
  4.         icon: '',                       //（可选项）字符串类型；图标路径（本地路径，支持fs://、widget://）；默认：对勾图标
  5.         position: 'bottom_left',        //（可选项）字符串类型；图标的位置，默认：'bottom_left'
  6.                                         // 取值范围：
  7.                                         // top_left（左上角）
  8.                                         // bottom_left（左下角）
  9.                                         // top_right（右上角）
  10.                                         // bottom_right（右下角）
  11.         size: 20                        //（可选项）数字类型；图标的大小；默认：显示的缩略图的宽度的三分之一
  12.     },
  13.     nav: {                              //（可选项）JSON对象；导航栏样式
  14.         bg: '#eee',                     //（可选项）字符串类型；导航栏背景，支持 rgb，rgba，#；默认：'#eee'
  15.         stateColor: '#000',             //（可选项）字符串类型；状态文字颜色，支持 rgb，rgba，#；默认：'#000'
  16.         stateSize: 18,                  //（可选项）数字类型；状态文字大小，默认：18
  17.         cancelBg: 'rgba(0,0,0,0)',      //（可选项）字符串类型；取消按钮背景，支持 rgb，rgba，#；默认：'rgba(0,0,0,0)'
  18.         cancelColor: '#000',            //（可选项）字符串类型；取消按钮的文字颜色；支持 rgb，rgba，#；默认：'#000'
  19.         cancelSize: 18,                 //（可选项）数字类型；取消按钮的文字大小；默认：18
  20.         finishBg: 'rgba(0,0,0,0)',      //（可选项）字符串类型；完成按钮的背景，支持 rgb，rgba，#；默认：'rgba(0,0,0,0)'
  21.         finishColor: '#000',            //（可选项）字符串类型；完成按钮的文字颜色，支持 rgb，rgba，#；默认：'#000'
  22.         finishSize: 18                  //（可选项）数字类型；完成按钮的文字大小；默认：18
  23.     }
  24. }

scrollToBottom：

  • 类型：JSON 对象
  • 默认值：见内部字段
  • 描述：（可选项）打开媒体资源界面后间隔一段时间开始自动滚动到底部设置
  • 内部字段：
  1. {
  2.    intervalTime:       //（可选项）数字类型；打开媒体资源界面后间隔的时间开始自动滚动到底部，单位秒（s），小于零的数表示不滚动到底部；默认：-1
  3.    anim:               //（可选项）布尔类型；滚动时是否添加动画，android 平台不支持动画效果；默认true
  4. }

exchange：

  • 类型：布尔
  • 默认值：false
  • 描述：是否交换‘确定’和‘取消’按钮的位置（默认‘取消’按钮在右边，‘确定’按钮在左边）

rotation：

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

showPreview：

  • 类型：布尔
  • 默认值：false
  • 描述：是否支持返回预览事件
  • 注意：
  1. {
  2.    当本参数为 true 时，styles-》mark-》position 参数恒为 top_right，切此时模块会为 mark 提供一个未选中时的图标。当用户点击缩略图右上角时，触发选中/取消事件。当用户点击已选中的缩略图其它区域时，触发预览事件，并且模块会把当前所选中的所有图片信息回调给前端。
  3. }

showBrowser：

  • 类型：布尔
  • 默认值：false
  • 描述：是否支持打开已选图片预览效果
  • 注意：
  1. {
  2.    当本参数为 true 时，styles-》mark-》position 参数恒为 top_right，切此时模块会为 mark 提供一个未选中时的图标。当用户点击缩略图右上角时，触发选中/取消事件。当用户点击已选中的缩略图其它区域时，触发已选图片预览事件，并且模块自动跳转到图片预览界面。预览界面完成按钮事件同本接口回调函数里的confirm
  3. }

callback(ret)

ret：

  • 类型：JSON 对象
  • 内部字段：
  1. {
  2.     eventType: cancel,               // 字符串类型 按钮点击事件 取值范围
  3.                                      // confirm 点击确定按钮
  4.                                      // cancel 点击取消按钮
  5.                                      // preview 用户点击缩略图触发的预览事件，仅当 showPreview 为 true 时有效
  6.                                      // albumError（访问相册失败）
  7.     list: [{                         //数组类型；返回选定的资源信息数组
  8.         path: '',                    //字符串类型；资源路径，返回资源在本地的绝对路径，注意：iOS 平台上需要用 transPath 接口转换之后才可读取原图
  9.         thumbPath: '',               //字符串类型；缩略图路径，返回资源缩略图在本地的绝对路径
  10.         suffix: '',                  //字符串类型；文件后缀名，如：png，jpg, mp4
  11.         size: 1048576,               //数字类型；资源大小，单位（Bytes）
  12.         time: '2015-06-29 15:49',    //字符串类型；资源创建时间，格式：yyyy-MM-dd HH:mm:ss
  13.         duration: -1                 //数字类型；若资源为视频时，则返回其视频时长，若为图片时本次参数为-1，暂仅支持 iOS 平台                          
  14.     }]
  15. }

示例代码

  1. var UIMediaScanner = api.require('UIMediaScanner');
  2. UIMediaScanner.open({
  3.     type: 'picture',
  4.     column: 4,
  5.     classify: true,
  6.     max: 4,
  7.     sort: {
  8.         key: 'time',
  9.         order: 'desc'
  10.     },
  11.     texts: {
  12.         stateText: '已选择*项',
  13.         cancelText: '取消',
  14.         finishText: '完成'
  15.     },
  16.     styles: {
  17.         bg: '#fff',
  18.         mark: {
  19.             icon: '',
  20.             position: 'bottom_left',
  21.             size: 20
  22.         },
  23.         nav: {
  24.             bg: '#eee',
  25.             stateColor: '#000',
  26.             stateSize: 18,
  27.             cancelBg: 'rgba(0,0,0,0)',
  28.             cancelColor: '#000',
  29.             cancelSize: 18,
  30.             finishBg: 'rgba(0,0,0,0)',
  31.             finishColor: '#000',
  32.             finishSize: 18
  33.         }
  34.     },
  35.     scrollToBottom: {
  36.         intervalTime: 3,
  37.         anim: true
  38.     },
  39.     exchange: true,
  40.     rotation: true
  41. }, function(ret) {
  42.     if (ret) {
  43.         alert(JSON.stringify(ret));
  44.     }
  45. });

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

scan

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

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

params

type：

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

count：

  • 类型：数字
  • 描述：（可选项）每次返回的资源数量；
  • 默认：全部资源数量

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

showGroup：

  • 类型：布尔类型
  • 描述：（可选项）是否返回图片所在分组名，本参数对 android 平台无效
  • 默认：false（在 android 平台上本参数始终为 true）
  • 注意：
  1. {
  2.     由于系统平台差异，iOS 上和 android 上相册分组策略有所不同。
  4.     iOS 上系统相册分组策略如下：
  5.     相机胶卷（All组）:  a,b,c,d,e,f,g
  6.     A组：a
  7.     B组：b,c
  8.     C组：f,g
  10.     android 上系统相册分组策略如下：
  11.     A组：a
  12.     B组：b,c
  13.     C组：d,e,f,g
  15.     因此，若要在 android 平台上显示 All 组，开发者需自行组合。
  16. }

callback(ret)

ret：

  • 类型：JSON 对象
  • 内部字段：
  1. {
  2.     eventType: cancel,               // 字符串类型 按钮点击事件 取值范围
  3.                                      // success （获取成功）
  4.                                      // albumError（访问相册失败）
  5.     total: 100,                      //数字类型；媒体资源总数
  6.     list: [{                         //数组类型；返回指定的资源信息数组
  7.           path: '',                    //字符串类型；资源路径，返回资源在本地的绝对路径。注意：在 iOS 平台上需要先调用 transPath 接口将路径转换之后才能读取目标资源媒体文件
  8.         thumbPath: '',               //字符串类型；缩略图路径，返回资源缩略图在本地的绝对路径
  9.         suffix: '',                  //字符串类型；文件后缀名，如：png，jpg, mp4
  10.         size: 1048576,               //数字类型；资源大小，单位（Bytes）
  11.         time: '2015-06-29 15:49:22,  //字符串类型；资源创建时间，格式：yyyy-MM-dd HH:mm:ss
  12.         groupName: ''                //字符串类型；所在相册分组的组名，在 iOS 平台上仅当 showGroup 为 true 时本参数有值
  13.     }]
  14. }

示例代码

  1. var UIMediaScanner = api.require('UIMediaScanner');
  2. UIMediaScanner.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.         path: '',                    //字符串类型；资源路径，返回资源在本地的绝对路径。注意：在 iOS 平台上需要先调用 transPath 接口将路径转换之后才能读取目标资源媒体文件
  4.         thumbPath: '',               //字符串类型；缩略图路径，返回资源缩略图在本地的绝对路径
  5.         suffix: '',                  //字符串类型；文件后缀名，如：png，jpg, mp4
  6.         size: 1048576,               //数字类型；资源大小，单位（Bytes）
  7.         time: '2015-06-29 15:49',    //字符串类型；资源创建时间，格式：yyyy-MM-dd HH:mm:ss
  8.         groupName: ''                //字符串类型；所在相册分组的组名，在 iOS 平台上仅当 scan 接口内 showGroup 为 true 时本参数有值
  9.     }]
  10. }

示例代码

  1. var UIMediaScanner = api.require('UIMediaScanner');
  2. UIMediaScanner.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及更高版本

transPath

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

注意：本接口只对 iOS 平台有效，在 android 平台上不做任何处理，会把原路径返回

transPath({params}, callback(ret))

params

path：

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

scale：

  • 类型：JSON 对象
  • 描述：（可选项）从本地相册拷贝图片到缓存目录时对图片的压缩处理，若不传则取内部字段中的默认值
  • 内部字段：
  1. {
  2.      untreated: false,  //（可选项）布尔类型；是否获取原图，若获取原图可能有图片旋转的问题；默认：false
  3.      quality: 50,       //（可选项）数字类型；压缩图片后的质量，只针对jpg格式图片有效，取值范围：0-100；默认：50
  4.      width: ,           //（可选项）数字类型；压缩后的图片宽度，图片会按比例适配此宽度；默认：原图宽度
  5.      height:            //（可选项）数字类型；压缩后的图片高度，图片会按比例适配此高度；默认：原图高度
  6. }

callback(ret)

ret：

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

示例代码

  1. var UIMediaScanner = api.require('UIMediaScanner');
  2. UIMediaScanner.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及更高版本

getVideoDuration

getVideoDuration({params}, callback(ret))

params

path：

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

callback(ret)

ret：

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

示例代码

  1. var UIMediaScanner = api.require('UIMediaScanner');
  2. UIMediaScanner.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及更高版本