API Reference

Plugins

Native.js


gallery

Gallery模块管理系统相册，支持从相册中选择图片或视频文件、保存图片或视频文件到相册等功能。通过plus.gallery获取相册管理对象。

方法：

对象：

回调方法：

模块：

5+功能模块（permissions）


{
// ...
"permissions":{
	// ...
	"Gallery": {
		"description": "系统相册"
	}
}
}

pick

从系统相册选择文件（图片或视频）


void plus.gallery.pick( successCB, errorCB, option );

说明：

从系统相册中选择图片或视频文件。每次仅能选择一个文件，选择后将返回选择的文件路径。

参数：

返回值：

void : 无

平台支持：

示例：


<!DOCTYPE html>
<html>
	<head>
	<meta charset="utf-8">
	<title>Gallery Example</title>
	<script type="text/javascript">
// 扩展API加载完毕后调用onPlusReady回调函数 
document.addEventListener( "plusready", onPlusReady, false );
// 扩展API加载完毕，现在可以正常调用扩展API 
function onPlusReady() {
}
// 从相册中选择图片 
function galleryImg() {
	// 从相册中选择图片
	console.log("从相册中选择图片:");
    plus.gallery.pick( function(path){
    	console.log(path);
    }, function ( e ) {
    	console.log( "取消选择图片" );
    }, {filter:"image"} );
}
// 从相册中选择多张图片 
function galleryImgs(){
	// 从相册中选择图片
	console.log("从相册中选择多张图片:");
    plus.gallery.pick( function(e){
    	for(var i in e.files){
	    	console.log(e.files[i]);
    	}
    }, function ( e ) {
    	console.log( "取消选择图片" );
    },{filter:"image",multiple:true});
}
	</script>
	</head>
	<body >
		从相册中选择图片
		<br/>
		<button onclick="galleryImg()">选择单张图片</button>
		<br/>
		<button onclick="galleryImgs()">选择多张图片</button>
	</body>
</html>

save

保存文件到系统相册中


void plus.gallery.save( path, successCB, errorCB );

说明：

保存文件到系统相册中。 每次仅能保存一个文件，支持图片类型（jpg/jpeg、png、bmp等格式）和视频文件（3gp、mov等格式）。 若保存的文件系统不支持，则通过errorCB返回错误信息。

参数：

返回值：

void : 无

平台支持：

示例：


<!DOCTYPE html>
<html>
	<head>
	<meta charset="utf-8">
	<title>Gallery Example</title>
	<script type="text/javascript" >
// 扩展API加载完毕后调用onPlusReady回调函数 
document.addEventListener( "plusready", onPlusReady, false );
var r = null; 
// 扩展API加载完毕，现在可以正常调用扩展API 
function onPlusReady() {
}
// 保存图片到相册中 
function savePicture() {
	plus.gallery.save( "_doc/a.jpg", function () {
		alert( "保存图片到相册成功" );
	} );
}
	</script>
	</head>
	<body >
	<input type="button" value="Save picture to Gallery" onclick="savePicture();" ></input>
	</body>
</html>

GalleryOptions

JSON对象，从相册中选择文件的参数

属性：

GalleryFilter

相册选择文件过滤类型

属性：

GallerySaveEvent

保存图片到相册成功事件

属性：

PopPosition

JSON对象，弹出拍照或摄像界面指示位置

属性：

GalleryPickSuccessCallback

单选系统相册图片成功的回调


void onSuccess( file ) {
	// Success code
}

说明：

系统相册中单选图片或视频文件成功的回调函数，在选择文件操作成功时调用。

参数：

返回值：

void : 无

示例：


<!DOCTYPE html>
<html>
	<head>
	<meta charset="utf-8">
	<title>Gallery Example</title>
	<script type="text/javascript" >
// 扩展API加载完毕后调用onPlusReady回调函数 
document.addEventListener( "plusready", onPlusReady, false );
var r = null; 
// 扩展API加载完毕，现在可以正常调用扩展API 
function onPlusReady() {
}
// 从相册中选择单张图片 
function galleryImg() {
	// 从相册中选择图片
	console.log("从相册中选择图片:");
    plus.gallery.pick( function(path){
    	console.log(path);
    }, function ( e ) {
    	console.log( "取消选择图片" );
    }, {filter:"image"} );
}
	</script>
	</head>
	<body >
		从相册中选择单张图片
		<br/>
		<button onclick="galleryImg()">选择图片</button>
	</body>
</html>

GalleryMultiplePickSuccessCallback

多选系统相册图片成功的回调


void onSuccess( event ) {
	// Pick success
	var files = event.files; // 保存多选的图片或视频文件路径
}

说明：

系统相册中多选图片或视频文件成功的回调函数，在多选择文件操作成功时调用。

参数：

返回值：

void : 无

示例：


<!DOCTYPE html>
<html>
	<head>
	<meta charset="utf-8">
	<title>Gallery Example</title>
	<script type="text/javascript" >
// 扩展API加载完毕后调用onPlusReady回调函数 
document.addEventListener( "plusready", onPlusReady, false );
var r = null; 
// 扩展API加载完毕，现在可以正常调用扩展API 
function onPlusReady() {
}
// 从相册中选择多张图片 
function galleryImgs(){
	// 从相册中选择图片
	console.log("从相册中选择多张图片:");
    plus.gallery.pick( function(e){
    	for(var i in e.files){
	    	console.log(e.files[i]);
    	}
    }, function ( e ) {
    	console.log( "取消选择图片" );
    },{filter:"image",multiple:true});
}
	</script>
	</head>
	<body >
		从相册中选择多张图片
		<br/>
		<button onclick="galleryImgs()">选择图片</button>
	</body>
</html>

GallerySaveSuccessCallback

参数：

无

返回值：

:

GallerySuccessCallback

操作系统相册成功的回调


void onSuccess(GallerySaveEvent event) {
	// Success code
}

说明：

系统相册操作成功的回调函数，在保存文件到系统相册操作成功时调用。

参数：

返回值：

void : 无

GalleryErrorCallback

系统相册操作失败的回调


void onError( error ) {
	// Handle error
	var code = error.code; // 错误编码
	var message = error.message; // 错误描述信息
}

说明：

系统相册操作失败的回调函数，在选择或保存图片操作失败时调用。

参数：

返回值：

void : 无