WXPhotoPicker

立即使用

概述

WXPhotoPicker 是一个本地媒体资源扫描器,在 Android 平台上扫描图片库资源,

注意本模块在iPhone设备上仅支持 iOS9.0 及以上版本。

iOS 仅扫描相册内的资源。

本模块封装了几种方案。

方案一:

通过 open 接口打开一个自带 UI 界面的媒体资源浏览页面(高仿微信)

方案二:

通过 scan 接口扫描指定数量的媒体资源文件,本接口是纯功能类接口,不带界面。开发者可根据此接口扫描到的文件自行开发展示页面,极大的提高了自定义性。注意展示页面要做成赖加载模式,以免占用内存过高导致 app 假死。懒加载模式可通过 fetch 接口实现持续向下加载更多功能。注意:在 iOS 平台上需要先调用 transPath 接口将路径转换之后才能读取目标资源媒体文件。

方案三:

通过 scanGroups 接口扫描相册所有分组,本接口是纯功能类接口,不带界面。开发者可根据此接口扫描到的文件自行开发展示页面,极大的提高了自定义性。注意展示页面要做成赖加载模式,以免占用内存过高导致 app 假死。懒加载模式可通过 scanByGroupId 和 fetchGroup 接口实现持续向下加载更多功能。注意:在 iOS 平台上需要先调用 transPath 接口将路径转换之后才能读取目标资源媒体文件。

方案四:

通过 openGroup 接口以 frame(view)形式打开指定分组的选择器,本接口带界面。开发者可根据需求通过相关参数自定义展示页面,极大的提高了自定义性。通过 changeGroup 接口改变选择器展示的分组,closeGroup 可关闭选择器的 frame。注意:在 iOS 平台上需要先调用 transPath 接口将路径转换之后才能读取目标资源媒体文件。

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

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

模块接口

requestAlbumPermissions

请求相册权限(仅iOS支持)

requestAlbumPermissions( callback(ret))

callback(ret)

ret:

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

示例代码

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

可用性

iOS 系统

可提供的 1.0.0 及更高版本

open

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

本接口打开的选择器UI高仿微信,支持图片编辑、视频剪切等功能。

open({params}, callback(ret))

params

max:

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

styles:

  • 类型:JSON 对象
  • 描述:(可选项)模块各部分的样式
  • 内部字段:
{
    bg: '#313233',                  //(可选项)字符串类型;资源选择器背景色,支持 rgb,rgba,#;默认:'#313233'
    textColor: '#fff',         //(可选项)字符串类型;文字颜色,支持 rgb,rgba,#;默认:'#fff'
    mark: {                         //(可选项)JSON对象;选中图标的样式
       checked:'',                 //(可选项)字符串类型;选中状态下选中按钮的背景颜色;默认:'#32CD32'
       checkedText: '',              //(可选项)字符串类型;选中状态下选中按钮的文字颜色;默认:'#FFFFFF'                     
    },
    nav: {                          //(可选项)JSON对象;导航栏样式
        bg: '#343634',                 //(可选项)字符串类型;导航栏背景,支持 rgb,rgba,#;默认:'#343634'
         cancelText: '返回',         //(可选项)字符串类型;取消按钮文字内容;默认:'取消'(仅iOS支持)  
    },
    bottomTabBar: {           //(可选项)JSON对象;底部导航栏样式   
        bg: '#343634',  //(可选项)字符串类型;底部导航栏背景,支持 rgb,rgba,#;默认:'#343634'
         sendText: '发送',           //(可选项)字符串类型;发送按钮文字内容;默认:'发送' 
        sendBgColor:'#00FA9A',     //(可选项)字符串类型;发送按钮背景颜色,支持 rgb,rgba,#;默认:'#00FA9A'  
    }
}

alert:

  • 类型:JSON 对象
  • 描述:(可选项)超过设置的选中的数量时的提示框样式
  • 内部字段:
{
    content: '只能选*张',   //(可选项)字符串类型;超过设置的选中图片的数量时的提示框内容,*为max设置的数值。;默认:你最多只能选择*张照片
    title:'',              //(可选项)字符串类型;确认按钮文字;默认:我知道了(仅iOS支持)
}

videoTimeFilter:

  • 类型:数字
  • 描述:(可选项)选取视频的截取时长,单位秒。(仅iOS支持)
  • 默认:15

callback(ret)

ret:

  • 类型:JSON 对象
  • 内部字段:
{
    eventType: cancel,               //字符串类型;按钮点击事件,取值范围
                                     //confirm 用户点击确定按钮事件
                                     //cancel 用户点击取消按钮事件
    list: [{                         //数组类型;返回选定的资源信息数组
        gifImagePath:'',             //字符串类型;gif图路径,返回gif图在本地的绝对路径,可直接使用 注意:当gifImagePath存在,则不返回path、thumbPath以及videoPath路径
        videoPath:'',                 //字符串类型;返回视频在本地的绝对路径 
        path: '',                    //字符串类型;返回图片在本地的绝对路径 
        thumbPath: '',               //字符串类型;缩略图路径,返回资源缩略图在本地的绝对路径
        size: 1048576,               //数字类型;资源大小,单位(Bytes)
        time: '1490580032000',       //字符串类型;资源修改时间,格式:时间戳,单位为毫秒。  
        longitude:116.3718,           //数字类型;资源的经度 ;注意确认一下相机的定位权限是否被开启,如果不开启的话经纬度为0,查看方式:设置-->隐私-->定位服务-->相机 (仅支持iOS)
        latitude:39.982',             //数字类型;资源的纬度度 (仅iOS支持)   
    }]
}

示例代码

var WXPhotoPicker = api.require('WXPhotoPicker');
WXPhotoPicker.open({
    max: 9
}, function(ret) {
    if (ret) {
        api.alert({msg:JSON.stringify(ret)});
    }
});

可用性

iOS 系统,android 系统

可提供的 1.0.0 及更高版本

scan

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

scan({params}, callback(ret))

params

type:

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

count:

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

sort:

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

callback(ret)

ret:

  • 类型:JSON 对象
  • 内部字段:
{
    total: 100,                      //数字类型;媒体资源总数
    list: [{                          //数组类型;返回指定的资源信息数组
         gifImagePath:'',             //字符串类型;gif图路径,返回gif图在本地的绝对路径,可直接使用 注意:当gifImagePath存在,则不返回path、thumbPath和videoPath路径(仅iOS支持 android均在path中返回)
        videoPath:'',                 //字符串类型;返回视频的路径(仅iOS支持,android均在path中返回)注意:在 iOS 平台上需要先调用 transPath 接口将路径转换之后才能读取目标资源媒体文件
          path: '',                    //字符串类型;资源路径,返回资源在本地的绝对路径。注意:在 iOS 平台上需要先调用 transVideoPath 接口将路径转换之后才能读取目标资源媒体文件
        thumbPath: '',                //字符串类型;缩略图路径,返回资源缩略图在本地的绝对路径 
        size: 1048576,                //数字类型;资源大小,单位(Bytes)
        time: '1490580032000',        //字符串类型;资源修改时间,格式:时间戳,单位为毫秒。
        mediaType:'',                 //字符串类型;所在相册的类型,   Image ,Video ,Audio。
        duration:'',                  //字符串类型;视频时长,单位为毫秒
         isVideo:,               //布尔类型;是否为视频(仅android支持)
        isGif:,                 //布尔类型;是否为gif(仅android支持)
    }]
}

示例代码

var WXPhotoPicker = api.require('WXPhotoPicker');
WXPhotoPicker.scan({
    type: 'all',
    count: 10,
    sort: {
        key: 'time',
        order: 'desc'
    }
}, function(ret) {
    if (ret) {
        api.alert({msg:JSON.stringify(ret)});
    }
});

可用性

iOS 系统,Android 系统

可提供的 1.0.0 及更高版本

fetch

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

fetch(callback(ret))

callback(ret)

ret:

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

示例代码

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

可用性

iOS 系统

可提供的 1.0.0 及更高版本

scanGroups

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

scanGroups({params}, callback(ret))

params

type:

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

callback(ret)

ret:

  • 类型:JSON 对象
  • 内部字段:
{
    total: 10,                      //数字类型;媒体资源分组总数
    list: [{                        //数组类型;返回指定的资源信息数组
        firstMediaPath:'',          //字符串类型;第一个文件路径(仅android支持)
        groupName: '',              //字符串类型;分组名称
         groupId: '',                 //字符串类型;分组名称
         imgCount:23                       //数字类型;分组中图片数量
    }]
}

示例代码

var WXPhotoPicker = api.require('WXPhotoPicker');
WXPhotoPicker.scanGroups({
    type: 'all'
}, function(ret) {
    if (ret) {
        api.alert({msg:JSON.stringify(ret)});
    }
});

可用性

iOS 系统,Android 系统

可提供的 1.0.0 及更高版本

scanByGroupId

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

scanByGroupId({params}, callback(ret))

params

groupId:

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

type:

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

count:

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

page:

  • 类型:数字类型
  • 描述:(可选项)第几页(仅android支持)
  • 默认:0

pageSize

  • 类型:数字类型
  • 描述:(可选项)每页个数(仅android支持)
  • 默认:100

sort:

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

callback(ret)

ret:

  • 类型:JSON 对象
  • 内部字段:
{
    total: 100,                       //数字类型;媒体资源总数
    list: [{                           //数组类型;返回指定的资源信息数组
         gifImagePath:'',              //字符串类型;gif图路径,返回gif图在本地的绝对路径,可直接使用 注意:当gifImagePath存在,则不返回path、thumbPath和videoPath路径
        videoPath:'',                 //字符串类型;返回视频的路径,iOS端需transVideoPath转换
          path: '',                    //字符串类型;资源路径,返回资源在本地的绝对路径。注意:在 iOS 平台上需要先调用 transPath 接口将路径转换之后才能读取目标资源媒体文件
        thumbPath: '',                //字符串类型;缩略图路径,返回资源缩略图在本地的绝对路径(仅iOS支持)
        size: 1048576,                //数字类型;资源大小,单位(Bytes)
        time: '1490580032000',        //字符串类型;资源修改时间,格式:时间戳,单位为毫秒。
        duration:''                  //字符串类型;视频时长,单位为毫秒
    }]
}

示例代码

var WXPhotoPicker = api.require('WXPhotoPicker');
WXPhotoPicker.scanByGroupId({
    groupId : 123456,
    type: 'image',
    count: 10,
    sort: {
        key: 'time',
        order: 'desc'
    }
}, function(ret) {
    if (ret) {
        api.alert({msg:JSON.stringify(ret)});
    }
});

可用性

iOS 系统,Android 系统

可提供的 1.0.0 及更高版本

fetchGroup

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

fetchGroup(callback(ret))

callback(ret)

ret:

  • 类型:JSON 对象
  • 内部字段:
{
    list: [{                         //数组类型;返回指定的资源信息数组
         gifImagePath:'',            //字符串类型;gif图路径,返回gif图在本地的绝对路径,可直接使用 注意:当gifImagePath存在,则不返回path、thumbPath和videoPath路径
        videoPath:'',                 //字符串类型;返回视频的路径,iOS端需transVideoPath转换
          path: '',                   //字符串类型;资源路径,返回资源在本地的绝对路径。注意:在 iOS 平台上需要先调用 transPath 接口将路径转换之后才能读取目标资源媒体文件
        thumbPath: '',               //字符串类型;缩略图路径,返回资源缩略图在本地的绝对路径 
        size: 1048576,               //数字类型;资源大小,单位(Bytes)
        time: '1490580032000',       //字符串类型;资源修改时间,格式:时间戳,单位为毫秒。
        duration:''                  //字符串类型;视频时长,单位为毫秒
    }]
}

示例代码

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

可用性

iOS系统

可提供的 1.0.0 及更高版本

transPath

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

transPath({params}, callback(ret))

params

path:

  • 类型:字符串
  • 描述:要转换的图片路径(在iOS端为在相册库的ID)

scale:

  • 类型:数字
  • 描述:图片质量
  • 默认:1.0
  • 取值范围:0~1.0

callback(ret)

ret:

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

err:

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

示例代码

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

可用性

iOS 系统

可提供的 1.0.0 及更高版本

transVideoPath

视频路径转化,iOS端直接获取的路径需经本接口转换后才能使用(播放、上传等)(仅iOS支持)

transVideoPath({params}, callback(ret))

params

path:

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

callback(ret)

ret:

  • 类型:JSON 对象
  • 内部字段:
{
   status: true,     //布尔类型
   fileSize: 3819599 //视频文件大小;byte为单位
   duration: 4       //视频时长;单位为秒
   path:''           //字符串类型;视频路径;可用此路径进行播放、上传等操作; 
}

err:

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

示例代码

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

可用性

iOS 系统

可提供的 1.0.0 及更高版本

openGroup

openGroup({params}, callback(ret))

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

params

rect:

  • 类型:JSON 对象
  • 描述:(可选项)模块的位置及尺寸
  • 内部字段:
{
    x: 0,   //(可选项)数字类型;模块左上角的 x 坐标(相对于所属的 Window 或 Frame);默认:0
    y: 0,   //(可选项)数字类型;模块左上角的 y 坐标(相对于所属的 Window 或 Frame);默认:0
    w: 320, //(可选项)数字类型;模块的宽度;默认:屏幕宽度
    h: 200  //(可选项)数字类型;模块的高度;默认:w (android为屏幕高度)
}

groupId:

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

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

fixedOn:

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

fixed:

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

callback(ret)

ret:

  • 类型:JSON 对象
  • 内部字段:
{
  eventType: 'camera',              //字符串类型;交互事件类型,取值范围如下:
                                     //camera:点击拍照按钮(仅iOS支持)
                                     //select:选中图片事件
                                     //cancel:取消选中图片事件
                                     //show:打开预览区域成功事件
                                     //change:改变显示分组成功事件
   groupId: '',                      //字符串类型;当前分组 ID                                  
   target:{                          //JSON对象;返回所操作的资源信息
        gifImagePath:'',             //字符串类型;gif图路径,返回gif图在本地的绝对路径,可直接使用 
        path: '',                    //字符串类型;资源路径,返回资源在本地的绝对路径,注意:iOS 平台上需要用 transPath 接口转换之后才可读取原图
        thumbPath: '',               //字符串类型;缩略图路径,返回资源缩略图在本地的绝对路径(仅iOS支持)
    }
}

示例代码

var WXPhotoPicker = api.require('WXPhotoPicker');
WXPhotoPicker.openGroup({
    groupId:''
}, function(ret) {
    api.alert({msg:JSON.stringify(ret)});
});

可用性

iOS 系统,Android 系统

可提供的 1.0.0 及更高版本

changeGroup

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

changeGroup({params})

params

groupId:

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

示例代码

var WXPhotoPicker = api.require('WXPhotoPicker');
WXPhotoPicker.changeGroup({
    groupId:''
});

可用性

iOS 系统,Android 系统

可提供的 1.0.0 及更高版本

closeGroup

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

closeGroup()

示例代码

var WXPhotoPicker = api.require('WXPhotoPicker');
WXPhotoPicker.closeGroup();

可用性

iOS 系统,Android 系统

可提供的 1.0.0 及更高版本