WXPhotoPicker
概述
WXPhotoPicker 是一个本地媒体资源扫描器，在 Android 平台上扫描图片库资源，
注意本原生插件在iPhone设备上仅支持 iOS11.0 及以上版本。。
iOS 仅扫描相册内的资源。
本原生插件封装了几种方案。
方案一：
通过 open 接口打开一个自带 UI 界面的媒体资源浏览页面（高仿微信）
方案二：
通过 scan 接口扫描指定数量的媒体资源文件，本接口是纯功能类接口，不带界面。开发者可根据此接口扫描到的文件自行开发展示页面，极大的提高了自定义性。注意展示页面要做成赖加载模式，以免占用内存过高导致 app 假死。懒加载模式可通过 fetch 接口实现持续向下加载更多功能。注意：在 iOS 平台上需要先调用 transPath 接口将路径转换之后才能读取目标资源媒体文件。
方案三：
通过 scanGroups 接口扫描相册所有分组，本接口是纯功能类接口，不带界面。开发者可根据此接口扫描到的文件自行开发展示页面，极大的提高了自定义性。注意展示页面要做成赖加载模式，以免占用内存过高导致 app 假死。懒加载模式可通过 scanByGroupId 和 fetchGroup 接口实现持续向下加载更多功能。注意：在 iOS 平台上需要先调用 transPath 接口将路径转换之后才能读取目标资源媒体文件。
方案四：
通过 openGroup 接口以 frame（view）形式打开指定分组的选择器，本接口带界面。开发者可根据需求通过相关参数自定义展示页面，极大的提高了自定义性。通过 changeGroup 接口改变选择器展示的分组，closeGroup 可关闭选择器的 frame。注意：在 iOS 平台上需要先调用 transPath 接口将路径转换之后才能读取目标资源媒体文件。
注意：使用本原生插件前需在云编译页面添加勾选访问相册权限，否则会有崩溃闪退现象
iOS只支持中文,英文,繁体中文三种语言
iOS端选取的相册图片会被拷贝到临时文件夹，调用 api.clearCache 接口可清除该临时图片文件
原生插件接口
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（视频）
isShowOriginal：
- 类型：布尔类型
- 描述：（可选项）是否显示原图按钮，若为false，不显示原图按钮并且返回的图片默认为原图路径
- 默认值：true
canEdit：
- 类型：布尔类型
- 描述：（可选项）照片、视频是否可以编辑，若为true，则显示编辑按钮，此参数仅支持iOS
- 默认值：false
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 及更高版本
setLanguage
设置多媒体资源选择器文字语言
setLanguage({params})
params
language：
- 类型：字符串类型
- 描述：（可选项）定制播放器文字语言
- 取值范围：
- zh：简体中文
- zh-Hant：繁体中文
- en：英文
- 默认：'zh'
##示例代码
var WXPhotoPicker = api.require('WXPhotoPicker');
WXPhotoPicker.setLanguage({
language: 'en'
});
可用性
iOS系统，Android系统
可提供的1.1.4及更高版本