nativeObj

nativeObj管理系统原生对象。

对象：

Bitmap: 原生图片对象
BitmapSaveOptions: JSON对象，保存图片的参数

回调方法：

BitmapSaveSuccessCallback: 图片保存操作成功回调接口
NativeObjSuccessCallback: 操作成功回调函数接口
NativeObjErrorCallback: 操作错误回调函数接口

权限：

permissions


"NativeObj": {
	"description": "系统原生对象"
}

Bitmap

原生图片对象

说明：

原生图片对象会占用较大的内存资源，在使用时需谨慎管理，当图片不再使用时应该及时调用clear方法进行销毁。

构造：

Bitmap(id): 创建Bitmap对象

属性：

id: Bitmap对象的标识

方法：

getItems: 静态方法，获取所有Bitmap图片对象
getBitmapById: 静态方法，获取指定标识的Bitmap图片对象
clear: 销毁Bitmap图片
load: 加载Bitmap图片
loadBase64Data: 加载Base64编码格式图片到Bitmap对象
save: 保存图片
toBase64Data: 获取图片的Base64编码数据

Bitmap(id)

创建Bitmap对象


var bitmap = new plus.nativeObj.Bitmap( id );

说明：

创建后为空Bitmap对象，需要调用Webview对象的draw方法更新，或者调用load/loadBase64Data方法加载图片。

参数：

id: ( String ) 可选 Bitmap图片对象的id
给图片对象指定id后，可以通过plus.nativeObj.Bitmap.getBitmapById()获取。如果不设置id则创建匿名图片对象，仅可通过plus.nativeObj.Bitmap.getItems()获取。可创建多个相同id的图片，此时plus.nativeObj.Bitmap.getBitmapById()获取第一个创建的id图片对象。

返回值：

Bitmap : Bitmap图片对象

示例：


<!DOCTYPE HTML>
<html>
	<head>
		<meta charset="utf-8"/>
		<meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0, user-scalable=no"/>
		<title>NativeObj Example</title>
		<script type="text/javascript">
var wc=null,bitmap=null;
// H5 plus事件处理
function plusReady(){
	wc = plus.webview.currentWebview();
	bitmap = new plus.nativeObj.Bitmap("test");
	// 将webview内容绘制到Bitmap对象中
	wc.draw(bitmap,function(){
		console.log('绘制图片成功');
	},function(e){
		console.log('绘制图片失败：'+JSON.stringify(e));
	});
}
if(window.plus){
	plusReady();
}else{
	document.addEventListener("plusready",plusReady,false);
}
		</script>
	</head>
	<body>
		创建Bitmap对象<br/>
	</body>
</html>

id

Bitmap对象的标识

说明：

String 类型只读属性

在创建Bitmap对象时设置，如果没有设置标识，此属性值为null。

示例：


<!DOCTYPE HTML>
<html>
	<head>
		<meta charset="utf-8"/>
		<meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0, user-scalable=no"/>
		<title>NativeObj Example</title>
		<script type="text/javascript">
// H5 plus事件处理
function plusReady(){
	var bitmap = new plus.nativeObj.Bitmap("test");
	// ...
	console.log( bitmap.id ); // 输出"test"
}
if(window.plus){
	plusReady();
}else{
	document.addEventListener("plusready",plusReady,false);
}
		</script>
	</head>
	<body>
		Bitmap对象的标识<br/>
	</body>
</html>

getItems

静态方法，获取所有Bitmap图片对象


						
Array[Bitmap] plus.nativeObj.Bitmap.getItems();

说明：

获取应用运行期创建的所有Bitmap图片对象，包含所有空Bitmap对象，不包含已经销毁的Bitmap对象。返回的Bitmap对象在数组中按创建的属性排列，及数组中第一个是最先创建的Bitmap对象。

参数：

无

返回值：

Array[ Bitmap ] : 应用中创建的所有Bitmap图片对象数组。

示例：


<!DOCTYPE HTML>
<html>
	<head>
		<meta charset="utf-8"/>
		<meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0, user-scalable=no"/>
		<title>NativeObj Example</title>
		<script type="text/javascript">
// H5 plus事件处理
function plusReady(){
	// 获取所有Bitmap对象
	var bitmaps=plus.nativeObj.Bitmap.getItems();
	for(var i=0;i<bitmaps.length;i++){
		console.log("Bitmap"+i+": "+bitmaps[i].id);
	}
}
if(window.plus){
	plusReady();
}else{
	document.addEventListener("plusready",plusReady,false);
}
		</script>
	</head>
	<body>
		获取所有Bitmap图片对象<br/>
	</body>
</html>

getBitmapById

静态方法，获取指定标识的Bitmap图片对象


						
Bitmap plus.nativeObj.Bitmap.getBitmapById( id );

说明：

在应用中已创建的图片对象中查找指定标识的Bitmap对象并返回。若存在多个相同标识的Bitmap图片，则返回第一个创建的Bitmap图片。

参数：

id: ( String ) 必选 要查找的Bitmap图片标识

返回值：

Bitmap : Bitmap图片对象，若没有查找到指定标识的图片对象则返回null。

示例：


<!DOCTYPE HTML>
<html>
	<head>
		<meta charset="utf-8"/>
		<meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0, user-scalable=no"/>
		<title>NativeObj Example</title>
		<script type="text/javascript">
// H5 plus事件处理
function plusReady(){
	wc = plus.webview.currentWebview();
	bitmap = new plus.nativeObj.Bitmap("test");
	// 将webview内容绘制到Bitmap对象中
	wc.draw(bitmap,function(){
		console.log('绘制图片成功');
	},function(e){
		console.log('绘制图片失败：'+JSON.stringify(e));
	});
}
if(window.plus){
	plusReady();
}else{
	document.addEventListener("plusready",plusReady,false);
}
// 查找Bitmap对象
function findBitmap(){
	var bitmap = plus.nativeObj.Bitmap.getBitmapById("test");
	if(bitmap){
		console.log("Success: "+bitmap.id);
	}else{
		console.log("Can't find bitmap");
	}
}
		</script>
	</head>
	<body>
		获取指定标识的Bitmap图片对象<br/>
		<button onclick="findBitmap()">Find</button>
	</body>
</html>

clear

销毁Bitmap图片


						
void bitmap.clear();

说明：

释放Bitmap图片占用的内存资源，销毁后图片对象将不可使用，其id属性值为undefined，调用其所有方法操作都会失败。

参数：

无

返回值：

void : 无

示例：


<!DOCTYPE HTML>
<html>
	<head>
		<meta charset="utf-8"/>
		<meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0, user-scalable=no"/>
		<title>NativeObj Example</title>
		<script type="text/javascript">
var wc=null,bitmap=null;
// H5 plus事件处理
function plusReady(){
	wc = plus.webview.currentWebview();
	bitmap = new plus.nativeObj.Bitmap("test");
	// 将webview内容绘制到Bitmap对象中
	wc.draw(bitmap,function(){
		console.log('绘制图片成功');
	},function(e){
		console.log('绘制图片失败：'+JSON.stringify(e));
	});
}
if(window.plus){
	plusReady();
}else{
	document.addEventListener("plusready",plusReady,false);
}
// 销毁Bitmap图片
function clearBitmap(){
	bitmap.clear();
}
		</script>
	</head>
	<body>
		销毁Bitmap图片<br/>
		<button onclick="clearBitmap()">Clear</button>
	</body>
</html>

load

加载Bitmap图片


						
void bitmap.load( path, successCallback, errorCallback );

说明：

从指定的路径（仅支持本地文件系统）中加载图片，此操作将覆盖之前的图片内容，如果加载图片失败则保留之前的图片内容。

参数：

path: ( String ) 必选 要加载的图片路径
支持以下图片路径：相对路径 - 相对于当前页面的host位置，如"a.jpg"，注意当前页面为网络地址则不支持；绝对路径 - 系统绝对路径，如Android平台"/storage/sdcard0/Android/data/io.dcloud.HBuilder/.HBuilder/apps/HBuilder/www/ａ.jpg"，iOS平台"/var/mobile/Containers/Data/Application/757966CF-345C-4348-B07F-EEF83CF9A369/Library/Pandora/apps/HBuilder/www/a.png"；相对路径URL(RelativeURL) - 以"_"开头的相对路径，如"_www/a.jpg"、"_doc/b.jpg"、"_documents/c.jpg"、"_downloads/d.jpg"；本地路径URL - 以“file://”开头，后面跟随系统绝对路径。
successCallback: ( NativeObjSuccessCallback ) 必选 加载图片操作成功回调
加载图片操作成功时调用。
errorCallback: ( NativeObjErrorCallback ) 必选 加载图片操作失败回调
加载图片操作失败时调用，并返回失败信息。

返回值：

void : 无

示例：


<!DOCTYPE HTML>
<html>
	<head>
		<meta charset="utf-8"/>
		<meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0, user-scalable=no"/>
		<title>NativeObj Example</title>
		<script type="text/javascript">
// H5 plus事件处理
function plusReady(){
	var bitmap = new plus.nativeObj.Bitmap("test");
	// 从本地加载Bitmap图片
	bitmap.load('icon.png',function(){
		console.log('加载图片成功');
	},function(e){
		console.log('加载图片失败：'+JSON.stringify(e));
	});
}
if(window.plus){
	plusReady();
}else{
	document.addEventListener("plusready",plusReady,false);
}
		</script>
	</head>
	<body>
		加载Bitmap图片<br/>
	</body>
</html>

loadBase64Data

加载Base64编码格式图片到Bitmap对象


						
void bitmap.loadBase64Data( data, successCallback, errorCallback );

说明：

从Base64编码格式图片数据中加载图片，此操作将覆盖之前的图片内容，如果加载图片失败则保留之前的图片内容。

参数：

data: ( String ) 必选 要加载图片的Base64编码格式数据
如果数据格式不正确或者不是有效的图片数据则返回失败。
successCallback: ( NativeObjSuccessCallback ) 必选 加载图片操作成功回调
加载图片操作成功时调用。
errorCallback: ( NativeObjErrorCallback ) 必选 加载图片操作失败回调
加载图片操作失败时调用，并返回失败信息。

返回值：

void : 无

示例：


<!DOCTYPE HTML>
<html>
	<head>
		<meta charset="utf-8"/>
		<meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0, user-scalable=no"/>
		<title>NativeObj Example</title>
		<script type="text/javascript">
var bitmap=null;
// H5 plus事件处理
function plusReady(){
	bitmap = new plus.nativeObj.Bitmap("test");
}
if(window.plus){
	plusReady();
}else{
	document.addEventListener("plusready",plusReady,false);
}
		</script>
	</head>
	<body>
		加载Base64编码格式图片到Bitmap对象<br/>
		<button onclick="loadDataImage()">LoadBase64Data</button><br/>
		<canvas id="cimg"></canvas><br/>
	</body>
	<script type="text/javascript">
// 获取图片的base64格式数据
var data = null;
var img = new Image();
img.onload = function(){
	var cx = cimg.getContext('2d');
	cimg.width = img.width;
	cimg.height = img.height;
	cx.drawImage( img, 0, 0 );
	data = cimg.toDataURL();
}
img.src = 'logo.png';
// 加载Base64编码格式图片到Bitmap对象
function loadDataImage(){
	bitmap.loadBase64Data( data, function(){
		console.log("加载Base64图片数据成功");
	}, function(){
		console.log('加载Base64图片数据失败：'+JSON.stringify(e));
	} );
}
	</script>
</html>

save

保存图片


						
void bitmap.save( path, options, successCallback, errorCallback );

说明：

将图片保存到指定的路径（仅支持本地文件系统），如果图片为空或者指定的路径文件已经存在则返回失败。

参数：

path: ( String ) 必选 要保存的图片路径
支持以下图片路径：绝对路径 - 系统绝对路径，如Android平台"/storage/sdcard0/Android/data/io.dcloud.HBuilder/.HBuilder/apps/HBuilder/doc/ａ.jpg"，iOS平台"/var/mobile/Containers/Data/Application/757966CF-345C-4348-B07F-EEF83CF9A369/Library/Pandora/apps/HBuilder/doc/a.png"；相对路径URL(RelativeURL) - 以"_"开头的相对路径，如"_doc/b.jpg"、"_documents/c.jpg"、"_downloads/d.jpg"；本地路径URL - 以“file://”开头，后面跟随系统绝对路径。如果指定的路径无效，或者不可访问则返回失败。
options: ( BitmapSaveOptions ) 必选 保存图片的属性
可设置保存图片的格式，压缩质量等参数。
successCallback: ( BitmapSaveSuccessCallback ) 必选 保存图片操作成功回调
加载图片操作成功时调用。
errorCallback: ( NativeObjErrorCallback ) 必选 保存图片操作失败回调
加载图片操作失败时调用，并返回失败信息。

返回值：

void : 无

示例：


<!DOCTYPE HTML>
<html>
	<head>
		<meta charset="utf-8"/>
		<meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0, user-scalable=no"/>
		<title>NativeObj Example</title>
		<script type="text/javascript">
var wc=null,bitmap=null;
// H5 plus事件处理
function plusReady(){
	wc = plus.webview.currentWebview();
	bitmap = new plus.nativeObj.Bitmap("test");
	// 将webview内容绘制到Bitmap对象中
	wc.draw(bitmap,function(){
		console.log('绘制图片成功');
	},function(e){
		console.log('绘制图片失败：'+JSON.stringify(e));
	});
}
if(window.plus){
	plusReady();
}else{
	document.addEventListener("plusready",plusReady,false);
}
// 保存图片
function saveBitmap(){
	bitmap.save( "_doc/a.jpg"
	,{}
	,function(i){
		console.log('保存图片成功：'+JSON.stringify(i));
	}
	,function(e){
		console.log('保存图片失败：'+JSON.stringify(e));
	});
}
		</script>
	</head>
	<body>
		保存图片<br/>
		<button onclick="saveBitmap()">Save</button>
	</body>
</html>

toBase64Data

获取图片的Base64编码数据


						
String bitmap.toBase64Data();

说明：

读取图片的数据内容，并转换为Base64编码格式字符串。

参数：

无

返回值：

String : 图片的Base64编码数据，如果图片为空则返回null。

示例：


<!DOCTYPE HTML>
<html>
	<head>
		<meta charset="utf-8"/>
		<meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0, user-scalable=no"/>
		<title>NativeObj Example</title>
		<script type="text/javascript">
var bitmap = null,wi=null;
// H5 plus事件处理
function plusReady(){
	// 获取首页Webview窗口
	wi = plus.webview.getLaunchWebview();
	// 创建Bitmap对象
	bitmap = new plus.nativeObj.Bitmap("test");
	// 将首页Webview窗口截图保存到Bitmap中
	wi.draw( bitmap, function(){
		console.log("截图成功");
	}, function(e){
		console.log("截图失败："+JSON.stringify(e));
	} );
}
if(window.plus){
	plusReady();
}else{
	document.addEventListener("plusready",plusReady,false);
}
// 获取图片的Base64编码数据
function base64Image(){
	var img=document.getElementById("img");
	img.src = bitmap.toBase64Data();
}
		</script>
	</head>
	<body>
		获取图片的Base64编码数据<br/>
		<button onclick="base64Image()">Base64Data</button><br/>
		<img id="img"></img>
	</body>
</html>

BitmapSaveOptions

JSON对象，保存图片的参数

属性：

overwrite: (Boolean 类型 )覆盖保存图片文件
仅在保存的图片路径文件存在时有效： true表示覆盖存在的文件； false表示不覆盖，如果文件存在，则返回失败。默认值为false。
format: (String 类型 )保存图片的格式
支持"jpg"、"png"，如果未指定则默认使用指定的保存路径后缀对应的文件格式，如果后缀文件格式无效则使用jpg格式。
quality: (Number 类型 )保存图片的质量
取值范围为1-100，1表示使用最低的图片质量（保存后的图片文件最小）、100表示使用最高的图片质量（保存后的图片文件最大）；默认值为50。

BitmapSaveSuccessCallback

图片保存操作成功回调接口


void onSuccess( Event event ){
	// Code here
	var target = event.target; // 保存后的图片url路径，以"file://"开头
	var size = event.size; // 保存后图片的大小，单位为字节（Byte）
	var width = event.width; // 保存后图片的实际宽度，单位为px
	var height = event.height; // 保存后图片的实际高度，单位为px
}

参数：

event: ( Event ) 可选 保存后的图片信息
可通过event.target（String类型）获取保存后的图片url路径，以"file://"开头，可直接在html页面中通过src属性引用，如Android平台"file:///storage/sdcard0/Android/data/io.dcloud.HBuilder/.HBuilder/apps/HBuilder/doc/ａ.jpg"，iOS平台"file:///var/mobile/Containers/Data/Application/757966CF-345C-4348-B07F-EEF83CF9A369/Library/Pandora/apps/HBuilder/doc/a.png"；可通过event.size（Number类型）获取保存后图片的大小，单位为字节（Byte）；可通过event.width（Number类型）获取保存后的图片的实际宽度，单位为px；可通过event.height（Number类型）获取保存后的图片的实际高度，单位为px。

返回值：

void : 无

NativeObjSuccessCallback

操作成功回调函数接口


void onSuccess(){
	// Code here
}

参数：

无

返回值：

void : 无

NativeObjErrorCallback

操作错误回调函数接口


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

参数：

error: ( Exception ) 必选 用户选择操作失败信息
可通过error.code（Number类型）获取错误编码；可通过error.message（String类型）获取错误描述信息。

返回值：

void : 无