WXPhotoPicker

立即使用

requestAlbumPermissions open scan fetch scanGroups scanByGroupId fetchGroup transPath transVideoPath openGroup closeGroup changeGroup getVideoDuration

概述

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

isCache：

类型：布尔类型
描述：（可选项）是否本地缓存图片，若为false，返回的资源路径均为相册ID，不存在本地沙盒路径中，thumbPath不返回，仅支持iOS
默认值：true

type：

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

callback(ret)

ret：

类型：JSON 对象
内部字段：

{
    eventType: cancel,               //字符串类型；按钮点击事件，取值范围
                                     //confirm 用户点击确定按钮事件
                                     //cancel 用户点击取消按钮事件
    list: [{                         //数组类型；返回选定的资源信息数组
        gifImagePath:'',             //字符串类型；gif图路径，返回gif图在本地的绝对路径，可直接使用 注意:当gifImagePath存在，则不返回path、thumbPath以及videoPath路径
        videoPath:'',                 //字符串类型；返回视频在本地的绝对路径 
        path: '',                    //字符串类型；返回图片在本地的绝对路径 
        thumbPath: '',               //字符串类型；缩略图路径，返回资源缩略图在本地的绝对路径，Android系统目前只有选择视频文件支持该项
        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（新->旧）
}

isCache：

类型：布尔类型
描述：（可选项）是否本地缓存图片，若为false，thumbPath字段将不返回，仅支持iOS
默认值：true

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: '',                //字符串类型；缩略图路径，返回资源缩略图在本地的绝对路径。注意：Android系统不支持
        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: '',                //字符串类型；缩略图路径，返回资源缩略图在本地的绝对路径。注意：Android系统不支持
        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（新->旧）
}

isCache：

类型：布尔类型
描述：（可选项）是否本地缓存图片，若为false，thumbPath字段将不返回，仅支持iOS
默认值：true

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: '',               //字符串类型；缩略图路径，返回资源缩略图在本地的绝对路径(仅iOS支持) 
        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

isCache：

类型：布尔类型
描述：（可选项）是否本地缓存图片，若为false，thumbPath字段将不返回，仅支持iOS
默认值：true

fixedOn：

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

fixed:

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

callback(ret)

ret：

类型：JSON 对象
内部字段：

{
  eventType: 'camera',              //字符串类型；交互事件类型，取值范围如下：
                                     //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 及更高版本

getVideoDuration

获取视频长度

getVideoDuration({params}, callback(ret))

params

path：

类型：字符串
描述：视频本地路径（支持 fs:// widget://路径）
注意：Android不支持widget://路径

callback(ret)

ret：

类型：JSON 对象
内部字段：

{
   duration: 60    //数字类型；视频时长,单位为秒
}

示例代码

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

可用性

iOS 系统，Android 系统

可提供的 1.0.0 及更高版本

APICloud

模块开发

端API

设备访问

功能扩展

界面布局

导航菜单

开放SDK

云服务对接

AVM多端模块

H5模块

前端框架

云API

技术专题

开发工具

下载

微信公众号适配

七天培训课教程

其他

Faq

开放平台接入指南

自定义加速域名

云主机

入门教程

部署与管理

常见FAQ

WXPhotoPicker

概述

模块接口

requestAlbumPermissions

callback(ret)

示例代码

可用性

open

params

callback(ret)

示例代码

可用性

scan

params

callback(ret)

示例代码

可用性

fetch

callback(ret)

示例代码

可用性

scanGroups

params

callback(ret)

示例代码

可用性

scanByGroupId

params

callback(ret)

示例代码

可用性

fetchGroup

callback(ret)

示例代码

可用性

transPath

params

callback(ret)

示例代码

可用性

transVideoPath

params

callback(ret)

示例代码

可用性

openGroup

params

callback(ret)

示例代码

可用性

changeGroup

params

示例代码

可用性