UIMediaScanner

open fetch getVideoDuration

模块概述

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

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

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

本模块封装了两种方案。

方案一：

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

方案二：

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

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

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

本模块源码开源地址为：

实例widget下载地址

open

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

open({params}, callback(ret))

params

type：

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

column：

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

classify：

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

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

sort：

• 类型：JSON 对象
• 描述：（可选项）图片排序方式
• 内部字段：

texts：

• 类型：JSON 对象
• 描述：（可选项）模块各部分的文字内容
• 内部字段：

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

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，#；默认：'#eee'
        stateColor: '#000',             //（可选项）字符串类型；状态文字颜色，支持 rgb，rgba，#；默认：'#000'
        stateSize: 18,                  //（可选项）数字类型；状态文字大小，默认：18
        cancelBg: 'rgba(0,0,0,0)',      //（可选项）字符串类型；取消按钮背景，支持 rgb，rgba，#；默认：'rgba(0,0,0,0)'
        cancelColor: '#000',            //（可选项）字符串类型；取消按钮的文字颜色；支持 rgb，rgba，#；默认：'#000'
        cancelSize: 18,                 //（可选项）数字类型；取消按钮的文字大小；默认：18
        finishBg: 'rgba(0,0,0,0)',      //（可选项）字符串类型；完成按钮的背景，支持 rgb，rgba，#；默认：'rgba(0,0,0,0)'
        finishColor: '#000',            //（可选项）字符串类型；完成按钮的文字颜色，支持 rgb，rgba，#；默认：'#000'
        finishSize: 18                  //（可选项）数字类型；完成按钮的文字大小；默认：18
    }
}

scrollToBottom：

• 类型：JSON 对象
• 默认值：见内部字段
• 描述：（可选项）打开媒体资源界面后间隔一段时间开始自动滚动到底部设置
• 内部字段：

{
   intervalTime:       //（可选项）数字类型；打开媒体资源界面后间隔的时间开始自动滚动到底部，单位秒（s），小于零的数表示不滚动到底部；默认：-1
   anim:               //（可选项）布尔类型；滚动时是否添加动画，android 平台不支持动画效果；默认true
}

exchange：

• 类型：布尔
• 默认值：false

rotation：

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

showPreview：

• 类型：布尔
• 默认值：false
• 描述：是否支持返回预览事件
• 注意：

{
   当本参数为 true 时，styles-》mark-》position 参数恒为 top_right，切此时模块会为 mark 提供一个未选中时的图标。当用户点击缩略图右上角时，触发选中/取消事件。当用户点击已选中的缩略图其它区域时，触发预览事件，并且模块会把当前所选中的所有图片信息回调给前端。
}

showBrowser：

• 类型：布尔
• 默认值：false
• 描述：是否支持打开已选图片预览效果
• 注意：

{
   当本参数为 true 时，styles-》mark-》position 参数恒为 top_right，切此时模块会为 mark 提供一个未选中时的图标。当用户点击缩略图右上角时，触发选中/取消事件。当用户点击已选中的缩略图其它区域时，触发已选图片预览事件，并且模块自动跳转到图片预览界面。预览界面完成按钮事件同本接口回调函数里的confirm
}

callback(ret)

ret：

• 类型：JSON 对象
• 内部字段：

示例代码

var UIMediaScanner = api.require('UIMediaScanner');
UIMediaScanner.open({
    type: 'picture',
    column: 4,
    classify: true,
    max: 4,
    sort: {
        key: 'time',
        order: 'desc'
    },
    texts: {
        stateText: '已选择*项',
        cancelText: '取消',
        finishText: '完成'
    },
    styles: {
        bg: '#fff',
            icon: '',
            position: 'bottom_left',
            size: 20
        },
        nav: {
            bg: '#eee',
            stateColor: '#000',
            stateSize: 18,
            cancelBg: 'rgba(0,0,0,0)',
            cancelColor: '#000',
            cancelSize: 18,
            finishBg: 'rgba(0,0,0,0)',
            finishColor: '#000',
            finishSize: 18
        }
    },
    scrollToBottom: {
        intervalTime: 3,
        anim: true
    },
    exchange: true,
    rotation: true
}, function(ret) {
    if (ret) {
        alert(JSON.stringify(ret));
    }
});

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

scan

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

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

params

type：

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

count：

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

sort：

• 类型：JSON 对象
• 描述：（可选项）图片排序方式
• 内部字段：

{
    key: 'time',    //（可选项）字符串类型；排序方式；默认：'time'
                    //取值范围：
                    //time（按图片创建时间排序）
    order: 'desc'   //（可选项）字符串类型；排列顺序；默认：'desc'
                    //取值范围：
                    //asc（旧->新）
                    //desc（新->旧）
}

thumbnail：

• 类型：JSON 对象
• 描述：（可选项）返回的缩略图配置，建议本图片不要设置过大 若已有缩略图，则使用已有的缩略图。若要重新生成缩略图，可先调用清除缓存接口api.clearCache()。
• 内部字段：

{
      w: 100,     //（可选项）数字类型；返回的缩略图的宽；默认：100
      h: 100      //（可选项）数字类型；返回的缩略图的宽；默认：100
}

showGroup：

• 类型：布尔类型
• 默认：false（在 android 平台上本参数始终为 true）
• 注意：

{
    由于系统平台差异，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 组，开发者需自行组合。
}

• 类型：JSON 对象
• 内部字段：

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

示例代码

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

fetch

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

fetch(callback(ret))

callback(ret)

ret：

• 类型：JSON 对象
• 内部字段：

{
    list: [{                         //数组类型；返回指定的资源信息数组
        path: '',                    //字符串类型；资源路径，返回资源在本地的绝对路径。注意：在 iOS 平台上需要先调用 transPath 接口将路径转换之后才能读取目标资源媒体文件
        thumbPath: '',               //字符串类型；缩略图路径，返回资源缩略图在本地的绝对路径
        suffix: '',                  //字符串类型；文件后缀名，如：png，jpg, mp4
        size: 1048576,               //数字类型；资源大小，单位（Bytes）
        time: '2015-06-29 15:49',    //字符串类型；资源创建时间，格式：yyyy-MM-dd HH:mm:ss
        groupName: ''                //字符串类型；所在相册分组的组名，在 iOS 平台上仅当 scan 接口内 showGroup 为 true 时本参数有值
    }]
}

示例代码

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

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

transPath

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

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

transPath({params}, callback(ret))

params

path：

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

scale：

• 类型：JSON 对象
• 描述：（可选项）从本地相册拷贝图片到缓存目录时对图片的压缩处理，若不传则取内部字段中的默认值
• 内部字段：

{
     untreated: false,  //（可选项）布尔类型；是否获取原图，若获取原图可能有图片旋转的问题；默认：false
     quality: 50,       //（可选项）数字类型；压缩图片后的质量，只针对jpg格式图片有效，取值范围：0-100；默认：50
     width: ,           //（可选项）数字类型；压缩后的图片宽度，图片会按比例适配此宽度；默认：原图宽度
     height:            //（可选项）数字类型；压缩后的图片高度，图片会按比例适配此高度；默认：原图高度
}

ret：

• 类型：JSON 对象
• 内部字段：

{
   path: ''     //字符串类型；相册内图片被拷贝到临时文件夹，返回已拷贝图片的绝对路径
}

示例代码

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

可用性

iOS系统，Android系统

可提供的1.0.0及更高版本

getVideoDuration

getVideoDuration({params}, callback(ret))

params

path：

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

callback(ret)

ret：

• 类型：JSON 对象
• 内部字段：

示例代码

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

可用性

可提供的1.0.0及更高版本