Html5+ 技术规范
(下)
2016-03-01
修订历史:
类型 |
日期 |
作者 |
里程碑版本号 |
章节 |
备注 |
创建 |
2016-03-01 |
1.0.0.BUILD.01 |
全部 |
目 录
NativeUI......................................................................................................................... 23
Navigator....................................................................................................................... 61
OAuth............................................................................................................................ 90
Orientation................................................................................................................... 114
Payment........................................................................................................................ 122
Push.............................................................................................................................. 150
Runtime........................................................................................................................ 163
Share............................................................................................................................ 189
Speech.......................................................................................................................... 210
Statistic......................................................................................................................... 219
Storage.......................................................................................................................... 225
Uploader....................................................................................................................... 233
Webview....................................................................................................................... 265
XMLHttpRequest............................................................................................................ 379
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/a.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/a.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/a.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 : 无
NativeUI
nativeUI管理系统原生界面,可用于弹出系统原生提示对话框窗口、时间日期选择对话框、等待对话框等。
方法:
actionSheet: 弹出系统选择按钮框
alert: 弹出系统提示对话框
confirm: 弹出系统确认对话框
closeWaiting: 关闭系统等待对话框
showWaiting: 显示系统等待对话框
pickDate: 弹出系统日期选择对话框
pickTime: 弹出系统时间选择对话框
prompt: 弹出系统输入对话框
toast: 显示自动消失的提示消息
对象:
ActionButtonStyle: JSON对象,原生选择按钮框上按钮的样式参数
ActionSheetStyle: JSON对象,原生选择按钮框的样式参数
PickDateOption: JSON对象,日期选择对话框的参数
PickTimeOption: JSON对象,时间选择对话框的参数
Waiting: 系统等待对话框对象
WaitingOptions: JSON对象,原生等待对话框的参数
WaitingLoadingOptions: JSON对象,原生等待对话框上loading图标自定义样式
ToastOption: JSON对象,系统提示消息框要设置的参数
回调方法:
ActionSheetCallback: 系统选择按钮框的回调函数
AlertCallback: 系统提示框确认的回调函数
ConfirmCallback: 关闭确认对话框的回调函数
PromptCallback: 系统输入对话框关闭后的回调函数
PickDatetimeSuccessCallback: 选择日期或时间操作成功的回调函数
PickDatetimeErrorCallback: 选择日期或时间操作取消或失败的回调函数
权限:
permissions
"NativeUI": {
"description": "原生UI控件"}
actionSheet
弹出系统选择按钮框
void plus.nativeUI.actionSheet( actionsheetStyle, actionsheetCallback );
说明:
从底部动画弹出系统样式选择按钮框,可设置选择框的标题、按钮文字等。 弹出的提示框为非阻塞模式,用户点击选择框上的按钮后关闭,并通过actionsheetCallback回调函数通知用户选择的按钮。
参数:
actionsheetStyle: ( ActionSheetStyle ) 必选 选择按钮框显示的样式
actionsheetCallback: ( ActionSheetCallback ) 可选 选择按钮框关闭后的回调函数
返回值:
void : 无
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>nativeUI Example</title>
<script type="text/javascript">// H5 plus事件处理function plusReady(){
// 弹出系统选择按钮框
plus.nativeUI.actionSheet( {title:"Plus is ready!",cancel:"取消",buttons:[{title:"1"},{title:"2"}]}, function(e){
console.log( "User pressed: "+e.index );
} );}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}
</script>
</head>
<body>
弹出系统选择按钮框
</body></html>
alert
弹出系统提示对话框
void plus.nativeUI.alert( message, alertCB, title, buttonCapture );
说明:
创建并显示系统样式提示对话框,可设置提示对话框的标题、内容、按钮文字等。 弹出的提示对话框为非阻塞模式,用户点击提示对话框上的按钮后关闭,并通过alertCB回调函数通知对话框已关闭。
参数:
message: ( String ) 必选 提示对话框上显示的内容
alertCB: ( AlertCallback ) 可选 提示对话框上关闭后的回调函数
title: ( String ) 可选 提示对话框上显示的标题
buttonCapture: ( String ) 必选 提示对话框上按钮显示的内容
返回值:
void : 无
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>nativeUI Example</title>
<script type="text/javascript">// H5 plus事件处理function plusReady(){
// 弹出系统提示对话框
plus.nativeUI.alert( "Plus is ready!", function(){
console.log( "User pressed!" );
}, "nativeUI", "OK" );}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}
</script>
</head>
<body>
弹出系统提示对话框
</body></html>
confirm
弹出系统确认对话框
void plus.nativeUI.confirm( message, confirmCB, title, buttons );
说明:
创建并显示系统样式确认对话框,可设置确认对话框的标题、内容、按钮数目及其文字。 弹出的确认对话框为非阻塞模式,用户点击确认对话框上的按钮后关闭,并通过confirmCB回调函数通知用户点击的按钮索引值。
参数:
message: ( String ) 必选 确认对话框上显示的内容
confirmCB: ( ConfirmCallback ) 可选 确认对话框关闭后的回调函数
回调函数中包括Event参数,可通过其index属性(Number类型)获取用户点击按钮的索引值。
title: ( String ) 可选 确认对话框上显示的标题
buttons: ( Array[ String ] ) 可选 确认对话框上显示的按钮
字符串数组,每项对应在确认对话框上显示一个按钮,用户点击后通过confirmCB返回用户点击按钮的在数组中的索引值。
返回值:
void : 无
平台支持:
Android - 2.2+ (支持): 对话框上最多只能支持三个按钮,buttons参数超过三个的值则忽略。
iOS - 4.5+ (支持)
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>nativeUI Example</title>
<script type="text/javascript">// H5 plus事件处理function plusReady(){
// 弹出提示信息对话框
plus.nativeUI.confirm( "Are you sure ready?", function(e){
console.log( (e.index==0)?"Yes!":"No!" );
}, "nativeUI", ["Yes","No"] );}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}
</script>
</head>
<body>
弹出系统确认对话框
</body></html>
closeWaiting
关闭系统等待对话框
void plus.nativeUI.closeWaiting();
说明:
关闭已经显示的所有系统样式等待对话框,触发Waiting对象的onclose事件。
参数:
无
返回值:
void : 无
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>nativeUI Example</title>
<script type="text/javascript">// H5 plus事件处理function plusReady(){
// 弹出系统等待对话框
plus.nativeUI.showWaiting( "等待中..." );
setTimeout( function(){
plus.nativeUI.closeWaiting();
}, 5000 );}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}
</script>
</head>
<body>
显示系统等待对话框
5S后自动关闭
</body></html>
showWaiting
显示系统等待对话框
Waiting plus.nativeUI.showWaiting( title, options );
说明:
创建并显示系统样式等待对话框,并返回等待对话框对象Waiting,显示后需调用其close方法进行关闭。
参数:
title: ( String ) 可选 等待对话框上显示的提示标题内容
options: ( WaitingOptions ) 可选 等待对话框的显示参数
可设置等待对话框的宽、高、边距、背景等样式。
返回值:
Waiting : Waiting对象
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>nativeUI Example</title>
<script type="text/javascript">// H5 plus事件处理function plusReady(){
// 弹出系统等待对话框
var w = plus.nativeUI.showWaiting( "等待中..." );}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}
</script>
</head>
<body>
显示系统等待对话框
</body></html>
pickDate
弹出系统日期选择对话框
void plus.nativeUI.pickDate( successCB, errorCB, options );
说明:
创建并显示系统样式日期选择对话框,可进行日期的选择。 用户操作确认后通过successCB回调函数返回用户选择的日期,若用户取消选择则通过errorCB回调。
参数:
successCB: ( PickDatetimeSuccessCallback ) 必选 日期选择操作成功的回调函数
回调函数中包括Event参数,可通过其date属性(Date类型)获取用户选择的时间。
errorCB: ( PickDatetimeErrorCallback ) 可选 日期选择操作取消或失败的回调函数
options: ( PickDateOption ) 可选 日期选择操作的参数
返回值:
void : 无
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>nativeUI Example</title>
<script type="text/javascript">// H5 plus事件处理function plusReady(){}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}// 选择日期function pickDate(){
plus.nativeUI.pickDate( function(e){
var d=e.date;
console.log( "选择的日期:"+d.getFullYear()+"-"+(d.getMonth()+1)+"-"+d.getDate() );
},function(e){
console.log( "未选择日期:"+e.message );
});}
</script>
</head>
<body>
弹出系统日期选择对话框
<br/>
<button onclick="pickDate()">选择日期</button>
</body></html>
pickTime
弹出系统时间选择对话框
void plus.nativeUI.pickTime( successCB, errorCB, options );
说明:
创建并弹出系统样式时间选择对话框,可进行时间的选择。 用户操作确认后通过successCB回调函数返回用户选择的时间,若用户取消选择则通过errorCB回调。
参数:
successCB: ( PickDatetimeSuccessCallback ) 必选 时间选择操作成功的回调函数
回调函数中包括Event参数,可通过其date属性(Date类型)获取用户选择的时间。
errorCB: ( PickDatetimeErrorCallback ) 可选 时间选择操作取消或失败的回调函数
options: ( PickTimeOption ) 可选 时间选择操作的参数
返回值:
void : 无
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>nativeUI Example</title>
<script type="text/javascript">// H5 plus事件处理function plusReady(){}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}// 选择时间function pickTime(){
plus.nativeUI.pickTime( function(e){
var d=e.date;
console.log( "选择的时间:"+d.getHours()+":"+d.getMinutes() );
},function(e){
console.log( "未选择时间:"+e.message );
});}
</script>
</head>
<body>
弹出系统时间选择对话框
<br/>
<button onclick="pickTime()">选择时间</button>
</body></html>
prompt
弹出系统输入对话框
void plus.nativeUI.prompt( message, promptCB, title, tip, buttons );
说明:
创建并显示系统样式输入对话框,可设置输入对话框的标题、内容、提示输入信息、按钮数目及其文字。 弹出的输入对话框为非阻塞模式,其中包含编辑框供用户输入内容,用户点击输入对话框上的按钮后自动关闭,并通过promptCB回调函数返回用户点击的按钮及输入的内容。
参数:
message: ( String ) 必选 输入对话框上显示的内容
promptCB: ( PromptCallback ) 可选 关闭输入对话框的回调函数
回调函数中包括Event参数,可通过其index属性(Number类型)获取用户点击按钮的索引值,通过其value属性(String类型)获取用户输入的内容。
title: ( String ) 可选 输入对话框上显示的标题
tip: ( String ) 可选 输入对话框上编辑框显示的提示文字
buttons: ( Array[ String ] ) 可选 输入对话框上显示的按钮数组
返回值:
void : 无
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>nativeUI Example</title>
<script type="text/javascript">// H5 plus事件处理function plusReady(){
// 弹出输入对话框
plus.nativeUI.prompt( "Input your name: ", function(e){
console.log( ((e.index==0)?"OK: ":"Cancel")+e.value );
},"nativeUI", "your name", ["OK","Cancel"]);}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}
</script>
</head>
<body>
弹出系统输入对话框
</body></html>
toast
显示自动消失的提示消息
void plus.nativeUI.toast( message, options );
说明:
创建并显示系统样式提示消息,弹出的提示消息为非阻塞模式,显示指定时间后自动消失。 提示消息显示时间可通过options的duration属性控制,长时间提示消息显示时间约为3.5s,短时间提示消息显示时间约为2s。
参数:
message: ( String ) 必选 提示消息上显示的文字内容
options: ( ToastOption ) 可选 提示消息的参数
可设置提示消息显示的图标、持续时间、位置等。
返回值:
void : 无
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>nativeUI Example</title>
<script type="text/javascript">// H5 plus事件处理function plusReady(){
// 显示自动消失的提示消息
plus.nativeUI.toast( "I'am toast information!");}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}
</script>
</head>
<body>
显示自动消失的提示消息
</body></html>
ActionButtonStyle
JSON对象,原生选择按钮框上按钮的样式参数
属性:
title: (String 类型 )按钮上显示的文字内容
style: (String 类型 )按钮的样式,可取值“destructive”、“default”
“destructive”表示警示按钮样式、“default”表示默认按钮样式,默认为“default”。
平台支持
Android - ALL (不支持)
iOS - 5.0+ (支持): iOS7及以下系统只仅支持一个按钮为“destructive”样式按钮,iOS8及以上系统可支持多个“destructive”样式按钮。
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>nativeUI Example</title>
<script type="text/javascript">// H5 plus事件处理function plusReady(){
// 弹出系统选择按钮框
var actionbuttons=[{title:"不同意",style:"destructive"},{title:"1"},{title:"2"},{title:"3"}];
var actionstyle={title:"Plus is ready!",cancel:"取消",buttons:actionbuttons};
plus.nativeUI.actionSheet( {title:"Plus is ready!",cancel:"取消",actionstyle, function(e){
console.log( "User pressed: "+e.index );
} );}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}
</script>
</head>
<body>
弹出系统选择按钮框
</body></html>
ActionSheetStyle
JSON对象,原生选择按钮框的样式参数
属性:
title: (String 类型 )选择按钮框的标题
cancel: (String 类型 )取消按钮上显示的文字内容
不设置此属性,则不显示取消按钮。
buttons: (Array[ ActionButtonStyle ] 类型 )选择框上的按钮,ActionButtonStyle对象数组
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>nativeUI Example</title>
<script type="text/javascript">// H5 plus事件处理function plusReady(){
// 弹出系统选择按钮框
var actionbuttons=[{title:"不同意",style:"destructive"},{title:"1"},{title:"2"},{title:"3"}];
var actionstyle={title:"Plus is ready!",cancel:"取消",buttons:actionbuttons};
plus.nativeUI.actionSheet( {title:"Plus is ready!",cancel:"取消",actionstyle, function(e){
console.log( "User pressed: "+e.index );
} );}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}
</script>
</head>
<body>
弹出系统选择按钮框
</body></html>
PickDateOption
JSON对象,日期选择对话框的参数
属性:
title: (String 类型 )日期选择对话框显示的标题
如果未设置标题,则默认显示标题为当前选择的日期。
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>nativeUI Example</title>
<script type="text/javascript">// H5 plus事件处理function plusReady(){}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}// 选择日期function pickDate(){
plus.nativeUI.pickDate( function(e){
var d=e.date;
console.log( "选择的日期:"+d.getFullYear()+"-"+(d.getMonth()+1)+"-"+d.getDate() );
},function(e){
console.log( "未选择日期:"+e.message );
},{title:"请选择日期:"});}
</script>
</head>
<body>
弹出系统日期选择对话框
<br/>
<button onclick="pickDate()">选择日期</button>
<br/>
设置标题为“请选择日期:”
</body></html>
date: (Date 类型 )日期选择对话框默认显示的日期
如果未设置默认显示的日期,则显示当前的日期。
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>nativeUI Example</title>
<script type="text/javascript">// H5 plus事件处理function plusReady(){}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}// 选择日期function pickDate(){
var d=new Date();
d.setFullYear(2008,7,8);
plus.nativeUI.pickDate( function(e){
var d=e.date;
console.log( "选择的日期:"+d.getFullYear()+"-"+(d.getMonth()+1)+"-"+d.getDate() );
},function(e){
console.log( "未选择日期:"+e.message );
},{date:d});}
</script>
</head>
<body>
弹出系统日期选择对话框
<br/>
<button onclick="pickDate()">选择日期</button>
<br/>
设置默认日期为“2008-08-08”
</body></html>
minDate: (Date 类型 )日期选择对话框可选择的最小日期
Date类型对象,如果未设置可选择的最小日期,则使用系统默认可选择的最小日期值。
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>nativeUI Example</title>
<script type="text/javascript">// H5 plus事件处理function plusReady(){}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}// 选择日期function pickDate(){
var d=new Date();
d.setFullYear(2010,0,1);
plus.nativeUI.pickDate( function(e){
var d=e.date;
console.log( "选择的日期:"+d.getFullYear()+"-"+(d.getMonth()+1)+"-"+d.getDate() );
},function(e){
console.log( "未选择日期:"+e.message );
},{minDate:d});}
</script>
</head>
<body>
弹出系统日期选择对话框
<br/>
<button onclick="pickDate()">选择日期</button>
<br/>
设置最小可选日期为“2010-01-01”
</body></html>
maxDate: (Date 类型 )日期选择对话框可选择的最大日期
Date类型对象,如果未设置可选择的最大日期,则使用系统默认可选择的最大日期值。 其值必须大于minDate设置的值,否则使用系统默认可选择的最大日期值。
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>nativeUI Example</title>
<script type="text/javascript">// H5 plus事件处理function plusReady(){}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}// 选择日期function pickDate(){
var d=new Date();
d.setFullYear(2014,11,31);
plus.nativeUI.pickDate( function(e){
var d=e.date;
console.log( "选择的日期:"+d.getFullYear()+"-"+(d.getMonth()+1)+"-"+d.getDate() );
},function(e){
console.log( "未选择日期:"+e.message );
},{maxDate:d});}
</script>
</head>
<body>
弹出系统日期选择对话框
<br/>
<button onclick="pickDate()">选择日期</button>
<br/>
设置最大可选日期为“2014-12-31”
</body></html>
popover: (JSON 类型 )时间选择对话框弹出指示区域
JSON类型对象,格式如{top:10;left:10;200;height:200;},所有值为像素值,其值为相对于容器Webview的位置。 如未设置此值,默认在屏幕居中显示。仅在iPad上有效,其它设备忽略此值。
PickTimeOption
JSON对象,时间选择对话框的参数
属性:
time: (Date 类型 )时间选择对话框默认显示的时间
如果未设置标题,则默认显示标题为当前选择的时间。
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>nativeUI Example</title>
<script type="text/javascript">// H5 plus事件处理function plusReady(){}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}// 选择时间function pickTime(){
var t=new Date();
t.setHours(6,0);
plus.nativeUI.pickTime( function(e){
var d=e.date;
console.log( "选择的时间:"+d.getHours()+":"+d.getMinutes() );
},function(e){
console.log( "未选择时间:"+e.message );
},{time:t});}
</script>
</head>
<body>
弹出系统时间选择对话框
<br/>
<button onclick="pickTime()">选择时间</button>
<br/>
设置默认显示时间为早上6点
</body></html>
title: (String 类型 )时间选择对话框显示的标题
如果未设置标题,则默认显示标题为当前选择的时间。
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>nativeUI Example</title>
<script type="text/javascript">// H5 plus事件处理function plusReady(){}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}// 选择时间function pickTime(){
plus.nativeUI.pickTime( function(e){
var d=e.date;
console.log( "选择的时间:"+d.getHours()+":"+d.getMinutes() );
},function(e){
console.log( "未选择时间:"+e.message );
},{title:"请选择时间:"});}
</script>
</head>
<body>
弹出系统时间选择对话框
<br/>
<button onclick="pickTime()">选择时间</button>
<br/>
设置标题为“请选择时间:”
</body></html>
is24Hour: (Boolean 类型 )是否24小时制模式
true表示使用24小时制模式显示,fale表示使用12小时制模式显示,默认值为true。
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>nativeUI Example</title>
<script type="text/javascript">// H5 plus事件处理function plusReady(){}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}// 选择时间function pickTime(){
plus.nativeUI.pickTime( function(e){
var d=e.date;
console.log( "选择的时间:"+d.getHours()+":"+d.getMinutes() );
},function(e){
console.log( "未选择时间:"+e.message );
},{is24Hour:false});}
</script>
</head>
<body>
弹出系统时间选择对话框
<br/>
<button onclick="pickTime()">选择时间</button>
<br/>
设置12小时制显示
</body></html>
popover: (JSON 类型 )日期选择对话框弹出指示区域
JSON类型对象,格式如{top:10;left:10;200;height:200;},所有值为像素值,其值相对于容器webview的位置。 如未设置此值,默认在屏幕居中显示。仅在iPad上有效,其它设备忽略此值。
Waiting
系统等待对话框对象
说明:
可通过plus.nativeUI.showWaiting方法创建,用于控制系统样式等待对话框的操作,如关闭、设置标题内容等。
方法:
setTitle: 设置等待对话框上显示的文字内容
close: 关闭显示的系统等待对话框
事件:
onclose: 等待对话框关闭事件
setTitle
设置等待对话框上显示的文字内容
wobj.setTitle( title );
说明:
在调用plus.nativeUI.showWaiting方法时设置等待对话框初始显示的文字内容,显示后可通过此方法动态修改等待对话框上显示的文字,设置后文字内容将立即更新。
参数:
title: ( String ) 必选 要设置的文本信息
返回值:
void : 无
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>nativeUI Example</title>
<script type="text/javascript">// H5 plus事件处理function plusReady(){
// 弹出系统等待对话框
var w = plus.nativeUI.showWaiting( "等待中..." );
// 2秒后更新
setTimeout( function(){
w.setTitle( "正在更新" );
}, 2000 );}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}
</script>
</head>
<body>
显示系统等待对话框<br/>
设置等待对话框上显示的文字内容
</body></html>
close
关闭显示的系统等待对话框
wobj.close();
说明:
调用plus.nativeUI.showWaiting方法创建并显示系统等待界后,可通过其close方法将原生等待控件关闭。 一个系统等待对话框只能关闭一次,多次调用将无任何作用。
参数:
无
返回值:
void : 无
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>nativeUI Example</title>
<script type="text/javascript">// H5 plus事件处理function plusReady(){
// 弹出系统等待对话框
var w = plus.nativeUI.showWaiting( "等待中..." );
// 2秒后关闭
setTimeout( function(){
w.close();
}, 2000 );}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}
</script>
</head>
<body>
显示系统等待对话框<br/>
关闭显示的系统等待对话框
</body></html>
onclose
等待对话框关闭事件
wobj.onclose = function() {
console.log( "Waiting closed!" );};
说明:
function 类型
等待框关闭时触发,当调用close方法或用户点击返回按钮导致等待框关闭时触发。
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>nativeUI Example</title>
<script type="text/javascript">// H5 plus事件处理function plusReady(){
// 弹出系统等待对话框
var w = plus.nativeUI.showWaiting( "等待中..." );
// 关闭事件
w.onclose = function() {
console.log( "Waiting onclose!" );
}
// 2秒后关闭
setTimeout( function(){
w.close();
}, 2000 );}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}
</script>
</head>
<body>
显示系统等待对话框<br/>
关闭显示的系统等待对话框
</body></html>
WaitingOptions
JSON对象,原生等待对话框的参数
属性:
(String 类型 )等待框背景区域的宽度
值支持像素值("500px")或百分比("50%"),百分比相对于屏幕的宽计算,如果不设置则根据内容自动计算合适的宽度。
height: (String 类型 )等待框背景区域的高度
值支持像素绝对值("500px")或百分比("50%"),如果不设置则根据内容自动计算合适的高度。
color: (String 类型 )等待框中文字的颜色
颜色值支持(参考CSS颜色规范):颜色名称(参考CSS Color Names)/十六进制值/rgb值/rgba值,默认值为白色。
size: (String 类型 )等待框中文字的字体大小
如"14px"表示使用14像素高的文字,未设置则使用系统默认字体大小。
textalign: (String 类型 )等待对话框中标题文字的水平对齐方式
对齐方式可选值包括:"left":水平居左对齐显示,"center":水平居中对齐显示,"right":水平居右对齐显示。默认值为水平居中对齐显示,即"center"。
padding: (String 类型 )等待对话框的内边距
值支持像素值("10px")和百分比("5%"),百分比相对于屏幕的宽计算,默认值为"3%"。
background: (String 类型 )等待对话框显示区域的背景色
背景色的值支持(参考CSS颜色规范):颜色名称(参考CSS Color Names)/十六进制值/rgb值/rgba值,默认值为rgba(0,0,0,0.8)。
style: (String 类型 )等待对话框样式
可取值"black"、"white",black表示等待框为黑色雪花样式,通常在背景主色为浅色时使用;white表示等待框为白色雪花样式,通常在背景主色为深色时使用。 仅在iOS平台有效,其它平台忽略此值,未设置时默认值为white。
平台支持
Android - 2.3+ (不支持): 忽略此属性值。
iOS - 4.5+ (支持): 支持"black"、"white"两种样式。
modal: (Boolen 类型 )等待框是否模态显示
模态显示时用户不可操作直到等待对话框关闭,否则用户在等待对话框显示时也可操作下面的内容,未设置时默认为true。
round: (Number 类型 )等待框显示区域的圆角
值支持像素值("10px"),未设置时使用默认值"10px"。
padlock: (Boolen 类型 )点击等待显示区域是否自动关闭
true表示点击等待对话框显示区域时自动关闭,false则不关闭,未设置时默认值为false。
back: (String 类型 )返回键处理方式
可取值"none"表示截获处理返回键,但不做任何响应;"close"表示截获处理返回键并关闭等待框;"transmit"表示不截获返回键,向后传递给Webview窗口继续处理(与未显示等待框的情况一致)。
平台支持
Android - 2.3+ (支持)
iOS - ALL (不支持): iOS设备无返回键,忽略此属性。
loading: (WaitingLoadingOptions 类型 )自定义等待框上loading图标样式
WaitingLoadingOptions
JSON对象,原生等待对话框上loading图标自定义样式
属性:
display: (String 类型 )loading图标显示样式
可取值: "block"表示图标与文字分开两行显示,上面显示loading图标,下面显示文字; "inline"表示loading图标与文字在同一行显示,左边显示loading图标,右边显示文字; "none"表示不显示loading图标;
icon: (String 类型 )loading图标路径
自定义loading图标的路径,必须是本地资源地址; loading图要求宽是高的整数倍,显示等待框时按照图片的高横向截取每帧刷新。
interval: (Number 类型 )loading图每帧刷新间隔
单位为ms(毫秒),默认值为100ms。
ToastOption
JSON对象,系统提示消息框要设置的参数
属性:
icon: (String 类型 )提示消息框上显示的图标
duration: (String 类型 )提示消息框显示的时间
可选值为"long"、"short",值为"long"时显示时间约为3.5s,值为"short"时显示时间约为2s,未设置时默认值为"short"。
align: (String 类型 )提示消息框在屏幕中的水平位置
可选值为"left"、"center"、"right",分别为水平居左、居中、居右,未设置时默认值为"center"。
verticalAlign: (String 类型 )提示消息在屏幕中的垂直位置
可选值为"top"、"center"、"bottom",分别为垂直居顶、居中、居底,未设置时默认值为"bottom"。
ActionSheetCallback
系统选择按钮框的回调函数
void onActioned( Event event ){
// actionsheet handled code.
var index=event.index; // 用户关闭时点击按钮的索引值}
参数:
event: ( Event ) 必选 用户操作选择按钮框关闭后返回的数据
可通过event.index(Number类型)获取用户关闭时点击按钮的索引值,索引值从0开始; 0表示用户点击取消按钮,大于0值表示用户点击ActionSheetStyle中buttons属性定义的按钮,索引值从1开始(即1表示点击buttons中定义的第一个按钮)。
返回值:
void : 无
平台支持:
Android - ALL (不支持)
iOS - 4.3+ (支持): 用户只能通过点击选择按钮上的按钮进行关闭。
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>nativeUI Example</title>
<script type="text/javascript">// H5 plus事件处理function plusReady(){
// 弹出系统选择按钮框
var actionbuttons=[{title:"不同意",style:"destructive"},{title:"test1"},{title:"test2"},{title:"3"}];
var actionstyle={title:"Plus is ready!",cancel:"取消",buttons:actionbuttons};
plus.nativeUI.actionSheet( actionstyle, function(e){
if(e.index>0){
console.log( "User pressed: "+actionbuttons[e.index-1].title );
}else{
console.log( "User pressed 取消" );
}
} );}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}
</script>
</head>
<body>
弹出系统选择按钮框
</body></html>
AlertCallback
系统提示框确认的回调函数
void onAlerted( Event event ){
// Alert handled code.
var index=event.index; // 用户关闭提示对话框点击按钮的索引值}
参数:
event: ( Event ) 必选 用户操作确认对话框关闭后返回的数据
可通过event.index(Number类型)获取用户关闭确认对话框点击按钮的索引值,点击确认键的索引值为0。 Android平台上通过返回按钮关闭时索引值为-1。
返回值:
void : 无
平台支持:
Android - 2.2+ (支持): 用户点击设备“返回”按键导致提示对话框关闭,也会触发此回调函数,此时回调返回参数中的index属性值为-1。
iOS - 4.3+ (支持): 用户只能通过点击提示对话框上的按钮进行关闭。
ConfirmCallback
关闭确认对话框的回调函数
void onConfirmed( Event event ) {
// Confirm handled code.
var index=event.index; // 用户关闭确认对话框点击按钮的索引值}
参数:
event: ( Event ) 必选 用户操作确认对话框关闭后返回的数据
可通过event.index(Number类型)获取用户关闭确认对话框点击按钮的索引值,索引值从0开始;
返回值:
void : 无
平台支持:
Android - 2.2+ (支持): 用户点击设备“返回”按键导致确认对话框关闭,则回调函数中event的index属性值为-1。
iOS - 4.3+ (支持): 用户只能通过点击确认对话框上的按钮进行关闭。
PromptCallback
系统输入对话框关闭后的回调函数
function void onPrompted( Event event ) {
// Prompt handled code.
var index=event.index; // 用户关闭输入对话框点击按钮的索引值
var value=event.value; // 用户输入的内容}
参数:
event: ( Event ) 必选 用户操作输入对话框关闭后返回的数据
可通过event.index(Number类型)获取用户关闭输入对话框点击按钮的索引值,索引值从0开始; 通过event.value(String类型)获取用户输入的内容,如果没有输入则返回空字符串。
返回值:
void : 无
平台支持:
Android - 2.2+ (支持): 用户点击设备“返回”按键导致输入对话框关闭,则回调函数中event的index属性值为-1,value值为空字符串。
iOS - 4.3+ (支持): 用户只能通过点击输入对话框上的按钮进行关闭。
PickDatetimeSuccessCallback
选择日期或时间操作成功的回调函数
function void onPickSuccess( Event event ) {
// Date picked code.
var date = event.date;// 用户选择的日期或时间}
参数:
event: ( Event ) 必选 用户完成选择日期或时间后返回的数据
可通过event.date(Date类型)获取选择的日期或时间值。 若调用的是日期选择操作则仅年、月、日信息有效,若调用的是时间选择操作则仅时、分信息有效。
返回值:
void : 无
PickDatetimeErrorCallback
选择日期或时间操作取消或失败的回调函数
function void onPickError( Exception error ) {
// Date picked error.
var code = error.code; // 错误编码
var message = error.message; // 错误描述信息}
参数:
error: ( Exception ) 必选 用户选择操作失败信息
可通过error.code(Number类型)获取错误编码; 可通过error.message(String类型)获取错误描述信息。
返回值:
void : 无
Navigator
navigator用于管理浏览器运行环境信息
方法:
closeSplashscreen: 关闭程序启动界面
createShortcut: 创建应用快捷方式
hasShortcut: 查询是否存在应用快捷方式
isFullscreen: 判断应用当前是否全屏模式显示
isLogs: 判断应用当前是否输出日志
setFullscreen: 设置应用是否全屏显示
setLogs: 设置应用是否输出日志
setStatusBarBackground: 设置系统状态栏背景颜色
getStatusBarBackground: 获取系统状态栏背景颜色
setStatusBarStyle: 设置系统状态栏样式
getStatusBarStyle: 获取系统状态栏样式
getStatusbarHeight: 获取系统状态栏高度
isImmersedStatusbar: 判断当前是否为沉浸式状态栏模式
setUserAgent: 设置userAgent值
getUserAgent: 获取userAgent值
setCookie: 设置Cookie值
getCookie: 获取Cookie值
removeAllCookie: 删除应用所有Cookie值
removeCookie: 删除应用Cookie
removeSessionCookie: 删除应用所有会话期Cookie值
对象:
ShortcutOptions: JSON对象,创建应用快捷方式要设置的参数
回调方法:
ShortcutSuccessCallback: 创建桌面快捷方式成功的回调函数
NavigatorErrorCallback: 操作错误回调函数接口
权限:
permissions
"Navigator": {
"description": "浏览器信息"}
closeSplashscreen
关闭程序启动界面
void plus.navigator.closeSplashscreen();
说明:
很多情况下,程序启动后需要一段时间加载数据,为了避免界面显示空白内容,提高用户体验效果,这时可显示启动界面。 等数据加载完成后再关闭启动界面进入应用,通常可在应用首界面加载数据完成并更新显示内容后调用此方法。
参数:
无
返回值:
void : 无
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>navigator Example</title>
<script type="text/javascript">// H5 plus事件处理function plusReady(){
// 关闭程序启动界面
plus.navigator.closeSplashscreen();}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}
</script>
</head>
<body>
关闭程序启动界面
</body></html>
createShortcut
创建应用快捷方式
void plus.navigator.createShortcut( options, successCallback, errorCallback );
说明:
在系统桌面创建应用的快捷方式,点击后可直接启动应用。
参数:
options: ( ShortcutOptions ) 可选 桌面快捷方式的参数
successCallback: ( ShortcutSuccessCallback ) 可选 创建桌面快捷方式成功回调
此功能受系统Launcher限制,可通过回调函数参数的sure属性判断创建桌面快捷方式是否一定成功。
errorCallback: ( NavigatorErrorCallback ) 可选 创建桌面快捷方式失败回调
返回值:
void : 无
平台支持:
Android - 2.3+ (支持): 注意:需要添加创建快捷方式的权限“<uses-permission android:name="com.android.launcher.permission.INSTALL_SHORTCUT"/>”。
iOS - ALL (不支持)
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>navigator Example</title>
<script type="text/javascript">// H5 plus事件处理function plusReady(){
// 创建快捷方式
plus.navigator.createShortcut();}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}
</script>
</head>
<body>
创建应用快捷方式
</body></html>
hasShortcut
查询是否存在应用快捷方式
void plus.navigator.hasShortcut(options, successCallback);
参数:
options: ( ShortcutOptions ) 可选 查询桌面快捷方式的参数
successCallback: ( ShortcutSuccessCallback ) 可选 查询桌面快捷方式是否存在回调函数
可通过回调函数参数的result属性判断获取结果: "existing":快捷方式已存在;"none":快捷方式不存在(支持创建);"unsupported":不支持创建桌面快捷方式;"unknown":不确定快捷方式是否存在。
返回值:
void : 无
平台支持:
Android - 2.3+ (支持)
iOS - ALL (不支持)
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>navigator Example</title>
<script type="text/javascript">// H5 plus事件处理function plusReady(){}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}function queryShortcut(){
plus.navigator.hasShortcut({}, function(e){
// 可通过eresult获取结果:
// "existing":快捷方式已存在;
// "none":快捷方式不存在(支持创建);
// "unsupported":不支持创建桌面快捷方式;
// "unknown":不确定快捷方式是否存在。
console.log("查询结果:"+e.result);
});}
</script>
</head>
<body>
查询是否创建应用快捷方式
<br/>
<button onclick="queryShortcut()">查询</button>
</body></html>
isFullscreen
判断应用当前是否全屏模式显示
Boolean plus.navigator.isFullscreen();
参数:
无
返回值:
Boolean : 应用全屏模式显示时返回true,否则返回false。
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>navigator Example</title>
<script type="text/javascript">// H5 plus事件处理function plusReady(){
// 是否全屏显示
console.log( plus.navigator.isFullscreen()?"Fullscreen!":"Not fullscreen!" );}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}
</script>
</head>
<body>
判断应用当前是否全屏模式显示
</body></html>
isLogs
判断应用当前是否输出日志
Boolean plus.navigator.isLogs();
说明:
日志包括应用原生层内部跟踪日志(ADB、LogCat工具可获取的日志)及JS层跟踪日志(console.log输出的日志)。 开启日志在一定程度上会降低程序的性能,通常建议在正式发布时关闭日志输出,在调试时开启日志输出(此时可以通过工具ADB、LogCat获取分析日志)。
参数:
无
返回值:
Boolean : 应用输出日志时返回true,否则返回false。
平台支持:
Android - 2.3+ (支持)
iOS - 7.0+ (不支持): 无日志输出功能。
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>navigator Example</title>
<script type="text/javascript">// H5 plus事件处理function plusReady(){
// 是否全屏显示
alert( plus.navigator.isLogs()?"应用开启输出日志!":"应用关闭输出日志!" );}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}
</script>
</head>
<body>
判断应用当前是否输出日志
</body></html>
setFullscreen
设置应用是否全屏显示
void plus.navigator.setFullscreen( fullscreen );
说明:
设置应用在全屏模式显示时,将隐藏系统状态栏,通常游戏类应用才会设置为全屏模式显示。
参数:
fullscreen: ( Boolean ) 必选 是否全屏模式显示
true表示全屏模式显示,false表示非全屏模式显示,默认为非全屏模式显示。
返回值:
void : 无
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>navigator Example</title>
<script type="text/javascript">// H5 plus事件处理function plusReady(){
// 全屏显示
plus.navigator.setFullscreen( true );}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}
</script>
</head>
<body>
应用全屏模式显示
</body></html>
setLogs
设置应用是否输出日志
void plus.navigator.setLogs( log );
说明:
设置应用是否输出日志信息,默认关闭输出日志功能。 日志包括应用原生层内部跟踪日志(ADB、LogCat工具可获取的日志)及JS层跟踪日志(console.log输出的日志)。 开启日志在一定程度上会降低程序的性能,通常建议在正式发布时关闭日志输出,在调试时开启日志输出(此时可以通过工具ADB、LogCat获取分析日志)。
参数:
log: ( Boolean ) 必选 是否开启输出日志功能
true表示开启输出日志功能,false表示关闭输出日志功能,默认为关闭输出日志功能。
返回值:
void : 无
平台支持:
Android - 2.3+ (支持)
iOS - 7.0+ (不支持): 无日志输出功能。
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>navigator Example</title>
<script type="text/javascript">// H5 plus事件处理function plusReady(){
// 开启输出日志
plus.navigator.setLogs( true );}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}
</script>
</head>
<body>
应用开启输出日志功能
</body></html>
setStatusBarBackground
设置系统状态栏背景颜色
void plus.navigator.setStatusBarBackground( rgb );
说明:
设置应用在前台运行时系统状态栏的背景颜色,默认使用系统的白色背景。
参数:
rgb: ( String ) 必选 背景颜色字符串,格式为#RRGGBB
返回值:
void : 无
平台支持:
Android - 2.2+ (不支持): 不支持设置系统状态栏背景颜色。
iOS - 7.0+ (支持): 需iOS7.0及以上版本才支持设置系统状态栏背景颜色。
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>navigator Example</title>
<script type="text/javascript">// H5 plus事件处理function plusReady(){
// 设置系统状态栏背景为红色
plus.navigator.setStatusBarBackground( "#FF0000" );}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}
</script>
</head>
<body>
设置系统状态栏背景为红色
</body></html>
getStatusBarBackground
获取系统状态栏背景颜色
String plus.navigator.getStatusBarBackground();
说明:
获取应用在前台运行时系统状态栏的背景颜色。
参数:
无
返回值:
String : 系统状态栏的背景颜色,格式为#RRGGBB。
平台支持:
Android - 2.2+ (不支持): 不支持获取系统状态栏背景颜色。
iOS - 7.0+ (支持): 需iOS7.0及以上版本才能获取的正确的系统状态栏背景颜色。
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>navigator Example</title>
<script type="text/javascript">// H5 plus事件处理function plusReady(){
// 获取系统状态栏背景
var rgb = plus.navigator.getStatusBarBackground();
console.log( "StatusBarBackground: "+rgb );}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}
</script>
</head>
<body>
获取系统状态栏背景
</body></html>
setStatusBarStyle
设置系统状态栏样式
void plus.navigator.setStatusBarStyle( style );
说明:
设置应用在前台运行时系统状态栏的样式,此操作是应用全局配置,Webview窗口关闭后仍然生效,默认值可在manifest.json中配置。
参数:
style: ( String ) 必选 背景颜色字符串,格式为#RRGGBB
可取值:
"UIStatusBarStyleDefault":iOS6及以下系统状态栏为黑底白字,iOS7及以上系统用于定义系统状态栏上文字颜色为黑字(适用于浅色背景);
"UIStatusBarStyleBlackOpaque":深色背景色样式,iOS6及以下系统状态栏为黑底白字,iOS7及以上系统用于定义系统状态栏上文字颜色为白色(适用于深色背景);
"UIStatusBarStyleBlackTranslucent":iOS6及以下系统在启动界面为灰底白字,iOS7及以上系统与UIStatusBarStyleBlackOpaque效果一样。
返回值:
void : 无
平台支持:
Android - 2.2+ (不支持): 不支持设置系统状态栏样式。
iOS - 7.0+ (支持)
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>navigator Example</title>
<script type="text/javascript">// H5 plus事件处理function plusReady(){
// 设置系统状态栏样式为浅色文字
plus.navigator.setStatusBarStyle( "UIStatusBarStyleBlackOpaque" );}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}
</script>
</head>
<body>
设置系统状态栏样式为浅色(白色)文字
</body></html>
getStatusBarStyle
获取系统状态栏样式
String plus.navigator.getStatusBarStyle();
说明:
获取应用在前台运行时系统状态栏的样式。
参数:
无
返回值:
String : 系统状态栏的背景样式,可取值: "UIStatusBarStyleDefault":iOS6及以下系统状态栏为黑底白字,iOS7及以上系统用于定义系统状态栏上文字颜色为黑字(适用于浅色背景); "UIStatusBarStyleBlackOpaque":深色背景色样式,iOS6及以下系统状态栏为黑底白字,iOS7及以上系统用于定义系统状态栏上文字颜色为白色(适用于深色背景); "UIStatusBarStyleBlackTranslucent":iOS6及以下系统在启动界面为灰底白字,iOS7及以上系统不会返回此值。
平台支持:
Android - 2.2+ (不支持): 不支持获取系统状态栏样式。
iOS - 7.0+ (支持)
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>navigator Example</title>
<script type="text/javascript">// H5 plus事件处理function plusReady(){
// 获取系统状态栏样式
var ss = plus.navigator.getStatusBarStyle();
console.log( "Statusbar Style: "+ss );}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}
</script>
</head>
<body>
获取系统状态栏样式
</body></html>
getStatusbarHeight
获取系统状态栏高度
Number plus.navigator.getStatusbarHeight();
说明:
单位为像素(px),值为Webview中的逻辑高度单位,如果要获取真实高度则必须乘以plus.screen.scale。
参数:
无
返回值:
Number : 系统状态栏的高度值。
平台支持:
Android - 2.3+ (支持)
iOS - 5.1+ (支持)
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>navigator Example</title>
<script type="text/javascript">// H5 plus事件处理function plusReady(){
// 获取系统状态栏高度
var lh = plus.navigator.getStatusbarHeight();
console.log( "Statusbar Height: "+lh*plus.screen.scale );}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}
</script>
</head>
<body>
获取系统状态栏高度
</body></html>
isImmersedStatusbar
判断当前是否为沉浸式状态栏模式
Boolean plus.navigator.isImmersedStatusbar();
说明:
如果当前应用采用沉浸式状态栏则返回true,否则返回false。 注意:如果当前系统版本不支持沉浸式状态栏也返回false。
参数:
无
返回值:
Boolean : 是否为沉浸式状态栏模式。
平台支持:
Android - 2.3+ (支持)
iOS - 5.1+ (支持)
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>navigator Example</title>
<script type="text/javascript">// H5 plus事件处理function plusReady(){
// 获取是否为沉浸式状态栏模式
var bi = plus.navigator.isImmersedStatusbar();
console.log( "Immersed Statusbar: "+bi?"Yes":"No" );}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}
</script>
</head>
<body>
当前是否为沉浸式状态栏模式
</body></html>
setUserAgent
设置userAgent值
void plus.navigator.setUserAgent( useragent, checkplus );
说明:
设置应用通过navigator.userAgent获取的值,及所有发起Http请求时提交的userAgent值。 如果要设置启动页面的userAgent值则需要在manifest.json中进行配置。
参数:
useragent: ( String ) 必选 要设置的新的userAgent值
checkplus: ( Boolean ) 可选 是否检测userAgent中自动添加“Html5Plus”标识
布尔类型,true表示检测并自动添加“Html5Plus”标识,false则不检测,默认值为true。 Html5Plus标识格式为Html5Plus/%version%,%version%为版本号,目前为1.0,如" Html5Plus/1.0"。
返回值:
void : 无
平台支持:
Android - 2.2+ (支持): 调用此方法不能更新已经创建好的Webview窗口的userAgent,在此之后创建的Webview窗口将使用新设置的userAgent值。 同时调用此方法的Webview窗口也能及时更新userAgent值。
iOS - 4.5+ (支持): 调用此方法不能更新已经创建好的Webview窗口的userAgent,在此之后创建的Webview窗口将使用新设置的userAgent值。 调用此方法的Webview窗口同样不能更新userAgent值。
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>navigator Example</title>
<script type="text/javascript">// H5 plus事件处理function plusReady(){
// 设置userAgent
plus.navigator.setUserAgent( "Application/HelloWorld" );}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}
</script>
</head>
<body>
设置userAgent为“Application/HelloWorld”
</body></html>
getUserAgent
获取userAgent值
String plus.navigator.getUserAgent();
参数:
无
返回值:
string : 应用的userAgent值
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>navigator Example</title>
<script type="text/javascript">// H5 plus事件处理function plusReady(){}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}// 获取应用的userAgentfunction appUserAgent(){
alert( plus.navigator.getUserAgent() );}
</script>
</head>
<body>
获取userAgent值<br/>
<buttong onclick="appUserAgent()">Get userAgent</buttong>
</body></html>
setCookie
设置Cookie值
void plus.navigator.setCookie( url, value );
说明:
设置应用发起Http请求时提交的cookie值,调用此接口后所有的请求都生效。
参数:
url: ( String ) 必选 要设置的cookie所属的网络地址
value: ( String ) 必选 要设置的cookie值
cookie值的格式必需符合RFC2109中定义的SET-COOKIE响应数据格式,如“test=123;
expires=Friday,24-Jan-2014 16:24:36 GMT; path=/”。
返回值:
void : 无
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>navigator Example</title>
<script type="text/javascript">// H5 plus事件处理function plusReady(){
// 设置cookie
plus.navigator.setCookie( "http://www.dcloud.io/", "test=123; expires=Friday,24-Jan-2015 16:24:36 GMT; path=/" );}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}
</script>
</head>
<body>
设置cookie
</body></html>
getCookie
获取Cookie值
String plus.navigator.getCookie( url );
参数:
url: ( String ) 必选 要获取的cookie所属的网络地址
返回值:
string : Cookie值
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>navigator Example</title>
<script type="text/javascript">// H5 plus事件处理function plusReady(){}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}// 获取Cookiefunction getCookie(){
alert( plus.navigator.getCookie('http://www.dcloud.io/') );}
</script>
</head>
<body>
获取Cookie值<br/>
<buttong onclick="getCookie()">Get Cookie</buttong>
</body></html>
removeAllCookie
删除应用所有Cookie值
void plus.navigator.removeAllCookie();
参数:
无
返回值:
void : 无
平台支持:
Android - 2.2+ (支持)
iOS - 4.5+ (支持)
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>navigator Example</title>
<script type="text/javascript">// H5 plus事件处理function plusReady(){}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}// 清除应用的所有Cookiefunction clearCookie(){
plus.navigator.removeAllCookie();}
</script>
</head>
<body>
删除应用所有Cookie值<br/>
<buttong onclick="clearCookie()">Clear Cookie</buttong>
</body></html>
removeCookie
删除应用Cookie
void plus.navigator.removeCookie( url );
参数:
url: ( String ) 必选 要删除cookie所属的网络地址
返回值:
void : 无
平台支持:
Android - 2.2+ (不支持): 不支持删除指定网络地址的cookie值。
iOS - 4.5+ (支持)
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>navigator Example</title>
<script type="text/javascript">// H5 plus事件处理function plusReady(){}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}// 删除应用的Cookiefunction removeCookie(){
plus.navigator.removeCookie( "http://www.dcloud.io/" );}
</script>
</head>
<body>
删除应用Cookie<br/>
<buttong onclick="removeCookie()">Remove Cookie</buttong>
</body></html>
removeSessionCookie
删除应用所有会话期Cookie值
void plus.navigator.removeSessionCookie();
参数:
无
返回值:
void : 无
平台支持:
Android - 2.2+ (支持)
iOS - 4.5+ (支持)
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>navigator Example</title>
<script type="text/javascript">// H5 plus事件处理function plusReady(){}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}// 清除应用的所有会话期Cookiefunction clearCookie(){
plus.navigator.removeSessionCookie();}
</script>
</head>
<body>
删除应用所有会话期Cookie值<br/>
<buttong onclick="clearCookie()">Clear Cookie</buttong>
</body></html>
ShortcutOptions
JSON对象,创建应用快捷方式要设置的参数
属性:
name: (String 类型 )快捷方式名称
如果未设置则使用应用的名称,manifest.json中name属性值。
icon: (String 类型 )快捷方式的图标
如果未设置则优先使用应用中指定的图标(manifest.json中icon节点下对应分辨率的图标),如未区配则使用应用的图标(仅在独立打包时),否则使用runtime提供的默认图标。
toast: (String 类型 )创建快捷方式后的提示信息
快捷方式创建成功后显示,默认提示内容为“"XXXX"已创建桌面快捷方式”,其中"XXXX"为程序的名称,如果不需要提示则设置此值为空字符串。
extra: (JSON 类型 )快捷方式的扩展参数
其中key和value值都必须是字符串类型。
classname: (String 类型 )要启动Activity类名
通常情况下不需要指定此值,仅在5+SDK集成时自定义Activity才用到。
ShortcutSuccessCallback
创建桌面快捷方式成功的回调函数
void onSuccess( Event event ){
var sure=event.sure; // 是否确定创建桌面快捷方式成功}
参数:
event: ( Event ) 必选 创建桌面快捷方式返回的数据
在部分Launcher上无法确定是否创建桌面快捷方式成功,此时可通过event.sure(Boolean类型)获取是否确定创建成功。
返回值:
void : 无
平台支持:
Android - ALL (支持)
iOS - 4.3+ (不支持): 不支持创建桌面快捷方式。
NavigatorErrorCallback
操作错误回调函数接口
function void onError( Exception error ) {
// Error.
var code = error.code; // 错误编码
var message = error.message; // 错误描述信息}
参数:
error: ( Exception ) 必选 操作失败信息
可通过error.code(Number类型)获取错误编码; 可通过error.message(String类型)获取错误描述信息。
返回值:
void : 无
OAuth
OAuth模块管理客户端的用户授权登录验证功能,允许应用访问第三方平台的资源。
方法:
getServices: 获取授权登录认证服务列表
对象:
AuthService: 授权登录认证服务对象
AuthOptions: JSON对象,授权认证参数选项
回调方法:
ServicesSuccessCallback: 获取授权登录认证服务成功回调
AuthLogoutSuccessCallback: 注销授权登录认证操作成功回调函数
AuthSuccessCallback: 授权登录认证服务操作成功回调函数
AuthErrorCallback: 授权登录认证服务操作失败回调函数
权限:
permissions
"OAuth": {
"description": "访问授权登录认证插件"}
getServices
获取授权登录认证服务列表
void plus.oauth.getServices( successCB, errorCB );
说明:
获取终端支持的权登录认证服务列表,可用于提示用户进行登录平台的选择。获取授权登录认证服务成功后通过successCB回调返回支持的所有服务列表,获取服务失败则通过errorCB回调返回失败信息。
参数:
successCB: ( ServicesSuccessCallback ) 必选 获取授权登录认证服务成功回调函数
获取授权登录认证服务列表成功时触发回调,并返回终端支持的授权登录认证服务列表。
errorCB: ( AuthErrorCallback ) 可选 获取授权登录认证服务失败回调函数
获取授权登录认证服务列表失败时触发回调,并返回错误信息。
返回值:
void : 无
平台支持:
Android - 2.2+ (支持)
iOS - 5.0+ (支持)
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0, user-scalable=no"/>
<title>OAuth Example</title>
<script type="text/javascript">var auths=null;// 监听plusready事件
document.addEventListener( "plusready", function(){
// 扩展API加载完毕,现在可以正常调用扩展API
plus.oauth.getServices( function(services){
auths = services;
}, function(e){
alert( "获取分享服务列表失败:"+e.message+" - "+e.code );
} );}, false );
</script>
</head>
<body>
获取授权登录认证服务列表
</body></html>
AuthService
授权登录认证服务对象
interface plus.oauth.AuthService {
// Attributes
attribute String id;
attribute String description;
attribute JSON authResult;
attribute JSON userInfo;
attribute JSON extra;
// Methods
function void login( successCallback, errorCallback, options );
function void logout( successCallback, errorCallback );
function void getUserInfo( successCallback, errorCallback );
function void addPhoneNumber( successCallback, errorCallback );}
说明:
AuthService对象用于表示授权登录认证服务,在JS中为对象,用于向系统进行授权登录认证操作。
属性:
id: 授权登录认证服务标识
description: 授权登录认证服务描述
authResult: 授权认证结果数据
userInfo: 授权登录认证用户信息
extra: 授权登录认证扩展信息
方法:
login: 请求授权登录认证操作
logout: 注销授权登录认证
getUserInfo: 获取授权登录用户信息
addPhoneNumber: 添加用户手机号信息
id
授权登录认证服务标识
说明:
String 类型 只读属性
用于表示授权登录认证服务标识,如“weixin”表示微信、“qq”表示QQ、“sinaweibo”表示新浪微博、“qihoo”表示360账号登录(仅360手助流应用环境下支持)。
平台支持:
Android - 2.2+ (支持)
iOS - 5.0+ (支持)
description
授权登录认证服务描述
说明:
String 类型 只读属性
用于描述授权登录认证服务的信息,如“微信”、“QQ”、“新浪微博”、“360账号”。
平台支持:
Android - 2.2+ (支持)
iOS - 5.0+ (支持)
authResult
授权认证结果数据
说明:
JSON 类型 只读属性
用于标识此授权登录认证服务是否已经授权登录认证过,如果已经授权登录过则保存授权登录信息,否则为undefined。 例如“微信”,则可能保存以下数据: code - 用户换取access_token的code; lang - 微信客户端当前语言; country - 微信用户当前国家信息; access_token - 接口调用凭证; expires_in - access_token接口调用凭证超时时间,单位(秒); refresh_token - 用户刷新access_token; openid - 授权用户唯一标识; scope - 用户授权的作用域,使用逗号(,)分隔。
平台支持:
Android - 2.2+ (支持)
iOS - 5.0+ (支持)
userInfo
授权登录认证用户信息
说明:
JSON 类型 只读属性
用于标识此授权登录认证服务是否已经获取过用户信息,如果已经通过授权登录并获取用户信息成功则保存用户相关信息,否则为undefined。 例如“微信”,则可能保存以下数据: openid - 普通用户的标识,对当前开发者帐号唯一; nickname - 普通用户昵称; sex - 普通用户性别,1为男性,2为女性; province - 普通用户个人资料填写的省份; city - 普通用户个人资料填写的城市; country - 国家,如中国为CN; headimgurl - 用户头像,最后一个数值代表正方形头像大小(有0、46、64、96、132数值可选,0代表640*640正方形头像),用户没有头像时该项为空; privilege - 用户特权信息,json数组,如微信沃卡用户为(chinaunicom); unionid - 用户统一标识。针对一个微信开放平台帐号下的应用,同一用户的unionid是唯一的。
平台支持:
Android - 2.2+ (支持)
iOS - 5.0+ (支持)
extra
授权登录认证扩展信息
说明:
JSON 类型 只读属性 可选属性
用于保存授权登录认证服务返回的扩展信息,具体内容由各登录平台决定,如果没有扩展信息则为undefined。 例如“微信”,则可保存以下数据: state - 用于保持请求和回调的状态参数。
login
请求授权登录认证操作
void obj.login( successCallback, errorCallback, options );
说明:
对指定的授权登录认证服务进行登录认证操作,在登录前可通过对象的authResult属性判断是否已经登录认证过,通常只需要对没有进行过登录认证的服务进行登录认证操作。授权认证操作成功后通过successCB回调函数通知,失败则通过errorCB回调函数通知。
参数:
successCallback: ( AuthSuccessCallback ) 必选 授权登录认证服务登录认证成功回调函数
授权登录认证服务登录认证操作成功时触发,并返回登录认证成功信息。
errorCallback: ( AuthErrorCallback ) 可选 授权登录认证服务登录认证失败回调函数
授权登录认证服务授权认证操作失败时触发,并返回错误信息。
options: ( AuthOptions ) 可选 授权登录认证参数
授权登录认证服务授权认证操作使用的参数。
返回值:
void : 无
平台支持:
Android - 2.2+ (支持)
iOS - 5.0+ (支持)
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0, user-scalable=no"/>
<title>OAuth Example</title>
<script type="text/javascript">var auths=null;// 监听plusready事件
document.addEventListener( "plusready", function(){
// 扩展API加载完毕,现在可以正常调用扩展API
plus.oauth.getServices( function(services){
auths = services;
}, function(e){
alert( "获取分享服务列表失败:"+e.message+" - "+e.code );
} );}, false );// 登录操作function authLogin(){
var s = auths[0];
if ( !s.authResult ) {
s.login( function(e){
alert( "登录认证成功!" );
}, function(e){
alert( "登录认证失败!" );
} );
}else{
alert( "已经登录认证!" );
}}
</script>
</head>
<body>
1.请求授权登录认证操作<br/>
<button onclick="authLogin()">Login</button>
</body></html>
logout
注销授权登录认证
void obj.logout( successCallback, errorCallback );
说明:
对指定的授权登录认证服务注销登录认证操作,注销授权认证后,再次操作时需重新进行登录认证操作。 如果第三方平台不需要注销操作,则情况保存的相关登录认证等信息。
参数:
successCallback: ( AuthLogoutSuccessCallback ) 必选 注销授权登录认证成功回调函数
注销授权登录认证服务登录认证操作成功时触发,并返回注销登录认证成功信息。
errorCallback: ( AuthErrorCallback ) 可选 注销授权登录认证失败回调函数
注销授权登录认证服务授权认证操作失败时触发,并返回错误信息。
返回值:
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>OAuth Example</title>
<script type="text/javascript">var auths=null;// 监听plusready事件
document.addEventListener( "plusready", function(){
// 扩展API加载完毕,现在可以正常调用扩展API
plus.oauth.getServices( function(services){
auths = services;
}, function(e){
alert( "获取分享服务列表失败:"+e.message+" - "+e.code );
} );}, false );// 登录操作function authLogin(){
var s = auths[0];
if ( !s.authResult ) {
s.login( function(e){
alert( "登录认证成功!" );
}, function(e){
alert( "登录认证失败!" );
} );
}else{
alert( "已经登录认证!" );
}}// 注销所有授权登录认证服务function authLogout(){
for ( var i in auths ) {
var s = auths[i];
if ( s.authResult ) {
s.logout(function(e){
alert( "注销登录认证成功!" );
}, function(e){
alert( "注销登录认证失败!" );
});
}
}}
</script>
</head>
<body>
1.请求授权登录认证操作<br/>
<button onclick="authLogin()">Login</button>
2.请求授权登录认证操作<br/>
<button onclick="authLogout()">Logout</button>
</body></html>
getUserInfo
获取授权登录用户信息
void obj.getUserInfo( successCallback, errorCallback );
说明:
获取授权登录认证的用户信息,在获取前可通过对象的userInfo属性判断是否已经获取过,通常只需要对没有获取过用户信息的服务进行操作。 获取用户信息操作成功后通过successCallback回调函数通知,失败则通过errorCallback回调函数通知。
参数:
successCallback: ( AuthSuccessCallback ) 必选 获取授权登录用户信息成功回调函数
获取登录认证用户信息操作成功时触发,并返回用户的信息。
errorCallback: ( AuthErrorCallback ) 可选 获取授权登录用户信息失败回调函数
获取登录认证用户信息操作失败时触发,并返回错误信息。
返回值:
void : 无
平台支持:
Android - 2.2+ (支持)
iOS - 5.0+ (支持)
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0, user-scalable=no"/>
<title>OAuth Example</title>
<script type="text/javascript">var auths=null;// 监听plusready事件
document.addEventListener( "plusready", function(){
// 扩展API加载完毕,现在可以正常调用扩展API
plus.oauth.getServices( function(services){
auths = services;
}, function(e){
alert( "获取分享服务列表失败:"+e.message+" - "+e.code );
} );}, false );// 登录操作function authLogin(){
var s = auths[0];
if ( !s.authResult ) {
s.login( function(e){
alert( "登录认证成功!" );
}, function(e){
alert( "登录认证失败!" );
} );
}else{
alert( "已经登录认证!" );
}}// 获取登录用户信息操作function authUserInfo(){
var s = auths[0];
if ( !s.authResult ) {
alert("未授权登录!");
} else {
s.getUserInfo( function(e){
alert( "获取用户信息成功:"+JSON.stringify(s.userInfo) );
}, function(e){
alert( "获取用户信息失败:"+e.message+" - "+e.code );
} );
}}
</script>
</head>
<body>
1.请求授权登录认证操作<br/>
<button onclick="authLogin()">Login</button>
2. 获取授权登录用户信息<br/>
<button onclick="authUserInfo()">UserInfo</button>
</body></html>
addPhoneNumber
添加用户手机号信息
void obj.addPhoneNumber( successCallback, errorCallback );
说明:
打开授权登录服务的添加用户手机号界面进行操作,添加用户手机号操作成功后通过successCallback回调函数通知,否则通过errorCallback回调函数通知。
参数:
successCallback: ( AuthSuccessCallback ) 必选 添加用户手机号信息成功回调函数
errorCallback: ( AuthErrorCallback ) 可选 添加用户手机号信息失败回调函数
返回值:
void : 无
平台支持:
Android - ALL (不支持)
iOS - ALL (不支持)
360手助流应用 - 3.5+ (支持)
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0, user-scalable=no"/>
<title>OAuth Example</title>
<script type="text/javascript">var auths=null;// 监听plusready事件
document.addEventListener( "plusready", function(){
// 扩展API加载完毕,现在可以正常调用扩展API
plus.oauth.getServices( function(services){
auths = services;
}, function(e){
alert( "获取分享服务列表失败:"+e.message+" - "+e.code );
} );}, false );// 登录操作function authLogin(){
var s = auths[0];
if ( !s.authResult ) {
s.login( function(e){
alert( "登录认证成功!" );
}, function(e){
alert( "登录认证失败!" );
} );
}else{
alert( "已经登录认证!" );
}}// 添加用户手机号信息function addPhoneNumber(){
var s = auths[0];
if ( !s.authResult ) {
alert("未授权登录!");
} else {
s.addPhoneNumber( function(e){
alert( "添加用户手机号信息成功!" );
}, function(e){
alert( "添加用户手机号信息失败:"+e.message+" - "+e.code );
} );
}}
</script>
</head>
<body>
1.请求授权登录认证操作<br/>
<button onclick="authLogin()">Login</button>
2.添加用户手机号信息<br/>
<button onclick="addPhoneNumber()">AddPhoneNumber</button>
</body></html>
AuthOptions
JSON对象,授权认证参数选项
interface plus.oauth.AuthOptions {
attribute String scope;
attribute String state;
attribute String appkey;}
说明:
此对象支持的属性值由授权登录认证服务定义。 例如“微信”,则可配置以下参数: scope - 应用授权作用域; state - 用于保持请求和回调的状态参数。
属性:
scope: (String 类型 )申请的权限范围
state: (String 类型 )客户端的当前状态,可以指定任意值,登录认证后原封不动的返回保存到AuthService对象的extra中
appkey: (String 类型 )360开放平台申请的生活助手应用appkey标识
平台支持
Android - 2.2+ (不支持)
iOS - 5.0+ (不支持)
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0, user-scalable=no"/>
<title>OAuth Example</title>
<script type="text/javascript">var auths=null;// 监听plusready事件
document.addEventListener( "plusready", function(){
// 扩展API加载完毕,现在可以正常调用扩展API
plus.oauth.getServices( function(services){
auths = services;
}, function(e){
alert( "获取分享服务列表失败:"+e.message+" - "+e.code );
} );}, false );// 登录操作function authLogin(){
var s = auths[0];
if ( !s.authResult ) {
s.login( function(e){
alert( "登录认证成功!" );
}, function(e){
alert( "登录认证失败!" );
}, {appid:"wx0411fa6a39d61297" // 微信应用的appid
,scope:"snsapi_userinfo"} // 授权获取用户信息
);
}}
</script>
</head>
<body>
请求授权登录认证操作(配置参数)
<button onclick="authLogin()">Login</button>
</body></html>
ServicesSuccessCallback
获取授权登录认证服务成功回调
void ServicesSuccessCallback( services ) {
// Get oauth services success code}
说明:
当获取授权登录认证服务列表成功时触发,并通过services参数返回运行环境支持的授权登录认证服务列表。
参数:
services: ( Array[ AuthService ] ) 必选 运行环境支持的授权登录认证服务列表
运行环境支持的授权登录认证服务列表数组,可通过services.length获取服务列表的数目。 如果当前运行环境没有支持的授权登录认证服务,则返回空数组。
返回值:
void : 无
平台支持:
Android - 2.2+ (支持)
iOS - 5.0+ (支持)
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0, user-scalable=no"/>
<title>OAuth Example</title>
<script type="text/javascript">var auths=null;// 监听plusready事件
document.addEventListener( "plusready", function(){
// 扩展API加载完毕,现在可以正常调用扩展API
plus.oauth.getServices( function(services){
// services.length可获取当前运行环境支持授权登录认证服务数目
if(services.length>0){
auths = services;
}else{
alert("当前运行环境不支持授权登录认证服务!");
}
}, function(e){
alert( "获取分享服务列表失败:"+e.message+" - "+e.code );
} );}, false );
</script>
</head>
<body>
获取授权登录认证服务列表
</body></html>
AuthLogoutSuccessCallback
注销授权登录认证操作成功回调函数
void AuthLogoutSuccessCallback( event ) {
// logout code}
说明:
注销授权登录认证成功时触发,并返回操作结果。
参数:
event: ( JSON ) 必选 注销授权登录认证操作回调事件参数
包括以下参数: event.target - 表示授权登录认证服务对象; 其它属性可保存注销授权登录的扩展数据。
返回值:
void : 无
平台支持:
Android - 2.2+ (支持)
iOS - 5.0+ (支持)
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0, user-scalable=no"/>
<title>OAuth Example</title>
<script type="text/javascript">var auths=null;// 监听plusready事件
document.addEventListener( "plusready", function(){
// 扩展API加载完毕,现在可以正常调用扩展API
plus.oauth.getServices( function(services){
auths = services;
}, function(e){
alert( "获取分享服务列表失败:"+e.message+" - "+e.code );
} );}, false );// 注销所有授权登录认证服务function authLogout(){
for ( var i in auths ) {
var s = auths[i];
if ( s.authResult ) {
s.logout(function(e){
alert( "注销登录认证成功!" );
}, function(e){
alert( "注销登录认证失败!" );
});
}
}}
</script>
</head>
<body>
请求授权登录认证操作
<br/>
<button onclick="authLogout()">Logout</button>
</body></html>
AuthSuccessCallback
授权登录认证服务操作成功回调函数
void AuthSuccessCallback( event ) {
// auth code}
说明:
授权登录认证服务操作如请求授权登录认证、获取授权登录用户信息成功时触发,并返回操作结果。
参数:
event: ( JSON ) 必选 授权登录认证服务操作回调事件参数
包括以下参数: event.target - 表示授权登录认证服务对象,可以通过此对象的authResult、userInfo属性来获取操作结果信息。
返回值:
void : 无
平台支持:
Android - 2.2+ (支持)
iOS - 5.0+ (支持)
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0, user-scalable=no"/>
<title>OAuth Example</title>
<script type="text/javascript">var auths=null;// 监听plusready事件
document.addEventListener( "plusready", function(){
// 扩展API加载完毕,现在可以正常调用扩展API
plus.oauth.getServices( function(services){
auths = services;
}, function(e){
alert( "获取分享服务列表失败:"+e.message+" - "+e.code );
} );}, false );// 登录操作function authLogin(){
var s = auths[0];
if ( !s.authResult ) {
s.login( function(e){
// 获取登录操作结果
var result = e.target.authResult;
alert( "登录认证成功:"+JSON.stringify(result) );
}, function(e){
alert( "登录认证失败!" );
}, {} );
}}
</script>
</head>
<body>
请求授权登录认证操作
<button onclick="authLogin()">Login</button>
</body></html>
AuthErrorCallback
授权登录认证服务操作失败回调函数
void AuthErrorCallback( error ) {
// Error code}
说明:
授权登录认证服务操作如请求授权登录认证、注销授权登录认证、获取授权登录用户信息失败时触发,并返回错误信息。
参数:
error: ( Exception ) 必选 操作失败错误信息
包括以下参数: error.code - 表示错误代码; error.message - 错误描述信息;
返回值:
void : 无
平台支持:
Android - 2.2+ (支持)
iOS - 5.0+ (支持)
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0, user-scalable=no"/>
<title>OAuth Example</title>
<script type="text/javascript">var auths=null;// 监听plusready事件
document.addEventListener( "plusready", function(){
// 扩展API加载完毕,现在可以正常调用扩展API
plus.oauth.getServices( function(services){
auths = services;
}, function(e){
alert( "获取分享服务列表失败:"+e.message+" - "+e.code );
} );}, false );// 登录操作function authLogin(){
var s = auths[0];
if ( !s.authResult ) {
s.login( function(e){
alert( "登录认证成功!" );
}, function(e){
alert( "登录认证失败:"+e.message+" - "+e.code );
}, {} );
}}
</script>
</head>
<body>
请求授权登录认证操作
<button onclick="authLogin()">Login</button>
</body></html>
Orientation
Orientation模块管理设备的方向信息,包括alpha、beta、gamma三个方向信息,通过plus.orientation可获取设备方向管理对象。
方法:
getCurrentOrientation: 获取当前设备的方向信息,包括alpha、beta、gamma三个方向信息
watchOrientation: 监听设备方向信息的变化
clearWatch: 关闭监听设备方向信息
对象:
OrientationOption: JSON对象,监听设备方向感应器参数
Rotation: JSON对象,设备方向信息数据
回调方法:
OrientationSuccessCallback: 获取设备方向信息成功的回调函数
OrientationErrorCallback: 获取设备方向信息失败的回调函数
权限:
permissions
"Orientation": {
"description": "访问方向感应器信息"}
getCurrentOrientation
获取当前设备的方向信息,包括alpha、beta、gamma三个方向信息
void plus.orientation.getCurrentOrientation( successCB, errorCB );
说明:
方向信息是设备相对于水平初始方向分别以z、x、y轴为轴心旋转的角度,对应值为alpha、beta、gamma三个方向的信息。 方向信息可通过successCB回调函数返回。方向信息获取失败则调用回调函数errorCB
参数:
successCB: ( OrientationSuccessCallback ) 必选 获取设备方向信息成功回调函数
errorCB: ( OrientationErrorCallback ) 可选 获取设备方向信息失败回调函数
返回值:
void : 无
平台支持:
Android - 2.2+ (支持): 支持
iOS - 4.3+ (支持): 支持
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Orientation Example</title>
<script type="text/javascript">// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );// 扩展API加载完毕,现在可以正常调用扩展APIfunction onPlusReady() {
plus.orientation.getCurrentOrientation( function ( o ) {
alert( "Orientation Alpha:" + o.alpha + " Beta:" + o.beta + " Gamma:" + o.gamma );
} ); }
</script>
</head>
<body>
Orientation
</body></html>
watchOrientation
监听设备方向信息的变化
Number plus.orientation.watchOrientation( successCB, errorCB, option );
说明:
方向信息是设备相对于水平初始方向分别以z、x、y轴为轴心旋转的角度,对应值为alpha、beta、gamma三个方向的信息。watchOrientation每隔固定时间就获取一次设备的方向信息,通过successCB回调函数返回。可通过option的frequency参数设定获取设备方向信息的时间间隔。方向信息获取失败则调用回调函数errorCB。
参数:
successCB: ( OrientationSuccessCallback ) 必选
获取设备方向信息成功回调函数
errorCB: ( OrientationErrorCallback ) 可选
获取设备方向信息失败回调函数
option: ( OrientationOption ) 可选
监听设备方向信息的参数,如更新数据的频率等
返回值:
Number : 用于标识方向信息监听器,可通过clearWatch方法取消监听。
平台支持:
Android - 2.2+ (支持): 支持
iOS - 4.3+ (支持): 支持
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Orientation Example</title>
<script type="text/javascript">// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );// 扩展API加载完毕,现在可以正常调用扩展APIfunction onPlusReady() {
plus.orientation.watchOrientation( function ( o ) {
alert( "Orientation Alpha:" + o.alpha + " Beta:" + o.beta + " Gamma:" + o.gamma );
}, function ( e ) {
alert( "Orientation error: " + e.message );
} ); }
</script>
</head>
<body>
Orientation watch
</body></html>
clearWatch
关闭监听设备方向信息
void plus.orientation.clearWatch( watchId );
参数:
watchId: ( Number ) 必选
需要取消的方向监听器标识,调用watchOrientation方法的返回值。
返回值:
void : 无
平台支持:
Android - 2.2+ (支持): 支持
iOS - 4.3+ (支持): 支持
OrientationOption
JSON对象,监听设备方向感应器参数
属性:
frequency: (Number 类型 )更新方向信息的时间间隔
数值类型,单位为ms,默认值为500ms。
Rotation
JSON对象,设备方向信息数据
interface Rotation {
readonly attribute float alpha;
readonly attribute float beta;
readonly attribute float gamma;
readonly attribute float magneticHeading;
readonly attribute float trueHeading;
readonly attribute float headingAccuracy;}
属性:
alpha: (float 类型 )以z方向为轴心的旋转角度
浮点数类型,只读属性,取值范围为0到360(不等于360)。
beta: (float 类型 )以x方向为轴心的旋转角度
浮点数类型,只读属性,取值范围为-180到180(不等于180)。
gamma: (float 类型 )以y方向为轴心的旋转角度
浮点数类型,只读属性,取值范围为-180到180(不等于180)。
magneticHeading: (float 类型 )设备方向与地球磁场北极方向的角度
浮点数类型,只读属性,取值范围为0到360(不等于360)。
平台支持
Android - 2.2+ (支持)
iOS - 4.3+ (支持): iTouch、iPad设备不支持
trueHeading: (float 类型 )设备方向与地球真实北极方向的角度
浮点数类型,只读属性,取值范围为0到360(不等于360)。
平台支持
Android - 2.2+ (支持)
iOS - 4.3+ (支持): iTouch、iPad设备不支持
headingAccuracy: (float 类型 )设备方向值的误差值
浮点数类型,只读属性,取值范围为0到360(不等于360)。
平台支持
Android - 2.2+ (支持)
iOS - 4.3+ (支持): iTouch、iPad设备不支持
OrientationSuccessCallback
获取设备方向信息成功的回调函数
void onSuccess( rotation ){
// Get orientation success code.}
参数:
rotation: ( DOMString ) 必选 设备的方向信息Rotation
返回值:
void : 无
OrientationErrorCallback
获取设备方向信息失败的回调函数
void onError( error ) {
// Get orientation error code. }
参数:
error: ( DOMException ) 必选 失败信息
返回值:
void : 无
Payment
Payment模块管理支付功能,用于提供网页安全支付能力,支持通过Web接口进行支付操作。通过plus.payment可获取支付管理对象。
方法:
getChannels: 获取支付通道
request: 请求支付操作
对象:
PaymentChannel: 支付通道对象
OrderStatementIAP: IAP订单数据对象
PaymentResult: 支付操作结果对象
IAPProduct: IAP商品对象
IAPProductInfo: 购买IAP商品对象
IAPTransaction: 购买IAP商品交易信息对象
回调方法:
ChannelsSuccessCallback: 获取支付通道成功回调
IapRequestOrderSuccessCallback: 请求支付商品列表回调方法
IapRestoreComplateRequestCallback: 请求已经购买的非消耗性商品和订阅商品回调方法
PaymentSuccessCallback: 支付操作成功回调
PaymentErrorCallback: 支付操作失败回调
权限:
permissions
"Payment": {
"description": "访问支付插件"}
getChannels
获取支付通道
void plus.payment.getChannels( successCB, errorCB );
说明:
在进行支付操作前需获取终端支持的支付通道列表,用于提示用户进行选择。获取支付通道成功后通过successCB回调返回支持的所有通道列表,获取支付通道列表失败则通过errorCB回调返回。
参数:
successCB: ( ChannelsSuccessCallback ) 必选 获取支付通道成功回调函数
获取支付通道列表成功时的回调函数,用于返回终端支持的支付通道列表。
errorCB: ( PaymentErrorCallback ) 可选 获取支付通道失败回调函数
获取支付通道列表失败时的回调函数,用于返回错误信息。
返回值:
void : 无
平台支持:
Android - 2.2+ (支持)
iOS - 5.0+ (支持)
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0, user-scalable=no"/>
<title>Payment Example</title>
<script type="text/javascript">var channels=null;// 监听plusready事件
document.addEventListener( "plusready", function(){
// 扩展API加载完毕,现在可以正常调用扩展API
plus.payment.getChannels( function(s){
channels = s;
}, function(e){
alert( "获取支付通道列表失败:"+e.message );
} );}, false );
</script>
</head>
<body>
</body></html>
request
请求支付操作
void plus.payment.request( channel, statement, successCB, errorCB );
说明:
调用指定的支付通道进行支付操作,其中statement包含支付操作的相关信息,支付模块将弹出支付界面供用户进行支付信息的输入确认操作。用户支付操作成功后通过successCB回调返回支付操作结果,支付操作失败则通过errorCB回调返回。
参数:
channel: ( PaymentChannel ) 必选 支付通道
指定支付操作的通道,通过getChannels接口获取。
statement: ( String | JSON | OrderStatementIAP ) 必选 支付订单信息
支付订单信息,由支付通道定义的数据格式,通常是由业务服务器生成或向支付服务器获取,是经过加密的字符串信息。
successCB: ( PaymentSuccessCallback ) 必选 获取支付通道成功回调函数
获取支付通道列表成功时的回调函数,用于返回终端支持的支付通道列表。
errorCB: ( PaymentErrorCallback ) 可选 获取支付通道失败回调函数
获取支付通道列表失败时的回调函数,用于返回错误信息。
返回值:
void : 无
平台支持:
Android - 2.2+ (支持)
iOS - 5.0+ (支持)
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0, user-scalable=no"/>
<title>Payment Example</title>
<script type="text/javascript">var channels=null;// 监听plusready事件
document.addEventListener( "plusready", function(){
// 扩展API加载完毕,现在可以正常调用扩展API
plus.payment.getChannels( function(s){
channels = s;
}, function(e){
alert( "获取支付通道列表失败:"+e.message );
} );}, false );// 请求支付操作function requestPay( c ) {
// 必须从业务服务器获取支付信息
var statement = "...";
plus.payment.request( c, statement, function(){
alert( "支付操作成功!" );
}, function(e){
alert( "支付失败:"+e.message );
} );}
</script>
</head>
<body>
</body></html>
PaymentChannel
支付通道对象
interface plus.payment.PaymentChannel {
attribute String id;
attribute String description;
attribute Boolean serviceReady;
function void installService();
// iOS iAP
function void requestOrder(ids, successCB, errorCB);
function void restoreComplateRequest(options, successCB);}
说明:
PaymentChannel对象表示特定的支付通道,用于向系统请求支付操作。
属性:
id: 支付通道标识
description: 支付通道描述
serviceReady: 支付通道服务是否安装
方法:
installService: 安装支付通道依赖的服务
requestOrder: 向IAP服务器请求支付订单
restoreComplateRequest: 向IAP服务器请求已经购买的非消耗性商品和订阅商品
id
支付通道标识
说明:
String 类型 只读属性
用于标识支付通道,如“alipay”表示支付宝、“wxpay”表示微信支付、“appleiap”表示苹果应用内支付、“qhpay”表示360聚合支付(仅360手助流应用环境下支持)。
平台支持:
Android - 2.2+ (支持)
iOS - 5.0+ (支持)
description
支付通道描述
说明:
String 类型 只读属性
支付通道的描述信息,如“支付宝”、“微信”、“In-App Purchase”、“360聚合支付”。
平台支持:
Android - 2.2+ (支持)
iOS - 5.0+ (支持)
serviceReady
支付通道服务是否安装
说明:
Boolean 类型 只读属性
通常特定的支付通道依赖系统安装相关的服务,此属性用于标识其服务是否安装,如果没有安装则为false,否则为true。 若系统环境中没有安装相关的服务,则可能导致调用支付操作失败,这时可以调用installService方法进行安装。 注意:如果支付通道不需要依赖系统安装服务,则永远返回true。例如支付宝,如果设备上未安装支付宝客户端则调用Wap页面进行支付,因此值固定返回true; 而微信支付则依赖微信客户端,如果设备上未安装微信客户端则serviceReady值为false,此时应该提示用户安装微信客户端才能进行支付操作。
平台支持:
Android - 2.2+ (支持)
iOS - 5.0+ (支持)
installService
安装支付通道依赖的服务
void pay.installService();
说明:
对于某些支付通道,通常特定的支付通道依赖系统安装相关的服务,调用此方法将安装其依赖的支付服务。如支付宝,则在系统中安装支付宝客户端程序。
参数:
无
返回值:
void : 无
平台支持:
Android - 2.2+ (支持): 支付宝:支付操作可不依赖系统环境服务,此方法不做任何操作。当调用plus.payment.request请求支付操作时如果系统环境中已经安装“支付宝钱包”则会调用支付宝钱包进行支付,否则调用Webview窗口进行支付。
iOS - 5.0+ (支持): 支付宝:支付操作可不依赖系统环境服务,此方法不做任何操作。当调用plus.payment.request请求支付操作时如果系统环境中已经安装“支付宝钱包”则会调用支付宝钱包进行支付,否则调用Webview窗口进行支付。
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0, user-scalable=no"/>
<title>Payment Example</title>
<script type="text/javascript">var channels=null;// 监听plusready事件
document.addEventListener( "plusready", function(){
// 扩展API加载完毕,现在可以正常调用扩展API
plus.payment.getChannels( function(s){
channels = s;
}, function(e){
alert( "获取支付通道列表失败:"+e.message );
} );}, false );// 请求支付操作function requestPay( c ) {
// 必须从业务服务器获取支付信息
var statement = "...";
if ( !c.serviceReady ) {
c.installService();
}
plus.payment.request( c, statement, function(){
alert( "支付操作成功!" );
}, function(e){
alert( "支付失败:"+e.message );
} );}
</script>
</head>
<body>
</body></html>
requestOrder
向IAP服务器请求支付订单
void pay.requestOrder(ids, successCB, errorCB);
说明:
IAP支付在调用plus.payment.request方法支付前须先向服务器请求获取商品的详细信息,否则会支付失败。
参数:
ids: ( Array[ String ] ) 必选 请求商品的标识
successCB: ( IapRequestOrderSuccessCallback ) 必选 请求成功回调
errorCB: ( PaymentErrorCallback ) 必选 请求失败回调
返回值:
void : 无
平台支持:
Android - 2.2+ (不支持)
iOS - 5.0+ (支持): 仅苹果应用内支付(IAP)支持:需在itunesconnect上添加商品并配置好才能请求成功。
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0, user-scalable=no"/>
<meta name="HandheldFriendly" content="true"/>
<meta name="MobileOptimized" content="320"/>
<title>In-App Purchase</title>
<script type="text/javascript" src="../js/common.js"></script>
<script type="text/javascript">var iap=null;var ids=['donation','donation6'];//应用内购项目function plusReady(){
// 获取支付通道
plus.payment.getChannels(function(channels){
for(var i in channels){
var channel=channels[i];
if(channel.id==='appleiap'){
iap=channel;
}
}
requestOrder();
},function(e){
console.log("获取支付通道失败:"+e.message);
});}
document.addEventListener('plusready',plusReady,false);// 获取订单function requestOrder(){
plus.nativeUI.showWaiting('检测支付环境...');
iap.requestOrder(ids,function(e){
plus.nativeUI.closeWaiting();
console.log('requestOrder success: '+JSON.stringify(e));
},function(e){
console.log('requestOrder failed: '+JSON.stringify(e));
plus.nativeUI.closeWaiting();
plus.nativeUI.confirm("错误信息:"+JSON.stringify(e),function(e){
if(e.index==0){
requestOrder();
}else{
back();
}
},'重新请求支付',['确定','取消']);
});}// 支付function pay(id){
plus.nativeUI.showWaiting('',{style:"black",background:"rgba(0,0,0,0)"});
plus.payment.request(iap, {productid:id}, function(result){
plus.nativeUI.closeWaiting();
plus.nativeUI.alert("支付成功:感谢你的支持,我们会继续努力完善产品。",function(){
back();
},"捐赠");
},function(e){
plus.nativeUI.closeWaiting();
plus.nativeUI.alert("错误信息:"+e.message,null,"支付失败:"+e.code);
});}
</script>
<link rel="stylesheet" href="../css/common.css" type="text/css" charset="utf-8"/>
</head>
<body>
<header id="header">
<div class="nvbt iback" onclick="back()"></div>
<div class="nvtt">In-App Purchase</div>
</header>
<div id="content" class="content">
<br/><br/>
<p class="des" style="font-size:16px;line-height:30px;margin: 0px .5em;">
DCloud 是W3C会员、中国HTML5产业联盟发起单位,致力于推进HTML5发展,构建HTML5生态。
</p>
<br/>
<strong>
支持HTML5开发工具HBuilder
</strong>
<div class="button" onclick="pay(ids[0])">
捐赠1元
</div>
<div class="button" onclick="pay(ids[1])">
捐赠6元
</div>
</div>
</body>
<script type="text/javascript" src="../js/immersed.js" ></script></html>
restoreComplateRequest
向IAP服务器请求已经购买的非消耗性商品和订阅商品
void pay.restoreComplateRequest(options, successCB);
说明:
注意:不能获取已购买的消耗性商品。
参数:
options: ( json ) 必选 请求参数
支持属性:"username"用户名称,可选项,请求支付时设置的username值。
successCB: ( IapRestoreComplateRequestCallback ) 必选 请求成功回调
返回值:
void : 无
平台支持:
Android - 2.2+ (不支持)
iOS - 5.0+ (支持): 仅苹果应用内支付(IAP)支持。
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0, user-scalable=no"/>
<meta name="HandheldFriendly" content="true"/>
<meta name="MobileOptimized" content="320"/>
<title>In-App Purchase</title>
<script type="text/javascript">var iap=null;function plusReady(){
// 获取支付通道
plus.payment.getChannels(function(channels){
for(var i in channels){
var channel=channels[i];
if(channel.id==='appleiap'){
iap=channel;
}
}
},function(e){
console.log("获取支付通道失败:"+e.message);
});}
document.addEventListener('plusready',plusReady,false);// 获取已购买商品(非消耗性商品和订阅商品)function restoreComplateRequest(){
plus.nativeUI.showWaiting('',{style:"black",background:"rgba(0,0,0,0)"});
iap.restoreComplateRequest({},function(results){
plus.nativeUI.closeWaiting();
for(var i in results){
alert('restoreComplateRequest['+i+']: '+JSON.stringify(results[i]));
}
});}
</script>
</head>
<body>
<button onclick="restoreComplateRequest()">获取已购买商品</button>
</body></html>
OrderStatementIAP
IAP订单数据对象
interface plus.payment.OrderStatementIAP {
attribute String productid;
attribute String username;
attribute String quantity;}
说明:
描述IAP商品订单信息,如标识、数量等。
属性:
productid: (String 类型 )商品的标识
username: (String 类型 )购买用户名称
quantity: (String 类型 )商品数量
PaymentResult
支付操作结果对象
interface plus.payment.PaymentResult {
attribute PaymentChannel channel;
attribute String tradeno;
attribute String description;
attribute String url;
attribute String signature;
attribute String rawdata;}
说明:
PaymentResult对象表示支付操作返回结果,用于确认支付操作成功。
属性:
channel: (PaymentChannel 类型 )支付通道对象
用于发起支付操作的支付通道对象。
平台支持
Android - 2.2+ (支持)
iOS - 5.0+ (支持)
tradeno: (String 类型 )交易编号信息
如果支付平台不支持此数据则返回undefined。
description: (Boolean 类型 )交易描述信息
如果支付平台不支持此数据则返回undefined。
url: (Boolean 类型 )查找支付交易信息地址
用于向支付平台查询交易信息,如果支付平台不支持此数据则返回undefined。
signature: (String 类型 )支付操作指纹信息
用于向支付平台查询支付订单信息,如果支付平台不支持此数据则返回undefined。
rawdata: (String 类型 )支付平台返回的原始数据
如果支付平台返回key-value类型字符串,则组合成符合JSON格式的字符串。
IAPProduct
IAP商品对象
interface plus.payment.IAPProduct {
attribute String productid;
attribute String price;
attribute String title;
attribute String description;}
说明:
描述IAP商品详细信息,如标识、价格、标题、描述信息等。
属性:
productid: (String 类型 )商品的标识
price: (String 类型 )商品的价格
title: (String 类型 )商品标题
description: (String 类型 )商品的描述信息
IAPProductInfo
购买IAP商品对象
interface plus.payment.IAPProductInfo {
attribute String productIdentifier;
attribute String quantity;}
说明:
描述购买的IAP商品详细信息,如标识、数量等。
属性:
productIdentifier: (String 类型 )商品的标识
quantity: (String 类型 )商品的数量
IAPTransaction
购买IAP商品交易信息对象
interface plus.payment.IAPTransaction {
attribute IAPProductInfo payment;
attribute String transactionDate;
attribute String transactionIdentifier;
attribute String transactionReceipt;
attribute String transactionState;}
说明:
描述购买的IAP商品交易详细信息,如购买商品信息、交易日期、订单标识等。
属性:
payment: (String 类型 )购买商品的信息
transactionDate: (String 类型 )购买商品的交易日期
transactionIdentifier: (String 类型 )购买商品的交易订单标识
transactionReceipt: (String 类型 )购买商品的交易收据
base64编码格式字符串数据。
transactionState: (String 类型 )购买商品的交易状态
可取值:"1"为支付成功;"2"为支付失败;"3"为支付已恢复。
ChannelsSuccessCallback
获取支付通道成功回调
void ChannelsSuccessCallback( channels ) {
// Get payment channels success code}
说明:
当获取支付通道列表成功时的回调函数,用于返回终端支持的支付通道列表。
参数:
channels: ( Array ) 必选 数组,系统支持的支付通道PaymentChannel列表
返回值:
void : 无
平台支持:
Android - 2.2+ (支持)
iOS - 5.0+ (支持)
IapRequestOrderSuccessCallback
请求支付商品列表回调方法
void onsuccess( results ) {
// Payment success code}
说明:
获取IAP商品列表信息成功时的回调函数,返回商品详细信息。
参数:
results: ( Array[ IAPProduct ] ) 必选 商品信息数据
返回值:
void : 无
平台支持:
Android - 2.2+ (不支持)
iOS - 5.0+ (支持)
IapRestoreComplateRequestCallback
请求已经购买的非消耗性商品和订阅商品回调方法
void onsuccess( results ) {
// Payment success code}
说明:
获取IAP商品列表信息成功时的回调函数,返回商品详细信息。
参数:
results: ( Array[ IAPTransaction ] ) 必选 已购买的非消耗性商品和订阅商品交易信息
返回值:
void : 无
平台支持:
Android - 2.2+ (不支持)
iOS - 5.0+ (支持)
PaymentSuccessCallback
支付操作成功回调
void PaymentSuccessCallback ( result ) {
// Payment success code}
说明:
当支付操作成功时的回调函数,用于返回支付操作的成功信息。
参数:
result : ( PaymentResult | IAPTransaction ) 必选 支付操作成功的信息
iOS平台使用IAP支付返回的数据类型为IAPTransaction。
返回值:
void : 无
平台支持:
Android - 2.2+ (支持)
iOS - 5.0+ (支持)
PaymentErrorCallback
支付操作失败回调
void PaymentErrorCallback( error ) {
// Payment error code}
说明:
当支付操作失败时的回调函数,用于返回支付操作失败的错误信息。
参数:
error: ( DOMException ) 必选 支付操作失败错误信息,可通过error.code获取错误代码,具体错误码有各支付通道定义
支付宝支付错误代码如下: 62000,客户端未安装支付通道依赖的服务; 62001,用户取消支付操作; 62002,此设备不支持支付; 62003,数据格式错误; 62004,支付账号状态错误; 62005,订单信息错误; 62006,支付操作内部错误; 62007,支付服务器错误; 62008,网络问题引起的错误; 62009,其它未定义的错误。 微信支付错误代码如下: -1,一般错误; -2,用户取消; -3,发送失败; -4,认证被否决; -5,不支持错误。
返回值:
void : 无
平台支持:
Android - 2.2+ (支持)
iOS - 5.0+ (支持)
Proximity模块管理设备距离传感器,可获取当前设备的接近距离信息,通过plus.proximity可获取设备距离传感管理对象。
方法:
getCurrentProximity: 获取当前设备的接近距离信息
watchProximity: 监听设备接近距离的变化
clearWatch: 关闭监听设备接近距离变化
回调方法:
ProximitySuccessCallback: 获取设备接近距离信息成功的回调函数
ProximityErrorCallback: 获取设备接近距离信息失败的回调函数
权限:
permissions
"Proximity": {
"description": "访问距离感应器信息"}
getCurrentProximity
获取当前设备的接近距离信息
void plus.proximity.getCurrentProximity( successCB, errorCB );
说明:
获取当前接近设备的距离信息,距离值单位为厘米。如果感应器无法获取准确的距离值,则在接近设备时返回0,否则返回Infinity。 获取成功则调用successCB回调函数返接近回距离值。获取失败则调用errorCB回调函数错误信息。
参数:
successCB: ( ProximitySuccessCallback ) 必选 获取距离信息成功回调函数
errorCB: ( ProximityErrorCallback ) 可选 获取距离信息失败回调函数
返回值:
void : 无
平台支持:
Android - 2.2+ (支持): 支持
iOS - 4.3+ (支持): 支持
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Proximity Example</title>
<script type="text/javascript" >// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );// 扩展API加载完毕,现在可以正常调用扩展APIfunction onPlusReady() {}function getProximity() {
plus.proximity.getCurrentProximity( function ( d ) {
alert( "Get distance success: "+d );
}, function ( e ) {
alert( "Error: "+e.message );
} );}
</script>
</head>
<body >
<input type='button' onclick='getProximity();' value='Proximity'/>
</body></html>
watchProximity
监听设备接近距离的变化
Number plus.proximity.watchProximity( changeCB, errorCB );
说明:
watchProximity将监听设备的接近距离信息变化事件,当接近距离发生变化时通过changeCB回调函数返回距离值。监听距离变化事件失败则通过errorCB回调函数返回错误信息。
参数:
changeCB: ( ProximitySuccessCallback ) 必选 设备接近距离变化时的回调函数
errorCB: ( ProximityErrorCallback ) 可选
监听设备接近距离变化事件失败的回调函数
返回值:
Number : 用于标识接近距离变化事件监听器,可通过clearWatch方法取消监听。
平台支持:
Android - 2.2+ (支持): 支持
iOS - 4.3+ (支持): 支持
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Proximity Example</title>
<script type="text/javascript" >// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );// 扩展API加载完毕,现在可以正常调用扩展APIfunction onPlusReady() {
plus.proximity.watchProximity( function ( d ) {
document.getElementById("inf").innerText="Proximity: "+d;
}, function ( e ) {
alert( "Error: " + e.message );
} ); }
</script>
</head>
<body >
Proximity watch<br/>
<span id="inf"></span>
</body></html>
clearWatch
关闭监听设备接近距离变化
void plus.proximity.clearWatch( watchId );
参数:
watchId: ( Number ) 必选
需要取消的距离监听器标识,调用watchProximity方法的返回值。
返回值:
void : 无
平台支持:
Android - 2.2+ (支持): 支持
iOS - 4.3+ (支持): 支持
ProximitySuccessCallback
获取设备接近距离信息成功的回调函数
void onSuccess( distance ) {
// Get distance success code.}
参数:
distance: ( Number ) 必选 设备接近距离
设备接近距离传感器获取的距离值,单位为厘米。如果感应器无法获取准确的距离值,则在接近设备时返回0,否则返回Infinity。
返回值:
void : 无
ProximityErrorCallback
获取设备接近距离信息失败的回调函数
void onError( error ) {
// Get distance error code.}
参数:
error: ( DOMException ) 必选 失败信息
返回值:
void : 无
Push
Push模块管理推送消息功能,可以实现在线、离线的消息推送,通过plus.push可获取推送消息管理对象。
方法:
addEventListener: 添加推送消息事件监听器
clear: 清空所有推送消息
createMessage: 创建本地消息
getAllMessage: 获取所有推送消息
getClientInfo: 获取客户端推送标识信息
setAutoNotification: 设置程序是否将消息显示在系统消息中心
remove: 删除推送消息
对象:
ClientInfo: JSON对象,获取的客户端标识信息
PushMessage: JSON对象,推送消息对象
MessageOptions: JSON对象,获客户端创建本地消息的参数
回调方法:
PushReceiveCallback: 客户端接收到推动消息的回调函数
PushClickCallback: 用户点击推送消息事件的回调函数
权限:
permissions
"Push": {
"description": "访问推送插件"}
属性:
cover: 设定显示推送消息的模式
可取值true或false,true表示推送消息覆盖模式显示,即仅显示最后接收到的推送消息;false表示在系统消息中心显示多条消息。 默认值为ture。
平台支持
Android - 2.2+ (支持)
iOS - 4.3+ (不支持): 不支持覆盖消息,每条信息都在系统消息中心,忽略cover属性值。
addEventListener
添加推送消息事件监听器
void plus.push.addEventListener( event, listener, Boolean );
说明:
添加推送消息事件监听器,当指定推送事件发出时触发。
参数:
type: ( String ) 必选 事件类型
支持事件类型:"click"-从系统消息中心点击消息启动应用事件;"receive"-应用从推送服务器接收到推送消息事件。
listener: ( PushReceiveCallback ) 必选 事件监听器回调函数,在接收到推送消息时调用
capture: ( Boolean ) 可选 是否捕获事件,此处可忽略
返回值:
void : 无
平台支持:
Android - 2.2+ (支持)
iOS - 4.3+ (支持): 在客户端在运行时收到推送消息触发receive事件,离线接收到的推送消息全部进入系统消息中心。
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0, user-scalable=no"/>
<title>Push Example</title>
<script type="text/javascript">// 监听plusready事件
document.addEventListener( "plusready", function(){
// 扩展API加载完毕,现在可以正常调用扩展API
// 添加监听从系统消息中心点击某条消息启动应用事件
plus.push.addEventListener( "click", function ( msg ) {
// 分析msg.payload处理业务逻辑
alert( "You clicked: " + msg.content );
}, false ); }, false );
</script>
</head>
<body>
</body></html>
clear
清空所有推送消息
void plus.push.clear();
说明:
清空系统消息中心所有的推送消息。
参数:
无
返回值:
void : 无
createMessage
创建本地消息
void plus.push.createMessage( content, payload, option );
说明:
在本地直接创建推送消息,并添加到系统消息中心。
参数:
content: ( String ) 必选
消息显示的内容,在系统通知中心中显示的文本内容。
payload: ( String ) 可选
消息承载的数据,可根据业务逻辑自定义数据格式。
option: ( MessageOptions ) 可选
创建消息的额外参数,参考MessageOptions。
返回值:
void : 无
getAllMessage
获取所有推送消息
PushMessage[] plus.push.getAllMessage();
说明:
获取客户端接收到的所有推送消息。 仅包括在系统消息中心显示的推送消息,不包括调用setAutoNotification(false)方法设置不显示推送消息后接收到的消息。
参数:
无
返回值:
PushMessage : Array[PushMessage]对象,推送消息PushMessage数组。
平台支持:
Android - 2.2+ (支持)
iOS - 4.3+ (不支持): 无法获取系统消息中心的消息列表,调用此方法返回空数组。
getClientInfo
获取客户端推送标识信息
ClientInfo plus.push.getClientInfo();
说明:
客户端标识信息用于业务服务器下发推送消息时提交给推送服务器的数据,用于说明下发推送消息的接收者(客户端)。需要客户端在第一次运行时提交到业务服务器保存。
参数:
无
返回值:
ClientInfo : 客户端推送标识信息对象
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0, user-scalable=no"/>
<title>Push Example</title>
<script type="text/javascript">// 监听plusready事件
document.addEventListener( "plusready", function(){
// 扩展API加载完毕,现在可以正常调用扩展API
// 获取客户端标识信息
var info = plus.push.getClientInfo();
alert( JSON.stringify( info ) );
// 添加监听从系统消息中心点击消息启动事件
plus.push.addEventListener( "click", function ( msg ) {
// 分析msg.payload处理业务逻辑
alert( "You clicked: " + msg.content );
}, false ); }, false );
</script>
</head>
<body>
</body></html>
setAutoNotification
设置程序是否将消息显示在系统消息中心
void plus.push.setAutoNotification( notify );
说明:
默认情况下程序在接收到推送消息后将会在系统消息中心显示,通过此方法可关闭默认行为,接收到推送消息后不在系统消息中心显示,通过addEventListener方法的“receive”事件监听处理接收到的消息。 在这种模式下可通过createMessage方法创建在系统消息中心显示的消息。
参数:
notify: ( Boolean ) 必选 是否自动提示推送消息
可取值true或false,true表示自动显示推送消息,false则不显示。默认值为true。
返回值:
void : 无
平台支持:
Android - 2.2+ (支持): 如果程序没有运行时接收到推送消息,则在程序启动后调用addEventListener方法监听“receive”事件时返回接收到的消息。 注意:个推平台仅透传消息才支持此功能,其它消息依然会显示到系统消息中心。
iOS - 4.3+ (不支持): 无法修改是否显示离线推送消息,当程序在前台运行时接收到消息时一定不会添加到系统消息中心,当程序在不再前台运行时一定会添加到系统消息中。
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0, user-scalable=no"/>
<title>Push Example</title>
<script type="text/javascript">// 监听plusready事件
document.addEventListener( "plusready", function(){
// 扩展API加载完毕,现在可以正常调用扩展API
// 在程序运行时接收到的消息不显示在系统消息中心
plus.push.setAutoNotification( false );}, false );
</script>
</head>
<body>
</body></html>
remove
删除推送消息
void plus.push.remove( message )
说明:
删除系统消息中心指定的推送消息,可通过getAllMessage方法获取所有的消息后进行操作。
参数:
message: ( PushMessage ) 必选 要删除的消息对象,可通过getAllMessage()方法来获取消息。
返回值:
void : 无
平台支持:
Android - 2.2+ (支持)
iOS - 4.3+ (不支持): 无法对单条消息进行删除操作,可调用clear()方法清空所有消息。
ClientInfo
JSON对象,获取的客户端标识信息
属性:
token: (String 类型 )设备令牌(iOS设备唯一标识),用于APNS服务推送中标识设备的身份
平台支持
Android - 2.2+ (支持): 设备的唯一标识号,通常与clientid值一致。
iOS - 4.5+ (支持): 设备的DeviceToken值,向APNS服务器发送推送消息时使用。
clientid: (String 类型 )推送服务令牌(设备唯一标识),用于标识推送信息接收者身份
第三方推送服务器管理的设备唯一标识,在iOS平台此值通常与token不同;在其它平台此值通常与token值一致。
appid: (String 类型 )第三方推送服务的应用标识
第三方推送服务器管理的应用标识,通常需要在第三方推送服务器平台进行注册获取。
appkey: (String 类型 )第三方推送服务器的应用键值
第三方推送服务器管理的应用键值,通常需要在第三方推送服务器平台进行注册获取。
PushMessage
JSON对象,推送消息对象
属性:
title: (String 类型 )推送消息显示的标题
平台支持
Android - 2.2+ (支持)
iOS - ALL (支持): 。
content: (String 类型 )推送消息显示的内容
payload: (JSON 类型 )推送消息承载的数据
如果推送消息中传输的数据不符合JSON格式,则作为String类型数据保存。
aps: (JSON 类型 )Apple APNS推送协议数据
平台支持
Android - 2.2+ (不支持): 不支持此数据,返回值为undefined。
iOS - 5.0+ (支持): 仅封装标准APNS协议中的数据,其它数据封装在payload中。如果是通过本地API创建的消息此属性值则为undefined。
MessageOptions
JSON对象,获客户端创建本地消息的参数
属性:
title: (String 类型 )推送消息的标题
在系统消息中心显示的通知消息标题,默认值为程序的名称。
平台支持
Android - ALL (支持)
iOS - 5.0+ (不支持): 不支持设置消息的标题,固定为程序的名称。
sound: (String 类型 )推送消息的提示音
显示消息时的播放的提示音,可取值: “system”-表示使用系统通知提示音; “none”-表示不使用提示音; 默认值为“system”。
平台支持
Android - 2.3+ (支持)
iOS - 5.1+ (支持): 当程序在前台运行时,提示音不生效。 注:通常应该设置延迟时间,当程序切换到后台才创建本地推送消息时生效。
cover: (Boolean 类型 )是否覆盖上一次提示的消息
可取值true或false,true为覆盖,false不覆盖,默认为permission中设置的cover值。
平台支持
Android - ALL (支持)
iOS - 5.0+ (不支持): 不支持覆盖消息,只能创建新的消息。
when: (Date 类型 )消息上显示的提示时间
默认为当前时间,如果延迟显示则使用延时后显示消息的时间。
平台支持
Android - ALL (支持)
iOS - 5.0+ (不支持): 不支持设定消息的显示时间,由系统自动管理消息的创建时间。
delay: (Number 类型 )提示消息延迟显示的时间
当设备接收到推送消息后,可不立即显示,而是延迟一段时间显示,延迟时间单位为s,默认为0s,立即显示。
平台支持:
Android - 2.2+ (支持)
iOS - 4.3+ (支持): 不支持title、cover、when属性,忽略其属性值。
PushReceiveCallback
客户端接收到推动消息的回调函数
void onReceive( msg ) {
// Recieved push message code.}
参数:
msg: ( String ) 必选 接收到的推送信息msg
返回值:
void : 无
PushClickCallback
用户点击推送消息事件的回调函数
void onClick( msg ) {
// Clicked push message code. }
参数:
msg: ( String ) 必选 用户点击的推送信息msg
返回值:
void : 无
Runtime
Runtime模块管理运行环境,可用于获取当前运行环境信息、与其它程序进行通讯等。通过plus.runtime可获取运行环境管理对象。
属性:
appid: 当前应用的APPID
arguments: 第三方程序调用时传递给程序的参数
launcher: 应用启动来源
origin: 应用安装来源
version: 客户端的版本号
innerVersion: 客户端5+运行环境的版本号
launchLoadedTime: 获取当前应用首页加载的时间
方法:
getProperty: 获取指定APPID对应的应用信息
install: 安装应用
quit: 退出客户端程序
restart: 重启当前的应用
setBadgeNumber: 设置程序快捷方式上显示的提示数字
openURL: 调用第三方程序打开指定的URL
openFile: 调用第三方程序打开指定的文件
launchApplication: 调用第三方程序
对象:
WidgetOptions: JSON对象,应用安装参数
WidgetInfo: JSON对象,应用信息
OpenFileOption: JSON对象,打开文件参数
ApplicationInf: JSON对象,打开第三方程序参数
回调方法:
InstallSuccessCallback: 安装应用成功回调函数
InstallErrorCallback: 安装应用失败回调函数
GetPropertyCallBack: 获取应用属性成功回调函数
OpenErrorCallback: 打开本地文件或URL失败回调函数
LaunchErrorCallback: 调用第三方程序失败回调函数
权限:
permissions
"Runtime": {
"description": "访问运行环境信息"}
appid
当前应用的APPID
plus.runtime.appid;
说明:
String 类型 只读属性
当前应用的APPID,字符串类型。注意,如果是在HBuilder真机运行获取的是固定值“HBuilder”,需要提交App云端打包后运行才能获取真实的APPID值。
平台支持:
Android - 2.2+ (支持)
iOS - 4.3+ (支持)
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Runtime Example</title>
<script type="text/javascript">// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );// 扩展API加载完毕,现在可以正常调用扩展APIfunction onPlusReady() {
// 处理第三方传入的参数
alert( "Current APP: " + plus.runtime.appid );}
</script>
</head>
<body>
当前应用的APPID
</body></html>
arguments
第三方程序调用时传递给程序的参数
plus.runtime.arguments;
说明:
String 类型 只读属性
第三方程序传递过来的参数,字符串格式类型数据。 不是由第三方程序调用启动,则返回空字符串。
平台支持:
Android - 2.2+ (支持): 把第三方传递过来的参数组合成JSON格式字符串,如“{"name":"XiaoMing","password":"123456"}”。
iOS - 4.3+ (支持): 把第三方传递过来的参数,去掉前缀,如“name=XiaoMing&password=”,建议第三方程序传递JSON格式字符串。
示例:
<!DOCTYPE html><html><head>
<meta charset="utf-8">
<title>Runtime Example</title>
<script type="text/javascript">// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );// 扩展API加载完毕,现在可以正常调用扩展APIfunction onPlusReady() {
// 处理第三方传入的参数
if ( plus.runtime.arguments != "" ) {
try {
var aj = JSON.parse( plus.runtime.arguments );
// 处理JSON对象aj
}catch( e ) {
// 若传入的参数不是JSON格式字符,需处理异常情况
}
}}
</script></head><body>
第三方程序调用时传递给程序的参数</body></html>
launcher
应用启动来源
plus.runtime.launcher;
说明:
String 类型 只读属性
5+ APP启动类型,可取以下值: "default":默认启动方式,通常表示应用列表启动(360手助中搜索启动); "scheme":通过urlscheme方式触发启动; "push":通过点击系统通知方式触发启动; "stream":通过流应用api(plus.stream.open)启动; "shortcut":通过快捷方式启动,iOS平台表示通过3D Touch快捷方式,Android平台表示通过桌面快捷方式启动; "barcode":通过二维码扫描启动。
平台支持:
Android - 2.2+ (支持): "shortcut"表示通过桌面快捷方式启动。
iOS - 5.1+ (支持): "shortcut"表示通过3D Touch弹出的快捷方式启动。
360手助流应用 - 5.0+ (支持): 在360手机助手中,从推荐或搜索列表中启动时,启动方式为"default"。
origin
应用安装来源
plus.runtime.origin;
说明:
String 类型 只读属性
5+应用安装来源,可取以下值: "default":默认安装来源,apk/ipa安装包内置安装; "stream":通过流应用api(plus.stream.open)安装,仅流应用环境下支持; "push":通过点击系统通知方式触发安装,仅流应用环境下支持; "scheme":通过urlscheme方式触发安装,仅流应用环境下支持; "barcode":通过二维码扫描触发安装,仅流应用环境下支持。
version
客户端的版本号
plus.runtime.version;
说明:
String 类型 只读属性
字符串类型,在编译环境中设置的apk/ipa版本号。
平台支持:
Android - 2.2+ (支持)
iOS - 4.3+ (支持)
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Runtime Example</title>
<script type="text/javascript">// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );// 扩展API加载完毕,现在可以正常调用扩展APIfunction onPlusReady() {
// 获取apk/ipa版本号
alert( "Application(apk/ipa) version: " + plus.runtime.version );}
</script>
</head>
<body>
客户端(apk/ipa)的版本号
</body></html>
innerVersion
客户端5+运行环境的版本号
plus.runtime.innerVersion;
说明:
String 类型 只读属性
5+运行环境版本号,格式为:[主版本号].[次版本号].[修订版本号].[编译代号]。
平台支持:
Android - 2.2+ (支持)
iOS - 4.3+ (支持)
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Runtime Example</title>
<script type="text/javascript">// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );// 扩展API加载完毕,现在可以正常调用扩展APIfunction onPlusReady() {
// 获取5+运行环境的版本号
alert( "5+ Runtime version: " + plus.runtime.innerVersion );}
</script>
</head>
<body>
5+运行环境的版本号
</body></html>
launchLoadedTime
获取当前应用首页加载的时间
plus.runtime.launchLoadedTime;
说明:
Number 类型 只读属性
应用加载首页面的总时间,从开始加载首页面到首页面加载完成,单位为ms。 注意,应用首页为网络地址则包括网络传输时间。
平台支持:
Android - 2.2+ (支持)
iOS - 4.3+ (支持)
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Runtime Example</title>
<script type="text/javascript">// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );// 扩展API加载完毕,现在可以正常调用扩展APIfunction onPlusReady() {
// 处理第三方传入的参数
alert( "首页加载时间: " + plus.runtime.launchLoadedTime + "ms" );}
</script>
</head>
<body>
获取当前应用首页加载的时间
</body></html>
getProperty
获取指定APPID对应的应用信息
void plus.runtime.getProperty( appid, getPropertyCB );
参数:
appid: ( String ) 必选 应用的Appid
getPropertyCB: ( GetPropertyCallBack ) 必选 获得应用信息成功回调函数
返回值:
void : 无
平台支持:
Android - 2.2+ (支持): 支持
iOS - 4.3+ (支持): 支持
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Runtime Example</title>
<script type="text/javascript">// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );// 扩展API加载完毕,现在可以正常调用扩展APIfunction onPlusReady() {}// 获取应用信息function getAppInfo() {
plus.runtime.getProperty( plus.runtime.appid, function ( wgtinfo ) {
//appid属性
var wgtStr = "appid:"+wgtinfo.appid;
//version属性
wgtStr += "<br/>version:"+wgtinfo.version;
//name属性
wgtStr += "<br/>name:"+wgtinfo.name;
//description属性
wgtStr += "<br/>description:"+wgtinfo.description;
//author属性
wgtStr += "<br/>author:"+wgtinfo.author;
//email属性
wgtStr += "<br/>email:"+wgtinfo.email;
//licence属性
wgtStr += "<br/>license:"+wgtinfo.license;
//licensehref属性
wgtStr += "<br/>licensehref:"+wgtinfo.licensehref;
//features 属性
wgtStr += "<br/>features:"+wgtinfo.features;
console.log( wgtStr );
} );}
</script>
</head>
<body>
获取应用信息
<br/>
<button onclick="getAppInfo()">AppInfo</button>
</body></html>
install
安装应用
void plus.runtime.install( wgtFilePath, options, installSuccessCB, installErrorCB);
说明:
支持以下类型安装包: 1. 应用资源安装包(wgt),扩展名为'.wgt'; 2. 应用资源差量升级包(wgtu),扩展名为'.wgtu'; 3. 系统程序安装包,要求使用当前平台支持的安装包格式。 注意:仅支持本地地址,调用此方法前需把安装包从网络地址或其他位置放置到运行时环境可以访问的本地目录。
参数:
wgtFilePath: ( String ) 必选 要安装的文件路径
应用安装文件或基座安装文件(扩展名为'.wgt')
options: ( WidgetOptions ) 可选
应用安装设置的参数
installSuccessCB: ( InstallSuccessCallback ) 可选
正确安装后的回调
installErrorCB: ( InstallErrorCallback ) 可选
安装失败的回调
返回值:
void : 无
平台支持:
Android - 2.2+ (支持): 可支持apk包的安装
iOS - 4.3+ (支持): 不支持ipa包的安装
quit
退出客户端程序
void plus.runtime.quit();
参数:
无
返回值:
void : 无
平台支持:
Android - 2.2+ (支持): 支持
iOS - 4.3+ (支持): 5+APP:不支持此功能,调用后无任何作用,只能通过设备的Home键退出应用; 流应用:在“流应用”中调用则退出流应用,返回应用列表界面。
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Runtime Example</title>
<script type="text/javascript">// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );// 扩展API加载完毕,现在可以正常调用扩展APIfunction onPlusReady() {
plus.key.addEventListener( "backbutton", onKeyBack, false );}function onKeyBack() {
plus.runtime.quit();}
</script>
</head>
<body>
</body></html>
restart
重启当前的应用
void plus.runtime.restart();
参数:
无
返回值:
void : 无
平台支持:
Android - 2.2+ (支持): 支持
iOS - 4.3+ (支持): 支持
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Runtime Example</title>
<script type="text/javascript">// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );// 扩展API加载完毕,现在可以正常调用扩展APIfunction onPlusReady() {}// 重启当前的应用function restartApp() {
plus.runtime.restart();}
</script>
</head>
<body>
重启当前的应用
<br/>
<button onclick="restartApp()">Restart</button>
</body></html>
setBadgeNumber
设置程序快捷方式上显示的提示数字
void plus.runtime.setBadgeNumber( number );
参数:
number: ( String ) 必选
在快捷方式上显示的数字,参数为0则表示清除提示数字。
返回值:
void : 无
平台支持:
Android - 2.2+ (支持): 目前仅支持小米(MIUI v5),其它设备调用后无任何效果。
iOS - 4.3+ (支持): 应用需开启“Push Notifications”服务才生效。
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Runtime Example</title>
<script type="text/javascript">// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );// 扩展API加载完毕,现在可以正常调用扩展APIfunction onPlusReady() {}// 设置数字function setBadge() {
plus.runtime.setBadgeNumber(8);}// 清除数字function clearBadge() {
plus.runtime.setBadgeNumber(0);}
</script>
</head>
<body>
设置程序快捷方式上显示的提示数字
<br/>
<button onclick="setBadge()">Set</button>
<br/>
<button onclick="clearBadge()">Clear</button>
</body></html>
openURL
调用第三方程序打开指定的URL
void plus.runtime.openURL( url, errorCB, identity );
参数:
url: ( String ) 必选 要打开的URL地址
字符串类型,各平台支持的地址类型存在差异,参考平台URL支持表。
errorCB: ( OpenErrorCallback ) 可选 打开URL地址失败的回调
打开指定URL地址失败时回调,并返回失败信息。
identity: ( String ) 可选 指定打开URL地址的程序名称
在iOS平台此参数被忽略,在Android平台为程序包名,如果指定的包名不存在,则打开URL地址失败。
返回值:
void : 无
平台支持:
Android - 2.2+ (支持): 支持
iOS - 4.3+ (支持): 支持,不支持identity参数
openFile
调用第三方程序打开指定的文件
void plus.runtime.openFile( filepath, options, errorCB );
参数:
filepath: ( String ) 必选 打开文件的路径
字符串类型,文件路径必须是本地路径,否则会导致打开文件失败。
options: ( OpenFileOption ) 可选 打开文件参数
打开文件的参数,参考OpenFileOption对象。
errorCB: ( OpenErrorCallback ) 必选 打开文件失败的回调
打开文件操作失败时回调,返回失败信息。
返回值:
void : 无
平台支持:
Android - 2.2+ (支持): 支持
iOS - 4.3+ (支持): 支持
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Runtime Example</title>
<script type="text/javascript">// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );// 扩展API加载完毕,现在可以正常调用扩展APIfunction onPlusReady() {
}// 打开文件操作function testFile() {
plus.runtime.openFile( "_doc/a.pdf" );}
</script>
</head>
<body>
调用第三方程序打开文件
<br/>
<button onclick="testFile()">Open File</button>
</body></html>
launchApplication
调用第三方程序
void plus.runtime.launchApplication( appInf, errorCB );
参数:
appInf: ( ApplicationInf ) 必选 要启动第三方程序的描述信息
errorCB: ( LaunchErrorCallback ) 必选 启动第三方程序操作失败的回调函数
启动第三方程序失败时回调,并返回失败信息。
返回值:
void : 无
平台支持:
Android - 2.2+ (支持): 支持
iOS - 4.3+ (支持): 支持
示例:
<!DOCTYPE html><html><head><meta charset="utf-8"><title>Runtiem Example</title><script type="text/javascript">// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );// 扩展API加载完毕,现在可以正常调用扩展APIfunction onPlusReady() {
}// 调用第三方程序function launchApp() {
if ( plus.os.name == "Android" ) {
plus.runtime.launchApplication( {pname:"com.android.browser"
,extra:{url:"http://www.html5plus.org"}}, function ( e ) {
alert( "Open system default browser failed: " + e.message );
} );
} else if ( plus.os.name == "iOS" ) {
plus.runtime.launchApplication( {action:"http://www.html5plus.org"}, function ( e ) {
alert( "Open system default browser failed: " + e.message );
} );
}}</script></head><body>
调用第三方程序
<br/>
<button onclick="launchApp()">Launch Application</button></body></html>
WidgetOptions
JSON对象,应用安装参数
说明:
可通过对象设置安装的应用是否进行appid校验、版本号校验等。
属性:
force: (Boolean 类型 )是否强制安装
true表示强制安装,不进行版本号的校验;false则需要版本号校验,如果将要安装应用的版本号不高于现有应用的版本号则终止安装,并返回安装失败。 仅安装wgt和wgtu时生效,默认值 false。
平台支持:
Android - 2.2+ (支持): 支持
iOS - 4.3+ (支持): 支持
示例:
var options = {
force: true};
WidgetInfo
JSON对象,应用信息
属性:
appid: (String 类型 )应用的APPID
version: (String 类型 )应用的版本号
name: (String 类型 )应用的名称
description: (String 类型 )应用描述信息
author: (String 类型 )应用描述信息
email: (String 类型 )开发者邮箱地址
license: (String 类型 )应用授权描述信息
licensehref: (String 类型 )应用授权说明链接地址
features: (String[] 类型 )应用许可特性列表
平台支持:
Android - 2.2+ (支持): 支持
iOS - 4.3+ (支持): 支持
示例:
var wInfo = {
appid: "B8B4BD",
version: "1.0",
name: "测试应用"};
OpenFileOption
JSON对象,打开文件参数
属性:
popover: (json 类型 )弹出系统选择程序界面指示区域
JSON对象,格式如{top:10;left:10;200;height:200;},所有值为像素值,左上坐标相对于容器webview的位置。仅在iPad设备平台有效。
ApplicationInf
JSON对象,打开第三方程序参数
属性:
pname: (String 类型 )第三方程序包名
仅Android平台支持,表示程序的包名,其它平台忽略此属性值。
平台支持
Android - 2.2+ (支持): 第三方程序的包名,如“io.dclould.HelloH5”。
iOS - 4.3+ (支持): 忽略此属性值。
action: (String 类型 )程序的操作行为
Android平台上与系统的action值一致;iOS平台为要调用程序的URLScheme格式字符串。
平台支持
Android - 2.2+ (支持): 第三方程序的操作行为,与系统的action值完全一致。
iOS - 4.3+ (支持): 要调用程序的URLScheme格式字符串。
extra: (JSON 类型 )调用程序的参数
仅Android平台支持,为JSON格式,用于传递给要调用程序的参数,如extra:{url:"http://www.html5plus.org"}。
平台支持
Android - 2.2+ (支持): 传递给第三方程序的参数,必须是JSON格式数据,如“{'name':'value','name2':'value2'}”。
iOS - 4.3+ (支持): 忽略此属性值。
InstallSuccessCallback
安装应用成功回调函数
void onSuccess(widgetInfo){
// Code here}
参数:
widgetInfo: ( WidgetInfo ) 必选
应用信息,参见:WidgetInfo
返回值:
void : 无
平台支持:
Android - 2.2+ (支持): 支持,如安装文件为APK,则不触发此回调函数
iOS - 4.3+ (支持): 支持
InstallErrorCallback
安装应用失败回调函数
void onError(error){
// Handle the error}
参数:
error: ( DOMException ) 必选
安装失败的错误信息
返回值:
void : 无
平台支持:
Android - 2.2+ (支持): 支持
iOS - 4.3+ (支持): 支持
GetPropertyCallBack
获取应用属性成功回调函数
void onGetPropertyCB(widgetInfo){
// Code here}
参数:
widgetInfo: ( WidgetInfo ) 必选
应用信息,参见:WidgetInfo
返回值:
void : 无
平台支持:
Android - 2.2+ (支持): 支持
iOS - 4.3+ (支持): 支持
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Runtime Example</title>
<script type="text/javascript">// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );// 扩展API加载完毕,现在可以正常调用扩展APIfunction onPlusReady() {}// 获取应用信息function getAppInfo() {
plus.runtime.getProperty( plus.runtime.appid, function ( wgtinfo ) {
//appid属性
var wgtStr = "appid:"+wgtinfo.appid;
//version属性
wgtStr += "<br/>version:"+wgtinfo.version;
//name属性
wgtStr += "<br/>name:"+wgtinfo.name;
//description属性
wgtStr += "<br/>description:"+wgtinfo.description;
//author属性
wgtStr += "<br/>author:"+wgtinfo.author;
//email属性
wgtStr += "<br/>email:"+wgtinfo.email;
//licence属性
wgtStr += "<br/>license:"+wgtinfo.license;
//licensehref属性
wgtStr += "<br/>licensehref:"+wgtinfo.licensehref;
//features 属性
wgtStr += "<br/>features:"+wgtinfo.features;
console.log( wgtStr );
} );}
</script>
</head>
<body>
获取应用信息
<br/>
<button onclick="getAppInfo()">AppInfo</button>
</body></html>
OpenErrorCallback
打开本地文件或URL失败回调函数
void onError(error){
// Handle the error}
参数:
error: ( DOMException ) 必选
打开操作失败的错误信息
返回值:
void : 无
平台支持:
Android - 2.2+ (支持): 支持
iOS - 4.3+ (支持): 支持
LaunchErrorCallback
调用第三方程序失败回调函数
void onError(error){
// Handle the error}
参数:
error: ( DOMException ) 必选
操作失败的错误信息
返回值:
void : 无
平台支持:
Android - 2.2+ (支持): 支持
iOS - 4.3+ (支持): 支持
Share
Share模块管理客户端的社交分享功能,提供调用终端社交软件的分享能力。通过plus.share可获取社交分享管理对象。
方法:
getServices: 获取分享服务
对象:
ShareService: 分享服务对象
ShareServerIdentity: 分享服务标识
ShareMessage: JSON对象,分享消息对象
GeoPosition: JSON对象,用户位置信息
ShareMessageExtra: JSON对象,保存分享消息扩展信息
Authorize: 分享授权控件对象
回调方法:
ServicesSuccessCallback: 获取分享服务成功回调
AuthorizeSuccessCallback : 分享消息成功回调
ShareSuccessCallback : 分享操作成功回调
ShareErrorCallback : 分享操作失败回调
权限:
permissions
"Share": {
"description": "访问分享插件"}
getServices
获取分享服务
void plus.share.getServices( successCB, errorCB );
说明:
获取终端支持的分享通道列表,可用于提示用户进行分享服务器的选择。获取分享服务成功后通过successCB回调返回支持的所有服务列表,获取服务失败则通过errorCB回调返回。
参数:
successCB: ( ServicesSuccessCallback ) 必选 获取分享服务成功回调
获取分享服务列表成功时的回调函数,用于返回终端支持的分享服务列表。
errorCB: ( ShareErrorCallback ) 可选 获取分享服务失败回调
获取分享服务列表失败时的回调函数,用于返回错误信息。
返回值:
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>Share Example</title>
<script type="text/javascript">var shares=null;// 监听plusready事件
document.addEventListener( "plusready", function(){
// 扩展API加载完毕,现在可以正常调用扩展API
plus.share.getServices( function(s){
shares = s;
}, function(e){
alert( "获取分享服务列表失败:"+e.message );
} );}, false );
</script>
</head>
<body>
</body></html>
ShareService
分享服务对象
interface plus.share.ShareService {
// Attributes
attribute DOMString id;
attribute DOMString description;
attribute Boolean authenticated;
attribute DOMString accessToken;
attribute Boolean nativeClient;
// Methods
function void authorize( successCallback, errorCallback );
function void forbid();
function void send( message );}
说明:
ShareService对象用于表示分享服务,在JS中为对象,用于向系统请求分享操作。
属性:
id: 分享服务标识
description: 分享服务描述
authenticated: 是否授权认证
accessToken: 授权认证信息
nativeClient: 是否存在对应的分享客户端
方法:
authorize: 授权认证操作
forbid: 取消授权认证
send: 发送分享
id
分享服务标识
说明:
ShareServerIdentity 类型 只读属性
用于表示分享服务标识,如“sinaweibo”表示新浪微博、“tencentweibo”表示腾讯微博、“weixin”表示微信、“qq”表示腾讯QQ。
description
分享服务描述
说明:
DOMString 类型 只读属性
用于描述分享服务的信息,如“新浪微博”、“腾讯微博”、“微信”、“QQ”。
authenticated
是否授权认证
说明:
Boolean 类型 只读属性
用于标识此分享是否已经授权认证过,true表示已完成授权认证;false表示未完成授权认证。
accessToken
授权认证信息
说明:
DOMString 类型 只读属性
仅在authenticated为true时有效,标识客户认证标识信息,用于发送分享信息。
nativeClient
是否存在对应的分享客户端
说明:
Boolean 类型 只读属性
对于某些分享服务,可直接调用本地客户端程序进行授权认证,此属性即可提供此相关信息,若没有安装本地客户端则可能调用其它方式进行分享操作,如WAP方式等。
authorize
授权认证操作
void obj.authorize( successCB, errorCB );
说明:
对指定的分享服务进行授权认证操作,在授权前可通过ShareService.authenticated属性判断是否已经授权过,通常只需要对没有进行过授权认证的服务进行授权认证操作。授权认证操作成功后通过successCB回调函数通知操作完成,操作失败则通过errorCB回调返回。
参数:
successCB: ( AuthorizeSuccessCallback ) 必选 分享服务授权认证成功回调
分享服务授权认证操作成功时的回调函数,用于返回分享授权操作成功信息。
errorCB: ( ShareErrorCallback ) 可选 分享服务授权认证失败回调
分享服务授权认证操作失败时的回调函数,用于返回错误信息。
返回值:
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>Share Example</title>
<script type="text/javascript">var shares=null;// 监听plusready事件
document.addEventListener( "plusready", function(){
// 扩展API加载完毕,现在可以正常调用扩展API
plus.share.getServices( function(s){
shares = s;
}, function(e){
alert( "获取分享服务列表失败:"+e.message );
} );}, false );function shareAction(){
var s = shares[0];
if ( !s.authenticated ) {
s.authorize( functioin(){
alert( "认证完成!" );
}, function(e){
outLine( "未进行认证" );
} )
}}
</script>
</head>
<body>
</body></html>
forbid
取消授权认证
void obj.forbid();
说明:
对指定的分享服务取消授权认证操作,取消授权认证后,再次分享时需重新进行授权操作。
参数:
返回值:
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>Share Example</title>
<script type="text/javascript">var shares=null;// 监听plusready事件
document.addEventListener( "plusready", function(){
// 扩展API加载完毕,现在可以正常调用扩展API
plus.share.getServices( function(s){
shares = s;
}, function(e){
alert( "获取分享服务列表失败:"+e.message );
} );}, false );// 取消所有分享服务的function cancelAuthorize(){
for ( var i in shares ) {
var s = shares[i];
if ( s.authenticated ) {
s.forbid();
}
}}
</script>
</head>
<body>
</body></html>
send
发送分享
void obj.send( msg, successCB, errorCB );
说明:
发送分享消息,分享消息的内容通过msg设置。发送成功后通过successCB回调函数通知操作完成,发送失败则通过errorCB回调返回。若分享服务没有进行授权认证或授权认证失效则触发失败回调函数。
参数:
msg: ( ShareMessage ) 必选 要发送的分享消息对象
用于设置要分享的消息内容,如文字内容,图片等信息。
successCB: ( ShareSuccessCallback ) 必选 发送分享消息成功回调
发送分享消息操作成功时的回调函数,用于返回发送分享消息操作成功信息。
errorCB: ( ShareErrorCallback ) 可选 发送分享消息失败回调
发送分享消息操作失败时的回调函数,用于返回错误信息。
返回值:
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>Share Example</title>
<script type="text/javascript">var shares=null;// 监听plusready事件
document.addEventListener( "plusready", function(){
// 扩展API加载完毕,现在可以正常调用扩展API
plus.share.getServices( function(s){
shares = s;
}, function(e){
alert( "获取分享服务列表失败:"+e.message );
} );}, false );/**
* 分享操作
* @param {plus.share.ShareService} s
*/function shareAction(s) {
if ( !s ) {
return;
}
if ( s.authenticated ) {
shareMessage( s );
} else {
s.authorize( shareMessage, function(e){
alert( "未进行认证" );
} )
}}/**
* 发送分享消息
* @param {plus.share.ShareService} s
*/function shareMessage(s){
s.send( {content:"Hello"}, function(){
alert( "分享成功!" );
}, function(e){
alert( "分享失败:"+e.message );
} );}
</script>
</head>
<body>
</body></html>
ShareServerIdentity
分享服务标识
常量:
"sinaweibo": (DOMString 类型 )新浪微博
"tencentweibo": (DOMString 类型 )腾讯微博
"weixin": (DOMString 类型 )微信
ShareMessage
JSON对象,分享消息对象
interface plus.share.ShareMessage {
attribute String content;
attribute String[] thumbs;
attribute String[] pictures;
attribute String href;
attribute String title;
attribute JSON extra;
attribute GEOPosition geo;}
说明:
ShareMessage对象用于表示分享消息内容,在JS中为JSON对象,用于向系统发送分享信息操作。
属性:
content: (String 类型 )分享消息的文字内容
pictures: (String[] 类型 )分享消息的图片
分享消息中包含的图片路径,仅支持本地路径。 若分享平台仅支持提交一张图片,传入多张图片则仅提交第一张图片。 如果不能同时支持其它内容信息,优先级顺序为:pictures>content。
thumbs: (String[] 类型 )分享消息的缩略图
分享消息中包含的缩略图路径; 若分享平台仅支持提交一张图片,传入多张图片则仅提交第一张图片; 如果分享平台的信息不支持缩略图,若没有设置消息的图片(pictures)则使用缩略图,否则忽略其属性值。 注意:图片有大小限制,推荐图片小于20Kb。
平台支持
Android - 2.3+ (支持): 可支持网络图片路径。
iOS - 5.1+ (不支持): 不支持网络图片路径。
href: (String 类型 )分享独立的链接
分享独立链接地址,仅支持网络地址(以http://或https://开头)。 如果不能同时支持其它内容信息,优先级顺序为:href>pictures>content。
<!DOCTYPE html><html>
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0, user-scalable=no"/>
<title>Share Example</title>
<script type="text/javascript">var shares=null,sharewx=null;// 监听plusready事件
document.addEventListener( "plusready", function(){
// 扩展API加载完毕,现在可以正常调用扩展API
plus.share.getServices( function(s){
shares = s;
for(var i in s){
if('weixin'==s[i].id){
sharewx=s[i];
}
}
}, function(e){
alert( "获取分享服务列表失败:"+e.message );
} );}, false );function shareWeixinMessage(){
sharewx.send( {content:"DCloud HBuilder-做最好的HTML5开发工具",href:"http://www.dcloud.io/",extra:{scene:"WXSceneTimeline"}}, function(){
alert( "分享成功!" );
}, function(e){
alert( "分享失败:"+e.message );
});}
</script>
</head>
<body>
<button onclick="shareWeixinMessage()">分享链接到微信朋友圈</button>
</body></html>
title: (String 类型 )分享消息的标题
目前仅微信分享独立链接消息时支持。
geo: (GeoPosition 类型 )分享消息中包含的用户地理信息数据
extra: (ShareMessageExtra 类型 )分享消息扩展参数
GeoPosition
JSON对象,用户位置信息
interface plus.share.GeoPosition {
attribute Number latitude;
attribute Number longitude;}
说明:
GeoPosition对象用于表示用户分享消息时的位置信息。用于标识分享操作时用户的位置信息。
属性:
latitude: (Number 类型 )用户位置的纬度坐标信息
longitude: (Number 类型 )用户位置的经度坐标信息
ShareMessageExtra
JSON对象,保存分享消息扩展信息
interface plus.share.ShareMessageExtra {
attribute String scene;}
说明:
ShareMessageExtra对象用于保存各分享平台扩展的参数,用于自定义分享功能。
属性:
scene: (String 类型 )微信分享场景,仅微信分享平台有效
可取值: "WXSceneSession"分享到微信的“我的好友”; "WXSceneTimeline"分享到微信的“朋友圈”中; "WXSceneFavorite"分享到微信的“我的收藏”中。 默认值为"WXSceneSession"。
Authorize
分享授权控件对象
interface plus.share.Authorize {
// Methods
function void load( id );
function void setVisible( visible );
// Events
function void onloaded();
function void onauthenticated();
function void onerror();}
说明:
Authorize对象表示分享控件对象,用于在窗口中显示分享控件,使用此对象可自定义分享授权界面。
构造:
Authorize(id,display): 创建分享授权控件对象
方法:
load: 加载分享授权页面
setVisible: 设置分享授权控件是否可见
事件:
onloaded: 分享控件加载完成事件
onauthenticated: 分享授权认证成功事件
onerror: 分享授权认证失败事件
Authorize(id,display)
创建分享授权控件对象
var obj = new plus.share.Authorize( id, display );
说明:
根据指定的id的元素创建分享控件
参数:
id: ( DOMString ) 必选 分享控件在窗口的对应obj节点的id值,此id值用于定位控件位置
visible: ( Boolean ) 可选 分享控件是否创建后立即显示,默认值为true
返回值:
Authorize : 分享控件对象
load
加载分享授权页面
void obj.load( id );
说明:
创建分享授权页面后,需要调用此方法指定分享服务标识来加载授权页面数据,此标识可使用ShareService对象的id属性。
参数:
id: ( DOMString ) 必选 要加载的分享服务标识
返回值:
void : 无
setVisible
设置分享授权控件是否可见
void obj.setVisible( visible );
说明:
创建分享授权页面后,调用此方法设置分享授权控件在页面中是否可见。
参数:
visible: ( Boolean ) 必选 要设置分享控件是否可见,true标识可见,false表示不可见。
返回值:
void : 无
onloaded
分享控件加载完成事件
void obj.onloaded = function () {
// loaded code }
说明:
EventHandler 类型
分享授权控件内容加载完成事件,通过调用load方法加载分享授权控件内容,当内容加载完成时触发。
onauthenticated
分享授权认证成功事件
void obj.onauthenticated= function ( service) {
// Authenticate success code }
说明:
用户在分享授权控件上输入操作授权成功时触发,事件方法格式参考ShareSuccessCallback回调函数。
onerror
分享授权认证失败事件
void obj.onerror= function ( error ) {
// Error code }
说明:
用户在分享授权控件上输入操作授权认证错误时触发,事件方法格式参考ShareErrorCallback回调函数。
ServicesSuccessCallback
获取分享服务成功回调
void ServicesSuccessCallback( services ) {
// Get share services success code}
说明:
当获取分享服务列表成功时的回调函数,用于返回终端支持的分享服务列表。
参数:
services: ( ShareService ) 必选 数组,运行环境支持的分享服务列表
运行环境支持的分享服务列表数组,可通过services.length获取分享服务列表的数目。
返回值:
void : 无
AuthorizeSuccessCallback
分享消息成功回调
void AuthorizeSuccessCallback( service ) {
// Authorize success code}
说明:
分享操作成功回调函数,当分享操作成功时调用。
参数:
service: ( ShareService ) 必选 认证操作成功的分享服务对象
返回值:
void : 无
ShareSuccessCallback
分享操作成功回调
void ShareSuccessCallback () {
// Share success code}
说明:
分享操作成功回调函数,当分享操作成功时调用。
参数:
无
返回值:
void : 无
ShareErrorCallback
分享操作失败回调
void ShareErrorCallback ( error ) {
// Recognition error code}
说明:
当分享操作失败时的回调函数,用于返回分享相关操作失败的错误信息。
参数:
error: ( DOMException ) 必选 分享操作失败错误信息,通过error.code获取错误代码
返回值:
void : 无
Speech
Speech模块管理语音输入功能,提供语音识别功能,可支持用户通过麦克风设备进行语音输入内容。通过plus.speech可获取语音输入管理对象。
方法:
startRecognize: 启动语音识别
stopRecognize: 停止语音识别
对象:
SpeechRecognizeOption: JSON对象,语音识别参数
回调方法:
RecognitionSuccessCallback: 语音识别成功回调
RecognitionErrorCallback : 语音识别失败回调
权限:
permissions
"Speech": {
"description": "访问语音插件"}
startRecognize
启动语音识别
void plus.speech.startRecognize( options, successCB, errorCB );
说明:
启动语音识别时调用,当语音识别成功后通过successCallback回调返回识别出文本内容,调用语音识别失败则通过errorCallback回调返回。
参数:
options: ( SpeechRecognizeOption ) 必选 语音识别参数,用于控制语音引擎的各种技术参数
successCB: ( RecognitionSuccessCallback ) 可选 语音识别成功回调
当语音识别引擎识别数据成功时的回调函数,并返回识别出的文本内容。
errorCB: ( RecognitionErrorCallback ) 可选 语音识别失败时的回调函数
当语音识别引擎识别数据失败时的回调函数,并返回失败的错误信息。
返回值:
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>Speech Example</title>
<script type="text/javascript">// 监听plusready事件
document.addEventListener( "plusready", function(){
// 扩展API加载完毕,现在可以正常调用扩展API
// ...}, false );var text=null;function startRecognize () {
var options = {};
options.engine = 'iFly';
text = "";
alert( "开始语音识别:" );
plus.speech.startRecognize( options, function ( s ) {
text += s;
}, function ( e ) {
alert( "语音识别失败:"+e.message );
} );}
</script>
</head>
<body>
<button onclick="startRecognize">开始识别</button><br/>
<button onclick="alert(text);">识别内容</button>
</body></html>
stopRecognize
停止语音识别
void plus.speech.stopRecognize();
说明:
当语音识别完成时或用户取消语音识别时调用,调用此方法将导致errorCallback回调函数的调用。
参数:
无
返回值:
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>Speech Example</title>
<script type="text/javascript">// 监听plusready事件
document.addEventListener( "plusready", function(){
// 扩展API加载完毕,现在可以正常调用扩展API
// ...}, false );var text=null;function startRecognize () {
var options = {};
options.engine = 'iFly';
text = "";
alert( "开始语音识别:" );
plus.speech.startRecognize( options, function ( s ) {
text += s;
}, function ( e ) {
alert( "语音识别失败:"+e.message );
} );
setTimeout( stopRecognize, 10000 );}function stopRecognize(){
plus.speech.stopRecognize();}
</script>
</head>
<body>
<button onclick="startRecognize">开始识别(10s后自动关闭)</button><br/>
<button onclick="alert(text);">识别内容</button>
</body></html>
SpeechRecognizeOption
JSON对象,语音识别参数
interface plus.speech.SpeechRecognizeOption {
attribute DOMString engine;
attribute DOMString service;
attribute Number timeout;
attribute DOMString lang;
attribute Boolean continue;
attribute Number nbest;
attribute Boolean userInterface;
attribute EventHandler onstart;
attribute EventHandler onend;
attribute EventHandler onaudiostart;
attribute EventHandler onaudioend;
attribute EventHandler onrecognizestart;
attribute EventHandler onrecognizeend;}
说明:
控制语音识别引擎内部参数,在JS中为JSON对象,在启动语音识别时使用。
属性:
engine: (DOMString 类型 )语音识别引擎标识
用于兼容多语音识别引擎的浏览器,建议使用语音识别厂商的产品名称,如未设置或设置不正确则使用浏览器默认的语音识别引擎。
service: (DOMString 类型 )语音识别引擎服务器地址
可使用url地址或ip地址,如service:192.168.1.99指定定制的语音识别引擎服务器。默认值为浏览器内置服务器地址。
timeout: (Number 类型 )语音识别超时时间
语音识别超时的时间,单位为ms,如timeout:60000,默认值为10s。
lang: (DOMString 类型 )语音识别引擎的语言
用于定义语音识别引擎的语言,其取值需符合W3C的Language codes规范。默认值为浏览器的默认语言。
continue: (Boolean 类型 )语音识别是否采用持续模式
设置为true表示语音引擎不会根据语音输入自动结束,识别到文本内容将多次调用successCallback函数返回,如果需要结束语音识别则必须调用stopRecognize接口,默认值为false。
nbest: (Number 类型 )指定识别结果识别包括多候选结果
用于指定识别结果识别包括多候选结果。如nbest:3,识别返回3个候选结果,默认值为1。
userInterface: (Boolean 类型 )识别时是否显示用户界面
用于指定识别时是否显示用户界面,设置为true表示显示浏览器内置语音识别界面;设置为false表示不显示浏览器内置语音识别界面。默认值为true。
onstart: (EventHandler 类型 )语音识别开始事件
事件函数,语音识别开始启动,在调用startRecognize方法后触发,与onend事件成对触发。
onend: (EventHandler 类型 )语音识别结束事件
事件函数,语音识别结束,在调用stopRecognize方法后触发,或者在引擎内部自动完成语音识别后触发,与onstart事件成对触发。
onaudiostart: (EventHandler 类型 )录音开始事件
事件函数,录音开始事件,启动语音识别后,调用设备麦克风设备开始一段语音录音时触发,与onaudioend事件成对触发。
onaudioend: (EventHandler 类型 )录音结束事件
事件函数,录音结束事件,调用麦克风完成一段语音录音时触发,与onaudiostart事件成对触发。
onrecognizestart: (EventHandler 类型 )录音识别开始事件
事件函数,录音识别开始事件,开始对语音录音数据分析识别,与onrecognizeend事件成对触发。
onrecognizeend: (EventHandler 类型 )录音识别结束事件
事件函数,录音识别结束事件,开始对语音录音数据分析识别完成,与onrecognizestart事件成对触发。
RecognitionSuccessCallback
语音识别成功回调
void RecognitionSuccessCallback ( results ) {
// Recognition success code}
说明:
当语音识别成功时的回调函数,用于返回语音识别出的文本内容。
参数:
results: ( DOMString[] ) 必选 语音识别出的文本内容数组
语音识别出的候选文本内容,区配度高的在数组的前面,通过其length属性可获取总的候选内容的长度
返回值:
void : 无
RecognitionErrorCallback
语音识别失败回调
void RecognitionErrorCallback ( error ) {
// Recognition error code}
说明:
当语音识别失败时的回调函数,用于返回语音识别失败的错误信息。
参数:
error: ( DOMException ) 必选 语音识别失败的错误信息
返回值:
void : 无
Statistic
Statistic模块管理统计功能,用于提供应用内统计的能力,支持统计和分析用户属性和用户行为数据。通过plus.statistic可获取统计管理对象。
方法:
eventTrig: 触发事件
eventStart: 开始持续事件
eventEnd: 结束持续事件
eventDuration: 精确持续事件
权限:
permissions
"Statistic": {
"description": "访问统计插件"}
eventTrig
触发事件
void plus.statistic.eventTrig( id, label );
说明:
触发指定的统计事件,触发的事件必须要先在统计网站上注册事件ID。
参数:
id: ( DOMString ) 必选 要触发的事件ID
label: ( DOMString ) 可选 要触发事件的标签
返回值:
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>Statistic Example</title>
<script type="text/javascript">// 监听plusready事件
document.addEventListener( "plusready", function(){
// 扩展API加载完毕,现在可以正常调用扩展API
plus.statistic.eventTrig( "example", "open" );}, false );
</script>
</head>
<body>
</body></html>
eventStart
开始持续事件
void plus.statistic.eventStart( id, label );
说明:
开始指定的持续事件统计,当事件结束时调用eventEnd方法,,触发的事件必须要先在统计网站上注册事件ID。
参数:
id: ( DOMString ) 必选 要触发的事件ID
label: ( DOMString ) 可选 要触发事件的标签
返回值:
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>Statistic Example</title>
<script type="text/javascript">var winsetting = null;// 监听plusready事件
document.addEventListener( "plusready", function(){
// 扩展API加载完毕,现在可以正常调用扩展API
winsetting = plus.webview.create( "setting.html" );
winsetting.addEventListener( "loaded", function(){
plus.statistic.eventStart( "setting" );
}, false );
winsetting.addEventListener( "close", function(){
plus.statistic.eventEnd( "setting" );
}, false );
winsetting.show();}, false );
</script>
</head>
<body>
</body></html>
eventEnd
结束持续事件
void plus.statistic.eventEnd( id, label );
说明:
结束指定的持续事件统计,需先调用eventStart方法开始持续事件统计,触发的事件必须要先在统计网站上注册事件ID。
参数:
id: ( DOMString ) 必选 要触发的事件ID
label: ( DOMString ) 可选 要触发事件的标签
返回值:
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>Statistic Example</title>
<script type="text/javascript">var winsetting = null;// 监听plusready事件
document.addEventListener( "plusready", function(){
// 扩展API加载完毕,现在可以正常调用扩展API
winsetting = plus.webview.create( "setting.html" );
winsetting.addEventListener( "loaded", function(){
plus.statistic.eventStart( "setting" );
}, false );
winsetting.addEventListener( "close", function(){
plus.statistic.eventEnd( "setting" );
}, false );
winsetting.show();}, false );
</script>
</head>
<body>
</body></html>
eventDuration
精确持续事件
void plus.statistic.eventDuration( id, duration, label );
说明:
精确时长的持续事件统计,触发的事件必须要先在统计网站上注册事件ID。
参数:
id: ( DOMString ) 必选 要触发的事件ID
duration: ( Number ) 必选 要触发事件持续的时间,单位为ms
label: ( DOMString ) 可选 要触发事件的标签
返回值:
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>Statistic Example</title>
<script type="text/javascript">// 监听plusready事件
document.addEventListener( "plusready", function(){
// 扩展API加载完毕,现在可以正常调用扩展API}, false );function feedback() {
var start = new Date();
// Do something for feedback
var end = new Date();
var d = end.getTime() - start.getTime();
plus.statistic.duration( "feedback", d );}
</script>
</head>
<body>
<button onclick="feedback();">feedback</button>
</body></html>
Storage
Storage模块管理应用本地数据存储区,用于应用数据的保存和读取。应用本地数据与localStorage、sessionStorage的区别在于数据有效域不同,前者可在应用内跨域操作,数据存储期是持久化的,并且没有容量限制。通过plus.storage可获取应用本地数据管理对象。
方法:
getLength: 获取应用存储区中保存的键值对的个数
getItem: 通过键(key)检索获取应用存储的值
setItem: 修改或添加键值(key-value)对数据到应用数据存储中
removeItem: 通过key值删除键值对存储的数据
clear: 清除应用所有的键值对存储数据
key: 获取键值对中指定索引值的key值
权限:
permissions
"Storage": {
"description": "访问应用本地存储数据"}
getLength
获取应用存储区中保存的键值对的个数
var foo = plus.storage.getLength();
参数:
无
返回值:
Number : 键值对的个数
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Storage Example</title>
<script type="text/javascript">// H5 plus事件处理function plusReady(){}
document.addEventListener("plusready",plusReady,false);// Get storage item lengthfunction storageCount() {
return plus.storage.getLength();}
</script>
</head>
<body>
获取应用存储区中保存的键值对的个数<br/>
<button onclick="storageCount()">Count</button>
</body></html>
getItem
通过键(key)检索获取应用存储的值
var foo = plus.storage.getItem(key);
参数:
key: ( DOMString ) 必选
存储的键值
返回值:
DOMString : 键(key)对应应用存储的值,如果没有保存则返回null。
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Storage Example</title>
<script type="text/javascript">// H5 plus事件处理function plusReady(){}
document.addEventListener("plusready",plusReady,false);// Get storage item valuefunction getStorage() {
return plus.storage.getItem("test");}
</script>
</head>
<body>
获取应用存储区中保存的键值对的个数<br/>
<button onclick="alert(getStorage())">Get item(test)</button>
</body></html>
setItem
修改或添加键值(key-value)对数据到应用数据存储中
void plus.storage.setItem(key, value);
说明:
如果设置的键在应用数据存储中已经存在,更新存储的键值。 存储的键和值没有容量限制,但过多的数据量会导致效率降低,建议单个键值数据不要超过10Kb。
参数:
key: ( DOMString ) 必选
存储的键值
value: ( DOMString ) 必选
存储的内容
返回值:
void : 无
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Storage Example</title>
<script type="text/javascript">// H5 plus事件处理function plusReady(){}
document.addEventListener("plusready",plusReady,false);// Remove storage itemfunction setStorage() {
plus.storage.setItem("test","test with hbuilder!");}
</script>
</head>
<body>
修改或添加键值(key-value)对数据到应用数据存储中<br/>
<button onclick="setStorage()">Set item(test)</button>
</body></html>
removeItem
通过key值删除键值对存储的数据
void plus.storage.removeItem(key);
参数:
key: ( DOMString ) 必选
存储的键值
返回值:
void : 无
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Storage Example</title>
<script type="text/javascript">// H5 plus事件处理function plusReady(){}
document.addEventListener("plusready",plusReady,false);// Remove storage itemfunction removeStorage() {
plus.storage.removeItem("test");}
</script>
</head>
<body>
清除应用所有的键值对存储数据<br/>
<button onclick="removeStorage()">Remove item(test)</button>
</body></html>
clear
清除应用所有的键值对存储数据
void plus.storage.clear();
参数:
无
返回值:
void : 无
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Storage Example</title>
<script type="text/javascript">// H5 plus事件处理function plusReady(){}
document.addEventListener("plusready",plusReady,false);// Clear storage datafunction clearStorage() {
plus.storage.clear();}
</script>
</head>
<body>
清除应用所有的键值对存储数据<br/>
<button onclick="clearStorage()">Clear</button>
</body></html>
key
获取键值对中指定索引值的key值
var foo = plus.storage.key(index);
参数:
index: ( Number ) 必选 存储键值的索引
返回值:
void : 无
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Storage Example</title>
<script type="text/javascript">// H5 plus事件处理function plusReady(){}
document.addEventListener("plusready",plusReady,false);// Get value by indexfunction enumValueByIndex() {
var keyNames=[];
var values=[];
var numKeys=plus.storage.getLength();
for(var i=0; i<numKeys; i++) {
keyNames[i] = plus.storage.key(i);
values[i] = plus.storage.getItem(keyNames[i]);
}}
</script>
</head>
<body>
获取键值对中指定索引值的key值<br/>
<button onclick="enumValueByIndex()">Enum</button>
</body></html>
Uploader
Uploader模块管理网络上传任务,用于从本地上传各种文件到服务器,并支持跨域访问操作。通过plus.uploader可获取上传管理对象。Uploader上传使用HTTP的POST方式提交数据,数据格式符合Multipart/form-data规范,即rfc1867(Form-based File Upload in HTML)协议。
方法:
createUpload: 新建上传任务
enumerate: 枚举上传任务
clear: 清除上传任务
startAll: 开始所有上传任务
对象:
Upload: Upload对象管理一个上传任务
UploadState: 上传任务的状态,Number类型
UploadOptions: JSON对象,创建上传任务的参数
UploadFileOptions: JSON对象,添加上传文件的参数
回调方法:
UploadCompletedCallback: 上传任务完成时的回调函数
UploadStateChangedCallback: 上传任务状态变化回调函数,在上传任务状态发生变化时调用
UploadEnumerateCallback: 枚举上传任务回调函数,在枚举上传任务完成时时调用
权限:
permissions
"Uploader": {
"description": "管理上传任务"}
createUpload
新建上传任务
Upload plus.uploader.createUpload( url, options, completedCB );
说明:
请求上传管理创建新的上传任务,创建成功则返回Upload对象,用于管理上传任务。
参数:
url: ( String ) 必选 要上传文件的目标地址
上传服务器的url地址,仅支持http或https协议。 允许创建多个相同url地址的上传任务。
options: ( UploadOptions ) 可选 上传任务的参数
可通过此参数设置定义上传任务属性,如请求类型、上传优先级等。
completedCB: ( UploadCompletedCallback ) 可选 上传任务完成回调函数
当上传任务提交完成时触发,成功或失败都会触发。
返回值:
Upload : Upload对象
示例:
<!DOCTYPE html><html><head><meta charset="utf-8"><title>Uploader Example</title><script type="text/javascript" >// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );var r = null; // 扩展API加载完毕,现在可以正常调用扩展API function onPlusReady() {}// 创建上传任务function createUpload() {
var task = plus.uploader.createUpload( "http://www.test.com/upload.do",
{ method:"POST",blocksize:204800,priority:100 },
function ( t, status ) {
// 上传完成
if ( status == 200 ) {
alert( "Upload success: " + t.url );
} else {
alert( "Upload failed: " + status );
}
}
);
task.addFile( "_www/a.doc", {key:"testdoc"} );
task.addData( "string_key", "string_value" );
//task.addEventListener( "statechanged", onStateChanged, false );
task.start();}</script></head><body >
<input id="upload" type="button" value="Create upload task" onclick="createUpload();" ></input></body></html>
enumerate
枚举上传任务
plus.uploader.enumerate( enumCB, state );
说明:
枚举指定状态的上传任务列表,通过enumCB回调函数返回结果。
参数:
enumCB: ( UploadEnumerateCallback ) 必选 枚举上传任务回调函数
枚举上传任务完成时触发。
state: ( UploadState ) 可选 枚举上传任务的状态
如果未指定state值,则枚举所有未完成的上传任务。
返回值:
void : 无
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Uploader Example</title>
<script type="text/javascript" >// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );var r = null; // 扩展API加载完毕,现在可以正常调用扩展API function onPlusReady() {
plus.uploader.enumerate( function ( tasks ) {
alert( "Unfinished task count: " + tasks.length );
} );}
</script>
</head>
<body >
Enumerate all unfinished upload task.
</body></html>
clear
清除上传任务
plus.uploader.clear( state );
说明:
清除指定状态的上传任务。
参数:
state: ( UploadState ) 可选 清除上传任务的状态
如果未指定state值,则清除所有未完成的上传任务。
返回值:
void : 无
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Uploader Example</title>
<script type="text/javascript" >// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );var r = null; // 扩展API加载完毕,现在可以正常调用扩展API function onPlusReady() {
plus.uploader.clear();}
</script>
</head>
<body >
Clear all finished upload task.
</body></html>
startAll
开始所有上传任务
plus.uploader.startAll();
说明:
开始所有处于未开始调度或暂停状态的上传任务。 若上传任务数超过可并发处理的总数,超出的任务处于调度状态(等待上传),当有任务完成时根据调度状态任务的优先级选择任务开始上传。
参数:
无
返回值:
void : 无
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Uploader Example</title>
<script type="text/javascript" >// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );var r = null; // 扩展API加载完毕,现在可以正常调用扩展API function onPlusReady() {
plus.uploader.startAll();}
</script>
</head>
<body >
Start upload task.
</body></html>
Upload
Upload对象管理一个上传任务
interface Upload {
readonly attribute String url;
readonly attribute Number state;
readonly attribute UploadOptions options;
readonly attribute String responseText;
readonly attribute Number uploadedSize;
readonly attribute Number totalSize;
function void abort();
function Boolean addData( String key, String value );
function void addEventListener( String event, function Callback listener, Boolean capture );
function Boolean addFile( String path, UploadFileOptions options );
function String getAllResponseHeaders();
function String getResponseHeader( headerName );
function void pause();
function void resume();
function void setRequestHeader( String headerName, String headerValue );
function void start();}
属性:
id: 上传任务的标识
url: 上传文件的服务器地址
state: 任务的状态
options: 上传任务的参数
responseText: 上传任务完成后服务器返回的数据
uploadedSize: 已完成上传数据的大小)
totalSize: 上传数据的总大小
方法:
addFile: 添加上传文件
addData: 添加上传数据
start: 开始上传任务
pause: 暂停上传任务
resume: 恢复暂停的上传任务
abort: 取消上传任务
addEventListener: 添加上传任务事件监听器
getAllResponseHeaders: 获取上传请求HTTP响应头部信息
getResponseHeader: 获取上传请求指定的HTTP响应头部的值
setRequestHeader: 设置上传请求的HTTP头数据
id
上传任务的标识
download.id;
说明:
String 类型 只读属性
在创建任务时系统自动分配,用于标识上传任务的唯一性。
url
上传文件的服务器地址
upload.url;
说明:
String 类型 只读属性
调用plus.uploader.createUpload()方法创建上传任务时设置的值。
state
任务的状态
upload.state;
说明:
Number 类型 只读属性
上传任务的状态,参考UploadState,在UploadCompleteCallback事件和UploadStateChangedCallback事件触发时更新。
options
上传任务的参数
upload.options;
说明:
UploadOptions 类型 只读属性
上传任务配置的参数,参考UploadOptions。
responseText
上传任务完成后服务器返回的数据
upload.responseText;
说明:
String 类型 只读属性
表示当前上传任务的状态,可通过addEventListener()方法监听statechanged事件监听任务状态的变化。
uploadedSize
已完成上传数据的大小)
upload.UploadedSize;
说明:
Number 类型 只读属性
整数类型,单位为字节(byte),上传任务开始传输数据时,每次触发statechanged事件或上传任务完成更新。
totalSize
上传数据的总大小
upload.totalSize;
说明:
Number 类型 只读属性
整数类型,单位为字节(byte),上传任务开始传输数据时更新。
addFile
添加上传文件
Boolean upload.addFile( path, options );
说明:
向上传任务中添加文件,必须在任务开始上传前调用。 以下情况会导致添加上传文件失败: 1. options参数中指定的key在任务中已经存在,则添加失败返回false; 2. path参数指定的文件路径不合法或文件不存在,则添加失败返回false; 3. 上传任务已经开始调度,调用此方法则添加失败返回false。
参数:
path: ( String ) 必选 添加上传文件的路径
仅支持本地文件路径。
options: ( UploadFileOptions ) 必选 要添加上传文件的参数
可通过此参数设置上传任务属性,如文件标识、文件名称、文件类型等。
返回值:
Boolean : 添加文件成功返回true,失败则返回false。
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Uploader Example</title>
<script type="text/javascript" >// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );var r = null;// 扩展API加载完毕,现在可以正常调用扩展APIfunction onPlusReady() {}// 创建上传任务function createUpload() {
var task = plus.uploader.createUpload( "http://www.test.com/upload.do", {}, function ( t, status ) {
// 上传完成
if ( status == 200 ) {
alert( "Upload success: " + t.url );
} else {
alert( "Upload failed: " + status );
}
});
task.addFile( "_www/a.doc", {key:"testdoc"} );
task.addData( "string_key", "string_value" );
//task.addEventListener( "statechanged", onStateChanged, false );
task.start();}
</script>
</head>
<body >
<input id="upload" type="button" value="Create upload task" onclick="createUpload();" ></input>
</body></html>
addData
添加上传数据
Boolean upload.addData( key, value );
说明:
向上传任务中添加数据,必须在任务开始上传前调用。 以下情况会导致添加上传文件失败: 1. key参数中指定的键名在任务中已经存在,则添加失败返回false; 2. 上传任务已经开始调度,调用此方法则添加失败返回false。
参数:
key: ( String ) 必选 添加上传数据的键名
value: ( String ) 必选 添加上传数据的键值
返回值:
Boolean : 添加成功返回true,失败则返回false。
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Uploader Example</title>
<script type="text/javascript" >// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );
var r = null;
// 扩展API加载完毕,现在可以正常调用扩展API
function onPlusReady() {}// 创建上传任务function createUpload() {
var task = plus.uploader.createUpload( "http://www.test.com/upload.do", {}, function ( t, status ) {
// 上传完成
if ( status == 200 ) {
alert( "Upload success: " + t.url );
} else {
alert( "Upload failed: " + status );
}
});
task.addFile( "_www/a.doc", {key:"testdoc"} );
task.addData( "string_key", "string_value" );
//task.addEventListener( "statechanged", onStateChanged, false );
task.start();}
</script>
</head>
<body >
<input id="upload" type="button" value="Create upload task" onclick="createUpload();" ></input>
</body></html>
start
开始上传任务
void upload.start();
说明:
开始调度上传任务,如果任务已经处于开始状态则无任何响应。 在创建任务或任务上传失败后调用可重新开始上传。
参数:
无
返回值:
void : 无
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Uploader Example</title>
<script type="text/javascript" >// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );var r = null; // 扩展API加载完毕,现在可以正常调用扩展API function onPlusReady() {}// 创建上传任务function createUpload() {
var task = plus.uploader.createUpload( "http://www.test.com/upload.do", {}, function ( t, status ) {
// 上传完成
if ( status == 200 ) {
alert( "Upload success: " + t.url );
} else {
alert( "Upload failed: " + status );
}
});
task.addFile( "_www/a.doc", {key:"testdoc"} );
task.addData( "string_key", "string_value" );
//task.addEventListener( "statechanged", onStateChanged, false );
task.start();}
</script>
</head>
<body >
<input id="upload" type="button" value="Create upload task" onclick="createUpload();" ></input>
</body></html>
pause
暂停上传任务
void upload.pause();
说明:
暂停上传任务,如果任务已经处于初始状态或暂停状态则无任何响应。
参数:
无
返回值:
void : 无
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Uploader Example</title>
<script type="text/javascript" >// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );var task = null;// 扩展API加载完毕,现在可以正常调用扩展API function onPlusReady() {}// 创建上传任务function createUpload() {
var task = plus.uploader.createUpload( "http://www.test.com/upload.do", {}, function ( t, status ) {
// 上传完成
if ( status == 200 ) {
alert( "Upload success: " + t.url );
} else {
alert( "Upload failed: " + status );
}
});
task.addFile( "_www/a.doc", {key:"testdoc"} );
task.addData( "string_key", "string_value" );
//task.addEventListener( "statechanged", onStateChanged, false );
task.start();}// 暂停上传任务function pauseUpload() {
task.pause();}
</script>
</head>
<body >
<input type="button" value="Create upload task" onclick="createUpload();" ></input>
<input type="button" value="Pause upload task" onclick="pauseUpload();" ></input>
</body></html>
resume
恢复暂停的上传任务
void upload.resume();
说明:
继续暂停的上传任务,如果任务处于非暂停状态则无任何响应。
参数:
无
返回值:
void : 无
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Uploader Example</title>
<script type="text/javascript" >// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );var task = null;// 扩展API加载完毕,现在可以正常调用扩展APIfunction onPlusReady() {}// 创建上传任务function createUpload() {
var task = plus.uploader.createUpload( "http://www.test.com/upload.do", {}, function ( t, status ) {
// 上传完成
if ( status == 200 ) {
alert( "Upload success: " + t.url );
} else {
alert( "Upload failed: " + status );
}
});
task.addFile( "_www/a.doc", {key:"testdoc"} );
task.addData( "string_key", "string_value" );
//task.addEventListener( "statechanged", onStateChanged, false );
task.start();}// 暂停上传任务function pauseUpload() {
task.pause();}// 恢复上传任务function resumeUpload() {
task.resume();}
</script>
</head>
<body >
<input type="button" value="Create upload task" onclick="createUpload();" ></input>
<input type="button" value="Pause upload task" onclick="pauseUpload();" ></input>
<input type="button" value="Resume upload task" onclick="resumeUpload();" ></input>
</body></html>
abort
取消上传任务
void upload.abort();
说明:
如果任务未完成,则终止上传,并从任务列表中删除。
参数:
无
返回值:
void : 无
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Uploader Example</title>
<script type="text/javascript" >// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );var task = null;// 扩展API加载完毕,现在可以正常调用扩展API function onPlusReady() {}// 创建上传任务function createUpload() {
var task = plus.uploader.createUpload( "http://www.test.com/upload.do", {}, function ( t, status ) {
// 上传完成
if ( status == 200 ) {
alert( "Upload success: " + t.url );
} else {
alert( "Upload failed: " + status );
}
});
task.addFile( "_www/a.doc", {key:"testdoc"} );
task.addData( "string_key", "string_value" );
//task.addEventListener( "statechanged", onStateChanged, false );
task.start();}// 暂停上传任务function pauseUpload() {
task.pause();}// 取消上传任务function abortUpload() {
task.pause();}
</script>
</head>
<body >
<input type="button" value="Create upload task" onclick="createUpload();" ></input>
<input type="button" value="Pause upload task" onclick="pauseUpload();" ></input>
<input type="button" value="Abort upload task" onclick="abortUpload();" ></input>
</body></html>
addEventListener
添加上传任务事件监听器
void upload.addEventListener( type, listener, capture );
说明:
上传任务添加事件监听器后,当监听的事件发生时触发listener回调。
参数:
type: ( String ) 必选 事件类型
listener: ( UploadStateChangedCallback ) 必选 事件监听器回调函数
capture: ( Boolean ) 可选 事件流处理顺序,暂不支持
返回值:
void : 无
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Uploader Example</title>
<script type="text/javascript" >// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );var task = null;// 扩展API加载完毕,现在可以正常调用扩展API function onPlusReady() {}// 监听上传任务状态function onStateChanged( upload, status ) {
if ( upload.state == 4 && status == 200 ) {
// 上传完成
alert( "Upload success: " + upload.getFileName() );
}}// 创建上传任务function createUpload() {
var task = plus.uploader.createUpload( "http://www.test.com/upload.do" );
task.addFile( "_www/a.doc", {key:"testdoc"} );
task.addData( "string_key", "string_value" );
task.addEventListener( "statechanged", onStateChanged, false );
task.start();}// 暂停上传任务function pauseUpload() {
task.pause();}// 取消上传任务function abortUpload() {
task.abort();}
</script>
</head>
<body >
<input type="button" value="Create upload task" onclick="createUpload();" ></input>
<input type="button" value="Pause upload task" onclick="pauseUpload();" ></input>
<input type="button" value="Abort upload task" onclick="abortUpload();" ></input>
</body></html>
getAllResponseHeaders
获取上传请求HTTP响应头部信息
String upload.getAllResponseHeaders();
说明:
HTTP响应头部全部内容作为未解析的字符串返回,如果没有接收到这个HTTP响应头数据或者上传请求未完成则为空字符串。
参数:
无
返回值:
String : HTTP响应头数据
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Uploader Example</title>
<script type="text/javascript" >// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );var task = null;// 扩展API加载完毕,现在可以正常调用扩展API function onPlusReady() {}// 监听上传任务状态function onStateChanged( upload, status ) {
if ( upload.state == 4 && status == 200 ) {
// 获取上传请求响应头数据
console.log(upload.getAllResponseHeaders());
// 上传完成
alert( "Upload success: " + upload.getFileName() );
}}// 创建上传任务function createUpload() {
var task = plus.uploader.createUpload( "http://www.test.com/upload.do" );
task.addFile( "_www/a.doc", {key:"testdoc"} );
task.addData( "string_key", "string_value" );
task.addEventListener( "statechanged", onStateChanged, false );
task.start();}
</script>
</head>
<body >
<input type="button" value="Create upload task" onclick="createUpload();" ></input>
</body></html>
getResponseHeader
获取上传请求指定的HTTP响应头部的值
String upload.getResponseHeader( headerName );
说明:
其参数是要返回的HTTP响应头部的名称,可以使用任何大小写来制定这个头部名字,和响应头部的比较是不区分大小写的。 如果没有接收到这个头部或者伤处请求未完成则为空字符串;如果接收到多个有指定名称的头部,这个头部的值被连接起来并返回,使用逗号和空格分隔开各个头部的值。
参数:
headerName: ( String ) 可选 HTTP响应头数据名称
返回值:
String : HTTP响应头数据值
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Uploader Example</title>
<script type="text/javascript" >// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );var task = null;// 扩展API加载完毕,现在可以正常调用扩展API function onPlusReady() {}// 监听上传任务状态function onStateChanged( upload, status ) {
if ( upload.state == 4 && status == 200 ) {
// 获取上传请求响应头中的Content-Type值
console.log(dtask.getResponseHeader("Content-Type"));
// 上传完成
alert( "Upload success: " + upload.getFileName() );
}}// 创建上传任务function createUpload() {
var task = plus.uploader.createUpload( "http://www.test.com/upload.do" );
task.addFile( "_www/a.doc", {key:"testdoc"} );
task.addData( "string_key", "string_value" );
task.addEventListener( "statechanged", onStateChanged, false );
task.start();}
</script>
</head>
<body >
<input type="button" value="Create upload task" onclick="createUpload();" ></input>
</body></html>
setRequestHeader
设置上传请求的HTTP头数据
void upload.setRequestHeader( headerName, headerValue );
说明:
Http的Header应该包含在通过后续start()调用而发起的请求中,此方法必需在调用start()之前设置才能生效。 如果带有指定名称的头部已经被指定了,这个头部的新值就是:之前指定的值,加上逗号、以及这个调用指定的值(形成一个数组)。
参数:
headerName: ( String ) 必选 HTTP请求的头数据名称
headerValue: ( String ) 必选 HTTP请求的头数据值
返回值:
void : 无
平台支持:
Android - 2.2+ (支持): 不支持设置“Content-Type”、“User-Agent”、“Cookie”的值。
iOS - 5.1+ (支持): 不支持设置“Content-Type”、“User-Agent”的值。
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Uploader Example</title>
<script type="text/javascript" >// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );var task = null;// 扩展API加载完毕,现在可以正常调用扩展API function onPlusReady() {}// 监听上传任务状态function onStateChanged( upload, status ) {
if ( upload.state == 4 && status == 200 ) {
// 获取上传请求响应头中的Content-Type值
console.log(dtask.getResponseHeader("Content-Type"));
// 上传完成
alert( "Upload success: " + upload.getFileName() );
}}// 创建上传任务function createUpload() {
var task = plus.uploader.createUpload( "http://www.test.com/upload.do" );
task.addFile( "_www/a.doc", {key:"testdoc"} );
task.addData( "string_key", "string_value" );
// 设置自定义数据头
dtask.setRequestHeader('Customer','CustomerValue/XXXXXXXXXXXX');
task.addEventListener( "statechanged", onStateChanged, false );
task.start();}
</script>
</head>
<body >
<input type="button" value="Create upload task" onclick="createUpload();" ></input>
</body></html>
UploadState
上传任务的状态,Number类型
常量:
undefined: (undefined 类型 )上传任务未开始
通过plus.uploader.createUpload()方法创建上传任务后的初始状态,此时可调用其start()方法开始上传。
0: (number 类型 )上传任务开始调度
调用上传任务的start()方法之后处于此状态,此时上传任务处于可调度上传状态。
1: (number 类型 )上传任务开始请求
上传任务建立网络连接,发送请求到服务器并等待服务器的响应。
2: (number 类型 )上传任务请求已经建立
上传任务网络连接已建立,服务器返回响应,准备传输数据内容。
3: (number 类型 )上传任务提交数据
上传任务提交数据,监听statechanged事件时可多次触发此状态。
4: (number 类型 )上传任务已完成
上传任务完成数据提交并断开连接,上传成功或失败都会设置为此状态。
5: (number 类型 )上传任务已暂停
调用上传任务的pause()方法将任务暂停,此时可调用其resume()方法重新开始上传。
-1: (number 类型 )枚举任务状态
非上传任务状态,泛指所有上传任务的状态,用于enumerate()和clear()操作时指定作用于所有上传任务。
UploadOptions
JSON对象,创建上传任务的参数
属性:
method: (String 类型 )网络请求类型
仅支持http协议的“POST”请求。
blocksize: (number 类型 )上传任务每次上传的文件块大小(仅在支持断点续传的服务有效)
数值类型,单位为Byte(字节),默认值为102400,若设置值小于等于0则表示不分块上传。
priority: (number 类型 )上传任务的优先级
数值类型,数值越大优先级越高,默认优先级值为0。
timeout: (number 类型 )上传任务超时时间
数值类型,单位为s(秒),默认值为120s。 超时时间为服务器响应请求的时间(不是上传任务完成的总时间),如果设置为0则表示永远不超时。
retry: (number 类型 )上传任务重试次数
数值类型,默认为重试3次。
retryInterval: (Number 类型 )上传任务重试间隔时间
数值类型,单位为s(秒),默认值为30s。
UploadFileOptions
JSON对象,添加上传文件的参数
属性:
key: 文件键名
name: 文件名称
mime: 文件类型
key
文件键名
说明:
String 类型 可选属性
上传文件在上传任务中的键名,默认值为为文件名称。 上传任务中如果已经存在相同key的上传文件或数据将导致添加文件失败。
name
文件名称
说明:
String 类型 可选属性
上传文件的名称,默认值为上传文件路径中的名称。
mime
文件类型
说明:
String 类型
上传文件的类型(如图片文件为“image/jpeg”),默认值自动根据文件后缀名称生成。
UploadCompletedCallback
上传任务完成时的回调函数
void uploadCompleted( Upload upload, Number status ) {
// File upload completed code.}
说明:
在上传任务完成时调用,上传任务失败也将触发此回调。
参数:
upload: ( Upload ) 必选 上传任务对象
status: ( Number ) 必选 上传结果状态码
HTTP传输协议状态码,如果未获取传输状态则其值则为0,如下载成功其值通常为200。
返回值:
void : 无
UploadStateChangedCallback
上传任务状态变化回调函数,在上传任务状态发生变化时调用
void onStateChanged( Upload upload, status ) {
// Upload state changed code.}
参数:
upload: ( Upload ) 必选 上传任务对象
status: ( Number ) 必选 上传结果状态码
HTTP传输协议状态码,如果未获取传输状态则其值则为0,如下载成功其值通常为200。
返回值:
void : 无
UploadEnumerateCallback
枚举上传任务回调函数,在枚举上传任务完成时时调用
void onEnumerated( Upload[] uploads ) {
// Upload enumerate completed code.}
参数:
uploads: ( Array[ Upload ] ) 必选 枚举到的上传任务对象数组
返回值:
void : 无
Webview
Webview模块管理应用窗口界面,实现多窗口的逻辑控制管理操作。通过plus.webview可获取应用界面管理对象。
方法:
all: 获取所有Webview窗口
close: 关闭Webview窗口
create: 创建新的Webview窗口
currentWebview: 获取当前窗口的WebviewObject对象
getWebviewById: 查找指定标识的WebviewObject窗口
getLaunchWebview: 获取应用首页WebviewObject窗口对象
hide: 隐藏Webview窗口
open: 创建并打开Webview窗口
show: 显示Webview窗口
defauleHardwareAccelerated: 获取Webview默认是否开启硬件加速
对象:
AnimationTypeShow: 一组用于定义页面或控件显示动画效果
AnimationTypeClose: 一组用于定义页面或控件关闭的动画效果
WebviewObject: Webview窗口对象,用于操作加载HTML页面的窗口
WebviewBounceStyle: Webview窗口回弹样式
WebviewDock: 原生控件在窗口中停靠的方式
WebviewEvent: Webview窗口事件
WebviewRefreshStyle: Webview窗口下拉刷新样式
WebviewPosition: 原生控件在窗口中显示的位置
WebviewStyle: JSON对象,原生窗口设置参数的对象
WebviewExtraOptions: JSON对象,原生窗口扩展参数
WebviewTransform: 一组用于定义页面或控件变形的属性
WebviewTransition: 一组用于定义页面或控件转换效果的属性
回调方法:
BounceEventCallback: Webview窗口回弹事件的回调函数
EventCallback: Webview窗口事件的回调函数
PopGestureCallback: Webview窗口侧滑事件的回调函数
HistoryQueryCallback: 历史记录记录查询的回调函数
TitleUpdateCallback: Webview窗口加载页面标题更新的回调函数
SuccessCallback: Webview窗口操作成功回调函数
ErrorCallback: Webview窗口操作失败回调函数
权限:
permissions
"Webview": {
"description": "窗口管理"}
all
获取所有Webview窗口
Array[WebviewObject] plus.webview.all();
说明:
获取应用中已创建的所有Webview窗口,包括所有未显示的Webview窗口。 返回WebviewObject对象在数组中按创建的先后顺序排列,即数组中第一个WebviewObject对象用是加载应用的入口页面。
参数:
无
返回值:
Array[ WebviewObject ] : 应用中创建的所有Webview窗口对象数组。
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Webview Example</title>
<script type="text/javascript">// H5 plus事件处理function plusReady(){
// 获取所有Webview窗口
var wvs=plus.webview.all();
for(var i=0;i<wvs.length;i++){
console.log("webview"+i+": "+wvs[i].getURL());
}}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}
</script>
</head>
<body>
获取所有Webview窗口
</body></html>
close
关闭Webview窗口
void plus.webview.close( id_wvobj, aniClose, duration, extras );
说明:
关闭已经打开的Webview窗口,需先获取窗口对象或窗口id,并可指定关闭窗口的动画及动画持续时间。
参数:
id_wvobj: ( String | WebviewObject ) 必选 要关闭Webview窗口id或窗口对象
若操作窗口对象已经关闭,则无任何效果。 使用窗口id时,则查找对应id的窗口,如果有多个相同id的窗口则操作最先打开的窗口,若没有查找到对应id的WebviewObject对象,则无任何效果。
aniClose: ( AnimationTypeClose ) 可选 关闭Webview窗口的动画效果
如果没有指定关闭窗口动画,则使用默认值“auto”,即使用显示时设置的窗口动画相对应的关闭动画。
duration: ( Number ) 可选 关闭Webview窗口动画的持续时间
单位为ms,如果没有设置则使用显示窗口动画时间。
extras: ( WebviewExtraOptions ) 可选 关闭Webview窗口扩展参数
可用于指定Webview窗口动画是否使用图片加速。
返回值:
void : 无
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Webview Example</title>
<script type="text/javascript">// H5 plus事件处理function plusReady(){}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}
// 关闭自身窗口function closeme(){
var ws=plus.webview.currentWebview();
plus.webview.close(ws);}
</script>
</head>
<body>
关闭Webview窗口<br/>
<button onclick="closeme()">close</button>
</body></html>
create
创建新的Webview窗口
WebviewObject plus.webview.create( url, id, styles, extras );
说明:
创建Webview窗口,用于加载新的HTML页面,可通过styles设置Webview窗口的样式,创建完成后需要调用show方法才能将Webview窗口显示出来。
参数:
url: ( String ) 可选 新窗口加载的HTML页面地址
新打开Webview窗口要加载的HTML页面地址,可支持本地地址和网络地址。
id: ( String ) 可选 新窗口的标识
窗口标识可用于在其它页面中通过getWebviewById来查找指定的窗口,为了保持窗口标识的唯一性,应该避免使用相同的标识来创建多个Webview窗口。 如果传入无效的字符串则使用url参数作为WebviewObject窗口的id值。
styles: ( WebviewStyle ) 可选 创建Webview窗口的样式(如窗口宽、高、位置等信息)
extras: ( JSON ) 可选 创建Webview窗口的额外扩展参数
值为JSON类型,设置扩展参数后可以直接通过Webview的点(“.”)操作符获取扩展参数属性值,如: var
w=plus.webview.create('url.html','id',{},{preload:"preload webview"});
// 可直接通过以下方法获取preload值 console.log(w.preload); // 输出值为“preload webview”
返回值:
WebviewObject : Webview窗口对象
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Webview Example</title>
<script type="text/javascript">// H5 plus事件处理function plusReady(){}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}
// 创建并显示新窗口function create(){
var w = plus.webview.create( "http://weibo.com/dhnetwork" );
w.show(); // 显示窗口}
</script>
</head>
<body>
创建新的Webview窗口<br/>
<button onclick="create()">Create</button>
</body></html>
currentWebview
获取当前窗口的WebviewObject对象
WebviewObject plus.webview.currentWebview();
说明:
获取当前页面所属的Webview窗口对象。
参数:
无
返回值:
WebviewObject : Webview窗口对象
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Webview Example</title>
<script type="text/javascript">// H5 plus事件处理function plusReady(){
var ws=plus.webview.currentWebview();
console.log( "当前Webview窗口:"+ws.getURL() );}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}
</script>
</head>
<body>
获取自身Webview窗口
</body></html>
getWebviewById
查找指定标识的WebviewObject窗口
WebviewObject plus.webview.getWebviewById( id );
说明:
在已创建的窗口列表中查找指定标识的Webview窗口并返回。 若没有查找到指定标识的窗口则返回null,若存在多个相同标识的Webview窗口,则返回第一个创建的Webview窗口。 如果要获取应用入口页面所属的Webview窗口,其标识为应用的%APPID%,可通过plus.runtime.appid获取。
参数:
id: ( String ) 必选 要查找的Webview窗口标识
返回值:
WebviewObject : WebviewObject窗口对象
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Webview Example</title>
<script type="text/javascript">// H5 plus事件处理function plusReady(){
// 查找应用首页窗口对象
var h=plus.webview.getWebviewById( plus.runtime.appid );
console.log( "应用首页Webview窗口:"+h.getURL() );}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}
</script>
</head>
<body>
查找指定标识的窗口
</body></html>
getLaunchWebview
获取应用首页WebviewObject窗口对象
WebviewObject plus.webview.getLaunchWebview();
参数:
无
返回值:
WebviewObject : WebviewObject窗口对象
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Webview Example</title>
<script type="text/javascript">// H5 plus事件处理function plusReady(){
// 获取应用首页窗口对象
var h=plus.webview.getLaunchWebview();
console.log( "应用首页Webview窗口:"+h.getURL() );}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}
</script>
</head>
<body>
获取应用首页WebviewObject窗口对象
</body></html>
hide
隐藏Webview窗口
void plus.webview.hide( id_wvobj, aniHide, duration, extras );
说明:
根据指定的WebviewObject对象或id隐藏Webview窗口,使得窗口不可见。
参数:
id_wvobj: ( String | WebviewObject ) 必选 要隐藏的Webview窗口id或窗口对象
使用窗口对象时,若窗口对象已经隐藏,则无任何效果。 使用窗口id时,则查找对应id的窗口,如果有多个相同id的窗口则操作最先打开的,若没有查找到对应id的WebviewObject对象,则无任何效果。
aniHide: ( AnimationTypeClose ) 可选 隐藏Webview窗口的动画效果
如果没有指定窗口动画,则使用默认动画效果“none”。
duration: ( Number ) 可选 隐藏Webview窗口动画的持续时间
单位为ms,如果没有设置则使用默认窗口动画时间。
extras: ( WebviewExtraOptions ) 可选 隐藏Webview窗口扩展参数
可用于指定Webview窗口动画是否使用图片加速。
返回值:
void : 无
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Webview Example</title>
<script type="text/javascript">// H5 plus事件处理function plusReady(){}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}
// 隐藏自身窗口function hideeme(){
plus.webview.hide( plus.webview.currentWebview() );}
</script>
</head>
<body>
隐藏Webview窗口<br/>
<button onclick="hideeme()">Hide</button>
</body></html>
open
创建并打开Webview窗口
WebviewObject plus.webview.open( url, id, styles, aniShow, duration, showedCB );
说明:
创建并显示Webview窗口,用于加载新的HTML页面,可通过styles设置Webview窗口的样式,创建完成后自动将Webview窗口显示出来。
参数:
url: ( String ) 可选 打开窗口加载的HTML页面地址
新打开Webview窗口要加载的HTML页面地址,可支持本地地址和网络地址。
id: ( String ) 可选 打开窗口的标识
窗口标识可用于在其它页面中通过getWebviewById来查找指定的窗口,为了保持窗口标识的唯一性,应该避免使用相同的标识来创建多个Webview窗口。 如果传入无效的字符串则使用url参数作为WebviewObject窗口的id值。
styles: ( WebviewStyle ) 可选 创建Webview窗口的样式(如窗口宽、高、位置等信息)
aniShow: ( AnimationTypeShow ) 可选 显示Webview窗口的动画效果
如果没有指定窗口动画,则使用默认无动画效果“none”。
duration: ( Number ) 可选 显示Webview窗口动画的持续时间
单位为ms,如果没有设置则使用默认窗口动画时间600ms。
showedCB: ( SuccessCallback ) 可选 Webview窗口显示完成的回调函数
当指定Webview窗口显示动画执行完毕时触发回调函数,窗口无动画效果(如"none"动画效果)时也会触发此回调。
返回值:
WebviewObject : WebviewObject窗口对象
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Webview Example</title>
<script type="text/javascript">// H5 plus事件处理function plusReady(){}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}
// 创建并显示新窗口function openWebview(){
var w = plus.webview.open( "http://weibo.com/dhnetwork" );}
</script>
</head>
<body>
打开Webview窗口<br/>
<button onclick="openWebview()">Open</button>
</body></html>
show
显示Webview窗口
void plus.webview.show( id_wvobj, aniShow, duration, showedCB, extras );
说明:
显示已创建或隐藏的Webview窗口,需先获取窗口对象或窗口id,并可指定显示窗口的动画及动画持续时间。
参数:
id_wvobj: ( String | WebviewObject ) 必选 要显示Webview窗口id或窗口对象
若操作Webview窗口对象显示,则无任何效果。 使用窗口id时,则查找对应id的窗口,如果有多个相同id的窗口则操作最先创建的窗口,若没有查找到对应id的WebviewObject对象,则无任何效果。
aniShow: ( AnimationTypeShow ) 可选 显示Webview窗口的动画效果
如果没有指定窗口动画类型,则使用默认值“auto”,即自动选择上一次显示窗口的动画效果,如果之前没有显示过,则使用“none”动画效果。
duration: ( Number ) 可选 显示Webview窗口动画的持续时间
单位为ms,如果没有设置则使用默认窗口动画时间600ms。
showedCB: ( SuccessCallback ) 可选 Webview窗口显示完成的回调函数
当指定Webview窗口显示动画执行完毕时触发回调函数,窗口无动画效果(如"none"动画效果)时也会触发此回调。
extras: ( WebviewExtraOptions ) 可选 显示Webview窗口扩展参数
可用于指定Webview窗口动画是否使用图片加速。
返回值:
WebviewObject : Webview窗口对象
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Webview Example</title>
<script type="text/javascript">// H5 plus事件处理function plusReady(){}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}
// 创建并显示新窗口function create(){
var w = plus.webview.create( "http://weibo.com/dhnetwork" );
plus.webview.show( w ); // 显示窗口}
</script>
</head>
<body>
显示Webview窗口<br/>
<button onclick="create()">Create</button>
</body></html>
defauleHardwareAccelerated
获取Webview默认是否开启硬件加速
Boolean plus.webview.defauleHardwareAccelerated();
说明:
由于不同设备对硬件加速的支持情况存在差异,开启硬件加速能加速HTML页面的渲染,但也会消耗更多的系统资源,从而导致在部分设备上可能出现闪屏、发虚、分块渲染等问题, 因此5+ Runtime会根据设备实际支持情况自动选择是否开启硬件加速。 关闭硬件加速则可能会导致Webview页面无法支持Video标签播放视频等问题,如果在特定情况下需要调整修改默认开启硬件加速的行为,则可通过plus.webview.defauleHardwareAccelerated()方法获取当前设备默认是否开启硬件加速状态,从而决定是否需要显式开启或关闭指定Webview的硬件加速功能。
参数:
无
返回值:
Boolean : Webview窗口默认开启硬件加速则返回true,否则返回false。
平台支持:
Android - 2.3+ (支持): 返回当前设备默认是否开启硬件加速。
iOS - 5.1+ (不支持): 返回固定值true。
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Webview Example</title>
<script type="text/javascript">// H5 plus事件处理function plusReady(){}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}
// 创建新窗口并设置开启硬件加速function create(){
var styles={};
// 在Android5以上设备,如果默认没有开启硬件加速,则强制设置开启
if(!plus.webview.defauleHardwareAccelerated()&&parseInt(plus.os.version)>=5){
styles.hardwareAccelerated=true;
}
var w = plus.webview.create( "http://weibo.com/dhnetwork", "test", styles );
plus.webview.show( w ); // 显示窗口}
</script>
</head>
<body>
开启硬件加速显示Webview窗口<br/>
<button onclick="create()">Create</button>
</body></html>
AnimationTypeShow
一组用于定义页面或控件显示动画效果
常量:
"auto": (String 类型 )自动选择动画效果
自动选择动画效果,使用上次显示窗口设置的动画效果,如果是第一次显示则默认动画效果“none”。
"none": (String 类型 )无动画效果
立即显示页面,无任何动画效果,页面显示默认的动画效果。 此效果忽略动画时间参数,立即显示。 对应关闭动画"none"。
"slide-in-right": (String 类型 )从右侧横向滑动效果
页面从屏幕右侧外向内横向滑动显示。 对应关闭动画"slide-out-right"。
平台支持
Android - 2.2+ (支持): 默认动画时间为200ms。
iOS - 5.1.1+ (支持): 默认动画时间为300ms。
"slide-in-left": (String 类型 )从左侧横向滑动效果
页面从屏幕左侧向右横向滑动显示。 对应关闭动画"slide-out-left"。
平台支持
Android - 2.2+ (支持): 默认动画时间为200ms。
iOS - 5.1.1+ (支持): 默认动画时间为300ms。
"slide-in-top": (String 类型 )从上侧竖向滑动效果
页面从屏幕上侧向下竖向滑动显示。 对应关闭动画"slide-out-top"。
平台支持
Android - 2.2+ (支持): 默认动画时间为200ms。
iOS - 5.1.1+ (支持): 默认动画时间为300ms。
"slide-in-bottom": (String 类型 )从下侧竖向滑动效果
页面从屏幕下侧向上竖向滑动显示。 对应关闭动画"slide-out-bottom"。
平台支持
Android - 2.2+ (支持): 默认动画时间为200ms。
iOS - 5.1.1+ (支持): 默认动画时间为300ms。
"fade-in": (String 类型 )从透明到不透明逐渐显示效果
页面从完全透明到不透明逐渐显示。 对应关闭动画"fade-out"。
平台支持
Android - 2.2+ (支持): 默认动画时间为200ms。
iOS - 5.1.1+ (支持): 默认动画时间为300ms。
"zoom-out": (String 类型 )从小到大逐渐放大显示效果
页面在屏幕中间从小到大逐渐放大显示。 对应关闭动画"zoom-in"。
平台支持
Android - 2.2+ (支持): 默认动画时间为100ms。
iOS - 5.1.1+ (支持): 默认动画时间为100ms。
"zoom-fade-out": (String 类型 )从小到大逐渐放大并且从透明到不透明逐渐显示效果
页面在屏幕中间从小到大逐渐放大并且从透明到不透明逐渐显示。 对应关闭动画"zoom-fade-in"。
平台支持
Android - 2.2+ (支持): 默认动画时间为100ms。
iOS - 5.1.1+ (支持): 默认动画时间为100ms。
"pop-in": (String 类型 )从右侧平移入栈动画效果
页面从屏幕右侧滑入显示,同时上一个页面带阴影效果从屏幕左侧滑出隐藏。 对应关闭动画"pop-out"。
平台支持
Android - 2.2+ (支持): 默认动画时间为200ms。 此动画是新开窗口侧滑挤压当前屏幕窗口特效,必须是两个Webview窗口的组合动画, 如果当前屏幕已显示多个Webview窗口,则显示新窗口不支持此动画类型,自动转成“slide-in-right”。
iOS - 5.1.1+ (支持): 默认动画时间为300ms。
AnimationTypeClose
一组用于定义页面或控件关闭的动画效果
常量:
"auto": (String 类型 )自动选择动画效果
自动选择显示窗口相对于的动画效果。
"none": (String 类型 )无动画
立即关闭页面,无任何动画效果。 此效果忽略动画时间参数,立即关闭。
"slide-out-right": (String 类型 )横向向右侧滑出屏幕动画
页面从屏幕中横向向右侧滑动到屏幕外关闭。
平台支持
Android - 2.2+ (支持): 默认动画时间为200ms。
iOS - 5.1.1+ (支持): 默认动画时间为300ms。
"slide-out-left": (String 类型 )横向向左侧滑出屏幕动画
页面从屏幕中横向向左侧滑动到屏幕外关闭。
平台支持
Android - 2.2+ (支持): 默认动画时间为200ms。
iOS - 5.1.1+ (支持): 默认动画时间为300ms。
"slide-out-top": (String 类型 )竖向向上侧滑出屏幕动画
页面从屏幕中竖向向上侧滑动到屏幕外关闭。
平台支持
Android - 2.2+ (支持): 默认动画时间为200ms。
iOS - 5.1.1+ (支持): 默认动画时间为300ms。
"slide-out-bottom": (String 类型 )竖向向下侧滑出屏幕动画
页面从屏幕中竖向向下侧滑动到屏幕外关闭。
平台支持
Android - 2.2+ (支持): 默认动画时间为200ms。
iOS - 5.1.1+ (支持): 默认动画时间为300ms。
"fade-out": (String 类型 )从不透明到透明逐渐隐藏动画
页面从不透明到透明逐渐隐藏关闭。
平台支持
Android - 2.2+ (支持): 默认动画时间为200ms。
iOS - 5.1.1+ (支持): 默认动画时间为300ms。
"zoom-in": (String 类型 )从大逐渐缩小关闭动画
页面逐渐向页面中心缩小关闭。
平台支持
Android - 2.2+ (支持): 默认动画时间为100ms。
iOS - 5.1.1+ (支持): 默认动画时间为100ms。
"zoom-fade-in": (String 类型 )从大逐渐缩小并且从不透明到透明逐渐隐藏关闭动画
页面逐渐向页面中心缩小并且从不透明到透明逐渐隐藏关闭。
平台支持
Android - 2.2+ (支持): 默认动画时间为100ms。
iOS - 5.1.1+ (支持): 默认动画时间为100ms。
"pop-out": (String 类型 )从右侧平移出栈动画效果
页面从屏幕右侧滑出消失,同时上一个页面带阴影效果从屏幕左侧滑入显示。
平台支持
Android - 2.2+ (支持): 默认动画时间为200ms。
iOS - 5.1.1+ (支持): 默认动画时间为300ms。
WebviewObject
Webview窗口对象,用于操作加载HTML页面的窗口
属性:
id: Webview窗口的标识
方法:
addEventListener: 添加事件监听器
append: 在Webview窗口中添加子窗口
appendJsFile: 添加Webview窗口预加载js文件
back: 后退到上次加载的页面
canBack: 查询Webview窗口是否可后退
canForward: 查询Webview窗口是否可前进
children: 获取Webview窗口的所有子Webview窗口
clear: 清空原生Webview窗口加载的内容
close: 关闭Webview窗口
draw: 截屏绘制
evalJS: 在Webview窗口中执行JS脚本
forward: 前进到上次加载的页面
getStyle: 获取Webview窗口的样式
getTitle: 获取Webview窗口加载HTML页面的标题
getURL: 获取Webview窗口加载HTML页面的地址
hide: 隐藏Webview窗口
isVisible: 查询Webview窗口是否可见
loadData: 加载新HTML数据
loadURL: 加载新URL页面
nativeInstanceObject: 获取Webview窗口对象的原生(Native.JS)实例对象
opened: 获取在当前Webview窗口中创建的所有窗口
opener: 获取当前Webview窗口的创建者
parent: 获取当前Webview窗口的父窗口
reload: 重新加载Webview窗口显示的HTML页面
resetBounce: 重置Webview窗口的回弹位置
remove: 移除子Webview窗口
removeEventListener: 移除Webview窗口事件监听器
removeFromParent: 从父窗口中移除
setBounce: 设置Webview窗口的回弹效果
setBlockNetworkImage: 设置Webview窗口是否阻塞加载页面中使用的网络图片
setContentVisible: 设置HTML内容是否可见
setPullToRefresh: 设置Webview窗口的下拉刷新效果
setStyle: 设置Webview窗口的样式
setJsFile: 设置预加载的JS文件
show: 显示Webview窗口
stop: 停止加载HTML页面内容
事件:
onclose: Webview窗口关闭事件
onerror: Webview窗口错误事件
onloaded: Webview窗口页面加载完成事件
onloading: Webview窗口页面开始加载事件
id
Webview窗口的标识
说明:
String 类型
在打开或创建Webview窗口时设置,如果没有设置窗口标识,此属性值为undefined。
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Webview Example</title>
<script type="text/javascript">// H5 plus事件处理function plusReady(){
// 获取自身webview窗口
var ws=plus.webview.currentWebview();
console.log( "窗口标识: "+ws.id );}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}
</script>
</head>
<body>
Webview窗口的标识<br/>
</body></html>
addEventListener
添加事件监听器
wobj.addEventListener( event, listener, capture );
说明:
向Webview窗口添加事件监听器,当指定的事件发生时,将触发listener函数的执行。 可多次调用此方法向Webview添加多个监听器,当监听的事件发生时,将按照添加的先后顺序执行。
参数:
event: ( WebviewEvent ) 必选 Webview窗口事件类型
listener: ( EventCallback ) 必选 监听事件发生时执行的回调函数
capture: ( Boolean ) 可选 捕获事件流顺序,暂无效果
返回值:
void : 无
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Webview Example</title>
<script type="text/javascript">// H5 plus事件处理function plusReady(){}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}
var nw=null;// 监听Webview窗口事件function eventTest() {
if(nw){return;}
var w=plus.nativeUI.showWaiting()
// 打开新窗口
nw=plus.webview.create( "http://weibo.com/dhnetwork" );
nw.addEventListener( "loaded", function(){
console.log( "New Window loaded!" );
nw.show(); // 显示窗口
w.close();
w=null;
}, false );}
</script>
</head>
<body>
添加事件监听器<br/>
<button onclick="eventTest()">Event Listener</button>
</body></html>
append
在Webview窗口中添加子窗口
void wobj.append( webview );
说明:
将另一个Webview窗口作为子窗口添加到当前Webview窗口中,添加后其所有权归父Webview窗口,当父窗口关闭时子窗口自动关闭。
参数:
webview: ( WebviewObject ) 必选 被添加的子Webview窗口对象
被添加的Webview窗口需通过plus.webview.create方法创建,并且不能调用其show方法进行显示。 父窗口显示时子窗口会自动显示,父窗口隐藏时子窗口也会自动隐藏。
返回值:
void : 无
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Webview Example</title>
<script type="text/javascript">var embed=null;// H5 plus事件处理function plusReady(){
embed=plus.webview.create("http://weibo.com/dhnetwork","",{top:"46px",bottom:"0px"});
plus.webview.currentWebview().append( embed );}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}
</script>
</head>
<body>
在Webview窗口中添加子窗口
<button onclick="plus.webview.currentWebview().close();">Back</button>
</body></html>
appendJsFile
添加Webview窗口预加载js文件
wobj.appendJsFile( file );
说明:
对于一些网络HTML页面,在无法修改HTML页面时可通过此方法自动加载本地js文件。 当Webview窗口跳转到新页面时也会自动加载指定的js执行,添加多个js文件将按照添加的先后顺序执行。
参数:
file: ( String ) 必选 窗口预加载的js文件地址
js文件路径只支持本地文件,应该使用扩展相对路径类型的文件,如"_www/preload.js"。
返回值:
void : 无
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Webview Example</title>
<script type="text/javascript">// H5 plus事件处理function plusReady(){
var nw=plus.webview.create("http://weibo.com/dhnetwork");
nw.appendJsFile("_www/preload.js");
nw.show();}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}
</script>
</head>
<body>
添加Webview窗口预加载js文件
</body></html>
back
后退到上次加载的页面
void wobj.back();
说明:
Webview窗口历史记录操作,后退到窗口上次加载的HTML页面。 如果窗口历史记录中没有可后退的页面则不触发任何操作。
参数:
无
返回值:
void : 无
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Webview Example</title>
<script type="text/javascript">var embed=null;// H5 plus事件处理function plusReady(){
embed=plus.webview.create("http://weibo.com/dhnetwork","",{top:"46px",bottom:"0px"});
plus.webview.currentWebview().append( embed );}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}// 返回上次页面function goBack() {
embed.back();}// 前进到上次页面function goForward() {
embed.forward();}
</script>
</head>
<body>
后退到上次加载的页面
<button onclick="goBack()">Back</button>
<button onclick="goForward()">Forward</button>
</body></html>
canBack
查询Webview窗口是否可后退
void wobj.canBack( queryCallback );
说明:
Webview窗口历史记录查询操作,获取Webview是否可后退到历史加载的页面,结果通过queryCallback回调方法返回。
参数:
queryCallback: ( HistoryQueryCallback ) 必选 查询历史记录操作回调函数
返回值:
void : 无
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Webview Example</title>
<script type="text/javascript">var embed=null;// H5 plus事件处理function plusReady(){
embed=plus.webview.create("http://weibo.com/dhnetwork","",{top:"46px",bottom:"0px"});
plus.webview.currentWebview().append( embed );}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}// 是否可后退function canBack() {
embed.canBack( function(e){
console.log( "是否可返回:"+e.canBack );
});}
</script>
</head>
<body>
查询Webview窗口是否可后退
<button onclick="canBack()">canBack</button>
</body></html>
canForward
查询Webview窗口是否可前进
void wobj.canForward( queryCallback );
说明:
Webview窗口历史记录查询操作,获取Webview是否可前进到历史加载的页面,结果通过queryCallback回调方法返回。
参数:
queryCallback: ( HistoryQueryCallback ) 必选 查询历史记录操作回调函数
返回值:
void : 无
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Webview Example</title>
<script type="text/javascript">var embed=null;// H5 plus事件处理function plusReady(){
embed=plus.webview.create("http://weibo.com/dhnetwork","",{top:"46px",bottom:"0px"});
plus.webview.currentWebview().append( embed );}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}// 是否可前进function canForward() {
embed.canForward( function(e){
console.log( "是否可前进:"+e.canForward );
});}
</script>
</head>
<body>
查询Webview窗口是否可前进
<button onclick="canForward()">canForward</button>
</body></html>
children
获取Webview窗口的所有子Webview窗口
Array[WebviewObject] wobj.children();
说明:
获取添加到Webview窗口中的所有子Webview窗口,如果没有子Webview窗口则返回空数组。
参数:
无
返回值:
Array[ WebviewObject ] : 包含的子Webview窗口对象数组,没有则返回空数组。
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Webview Example</title>
<script type="text/javascript">var embed=null;// H5 plus事件处理function plusReady(){
embed=plus.webview.create("http://weibo.com/dhnetwork","",{top:"46px",bottom:"0px"});
plus.webview.currentWebview().append( embed );}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}// 获取子Webview窗口function listChildren() {
var list=plus.webview.currentWebview().children();
for(var i=0;i<list.length;i++){
console.log( "Children["+i+"]: "+list[i].getURL() );
}}
</script>
</head>
<body>
获取Webview窗口的所有子Webview窗口
<button onclick="listChildren()">Children</button>
</body></html>
clear
清空原生Webview窗口加载的内容
void wobj.clear();
说明:
清除原生窗口的内容,用于重置原生窗口加载的内容,清除其加载的历史记录等内容。
参数:
无
返回值:
void : 无
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Webview Example</title>
<script type="text/javascript">var embed=null;// H5 plus事件处理function plusReady(){
embed=plus.webview.create("http://weibo.com/dhnetwork","",{top:"46px",bottom:"0px"});
plus.webview.currentWebview().append( embed );}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}// 清空Webview窗口function webviewClear() {
embed.clear();}
</script>
</head>
<body>
清空原生Webview窗口加载的内容
<button onclick="webviewClear()">Clear</button>
</body></html>
close
关闭Webview窗口
void wobj.close( aniClose, duration, extras );
说明:
关闭并销毁Webview窗口,可设置关闭动画和动画持续时间。
参数:
aniClose: ( AnimationTypeClose ) 可选 关闭Webview窗口动画效果
如果没有指定关闭窗口动画,则使用默认值“auto”,即使用显示时设置的窗口动画相对应的关闭动画。
duration: ( Number ) 可选 关闭Webview窗口的动画持续时间
单位为ms,默认为窗口show方法设定的动画时间。
extras: ( WebviewExtraOptions ) 可选 关闭Webview窗口扩展参数
可用于指定Webview窗口动画是否使用图片加速。
返回值:
void : 无
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Webview Example</title>
<script type="text/javascript">var ws=null;// H5 plus事件处理function plusReady(){
ws=plus.webview.currentWebview();}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}// 关闭窗口function closeMe() {
ws.close();}
</script>
</head>
<body>
关闭Webview窗口
<button onclick="closeMe()">Close</button>
</body></html>
draw
截屏绘制
void wobj.draw( bitmap, successCallback, errorCallback );
说明:
将Webview窗口的可视区域截屏并绘制到Bitmap图片对象中。
参数:
bitmap: ( Bitmap ) 可选 要绘制的图片对象
如果图片中已经存在内容则覆盖,如果截屏绘制失败则保留之前的图片内容。
successCallback: ( SuccessCallback ) 可选 截屏绘制操作成功回调
截屏绘制操作成功时调用。
errorCallback: ( NativeObjErrorCallback ) 必选 截屏绘制操作失败回调
截屏绘制操作失败时调用,并返回失败信息。
返回值:
void : 无
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Webview Example</title>
<script type="text/javascript">var ws=null;// H5 plus事件处理function plusReady(){
ws=plus.webview.currentWebview();}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}// 截屏绘制var bitmap=null;function captureWebview() {
bitmap = new plus.nativeObj.Bitmap("test");
// 将webview内容绘制到Bitmap对象中
ws.draw(bitmap,function(){
console.log('截屏绘制图片成功');
},function(e){
console.log('截屏绘制图片失败:'+JSON.stringify(e));
});}
</script>
</head>
<body>
截屏绘制Webview窗口<br/>
<button onclick="captureWebview()">Draw</button>
</body></html>
evalJS
在Webview窗口中执行JS脚本
void wobj.evalJS( js );
说明:
将JS脚本发送到Webview窗口中运行,可用于实现Webview窗口间的数据通讯。
参数:
options: ( String ) 必选 要在窗口中运行的脚本
返回值:
void : 无
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Webview Example</title>
<script type="text/javascript">var ws=null,embed=null;// H5 plus事件处理function plusReady(){
ws=plus.webview.currentWebview();
embed=plus.webview.create("http://weibo.com/dhnetwork","",{top:"46px",bottom:"0px"});
ws.append( embed );}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}// 在Webview窗口中执行JS脚本function evalJS() {
embed.evalJS("alert('evalJS: '+location.href);");}
</script>
</head>
<body>
在Webview窗口中执行JS脚本
<button onclick="evalJS()">evalJS</button>
</body></html>
forward
前进到上次加载的页面
void wobj.forward();
说明:
Webview窗口历史记录操作,前进到窗口上次加载的HTML页面。 如果窗口历史记录中没有可前进的页面则不触发任何操作。
参数:
无
返回值:
void : 无
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Webview Example</title>
<script type="text/javascript">var embed=null;// H5 plus事件处理function plusReady(){
embed=plus.webview.create("http://weibo.com/dhnetwork","",{top:"46px",bottom:"0px"});
plus.webview.currentWebview().append( embed );}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}// 返回上次页面function goBack() {
embed.back();}// 前进到上次页面function goForward() {
embed.forward();}
</script>
</head>
<body>
前进到上次加载的页面
<button onclick="goBack()">Back</button>
<button onclick="goForward()">Forward</button>
</body></html>
getStyle
获取Webview窗口的样式
WebviewStyle wobj.getStyle();
说明:
获取Webview窗口的样式属性,如窗口位置、大小等信息。
参数:
无
返回值:
WebviewStyle : WebviewStyle对象
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Webview Example</title>
<script type="text/javascript">var ws=null;// H5 plus事件处理function plusReady(){
ws=plus.webview.currentWebview();}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}// 获取Webview窗口的样式function getStyle() {
var style=ws.getStyle();
alert( JSON.stringify(style) );}
</script>
</head>
<body>
获取Webview窗口的样式
<button onclick="getStyle()">getStyle</button>
</body></html>
getTitle
获取Webview窗口加载HTML页面的标题
String wobj.getTitle();
说明:
标题为HTML页面head节点下title节点中的文本内容,当窗口内容发生页面内跳转时可通过窗口触发的“loaded”事件中调用此方法来获取跳转后页面的标题。 如果HTML页面没有使用title节点来设置标题,则返回空字符串。
参数:
无
返回值:
String : 窗口加载页面的标题
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Webview Example</title>
<script type="text/javascript">var ws=null,embed=null;// H5 plus事件处理function plusReady(){
ws=plus.webview.currentWebview();
embed=plus.webview.create("http://weibo.com/dhnetwork","",{top:"46px",bottom:"0px"});
embed.show();}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}// 获取Webview窗口的标题function getTitle() {
alert( "标题为:"+embed.getTitle() );}
</script>
</head>
<body>
获取Webview窗口加载HTML页面的标题
<button onclick="getTitle()">getTitle</button>
</body></html>
getURL
获取Webview窗口加载HTML页面的地址
String wobj.getURL();
说明:
当窗口内容发生页面内跳转时可通过窗口触发的“loaded”事件中调用此方法来获取跳转后页面的地址。
参数:
无
返回值:
String : 窗口加载页面的URL地址
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Webview Example</title>
<script type="text/javascript">var ws=null,embed=null;// H5 plus事件处理function plusReady(){
ws=plus.webview.currentWebview();
embed=plus.webview.create("http://weibo.com/dhnetwork","",{top:"46px",bottom:"0px"});
embed.show();}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}// 获取Webview窗口加载HTML页面的地址function getURL() {
alert( "页面地址为:"+embed.getURL() );}
</script>
</head>
<body>
获取Webview窗口加载HTML页面的地址
<button onclick="getURL()">getURL</button>
</body></html>
hide
隐藏Webview窗口
void wobj.hide( aniHide, duration, extras );
说明:
隐藏Webview窗口可保存已加载HTML页面的上下文数据,能降低应用使用的系统资源,通过show方法可将隐藏的Webview窗口显示出来。
参数:
aniHide: ( AnimationTypeClose ) 可选 隐藏Webview窗口动画效果
如果没有指定隐藏窗口动画,则使用默认动画效果“none”。
duration: ( Number ) 可选 隐藏Webview窗口的动画持续时间
单位为ms,默认为窗口show方法设定的动画时间。
extras: ( WebviewExtraOptions ) 可选 隐藏Webview窗口扩展参数
可用于指定Webview窗口动画是否使用图片加速。
返回值:
void : 无
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Webview Example</title>
<script type="text/javascript">var ws=null,embed=null;// H5 plus事件处理function plusReady(){
ws=plus.webview.currentWebview();
embed=plus.webview.create("http://weibo.com/dhnetwork","",{top:"46px",bottom:"0px"});
embed.show();}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}// 隐藏Webview窗口function hideWebview() {
embed.hide();}
</script>
</head>
<body>
隐藏Webview窗口
<button onclick="hideWebview()">hide</button>
</body></html>
isVisible
查询Webview窗口是否可见
Boolean wobj.isVisible();
说明:
若Webview窗口已经显示则返回true,若Webview窗口被隐藏则返回false。
参数:
无
返回值:
Boolean : Webview窗口是否可见
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Webview Example</title>
<script type="text/javascript">var ws=null,embed=null;// H5 plus事件处理function plusReady(){
ws=plus.webview.currentWebview();
embed=plus.webview.create("http://weibo.com/dhnetwork","",{top:"46px",bottom:"0px"});
embed.show();}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}// 查询Webview窗口是否可见function visibleWebview() {
alert( "是否可见:"+embed.isVisible() );}// 隐藏Webview窗口function hideWebview() {
embed.hide();}
</script>
</head>
<body>
查询Webview窗口是否可见
<button onclick="visibleWebview()">isVisible</button>
<button onclick="hideWebview()">hide</button>
</body></html>
loadData
加载新HTML数据
void wobj.loadData( data );
说明:
触发Webview窗口加载HTML页面数据,如果HTML数据无效将导致页面加载失败。
参数:
data: ( String ) 必选 要加载的HTML数据
返回值:
void : 无
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Webview Example</title>
<script type="text/javascript">var ws=null,embed=null;// H5 plus事件处理function plusReady(){
ws=plus.webview.currentWebview();
embed=plus.webview.create("http://weibo.com/dhnetwork","",{top:"46px",bottom:"0px"});
embed.show();}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}// 加载新HTML数据function loadHtmlData() {
embed.loadData( '<html><body>Hello! loadData!</body></html>' );}
</script>
</head>
<body>
加载新HTML数据
<button onclick="loadHtmlData()">loadData</button>
</body></html>
loadURL
加载新URL页面
void wobj.loadURL( url );
说明:
触发Webview窗口从新的URL地址加载页面,如果url地址无效将导致页面显示失败。
参数:
url: ( String ) 必选 要加载的页面URL地址
返回值:
void : 无
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Webview Example</title>
<script type="text/javascript">var ws=null,embed=null;// H5 plus事件处理function plusReady(){
ws=plus.webview.currentWebview();
embed=plus.webview.create("http://weibo.com/dhnetwork","",{top:"46px",bottom:"0px"});
embed.show();}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}// 加载新URL页面function loadHtmlUrl() {
embed.loadURL( 'http://m.csdn.net/' );}
</script>
</head>
<body>
加载新URL页面
<button onclick="loadHtmlUrl()">loadURL</button>
</body></html>
nativeInstanceObject
获取Webview窗口对象的原生(Native.JS)实例对象
InstanceObject wobj.nativeInstanceObject();
说明:
Android平台返回Webview窗口对象的android.webkit.Webview实例对象, iOS平台返回Webview窗口对象的UIWebview实例对象。
参数:
无
返回值:
InstanceObject : Webview窗口对象的原生(Native.JS)实例对象。
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Webview Example</title>
<script type="text/javascript">var nws=null;// H5 plus事件处理function plusReady(){
// 获取当前Webview实例的原生(Native.JS)实例对象
nws=plus.webview.currentWebview().nativeInstanceObject();}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}
</script>
</head>
<body>
获取Webview窗口对象的原生(Native.JS)实例对象
</body></html>
opened
获取在当前Webview窗口中创建的所有窗口
Array[WebviewObject] wobj.opened();
说明:
返回从当前Webview中调用plus.webview.open或plus.webview.create创建的所有Webview窗口数组。
参数:
无
返回值:
Array[ WebviewObject ] : 此窗口创建的Webview窗口对象数组,没有则返回空数组。
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Webview Example</title>
<script type="text/javascript">var ws=null,embed=null;// H5 plus事件处理function plusReady(){
ws=plus.webview.currentWebview();
embed=plus.webview.create("http://weibo.com/dhnetwork","",{top:"46px",bottom:"0px"});
embed.show();}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}// 获取在当前Webview窗口中创建的所有窗口function openedWebview() {
var list=ws.opened();
for(var i=0;i<list.length;i++){
alert( "opened["+i+"]: "+list[i].getURL() );
}}
</script>
</head>
<body>
获取在当前Webview窗口中创建的所有窗口
<button onclick="openedWebview()">opened</button>
</body></html>
opener
获取当前Webview窗口的创建者
WebviewObject wobj.opener();
说明:
创建者为调用plus.webview.open或plus.webview.create方法创建当前窗口的Webview窗口。
参数:
无
返回值:
WebviewObject : 创建当前窗口的Webview窗口对象
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Webview Example</title>
<script type="text/javascript">var ws=null,embed=null;// H5 plus事件处理function plusReady(){
ws=plus.webview.currentWebview();
embed=plus.webview.create("http://weibo.com/dhnetwork","",{top:"46px",bottom:"0px"});
embed.show();}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}// 取当前Webview窗口的创建者function openerWebview() {
var wo=embed.opener();
alert( "opener: "+wo.getURL() );}
</script>
</head>
<body>
获取当前Webview窗口的创建者
<button onclick="openerWebview()">opener</button>
</body></html>
parent
获取当前Webview窗口的父窗口
WebviewObject wobj.parent();
说明:
Webview窗口作为子窗口添加(Webview.append)到其它Webview窗口中时有效,这时其它Webview窗口为父窗口。
参数:
无
返回值:
WebviewObject : 父Webview窗口对象,没有则返回null。
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Webview Example</title>
<script type="text/javascript">var ws=null,embed=null;// H5 plus事件处理function plusReady(){
ws=plus.webview.currentWebview();
embed=plus.webview.create("http://weibo.com/dhnetwork","",{top:"46px",bottom:"0px"});
ws.append(embed);}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}// 获取当前Webview窗口的父窗口function parentWebview() {
var wp=embed.parent();
alert( "parent: "+wp.getURL() );}
</script>
</head>
<body>
获取当前Webview窗口的父窗口
<button onclick="parentWebview()">parent</button>
</body></html>
reload
重新加载Webview窗口显示的HTML页面
void wobj.reload( force );
说明:
触发Webview窗口重新加载当前显示的页面内容。 如果当前HTML页面未加载完则停止并重新加载,如果当前Webview窗口没有加载任何页面则无响应。
参数:
force: ( Boolean ) 必选 是否强制不使用缓存
为加速HTML页面加载速度,默认在重新加载时会使用缓存,若force设置为true则不使用缓存,重新从URL地址加载所有页面内容。
返回值:
void : 无
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Webview Example</title>
<script type="text/javascript">var ws=null,embed=null;// H5 plus事件处理function plusReady(){
ws=plus.webview.currentWebview();
embed=plus.webview.create("http://weibo.com/dhnetwork","",{top:"46px",bottom:"0px"});
embed.show();}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}// 重新加载Webview窗口显示的HTML页面function reloadWebview() {
embed.reload(true);}
</script>
</head>
<body>
重新加载Webview窗口显示的HTML页面
<button onclick="reloadWebview()">reload</button>
</body></html>
resetBounce
重置Webview窗口的回弹位置
void wobj.resetBounce();
说明:
开启窗口回弹效果后,当窗口中展现的内容滚动到头(顶部或底部)时,再拖拽时窗口整体内容将跟随移动,松开后自动回弹到停靠位置。 这时需要调用此方法来重置窗口的回弹位置,窗口将采用动画方式回弹到其初始显示的位置。
参数:
无
返回值:
void : 无
平台支持:
Android - 2.2+ (支持)
iOS - ALL (不支持)
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Webview Example</title>
<script type="text/javascript">var ws=null;// H5 plus事件处理function plusReady(){
ws=plus.webview.currentWebview();
ws.setBounce({position:{top:"100px"},changeoffset:{top:"44px"}});}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}// 重置窗口回弹位置function resetBounce(){
ws.resetBounce();}
</script>
</head>
<body style="text-align:center;">
<br/><br/><br/>
设置Webview窗口的回弹效果<br/>
回弹后显示停靠到44px的位置<br/><br/>
<button onclick="resetBounce()">重置回弹位置</button>
<br/><br/><br/>
*暂仅支持顶部的回弹效果*
</body></html>
remove
移除子Webview窗口
void wobj.remove( webview );
说明:
从当前Webview窗口移除指定的子Webview窗口,若指定的webview对象不是当前窗口的子窗口则无任何作用。 移除后子Webview窗口不会关闭,需要调用其close方法才能真正关闭并销毁。
参数:
webview: ( WebviewObject ) 必选 要移除的Webview窗口
返回值:
void : 无
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Webview Example</title>
<script type="text/javascript">var ws=null,embed=null;// H5 plus事件处理function plusReady(){
ws=plus.webview.currentWebview();
embed=plus.webview.create("http://weibo.com/dhnetwork","",{top:"46px",bottom:"0px"});
ws.append(embed);}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}// 移除子Webview窗口function removeWebview() {
ws.remove(embed);
embed.close();}
</script>
</head>
<body>
移除子Webview窗口
<button onclick="removeWebview()">remove</button>
</body></html>
removeEventListener
移除Webview窗口事件监听器
void wobj.removeEventListener( event, listener );
说明:
从Webview窗口移除通过addEventListener方法添加的事件监听器,若没有查找到对应的事件监听器,则无任何作用。
参数:
event: ( NWindowEvent ) 必选 要移除的事件类型
listener: ( EventCallback ) 必选 要移除监听函数对象
返回值:
void : 无
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Webview Example</title>
<script type="text/javascript">var ws=null,embed=null;// H5 plus事件处理function plusReady(){
ws=plus.webview.currentWebview();
embed=plus.webview.create("http://weibo.com/dhnetwork","",{top:"46px",bottom:"0px"});
embed.addEventListener( "loaded", embedLoaded, false );
ws.append(embed);}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}// 页面跳转监听器function embedLoaded(e){
alert( "Loaded: "+embed.getURL() );}// 移除Webview窗口事件监听器function removeEvent() {
embed.removeEventListener( "loaded", embedLoaded );}
</script>
</head>
<body>
移除Webview窗口事件监听器
<button onclick="removeEvent()">removeEventListener</button>
</body></html>
removeFromParent
从父窗口中移除
void wobj.removeFromParent();
说明:
从所属的父Webview窗口移除,如果没有父窗口,则无任何作用。 从父窗口中移除后子Webview窗口不会关闭,需要调用其close方法才能真正关闭并销毁。
参数:
无
返回值:
void : 无
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Webview Example</title>
<script type="text/javascript">var ws=null,embed=null;// H5 plus事件处理function plusReady(){
ws=plus.webview.currentWebview();
embed=plus.webview.create("http://weibo.com/dhnetwork","",{top:"46px",bottom:"0px"});
ws.append(embed);}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}// 从父窗口中移除function removeFromeWebview() {
embed.removeFromParent();
embed.close();}
</script>
</head>
<body>
从父窗口中移除
<button onclick="removeFromeWebview()">removeFromParent</button>
</body></html>
setBounce
设置Webview窗口的回弹效果
void wobj.setBounce( style );
说明:
开启窗口回弹效果后,当窗口中展现的内容滚动到头(顶部或底部)时,再拖拽时窗口整体内容将跟随移动,松开后自动回弹到停靠位置(可通过style设置)。 拖拽窗口内容时页面显示Webview窗口的背景色,默认为透明,此时显示Webview下面的内容,利用这个特点可以实现自定下拉刷新特效。
参数:
style: ( WebviewBounceStyle ) 必选 Webview窗口回弹样式参数
可设置窗口的回弹效果支持的方向,自动回弹后停靠的位置等参数。
返回值:
void : 无
平台支持:
Android - 2.2+ (支持)
iOS - ALL (不支持)
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Webview Example</title>
<script type="text/javascript">var ws=null;// H5 plus事件处理function plusReady(){
ws=plus.webview.currentWebview();
ws.setBounce({position:{top:"100px"},changeoffset:{top:"0px"}});}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}
</script>
</head>
<body style="text-align:center;">
<br/><br/><br/>
设置Webview窗口的回弹效果<br/><br/><br/>
*暂仅支持顶部的回弹效果*
</body></html>
setBlockNetworkImage
设置Webview窗口是否阻塞加载页面中使用的网络图片
void wobj.setBlockNetworkImage( block );
参数:
block: ( Boolean ) 必选 是否阻塞加载网络图片
true表示不加载页面中使用的网络图片,false表示加载也页面中使用的网络图片。
返回值:
void : 无
平台支持:
Android - 2.2+ (支持)
iOS - ALL (不支持)
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Webview Example</title>
<script type="text/javascript">var ws=null;// H5 plus事件处理function plusReady(){}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}function blockOpen(){
// 阻塞网络图片模式打开页面
var w=plus.webview.create("http://m.csdn.net/","csdn",{blockNetworkImage:true});
w.addEventListener("loaded",function(){
w.show("slide-in-right",300);
// 加载网络图片
w.setBlockNetworkImage(false);
},false);}
</script>
</head>
<body>
显示窗口后再加载网络图片<br/>
<button onclick="blockOpen()">打开页面</button>
</body></html>
setContentVisible
设置HTML内容是否可见
void wobj.setContentVisible( visible );
说明:
设置HTML内容不可见后,将显示Webview窗口的背景色。
参数:
visible: ( Boolean ) 必选 设置页面是否可见,true表示可见,false表示不可见
返回值:
void : 无
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Webview Example</title>
<script type="text/javascript">var ws=null,embed=null;// H5 plus事件处理function plusReady(){
ws=plus.webview.currentWebview();
embed=plus.webview.create("http://weibo.com/dhnetwork","",{top:"46px",bottom:"0px"});
ws.append(embed);}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}// 设置HTML内容是否可见function setContentVisible(v) {
embed.setContentVisible(v);}
</script>
</head>
<body>
设置HTML内容是否可见
<button onclick="setContentVisible(true)">可见</button>
<button onclick="setContentVisible(false)">不可见</button>
</body></html>
setPullToRefresh
设置Webview窗口的下拉刷新效果
void wobj.setPullToRefresh( style, refreshCB );
说明:
开启Webview窗口的下拉刷新功能,显示窗口内置的下拉刷新控件样式。
参数:
style: ( WebviewRefreshStyle ) 必选 Webview窗口下拉刷新样式参数
可设置窗口内置的下拉刷新控件在各种状态显示的文字内容。
refreshCB: ( SuccessCallback ) 必选 Webview窗口下拉刷新事件回调
用户操作窗口的下拉刷新触发窗口刷新事件时触发。
返回值:
void : 无
平台支持:
Android - 2.2+ (支持)
iOS - ALL (支持)
示例:
<!DOCTYPE HTML><html>
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0, user-scalable=no"/>
<meta name="HandheldFriendly" content="true"/>
<meta name="MobileOptimized" content="320"/>
<title>Webview Example</title>
<script type="text/javascript" charset="utf-8">var ws=null;var list=null;// 扩展API加载完毕,现在可以正常调用扩展API function plusReady(){
ws=plus.webview.currentWebview();
ws.setPullToRefresh({support:true,
height:"50px",
range:"200px",
contentdown:{
caption:"下拉可以刷新"
},
contentover:{
caption:"释放立即刷新"
},
contentrefresh:{
caption:"正在刷新..."
}
},onRefresh);
plus.nativeUI.toast("下拉可以刷新");}// 判断扩展API是否准备,否则监听"plusready"事件if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}// DOM构建完成获取列表元素
document.addEventListener("DOMContentLoaded",function(){
list=document.getElementById("list");})// 刷新页面function onRefresh(){
setTimeout(function(){
if(list){
var item=document.createElement("li");
item.innerHTML="<span>New Item "+(new Date())+"</span>";
list.insertBefore(item,list.firstChild);
}
ws.endPullToRefresh();
},2000);}
</script>
<link rel="stylesheet" href="../css/common.css" type="text/css" charset="utf-8"/>
<style type="text/css">
li {
padding: 1em;
border-bottom: 1px solid #eaeaea;}
li:active {
background: #f4f4f4;}
</style>
</head>
<body>
<ul id="list" style="list-style:none;margin:0;padding:0;">
<li><span>Initializ List Item 1</span></li>
<li><span>Initializ List Item 2</span></li>
<li><span>Initializ List Item 3</span></li>
<li><span>Initializ List Item 4</span></li>
<li><span>Initializ List Item 5</span></li>
<li><span>Initializ List Item 6</span></li>
<li><span>Initializ List Item 7</span></li>
<li><span>Initializ List Item 8</span></li>
<li><span>Initializ List Item 9</span></li>
<li><span>Initializ List Item 10</span></li>
</ul>
</body></html>
setStyle
设置Webview窗口的样式
void wobj.setStyle( styles );
说明:
更新Webview窗口的样式,如窗口位置、大小、背景色等。
参数:
styles: ( WebviewStyle ) 必选 要设置的窗口样式
返回值:
void : 无
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Webview Example</title>
<script type="text/javascript">var ws=null,embed=null;// H5 plus事件处理function plusReady(){
ws=plus.webview.currentWebview();
embed=plus.webview.create("http://weibo.com/dhnetwork","",{top:"46px",bottom:"0px"});
ws.append(embed);}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}// 设置Webview窗口的样式function updateStyle() {
embed.setStyle( {top:"92px"} );}
</script>
</head>
<body>
设置Webview窗口的样式
<button onclick="updateStyle()">setStyle</button>
</body></html>
setJsFile
设置预加载的JS文件
void wobj.setJsFile( path );
说明:
预加载JS文件不需要在HTML页面中显式引用,在Webview窗口加载HTML页面时自动加载,在页面跳转时也会自动加载。 设置新的JS文件后将清空之前设置的值。
参数:
file: ( String ) 必选 预载入的JS文件地址,仅支持本地文件,格式为相对路径URL(plus.io.RelativeURL),如"_www/preload.js"
返回值:
void : 无
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Webview Example</title>
<script type="text/javascript">var ws=null,embed=null;// H5 plus事件处理function plusReady(){
ws=plus.webview.currentWebview();
embed=plus.webview.create("http://weibo.com/dhnetwork","",{top:"46px",bottom:"0px"});
embed.setJsFile( "_www/js/preload.js" );
ws.append(embed);}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}
</script>
</head>
<body>
设置预加载的JS文件
</body></html>
show
显示Webview窗口
void wobj.show( aniShow, duration, showedCB, extras );
说明:
当调用plus.webview.create方法创建Webview窗口后,需要调用其show方法才能显示,并可设置窗口显示动画及动画时间。 Webview窗口被隐藏后也可调用此方法来重新显示。
参数:
aniShow: ( AnimationTypeShow ) 可选 Webview窗口显示动画类型
如果没有指定窗口动画类型,则使用默认值“none”,即无动画。
duration: ( Number ) 可选 Webview窗口显示动画持续时间
单位为ms,默认使用动画类型想对应的默认时间。
showedCB: ( SuccessCallback ) 可选 Webview窗口显示完成的回调函数
当指定Webview窗口显示动画执行完毕时触发回调函数,窗口无动画效果(如"none"动画效果)时也会触发此回调。
extras: ( WebviewExtraOptions ) 可选 显示Webview窗口扩展参数
可用于指定Webview窗口动画是否使用图片加速。
返回值:
void : 无
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Webview Example</title>
<script type="text/javascript">var ws=null,embed=null;// H5 plus事件处理function plusReady(){
ws=plus.webview.currentWebview();}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}// 创建并显示Webview窗口function showWebview(){
embed=plus.webview.create("http://weibo.com/dhnetwork","",{top:"46px",bottom:"0px"});
embed.show( "slide-in-right", 300 );}
</script>
</head>
<body>
显示Webview窗口
<button onclick="showWebview()">show</button>
</body></html>
stop
停止加载HTML页面内容
void wobj.stop();
说明:
触发Webview窗口停止加载页面内容,如果已经加载部分内容则显示部分内容,如果加载完成则显示全部内容。
参数:
无
返回值:
void : 无
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Webview Example</title>
<script type="text/javascript">var ws=null,embed=null;// H5 plus事件处理function plusReady(){
ws=plus.webview.currentWebview();
embed=plus.webview.create("http://weibo.com/dhnetwork","",{top:"46px",bottom:"0px"});
ws.append(embed);}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}// 停止加载HTML页面内容function stopWebview(){
embed.stop();}
</script>
</head>
<body>
停止加载HTML页面内容
<button onclick="stopWebview()">stop</button>
</body></html>
onclose
Webview窗口关闭事件
说明:
EventCallback 类型
当Webview窗口关闭时触发此事件,类型为EventCallback。
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Webview Example</title>
<script type="text/javascript">var ws=null,embed=null;// H5 plus事件处理function plusReady(){
ws=plus.webview.currentWebview();
embed=plus.webview.create("http://weibo.com/dhnetwork","",{top:"46px",bottom:"0px"});
embed.onclose=embedClose;
ws.append(embed);}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}// 页面关闭事件回调函数function embedClose(e){
alert( "Closed!" );}
</script>
</head>
<body>
Webview窗口关闭事件
<button onclick="embed.close()">onclose</button>
</body></html>
onerror
Webview窗口错误事件
说明:
WebviewEvent 类型
当Webview窗口加载错误时触发此事件,类型为EventCallback。
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Webview Example</title>
<script type="text/javascript">var ws=null,embed=null;// H5 plus事件处理function plusReady(){
ws=plus.webview.currentWebview();
embed=plus.webview.create("http://weibo.com/dhnetwork","",{top:"46px",bottom:"0px"});
embed.onerror=embedError;
ws.append(embed);}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}// 页面错误事件回调函数function embedError(e){
alert( "Error!" );}
</script>
</head>
<body>
Webview窗口错误事件
<button onclick="embed.loadData('<xml>Not html</xml>')">onerror</button>
</body></html>
onloaded
Webview窗口页面加载完成事件
说明:
WebviewEvent 类型
当Webview窗口页面加载完成时触发此事件,类型为EventCallback。
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Webview Example</title>
<script type="text/javascript">var ws=null,embed=null;// H5 plus事件处理function plusReady(){
ws=plus.webview.currentWebview();
embed=plus.webview.create("http://weibo.com/dhnetwork","",{top:"46px",bottom:"0px"});
embed.onloaded=embedLoaded;
ws.append(embed);}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}// 页面加载完成事件回调函数function embedLoaded(e){
alert( "Loaded!" );}
</script>
</head>
<body>
Webview窗口页面加载完成事件
<button onclick="embed.loadURL('http://m.csdn.net')">onloaded</button>
</body></html>
onloading
Webview窗口页面开始加载事件
说明:
WebviewEvent 类型
当Webview窗口开始加载新页面时触发此事件,类型为EventCallback。
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Webview Example</title>
<script type="text/javascript">var ws=null,embed=null;// H5 plus事件处理function plusReady(){
ws=plus.webview.currentWebview();
embed=plus.webview.create("http://weibo.com/dhnetwork","",{top:"46px",bottom:"0px"});
embed.onloading=embedLoading;
ws.append(embed);}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}// 页面开始加载事件回调函数function embedLoading(e){
alert( "Loading!" );}
</script>
</head>
<body>
Webview窗口页面开始加载事件
<button onclick="embed.loadURL('http://m.csdn.net')">onloading</button>
</body></html>
WebviewBounceStyle
Webview窗口回弹样式
属性:
position: (JSON 类型 )Webview窗口支持回弹效果的方向
可通过此参数设置开启Webview哪个方向支持回弹效果。 支持以下属性: top:表示窗口顶部支持回弹效果; left:表示窗口左侧支持回弹效果; right:表示窗口右侧支持回弹效果; bottom:表示窗口底部支持回弹效果。 **目前仅支持top属性** 属性值:用于指定可拖拽的范围,可取百分比,如"10%";像素值,如"100px";自动计算值,如"auto";无回弹效果值,如"none";
changeoffset: (JSON 类型 )Webview窗口回弹时停靠的位置
开启窗口回弹效果后,当窗口中展现的内容滚动到头(顶部或底部)时,再拖拽时窗口整体内容将跟随移动,拖拽过程中将触发"dragBounce"事件,松开后自动回弹到停靠位置。 支持以下属性: top:表示窗口顶部回弹时停靠的位置。 属性值:用于指定窗口回弹的位置,可取百分比,如"5%";像素值,如"100px";自动计算值,如"auto",默认为可拖拽的范围值的一半;
slideoffset: (JSON 类型 )Webview窗口侧滑时停靠的位置
开启窗口回弹效果后,当窗口中展现的内容滚动到头(左侧或右侧)时,在拖拽时窗口整体内容将跟随移动,松开后自动停靠的侧滑位置,并触发"slideBounce"事件。 支持以下属性: left:表示窗口左侧侧滑的位置; right:表示窗口右侧侧滑的位置。 属性值:用于指定滑动后停靠的距离,可取百分比(left/right相对于窗口的宽度,top/bottom相对于窗口的高度),如"30%";像素值,如"100px";自动计算值,为可拖拽范围,如"auto"。
offset: (JSON 类型 )Webview窗口拖拽偏移的位置
开启窗口回弹效果后,可以通过此属性值来主动设置拖拽的偏移位置,与手动操作拖拽至此偏移位置松开后的逻辑一致。 支持以下属性: top:表示窗口顶部偏移的位置; left:表示窗口左侧偏移的位置; right:表示窗口右侧偏移的位置; bottom:表示窗口底部偏移的位置。 属性值:用于指定偏移的位置,可取百分比,如"5%";像素值,如"100px";有效值范围为0到position属性定义的位置。
preventTouchEvent: (Boolean 类型 )Webview窗口是否阻止touch事件传递给DOM元素
设置为true表示阻止touch事件,设置为false表示不阻止touch事件。当开启侧滑功能(左侧滑和右侧滑)时默认值为true,否则为false。
平台支持
Android - 2.3+ (支持): 由于Touch事件存在冲突,如果Webview使用侧滑功能,需要将Webview设置为阻止touch事件传递才能触发。 当html页面内容需要处理横向滚动时并且也需要侧滑效果时,需初始化时设置不阻止touch事件传递:webview.setBounce({position:{left:"100px"},solideoffset:{left:"auto"},preventTouchEvent:false});。当操作非横向滚动元素时及时动态设置阻止touch事件传递以触发侧滑效果:webview.setBounce({preventTouchEvent:true});。
iOS - 5.1+ (不支持): Touch事件不存在冲突,不支持此功能。
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Webview Example</title>
<script type="text/javascript">var ws=null;// H5 plus事件处理function plusReady(){
ws=plus.webview.currentWebview();
ws.setBounce({position:{top:"100px"},changeoffset:{top:"44px"}});}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}// 重置窗口回弹位置function resetBounce(){
ws.resetBounce();}
</script>
</head>
<body style="text-align:center;">
<br/><br/><br/>
设置Webview窗口的回弹效果<br/>
回弹后显示停靠到44px的位置<br/><br/>
<button onclick="resetBounce()">重置回弹位置</button>
<br/><br/><br/>
*暂仅支持顶部的回弹效果*
</body></html>
WebviewDock
原生控件在窗口中停靠的方式
常量:
"top": (String 类型 )控件停靠则页面顶部
"bottom": (String 类型 )控件停靠在页面底部
"right": (String 类型 )控件停靠在页面右侧
"left": (String 类型 )控件停靠在页面左侧
WebviewEvent
Webview窗口事件
常量:
"close": (String 类型 )Webview窗口关闭事件
通过WebviewObject对象的addEventListener方法添加事件监听函数,当Webview窗口关闭时触发此事件,回调函数类型为EventCallback。
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Webview Example</title>
<script type="text/javascript">var nw=null;// H5 plus事件处理function plusReady(){}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}
// 监听Webview窗口关闭事件function eventTest(){
if(nw){return;}
// 打开新窗口
nw=plus.webview.create( "http://weibo.com/dhnetwork", {top:"46px",bottom:"0px"} );
nw.addEventListener( "close", function(e){
console.log( "Webview closed!" );
nw=null;
}, false );
nw.show(); // 显示窗口}
</script>
</head>
<body>
Webview窗口关闭事件
<button onclick="eventTest()">start</button>
<button onclick="nw.close()">close</button>
</body></html>
"dragBounce": (String 类型 )Webview窗口回弹事件
通过WebviewObject对象的setBounce方法开启回弹效果设置顶部下拉回弹changeoffset属性后,当用户向下拖拽窗口时触发发此事件,回调函数类型为BounceEventCallback。
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Webview Example</title>
<script type="text/javascript">var ws=null;// H5 plus事件处理function plusReady(){
ws=plus.webview.currentWebview();
ws.setBounce({position:{top:"100px"},changeoffset:{top:"44px"}});
ws.addEventListener("dragBounce",onPullStateChange,false);}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}// 下拉状态改变function onPullStateChange(e){
switch(e.status){
case "beforeChangeOffset":
console.log("顶部回弹:可继续往下拖拽");
break;
case "afterChangeOffset":
console.log("顶部回弹:松开会重置回弹位置");
break;
case "dragEndAfterChangeOffset":
console.log("顶部回弹:松开停靠回弹");
break;
default:
break;
}}// 重置窗口回弹位置function resetBounce(){
ws.resetBounce();}
</script>
</head>
<body style="text-align:center;">
<br/><br/><br/>
设置Webview窗口的回弹效果<br/>
回弹后显示停靠到44px的位置<br/><br/>
<button onclick="resetBounce()">重置回弹位置</button>
<br/><br/><br/>
*暂仅支持顶部的回弹效果*
</body></html>
"slideBounce": (String 类型 )Webview窗口回弹事件
通过WebviewObject对象的setBounce方法开启回弹效果设置左右侧侧滑slideoffset属性后,当用户向左右侧拖拽窗口侧滑时触发发此事件,回调函数类型为BounceEventCallback。
"error": (String 类型 )Webview窗口加载错误事件
通过WebviewObject对象的addEventListener方法添加事件监听函数,当Webview窗口加载错误时触发此事件,回调函数类型为EventCallback。
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Webview Example</title>
<script type="text/javascript">var nw=null;// H5 plus事件处理function plusReady(){}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}
// 监听Webview窗口加载错误事件function eventTest() {
// 打开新窗口
nw=plus.webview.create( "", {top:"46px",bottom:"0px"} );
nw.addEventListener( "error", function(e){
console.log( "Error: "+nw.getURL() );
}, false );
nw.show(); // 显示窗口}
</script>
</head>
<body>
Webview窗口加载错误事件
<button onclick="eventTest()">start</button>
<button onclick="nw.loadURL('http://bucunzaideyuming.abcdeg')">error</button>
</body></html>
"hide": (String 类型 )Webview窗口隐藏事件
通过WebviewObject对象的addEventListener方法添加事件监听函数,当Webview窗口隐藏(窗口动画完成后)时触发此事件,回调函数类型为EventCallback。
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Webview Example</title>
<script type="text/javascript">var nw=null;// H5 plus事件处理function plusReady(){
createWebview();}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}
// 创建Webview窗口监听show、hide事件function createWebview(){
// 打开新窗口
nw=plus.webview.create( "http://m.csdn.net/", {top:"46px",bottom:"0px"} );
nw.addEventListener( "show", function(e){
console.log( "Webview Showed" );
}, false );
nw.addEventListener( "hide", function(e){
console.log( "Webview Hided" );
}, false );}// 显示Webview窗口function showWebview(){
nw.show( "slide-in-right" );}// 隐藏Webview窗口function hideWebview(){
nw.hide();}
</script>
</head>
<body>
Webview窗口显示隐藏事件
<button onclick="showWebview()">Show</button>
<button onclick="hideWebview()">Hide</button>
</body></html>
"loading": (String 类型 )Webview窗口页面开始加载事件
通过WebviewObject对象的addEventListener方法添加事件监听函数,当Webview窗口开始加载新页面时触发此事件,回调函数类型为EventCallback。
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Webview Example</title>
<script type="text/javascript">var nw=null;// H5 plus事件处理function plusReady(){}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}
// 监听Webview窗口页面开始加载事件function eventTest() {
// 打开新窗口
nw=plus.webview.create( "", {top:"46px",bottom:"0px"} );
nw.addEventListener( "loading", function(e){
console.log( "Loading: "+nw.getURL() );
}, false );
nw.show(); // 显示窗口}
</script>
</head>
<body>
Webview窗口页面开始加载事件
<button onclick="eventTest()">start</button>
<button onclick="nw.loadURL('http://m.csdn.net')">loading</button>
</body></html>
"loaded": (String 类型 )Webview窗口页面加载完成事件
通过WebviewObject对象的addEventListener方法添加事件监听函数,当Webview窗口页面加载完成时触发此事件,回调函数类型为EventCallback。
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Webview Example</title>
<script type="text/javascript">var nw=null;// H5 plus事件处理function plusReady(){}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}
// 监听Webview窗口页面加载完成事件function eventTest() {
// 打开新窗口
nw=plus.webview.create( "", "", {top:"46px",bottom:"0px"} );
nw.addEventListener( "loaded", function(e){
console.log( "Loaded: "+nw.getURL() );
}, false );
nw.show(); // 显示窗口}
</script>
</head>
<body>
Webview窗口页面加载完成事件
<button onclick="eventTest()">start</button>
<button onclick="nw.loadURL('http://m.csdn.net')">loaded</button>
</body></html>
"maskClick": (String 类型 )Webview窗口显示遮罩层时点击事件
通过WebviewObject对象的addEventListener方法添加事件监听函数,当Webview窗口通过mask属性设置显示遮罩层并且点击时触发此事件,回调函数类型为EventCallback。
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Webview Example</title>
<script type="text/javascript">var ws=null;// H5 plus事件处理function plusReady(){
ws=plus.webview.currentWebview();
// 显示遮罩层
ws.setStyle({mask:"rgba(0,0,0,0.5)"});
// 点击关闭遮罩层
ws.addEventListener("maskClick",function(){
ws.setStyle({mask:"none"});
},false);}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}
</script>
</head>
<body>
Webview窗口页面加载完成事件
<br/>
点击窗口关闭遮罩层
</body></html>
"show": (String 类型 )Webview窗口显示事件
通过WebviewObject对象的addEventListener方法添加事件监听函数,当Webview窗口显示(窗口动画完成后)时触发此事件,回调函数类型为EventCallback。
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Webview Example</title>
<script type="text/javascript">var nw=null;// H5 plus事件处理function plusReady(){
createWebview();}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}
// 创建Webview窗口监听show、hide事件function createWebview(){
// 打开新窗口
nw=plus.webview.create( "http://m.csdn.net/", "", {top:"46px",bottom:"0px"} );
nw.addEventListener( "show", function(e){
console.log( "Webview Showed" );
}, false );
nw.addEventListener( "hide", function(e){
console.log( "Webview Hided" );
}, false );}// 显示Webview窗口function showWebview(){
nw.show( "slide-in-right" );}// 隐藏Webview窗口function hideWebview(){
nw.hide();}
</script>
</head>
<body>
Webview窗口显示隐藏事件
<button onclick="showWebview()">Show</button>
<button onclick="hideWebview()">Hide</button>
</body></html>
"popGesture": (String 类型 )Webview窗口侧滑返回事件
通过WebviewObject对象的addEventListener方法添加事件监听函数,当Webview窗口侧滑返回时触发此事件,回调函数类型为PopGestureCallback。
平台支持
Android - 2.2+ (不支持): 不支持侧滑返回功能,不会触发此事件。
iOS - ALL (支持): Webview设置侧滑返回功能才能触发此事件。
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Webview Example</title>
<script type="text/javascript">var nw=null;// H5 plus事件处理function plusReady(){
createWebview();}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}
// 创建Webview窗口监听侧滑返回事件function createWebview(){
// 打开新窗口
nw=plus.webview.create( "http://m.csdn.net/","",{top:"100px",bottom:"0px",popGesture:"hide"} );
nw.addEventListener( "popGesture", function(e){
poplog.innerText="popGesture: "+e.type+","+e.result+","+e.progress;
}, false );}// 显示Webview窗口function showWebview(){
nw.show( "slide-in-right" );}// 隐藏Webview窗口function hideWebview(){
nw.hide();}// 关闭窗口function closeWebview(){
nw.close();
plus.webview.currentWebview().close();}
</script>
</head>
<body>
Webview窗口侧滑返回事件
<button onclick="closeWebview()">Close</button>
<button onclick="showWebview()">Show</button>
<button onclick="hideWebview()">Hide</button>
<div id="poplog"></div>
</body></html>
"titleUpdate": (String 类型 )Webview加载页面标题更新事件
通过WebviewObject对象的addEventListener方法添加事件监听函数,当Webview窗口加载新页面更新标题时触发此事件,回调函数类型为SuccessCallback。 注意:此事件会先于loaded事件触发,通常在加载网络页面时通过此事件可更快获取到页面的标题。
平台支持
Android - 2.2+ (支持)
iOS - 5.1+ (支持)
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Webview Example</title>
<script type="text/javascript">var nw=null;// H5 plus事件处理function plusReady(){
createWebview();}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}
// 创建Webview窗口监听侧滑返回事件function createWebview(){
// 打开新窗口
nw=plus.webview.create( "http://weibo.com/dhnetwork/","",{top:"100px",bottom:"0px"} );
nw.addEventListener( "titleUpdate", function(e){
console.log("Update title: "+e.title);
}, false );
plus.webview.currentWebview().append(nw);}
</script>
</head>
<body>
Webview窗口标题更新事件
<button onclick="closeWebview()">New</button>
</body></html>
WebviewRefreshStyle
Webview窗口下拉刷新样式
属性:
support: (Boolean 类型 )是否开启Webview窗口的下拉刷新功能
true表示开启窗口的下拉刷新功能; false表示关闭窗口的下拉刷新功能。
height: (String 类型 )窗口的下拉刷新控件高度
支持百分比,如"10%";像素值,如"50px"。
range: (String 类型 )窗口可下拉拖拽的范围
支持百分比,如"10%";像素值,如"50px"。
contentdown: (JSON 类型 )在下拉可刷新状态时显示的内容
支持以下属性: caption:在下拉可刷新状态时下拉刷新控件上显示的标题内容。
contentover: (JSON 类型 )在释放可刷新状态时显示的内容
支持以下属性: caption:在释放可刷新状态时下拉刷新控件上显示的标题内容。
contentrefresh: (JSON 类型 )在正在刷新状态时显示的内容
支持以下属性: caption:在正在刷新状态时下拉刷新控件上显示的标题内容。
示例:
<!DOCTYPE HTML><html>
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0, user-scalable=no"/>
<meta name="HandheldFriendly" content="true"/>
<meta name="MobileOptimized" content="320"/>
<title>Webview Example</title>
<script type="text/javascript" charset="utf-8">var ws=null;var list=null;// 扩展API加载完毕,现在可以正常调用扩展API function plusReady(){
ws=plus.webview.currentWebview();
ws.setPullToRefresh({support:true,
height:"50px",
range:"200px",
contentdown:{
caption:"下拉可以刷新"
},
contentover:{
caption:"释放立即刷新"
},
contentrefresh:{
caption:"正在刷新..."
}
},onRefresh);
plus.nativeUI.toast("下拉可以刷新");}// 判断扩展API是否准备,否则监听"plusready"事件if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}// DOM构建完成获取列表元素
document.addEventListener("DOMContentLoaded",function(){
list=document.getElementById("list");})// 刷新页面function onRefresh(){
setTimeout(function(){
if(list){
var item=document.createElement("li");
item.innerHTML="<span>New Item "+(new Date())+"</span>";
list.insertBefore(item,list.firstChild);
}
ws.endPullToRefresh();
},2000);}
</script>
<link rel="stylesheet" href="../css/common.css" type="text/css" charset="utf-8"/>
<style type="text/css">
li {
padding: 1em;
border-bottom: 1px solid #eaeaea;}
li:active {
background: #f4f4f4;}
</style>
</head>
<body>
<ul id="list" style="list-style:none;margin:0;padding:0;">
<li><span>Initializ List Item 1</span></li>
<li><span>Initializ List Item 2</span></li>
<li><span>Initializ List Item 3</span></li>
<li><span>Initializ List Item 4</span></li>
<li><span>Initializ List Item 5</span></li>
<li><span>Initializ List Item 6</span></li>
<li><span>Initializ List Item 7</span></li>
<li><span>Initializ List Item 8</span></li>
<li><span>Initializ List Item 9</span></li>
<li><span>Initializ List Item 10</span></li>
</ul>
</body></html>
WebviewPosition
原生控件在窗口中显示的位置
常量:
"static": (String 类型 )控件在页面中正常定位,如果页面存在滚动条则随窗口内容滚动
"absolute": (String 类型 )控件在页面中绝对定位,如果页面存在滚动条不随窗口内容滚动
"dock": (String 类型 )控件在页面中停靠,停靠的位置通过dock属性进行定义
WebviewStyle
JSON对象,原生窗口设置参数的对象
属性:
background: (String 类型 )窗口的背景颜色
窗口空白区域的背景模式,设置background为颜色值(参考CSS Color Names,可取值/十六进制值/rgb值/rgba值),窗口为独占模式显示(占整个屏幕区域); 设置background为“transparent”,则表示窗口背景透明,为非独占模式。
平台支持
Android - 2.2+ (支持): Android平台4.0以上系统才支持“transparent”背景透明样式,4.0以下系统窗口显示白色背景。
iOS - 5.0+ (支持): iOS平台不支持“transparent”背景透明样式,默认背景使用白色背景。
blockNetworkImage: (Boolean 类型 )是否阻塞网络图片的加载
布尔类型,true表示阻塞,false表示不阻塞,默认值为false。 阻塞后Webview窗口将不加载页面中使用的所有网络图片,可通过Webview窗口对象的setBlockNetWorkImage()方法动态修改此状态。
平台支持
Android - 2.2+ (支持)
iOS - 5.0+ (不支持): 忽略此属性,Webview窗口加载页面中所有图片。
bottom: (String 类型 )窗口垂直向上的偏移量
支持百分比、像素值,当设置了top和height值时,此属性值忽略;
bounce: (String 类型 )窗口遇到边框是否有反弹效果
可取值:none表示没有反弹效果;vertical表示垂直方向有反弹效果;horizontal表示水平方向有反弹效果;all表示垂直和水平方向都有反弹效果。
平台支持
Android - ALL (支持): 默认值为"none",无法单独控制垂直和水平方向(即"vertical","horizontal","all"都表示开启反弹效果)。 无法动态修改,只能在创建时设置此值。
iOS - 5.1.1+ (支持): 默认值为none,垂直和水平方向都没有反弹效果。
bounceBackground: (String 类型 )窗口回弹效果区域的背景
窗口回弹效果区域背景可支持颜色值或图片: 颜色值格式为"#RRGGBB",如"#FFFFFF"为设置白色背景; 背景图为"url(%image path%)",如"url(./icon.png)"为设置icon.png为背景图,图片采用平铺模式绘制。
平台支持
Android - (不支持)
iOS - 5.0+ (支持): 默认值为系统窗口背景色,通常为黑色。
dock: (WebviewDock 类型 )窗口的停靠方式
当Webview窗口添加到另外一个窗口中时,停靠方式才会生效,采用停靠方式添加会导致原Webview窗口自动调整其大小避免其内容呗子窗口盖住。 可取值:"top",控件停靠则页面顶部;"bottom",控件停靠在页面底部;"right",控件停靠在页面右侧;"left",控件停靠在页面左侧。
平台支持
Android - 2.2+ (支持)
iOS - 5.0+ (支持)
errorPage: (String 类型 )窗口加载错误时跳转的页面地址
当Webview窗口无法加载指定的url地址时(如本地页面不存在,或者无法访问的网络地址),此时会自动跳转到指定的错误页面地址(仅支持本地页面地址)。 设置为“none”则关闭跳转到错误页面功能,此时页面显示Webview默认的错误页面内容。默认使用5+ Runtime内置的错误页面。
平台支持
Android - 2.2+ (支持)
iOS - 5.0+ (支持)
hardwareAccelerated: (Boolean 类型 )窗口是否开启硬件加速
布尔类型,true表示开启硬件加速,false表示不开启硬件加速,默认情况5+ Runtime会根据设备实际支持情况自动选择是否开启硬件加速,可以通过plus.webview.defauleHardwareAccelerated()方法获取默认Webview是否开启硬件加速。 由于不同设备对硬件加速的支持情况存在差异,开启硬件加速能加速HTML页面的渲染,但也会消耗更多的系统资源,从而导致在部分设备上可能出现闪屏、发虚、分块渲染等问题,因此在特定设备的特定页面如果出现以上问题需要手动设置关闭硬件加速来避免。
平台支持
Android - 2.3+ (支持): 注意: 1. 如果在页面中使用Video标签播放视频则必须打开硬件加速功能; 2. 页面必须在创建时确定是否打开硬件加速功能,无法动态切换页面的硬件加速开关; 3. 首页Webview窗口是否开启硬件加速需在manifest.json中plus节点下的hardwareAccelerated属性值控制。
iOS - 5.1+ (不支持): 忽略此属性。
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Webview Example</title>
<script type="text/javascript">// H5 plus事件处理function plusReady(){}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}
// 创建新窗口并设置开启硬件加速function create(){
var styles={};
// 在Android5以上设备,如果默认没有开启硬件加速,则强制设置开启
if(!plus.webview.defauleHardwareAccelerated()&&parseInt(plus.os.version)>=5){
styles.hardwareAccelerated=true;
}
var w = plus.webview.create( "http://weibo.com/dhnetwork", "test", styles );
plus.webview.show( w ); // 显示窗口}
</script>
</head>
<body>
开启硬件加速显示Webview窗口<br/>
<button onclick="create()">Create</button>
</body></html>
height: (String 类型 )窗口的高度
支持百分比、像素值,默认为100%。未设置height属性值时,可同时设置top和bottom属性值改变窗口的默认高度。
left: (String 类型 )窗口水平向右的偏移量
支持百分比、像素值,默认值为0px。未设置left属性值时,可设置right属性值改变窗口的默认left位置。
margin: (String 类型 )窗口的边距
用于定位窗口的位置,支持auto,auto表示居中。若设置了left、right、top、bottom则对应的边距值失效。
mask: (String 类型 )窗口的遮罩
用于设置Webview窗口的遮罩层样式,遮罩层会覆盖Webview中所有内容,包括子webview,并且截获webview的所有触屏事件,此时Webview窗口的点击操作会触发maskClick事件。 字符串类型,可取值: rgba格式字符串,定义纯色遮罩层样式,如"rgba(0,0,0,0.5)",表示黑色半透明; "none",表示不使用遮罩层; 默认值为"none",即无遮罩层。
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Webview Example</title>
<script type="text/javascript">var ws=null;// H5 plus事件处理function plusReady(){
ws=plus.webview.currentWebview();
// 显示遮罩层
ws.setStyle({mask:"rgba(0,0,0,0.5)"});
// 点击关闭遮罩层
ws.addEventListener("maskClick",function(){
ws.setStyle({mask:"none"});
},false);}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}
</script>
</head>
<body>
Webview窗口页面加载完成事件
<br/>
点击窗口关闭遮罩层
</body></html>
opacity: (Number 类型 )窗口的不透明度
0为全透明,1为不透明,默认值为1,即不透明。
平台支持
Android - 2.2+ (支持): 需Android4.0及以上平台才支持,Android4.0以前平台忽略此属性。
iOS - 4.3+ (支持)
popGesture: (String 类型 )窗口的侧滑返回功能
可取值"none":无侧滑返回功能;"close":侧滑返回关闭Webview窗口;"hide":侧滑返回隐藏webview窗口。 仅iOS平台支持。
平台支持
Android - 2.2+ (不支持): 忽略此属性。
iOS - 5.0+ (支持)
// 创建webview支持侧滑返回:var wv=plus.webview.create('url','id',{'popGesture':'close'});
wv.show();// 或这样写var wv=plus.webview.open('url','id',{'popGesture':'close'});
// 动态改变webview的侧滑返回功能:var wv=plus.webview.currentWebview();// 关闭侧滑返回功能
wv.setStyle({'popGesture':'none'});// 侧滑返回后关闭webview
wv.setStyle({'popGesture':'close'});// 侧滑返回后隐藏webview
wv.setStyle({'popGesture':'hide'});
render: (String 类型 )窗口渲染模式
支持以下属性值: "onscreen" - Webview窗口在屏幕区可见时渲染,不可见时不进行渲染,此时能减少内存使用量; "always" - Webview在任何时候都渲染,在内存较大的设备上使用,被遮挡的窗口在此中模式下显示的时候会有更流畅的效果。 默认值为"onscreen"。 仅Android平台支持。
平台支持
Android - 2.2+ (支持)
iOS - 4.3+ (不支持)
right: (String 类型 )窗口水平向左的偏移量
支持百分比、像素值,默认无值。当设置了left和width值时,此属性值忽略;
scalable: (Boolean 类型 )窗口是否可缩放
窗口设置为可缩放(scalable:true)时,用户可通过双指操作放大或缩小页面,此时html页面可通过meta节点设置“name="viewport" content="user-scalable=no"”来限制页面不可缩放。 窗口设置为不可缩放(scalable:false)时,用户不可通过双指操作放大或缩小页面,即使页面中的meta节点也无法开启可缩放功能。 默认值为false,即不可缩放。
scrollIndicator: (String 类型 )窗口是否显示滚动条
用于控制窗口滚动条样式,可取值: "all":垂直和水平滚动条都显示; "vertical":仅显示垂直滚动条; "horizontal":仅显示水平滚动条; "none":垂直和水平滚动条都不显示。 默认值为"all",即垂直和水平滚动条都显示。 注意:显示滚动条的前提条件是窗口中的内容超过窗口显示的宽或高。
scrollsToTop: (Boolean 类型 )点击设备的状态栏时是否滚动返回至顶部
true表示点击设备的状态栏可以滚动返回至顶部,false表示点击设备的状态栏不可以,默认值为true。 此功能仅iOS平台支持,在iPhone上有且只有一个Webview窗口的scrollsToTop属性值为true时才生效,所以在显示和关闭Webview窗口时需动态更新所有Webview的scrollsToTop值,已确保此功能生效。
平台支持
Android - ALL (不支持)
iOS - 5.0+ (支持)
softinputMode: (String 类型 )弹出系统软键盘模式
可选值:“adjustPan”- 弹出软键盘时Webview窗口自动上移,以保证当前输入框可见;“adjustResize”- 自动调整Webview窗口大小(屏幕区域减去软键盘区域),同时自动滚动Webview保证输入框可见。 默认值为“adjustPan”。
平台支持
Android - ALL (不支持)
iOS - 5.0+ (支持)
top: (String 类型 )窗口垂直向下的偏移量
支持百分比、像素值,默认值为0px。未设置top属性值时,可设置bottom属性值改变窗口的默认top位置。
transition: (WebviewTransition 类型 )窗口定义窗口变换的动画效果
transform: (WebviewTransform 类型 )窗口定义窗口变形效果
position: (WebviewPosition 类型 )Webview窗口的排版位置
当Webview窗口添加到另外一个窗口中时,排版位置才会生效,排版位置决定子窗口在父窗口中的定位方式。 可取值:"static",控件在页面中正常定位,如果页面存在滚动条则随窗口内容滚动;"absolute",控件在页面中绝对定位,如果页面存在滚动条不随窗口内容滚动;"dock",控件在页面中停靠,停靠的位置由dock属性值决定。
平台支持
Android - (支持)
iOS - (支持)
(String 类型 )窗口的宽度
支持百分比、像素值,默认为100%。未设置width属性值时,可同时设置left和right属性值改变窗口的默认宽度。
zindex: (Number 类型 )窗口的堆叠顺序值
拥有更高堆叠顺序的窗口总是会处于堆叠顺序较低的窗口的前面,拥有相同堆叠顺序的窗口后调用show方法则在前面。
WebviewExtraOptions
JSON对象,原生窗口扩展参数
属性:
capture: (Bitmap 类型 )窗口动画使用的图片
当窗口执行动画操作时,使用图片会加速窗口动画效率,提升用户体验。 如果未指定窗口动画使用的图片,则根据动画效果默认使用窗口的实时动画效果。
平台支持
Android - 2.3+ (支持): 仅“pop-in”、“pop-out”窗口动画效果支持此参数,其它窗口动画忽略此参数。
iOS - 5.1+ (不支持): 暂不支持,忽略此参数。
otherCapture: (Bitmap 类型 )关联窗口动画使用的图片
当窗口执行动画操作时,使用图片会加速窗口动画效率,提升用户体验。 如果未指定关联窗口动画使用的图片,则根据动画效果默认使用关联窗口的实时动画变换效果。
平台支持
Android - 2.3+ (支持): 仅“pop-in”、“pop-out”窗口动画效果支持此参数,其它窗口动画忽略此参数。
iOS - 5.1+ (不支持): 暂不支持,忽略此参数。
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Webview Example</title>
<script type="text/javascript">var ws=null,wn=null;var bitmap1=null,bitmap2=null;// H5 plus事件处理function plusReady(){
ws=plus.webview.currentWebview();
// 截图
bitmap1 = new plus.nativeObj.Bitmap();
// 将webview内容绘制到Bitmap对象中
wc.draw(bitmap1,function(){
console.log('bitmap1绘制图片成功');
},function(e){
console.log('bitmap1绘制图片失败:'+JSON.stringify(e));
});
// 预创建新Webview窗口
wn=plus.webview.create("http://weibo.com/dhnetwork");
wn.addEventListener("loaded",function(){
bitmap2 = new plus.nativeObj.Bitmap();
wn.draw( bitmap2, function(){
console.log("bitmap2截图成功");
}, function(e){
console.log("bitmap2截图失败:"+JSON.stringify(e));
} );
},false);}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}// 创建并显示Webview窗口function showWebview(){
wn.show( "pop-in", 300, function(){
// 动画完成,销毁截图
bitmap1.clear();
bitmap2.clear();
}, {capture:bitmap2,otherCapture:bitmap1} );}
</script>
</head>
<body>
使用截图显示Webview窗口<br/>
<button onclick="showWebview()">show</button>
</body></html>
WebviewTransform
一组用于定义页面或控件变形的属性
WebviewTransition
一组用于定义页面或控件转换效果的属性
属性:
property: (String 类型 )产生变换效果的属性
默认值为"all",暂不支持其它值。
平台支持
Android - 2.2+ (支持)
iOS - 4.3+ (支持)
duration: (String 类型 )变换持续的时间
默认值为0,即无动画效果。
平台支持
Android - 2.2+ (支持)
iOS - 4.3+ (支持)
timingfunction: (String 类型 )窗口变换效果
可取值: "linear":匀速变化,匀速动画效果; "ease-in":匀加速变化,逐渐变快的动画效果; "ease-out":匀减速变化,逐渐变慢的动画效果; "ease-in-out":先加速后减速变化,先变快后变慢的动画效果。 默认值为"ease-in-out"。
平台支持
Android - 2.2+ (支持)
iOS - 4.3+ (支持)
BounceEventCallback
Webview窗口回弹事件的回调函数
void onEvent( Event event ){
// Event handled code.}
参数:
event: ( Event ) 必选 Webview窗口回弹事件触发时事件数据
Event对象包含以下属性: status - 表示回弹位置状态,设置顶部下拉回弹changeoffset属性后可取值:"beforeChangeOffset"表示可继续拖拽,此时松开拖拽窗口会回弹到其初始位置; "afterChangeOffset"表示回弹可停靠,此时松开拖拽窗口会回弹到停靠位置;
"dragEndAfterChangeOffset"表示已进松开拖拽,并且窗口回弹到停靠位置。 设置左右侧侧滑slideoffset属性后可取值:"beforeSlide"表示未侧滑状态;"afterSlide"表示已侧滑状态。 offset - 表示回弹方向,可取值:"left"表示左侧滑动,"right"表示右侧滑动,"top"表示上侧下拉滑动。 target - 保存触发回弹此事件的Webview窗口对象。
返回值:
void : 无
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Webview Example</title>
<script type="text/javascript">var ws=null;// H5 plus事件处理function plusReady(){
ws=plus.webview.currentWebview();
ws.setBounce({position:{top:"100px"},changeoffset:{top:"44px"}});
ws.addEventListener("dragBounce",onPullStateChange,false);}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}// 下拉状态改变function onPullStateChange(e){
switch(e.status){
case "beforeChangeOffset":
console.log("顶部回弹:可继续往下拖拽");
break;
case "afterChangeOffset":
console.log("顶部回弹:松开会重置回弹位置");
break;
case "dragEndAfterChangeOffset":
console.log("顶部回弹:松开停靠回弹");
break;
default:
break;
}}// 重置窗口回弹位置function resetBounce(){
ws.resetBounce();}
</script>
</head>
<body style="text-align:center;">
<br/><br/><br/>
设置Webview窗口的回弹效果<br/>
回弹后显示停靠到44px的位置<br/><br/>
<button onclick="resetBounce()">重置回弹位置</button>
<br/><br/><br/>
*暂仅支持顶部的回弹效果*
</body></html>
EventCallback
Webview窗口事件的回调函数
void onEvent( Event event ){
// Event handled code.}
参数:
event: ( Event ) 必选 Webview窗口事件触发时事件数据
Event对象包含以下属性: target:保存触发回弹此事件的Webview窗口对象。
返回值:
void : 无
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Webview Example</title>
<script type="text/javascript">var nw=null;// H5 plus事件处理function plusReady(){}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}
// 监听Webview窗口页面加载完成事件function eventTest() {
// 打开新窗口
nw=plus.webview.create( "", "", {top:"46px",bottom:"0px"} );
nw.addEventListener( "loaded", function(e){
console.log( "Loaded: "+e.target.getURL() );
}, false );
nw.show(); // 显示窗口}
</script>
</head>
<body>
Webview窗口页面加载完成事件
<button onclick="eventTest()">start</button>
<button onclick="nw.loadURL('http://m.csdn.net')">loaded</button>
</body></html>
PopGestureCallback
Webview窗口侧滑事件的回调函数
void onEvent( PopGestureEvent event ){
// Event handled code.}
参数:
event: ( PopGestureEvent ) 必选 Webview窗口事件触发时事件数据
PopGestureEvent对象包含以下属性: target:保存侧滑操作的Webview窗口对象。 type:保存侧滑事件类型,"start"表示开始侧滑返回,用户按下滑动时触发; “end”表示结束侧滑返回,用户松手时触发; “move"表示侧滑返回动作结束,用户移动侧滑时触发。 result:保存操作结果,仅在e.type为end时有效,boolean类型, true表示侧滑返回执行,false表示侧滑返回取消;否则为undefined。 progress:保存侧滑位置,Number类型,可带小数点,范围为0-100。
返回值:
void : 无
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8">
<title>Webview Example</title>
<script type="text/javascript">var nw=null;// H5 plus事件处理function plusReady(){
createWebview();}if(window.plus){
plusReady();}else{
document.addEventListener("plusready",plusReady,false);}
// 创建Webview窗口监听侧滑返回事件function createWebview(){
// 打开新窗口
nw=plus.webview.create( "http://m.csdn.net/","",{top:"100px",bottom:"0px",popGesture:"hide"} );
nw.addEventListener( "popGesture", function(e){
poplog.innerText="popGesture: "+e.type+","+e.result+","+e.progress;
}, false );}// 显示Webview窗口function showWebview(){
nw.show( "slide-in-right" );}// 隐藏Webview窗口function hideWebview(){
nw.hide();}// 关闭窗口function closeWebview(){
nw.close();
plus.webview.currentWebview().close();}
</script>
</head>
<body>
Webview窗口侧滑返回事件
<button onclick="closeWebview()">Close</button>
<button onclick="showWebview()">Show</button>
<button onclick="hideWebview()">Hide</button>
<div id="poplog"></div>
</body></html>
HistoryQueryCallback
历史记录记录查询的回调函数
void onQuery( Event event ) {
// Event handled code.}
参数:
event: ( Event ) 必选 查询Webview窗口历史记录操作事件数据
可通过event的canBack属性获取Webview窗口是否可后退,通过event的canForward属性获取Webview窗口是否可前进。
返回值:
void : 无
TitleUpdateCallback
Webview窗口加载页面标题更新的回调函数
void onQuery( Event event ) {
// Event handled code.}
参数:
event: ( Event ) 必选 Webview窗口加载页面标题更新事件数据
可通过event的title属性获取Webview窗口的标题。
返回值:
void : 无
SuccessCallback
Webview窗口操作成功回调函数
void onSuccess(){
// Success code.}
说明:
Webview窗口业务操作成功后触发回调函数。
参数:
无
返回值:
void : 无
ErrorCallback
Webview窗口操作失败回调函数
void onError(error){
// Handle the error
var code = error.code; // 错误编码
var message = error.message; // 错误描述信息}
参数:
error: ( Exception ) 可选 Webview窗口操作错误信息
可通过error.code(Number类型)获取错误编码; 可通过error.message(String类型)获取错误描述信息。
返回值:
void : 无
XMLHttpRequest
XMLHttpRequest模块管理网络请求,与标准HTML中的XMLHttpRequest用途一致,差别在于前者可以进行跨域访问。通过plus.net可获取网络请求管理对象。
对象:
XMLHttpRequest: 跨域网络请求对象
ProgressEvent: HTTP请求进度事件
回调方法:
XhrStateChangeCallback: 网络请求状态变化的回调函数
XhrProgressEventCallback: 网络请求进度事件的回调函数
权限:
permissions
"XMLHttpRequest": {
"description": "跨域网络访问"}
XMLHttpRequest
跨域网络请求对象
构造:
XMLHttpRequest(): 创建一个XMLHttpRequest 对象,对象创建时不触发任何时间和网络请求,需和open,send方法配合使用。
属性:
readyState: HTTP 请求的状态
response: 请求从服务器接收到的响应数据
responseText: 请求从服务器接收到的响应数据(字符串数据)
responseType: 请求响应数据response的类型
responseXML: 请求响应的Document对象
status: 服务器返回的HTTP状态代码
statusText: 服务器返回的HTTP状态描述
timeout: 请求服务器的超时时间,单位为毫秒(ms)
withCredentials: 是否支持跨域请求
方法:
abort: 取消当前响应,关闭连接并且结束任何未决的网络活动
getAllResponseHeaders: 获取HTTP响应头部信息
getResponseHeader: 获取指定的HTTP响应头部的值
open: 初始化HTTP请求参数,例如URL和HTTP方法,但是并不发送请求
send: 发送HTTP请求
setRequestHeader: 指定一个HTTP请求的Header
事件:
onreadystatechange: 网络请求状态发生变化事件
onloadstart: 网络请求开始事件
onprogress: 网络请求传输数据事件
onabort: 网络请求取消事件
onerror: 网络请求错误事件
onload: 网络请求成功事件
ontimeout: 网络请求超时事件
onloadend: 网络请求结束事件
XMLHttpRequest()
创建一个XMLHttpRequest 对象,对象创建时不触发任何时间和网络请求,需和open,send方法配合使用。
var xhr = new plus.net.XMLHttpRequest();
参数:
无
返回值:
示例:
<!DOCTYPE html><html>
<head>
<meta charset="UTF-8"/>
<script type="text/javascript">
document.addEventListener('plusready', function(){var xhr = new plus.net.XMLHttpRequest();
xhr.onreadystatechange = function () {
switch ( xhr.readyState ) {
case 0:
alert( "xhr请求已初始化" );
break;
case 1:
alert( "xhr请求已打开" );
break;
case 2:
alert( "xhr请求已发送" );
break;
case 3:
alert( "xhr请求已响应");
break;
case 4:
if ( xhr.status == 200 ) {
alert( "xhr请求成功:"+xhr.responseText );
} else {
alert( "xhr请求失败:"+xhr.readyState );
}
break;
default :
break;
}}
xhr.open( "GET", "http://www.baidu.com/" );
xhr.send();}, false );
</script>
</head>
<body onload="onload();">
</body></html>
readyState
HTTP 请求的状态
说明:
Number 类型
当一个 XMLHttpRequest 初次创建时,这个属性的值从 0 开始,直到接收到完整的 HTTP 响应,这个值增加到 4。 5 个状态中每一个都有一个相关联的非正式的名称,下表列出了状态、名称和含义: 0 Uninitialized,未初始化状态。XMLHttpRequest对象已创建或已被abort()方法重置。 1 Open,open()方法已调用,但是send()方法未调用。请求还没有被发送。 2 Sent,send()方法已调用,HTTP 请求已发送到Web服务器。未接收到响应。 3 Receiving,所有响应头部都已经接收到。响应体开始接收但未完成。 4 Loaded,HTTP响应已经完全接收。
response
请求从服务器接收到的响应数据
说明:
DOMString 类型 只读属性
如果没有从服务器接收到数据,则为null; 否则根据responseType类型决定: 如果responseType设置为空字符串或"text",则返回空字符串; 如果responseType设置为"document",则返回Document对象; 如果responseType设置为"json",则返回JSON对象; 若服务器返回的数据与设置的responseType类型不区配,则返回null。
responseText
请求从服务器接收到的响应数据(字符串数据)
说明:
DOMString 类型
如果还没有接收到数据的话,此属性值为空字符串; 如果readyState小于3,此属性值为空字符串; 如果readyState为3,此属性值返回目前已经接收的HTTP响应部分数据值; 如果readyState为4,此属性值保存了完整的HTTP响应数据体。 如果HTTP请求返回的数据头中包含了Content-Type值中指定字符编码,就使用该编码,否则,使用UTF-8字符集。
responseType
请求响应数据response的类型
说明:
DOMString 类型
默认值为空字符串,即reponse为DOMString,类型可设置:"document"表示Document对象,"json"表示JSON对象,"text"表示字符串。 此值必须在调用send方法之前设置,否则设置的值不生效,仍使用之前设置的值。
responseXML
请求响应的Document对象
说明:
DOMString 类型
对请求的响应,解析为 XML 并作为 Document 对象返回。 如果请求未成功,或响应的数据无法被解析为XML,则返回null。
status
服务器返回的HTTP状态代码
说明:
Number 类型
服务器返回的HTTP状态代码,如200表示成功,而404表示"Not Found"错误; 当readyState小于3的时候此属性值为0。
statusText
服务器返回的HTTP状态描述
说明:
DOMString 类型
此属性值用名称而不是数字指定了请求的HTTP的状态代码。 也就是说,当状态为200的时候它是"OK";当状态为404的时候它是"Not Found"。 和status属性类似,当readyState小于3的时候读取这一属性会返回空字符串。
timeout
请求服务器的超时时间,单位为毫秒(ms)
说明:
Number 类型
数值类型,单位为ms,其默认值为120秒。 超时时间为服务器响应请求的时间(不是Http请求完成的总时间),如果设置为0则表示永远不超时。 必须在请求发起前设置,否则当前请求将不生效,在当前请求完成后重新发起新请求时生效。
withCredentials
是否支持跨域请求
说明:
Boolean 类型 只读属性
此对象创建的HTTP请求都支持跨域,所以永远返回true。
abort
取消当前响应,关闭连接并且结束任何未决的网络活动
void abort();
说明:
此方法把XMLHttpRequest对象重置为readyState为0的状态,并且取消所有未决的网络活动。 调用此方法后将停止触发XMLHttpRequest对象的所有事件。 例如,如果请求用了太长时间,而且响应不再必要的时候,可以调用这个方法。
参数:
无
返回值:
void : 无
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0, user-scalable=no"/>
<meta name="HandheldFriendly" content="true"/>
<meta name="MobileOptimized" content="320"/>
<title>XMLHttpRequest</title>
<script type="text/javascript">var xhr=null;function testXHR(){
if(xhr){
return;
}
xhr=new plus.net.XMLHttpRequest();
xhr.onreadystatechange=function(){
console.log("onreadystatechange: "+xhr.readyState);
}
xhr.open( "GET", "http://www.dcloud.io/" );
xhr.send();}function abortXHR(){
if(xhr){
xhr.abort();
xhr=null;
}}
</script>
</head>
<body>
<button onclick="testXHR()">XMLHttpRequest</button><br/>
<button onclick="abortXHR()">Abort</button>
</body></html>
getAllResponseHeaders
获取HTTP响应头部信息
说明:
把HTTP响应头部作为未解析的字符串返回。 如果readyState小于3,这个方法返回null。 否则,它返回服务器发送的所有 HTTP 响应的头部。头部作为单个的字符串返回,一行一个头部。每行用换行符" "隔开。
参数:
无
返回值:
DOMString : HTTP 响应头
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0, user-scalable=no"/>
<meta name="HandheldFriendly" content="true"/>
<meta name="MobileOptimized" content="320"/>
<title>XMLHttpRequest</title>
<script type="text/javascript">var xhr=null;function testXHR(){
if(xhr){
return;
}
xhr=new plus.net.XMLHttpRequest();
xhr.onreadystatechange=function(){
console.log("onreadystatechange: "+xhr.readyState);
}
xhr.open( "GET", "http://www.dcloud.io/" );
xhr.send();}// 获取所有HTTP响应头部信息function allResponseHeader(){
if(xhr){
console.log(xhr.getAllResponseHeaders());
}}
</script>
</head>
<body>
<button onclick="testXHR()">XMLHttpRequest</button><br/>
<button onclick="allResponseHeader()">getAllResponseHeaders</button>
</body></html>
getResponseHeader
获取指定的HTTP响应头部的值
void getResponseHeader( headerName );
说明:
其参数是要返回的 HTTP 响应头部的名称。可以使用任何大小写来制定这个头部名字,和响应头部的比较是不区分大小写的。 该方法的返回值是指定的 HTTP 响应头部的值,如果没有接收到这个头部或者readyState小于3则为空字符串。 如果接收到多个有指定名称的头部,这个头部的值被连接起来并返回,使用逗号和空格分隔开各个头部的值。
参数:
headerName: ( DOMString ) 可选 HTTP响应头数据名称
返回值:
DOMString : HTTP响应头数据值
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0, user-scalable=no"/>
<meta name="HandheldFriendly" content="true"/>
<meta name="MobileOptimized" content="320"/>
<title>XMLHttpRequest</title>
<script type="text/javascript">var xhr=null;function testXHR(){
if(xhr){
return;
}
xhr=new plus.net.XMLHttpRequest();
xhr.onreadystatechange=function(){
console.log("onreadystatechange: "+xhr.readyState);
}
xhr.open( "GET", "http://www.dcloud.io/" );
xhr.send();}// 获取所有HTTP响应Content-Type信息function getResponseHeader(){
if(xhr){
console.log(xhr.getResponseHeaders("Content-Type"));
}}
</script>
</head>
<body>
<button onclick="testXHR()">XMLHttpRequest</button><br/>
<button onclick="getResponseHeader()">getResponseHeader</button>
</body></html>
open
初始化HTTP请求参数,例如URL和HTTP方法,但是并不发送请求
void open( method, url, username, password );
说明:
这个方法初始化请求参数以供 send() 方法稍后使用。它把readyState设置为1,删除之前指定的所有请求头部,以及之前接收的所有响应头部,并且把responseText、responseXML、status 以及 statusText 参数设置为它们的默认值。 当readyState为0的时候(当XMLHttpRequest对象刚创建或者abort()方法调用后)以及当readyState为4时(已经接收响应时),调用这个方法是安全的。 当针对任何其他状态调用的时候,open()方法的行为是为指定的。 除了保存供send()方法使用的请求参数,以及重置 XMLHttpRequest 对象以便复用,open()方法没有其他的行为。 要特别注意,当这个方法调用的时候,实现通常不会打开一个到Web服务器的网络连接。
参数:
method: ( DOMString ) 必选 请求URL的HTTP协议方法
值可以为"GET"、"POST"。
url: ( DOMString ) 必选 请求URL地址
username: ( DOMString ) 可选 请求URL所需的授权提供认证资格用户名
password: ( DOMString ) 可选 请求URL所需的授权提供认证资格密码
返回值:
void : 无
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0, user-scalable=no"/>
<meta name="HandheldFriendly" content="true"/>
<meta name="MobileOptimized" content="320"/>
<title>XMLHttpRequest</title>
<script type="text/javascript">var xhr=null;function testXHR(){
if(xhr){
return;
}
xhr=new plus.net.XMLHttpRequest();
xhr.onreadystatechange=function(){
console.log("onreadystatechange: "+xhr.readyState);
}
// 初始化HTTP请求
xhr.open( "GET", "http://www.dcloud.io/" );
xhr.send();}
</script>
</head>
<body>
<button onclick="testXHR()">XMLHttpRequest</button><br/>
</body></html>
send
发送HTTP请求
void send( body );
说明:
此方法触发HTTP请求发送,如果之前没有调用open(),或者更具体地说,如果readyState不是1,send()抛出一个异常。否则,将发送HTTP请求,该请求由以下几部分组成: 之前调用open()时指定的HTTP方法、URL; 之前调用setRequestHeader()时指定的请求头部(如果有的话); 传递给这个方法的body参数。 一旦请求发送了,send()把readyState设置为2,并触发onreadystatechange事件; 如果服务器响应带有一个HTTP重定向,send()方法在后台线程自动遵从重定向; 当所有的HTTP响应头部已经接收,send()或后台线程把readyState设置为3并触发onreadystatechange事件; 如果响应较长,send()或后台线程可能在状态3中触发多次onreadystatechange事件; 最后,当响应完成,send()或后台线程把readyState设置为4,并最后一次触发onreadystatechange事件。
参数:
body: ( String ) 可选 请求HTTP提交的数据内容
当open方法中设置的method参数为POST时必需传入body值。
返回值:
void : 无
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0, user-scalable=no"/>
<meta name="HandheldFriendly" content="true"/>
<meta name="MobileOptimized" content="320"/>
<title>XMLHttpRequest</title>
<script type="text/javascript">var xhr=null;function testXHR(){
if(xhr){
return;
}
xhr=new plus.net.XMLHttpRequest();
xhr.onreadystatechange=function(){
console.log("onreadystatechange: "+xhr.readyState);
}
xhr.open( "POST", "http://demo.dcloud.net.cn/test/xhr/post.php" );
var data={name:'HBuilder',version:'0.1.0'};
// 发送HTTP请求
xhr.send(JSON.stringify(data));}
</script>
</head>
<body>
<button onclick="testXHR()">XMLHttpRequest</button><br/>
</body></html>
setRequestHeader
指定一个HTTP请求的Header
void setRequestHeader( headerName, headerValue );
说明:
Http的Header应该包含在通过后续send()调用而发起的请求中。 此方法只有当readyState为1的时候才能调用,例如,在调用了open()之后,但在调用send()之前。 如果带有指定名称的头部已经被指定了,这个头部的新值就是:之前指定的值,加上逗号、以及这个调用指定的值(形成一个数组)。 如果Web服务器已经保存了和传递给open()的URL相关联的cookie,适当的Cookie或Cookie2头部也自动地包含到请求中,可以通过调用setRequestHeader()来把这些cookie添加到头部。
参数:
headerName: ( DOMString ) 必选 HTTP Header名称
headerValue: ( DOMString ) 必选 HTTP Header值
返回值:
void : 无
平台支持:
Android - 2.2+ (支持): 不支持设置“User-Agent”、“Cookie”的值。
iOS - 5.1+ (支持): 不支持设置“User-Agent”的值。
示例:
<!DOCTYPE html><html>
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0, user-scalable=no"/>
<meta name="HandheldFriendly" content="true"/>
<meta name="MobileOptimized" content="320"/>
<title>XMLHttpRequest</title>
<script type="text/javascript">var xhr=null;function testXHR(){
if(xhr){
return;
}
xhr=new plus.net.XMLHttpRequest();
xhr.onreadystatechange=function(){
console.log("onreadystatechange: "+xhr.readyState);
}
xhr.open( "POST", "http://demo.dcloud.net.cn/test/xhr/post.php" );
var data={name:'HBuilder',version:'0.1.0'};
xhr.setRequestHeader('Content-Type','application/json');
// 发送HTTP请求
xhr.send(JSON.stringify(data));}
</script>
</head>
<body>
<button onclick="testXHR()">XMLHttpRequest</button><br/>
</body></html>
onreadystatechange
网络请求状态发生变化事件
xhr.onreadystatechange = function(){
// 判断xhr状态};
说明:
网络请求状态发生变化时触发,通常在函数中判断对象的state属性值来获取当前请求的状态。
示例:
<!DOCTYPE HTML><html>
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0, user-scalable=no"/>
<meta name="HandheldFriendly" content="true"/>
<meta name="MobileOptimized" content="320"/>
<title>XMLHttpRequest</title>
<script type="text/javascript">var url="http://demo.dcloud.net.cn/test/xhr/event.html";var xhr=null;
function xhrEvent(){
xhr = new XMLHttpRequest();
xhr.onreadystatechange = function () {
console.log("onreadystatechange: "+xhr.readyState);
}
xhr.open( "GET", url );
xhr.send();}
</script>
</head>
<body>
<button onclick="xhrEvent()">XMLHttpRequest</button><br/>
</body></html>
onloadstart
网络请求开始事件
xhr.onloadstart = function(){
// xhr请求开始事件处理};
说明:
通常在调用send方法开始发起HTTP请求时触发。
示例:
<!DOCTYPE HTML><html>
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0, user-scalable=no"/>
<meta name="HandheldFriendly" content="true"/>
<meta name="MobileOptimized" content="320"/>
<title>XMLHttpRequest</title>
<script type="text/javascript">var url="http://demo.dcloud.net.cn/test/xhr/json.php";var xhr=null;function xhrEvent(){
xhr = new plus.net.XMLHttpRequest();
xhr.onloadstart=function(e){
var str="lengthComputable="+e.lengthComputable+"loaded="+e.loaded+";total="+e.total;
console.log("onloadstart: "+str);
}
xhr.open( "GET", url );
xhr.send();}
</script>
</head>
<body>
<button onclick="xhrEvent()">XMLHttpRequest</button><br/>
</body></html>
onprogress
网络请求传输数据事件
xhr.onprogress= function(){
// xhr数据传输开始事件处理};
说明:
通常在HTTP请求链接已经建立,开始传输数据时触发,在数据传输的过程中可能多次触发,此事件与onreadystatechange事件触发状态3类似。
示例:
<!DOCTYPE HTML><html>
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0, user-scalable=no"/>
<meta name="HandheldFriendly" content="true"/>
<meta name="MobileOptimized" content="320"/>
<title>XMLHttpRequest</title>
<script type="text/javascript">var url="http://demo.dcloud.net.cn/test/video/nocrygirl.mp4";//访问一个大文件,以便多次触发onprogress事件var xhr=null;function xhrEvent(){
xhr = new plus.net.XMLHttpRequest();
xhr.onprogress=function(e){
var str="lengthComputable="+e.lengthComputable+"loaded="+e.loaded+";total="+e.total;
console.log("onprogress: "+str);
}
xhr.open( "GET", url );
xhr.send();}
</script>
</head>
<body>
<button onclick="xhrEvent()">XMLHttpRequest</button><br/>
</body></html>
onabort
网络请求取消事件
xhr.onabort = function(){
// xhr请求被取消事件处理};
说明:
通常在调用abort方法取消HTTP请求时触发。 此事件在onreadystatechange事件触发状态4事件之后。
示例:
<!DOCTYPE HTML><html>
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0, user-scalable=no"/>
<meta name="HandheldFriendly" content="true"/>
<meta name="MobileOptimized" content="320"/>
<title>XMLHttpRequest</title>
<script type="text/javascript">var url="http://demo.dcloud.net.cn/test/video/nocrygirl.mp4";//访问一个大文件,以便操作触发onabort事件var xhr=null;function xhrEvent(){
xhr = new plus.net.XMLHttpRequest();
xhr.onabort=function(e){
var str="lengthComputable="+e.lengthComputable+"loaded="+e.loaded+";total="+e.total;
console.log("onabort: "+str);
}
xhr.open( "GET", url );
xhr.send();}function xhrAbort() {
if ( xhr ) {
xhr.abort();
xhr = null;
}}
</script>
</head>
<body>
<button onclick="xhrEvent()">XMLHttpRequest</button><br/>
<button onclick="xhrAbort()">Abort</button>
</body></html>
onerror
网络请求错误事件
xhr.onerror = function(){
// xhr请求出错事件处理};
说明:
通常在HTTP请求发生错误时触发,如无法连接到服务器等各种错误都触发此事件。 此事件在onreadystatechange事件触发状态4事件之后。
示例:
<!DOCTYPE HTML><html>
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0, user-scalable=no"/>
<meta name="HandheldFriendly" content="true"/>
<meta name="MobileOptimized" content="320"/>
<title>XMLHttpRequest</title>
<script type="text/javascript">var url="http://demo.dcloud.net.cn/test/xhr/error.html";//访问无效的网络地址处罚onerror事件var xhr=null;function xhrEvent(){
xhr = new plus.net.XMLHttpRequest();
xhr.onerror=function(e){
var str="lengthComputable="+e.lengthComputable+"loaded="+e.loaded+";total="+e.total;
console.log("onerror: "+str);
}
xhr.open( "GET", url );
xhr.send();}
</script>
</head>
<body>
<button onclick="xhrEvent()">XMLHttpRequest</button><br/>
</body></html>
onload
网络请求成功事件
xhr.onload = function(){
// xhr请求成功事件处理};
说明:
通常在HTTP请求成功完成时触发,如果HTTP请求发生错误则不触发此事件。 此事件在onreadystatechange事件触发状态4事件之后。
示例:
<!DOCTYPE HTML><html>
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0, user-scalable=no"/>
<meta name="HandheldFriendly" content="true"/>
<meta name="MobileOptimized" content="320"/>
<title>XMLHttpRequest</title>
<script type="text/javascript">var url="http://demo.dcloud.net.cn/test/xhr/json.php";var xhr=null;function xhrEvent(){
xhr = new plus.net.XMLHttpRequest();
xhr.onload=function(e){
var str="lengthComputable="+e.lengthComputable+"loaded="+e.loaded+";total="+e.total;
console.log("onload: "+str);
}
xhr.open( "GET", url );
xhr.send();}
</script>
</head>
<body>
<button onclick="xhrEvent()">XMLHttpRequest</button><br/>
</body></html>
ontimeout
网络请求超时事件
xhr.ontimeout = function(){
// xhr请求超时事件处理};
说明:
通常在HTTP请求超时时触发,此时不会触发onerror事件。 此事件在onreadystatechange事件触发状态4事件之后。
示例:
<!DOCTYPE HTML><html>
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0, user-scalable=no"/>
<meta name="HandheldFriendly" content="true"/>
<meta name="MobileOptimized" content="320"/>
<title>XMLHttpRequest</title>
<script type="text/javascript">var url="http://demo.dcloud.net.cn/test/xhr/json.php";var xhr=null;function xhrEvent(){
xhr = new plus.net.XMLHttpRequest();
xhr.ontimeout=function(e){
var str="lengthComputable="+e.lengthComputable+"loaded="+e.loaded+";total="+e.total;
console.log("ontimeout: "+str);
}
xhr.timeout=1; // 设置极小的超时时间用于处罚ontimeout事件
xhr.open( "GET", url );
xhr.send();}
</script>
</head>
<body>
<button onclick="xhrEvent()">XMLHttpRequest</button><br/>
</body></html>
onloadend
网络请求结束事件
xhr.onloadend = function(){
// xhr请求结束事件处理};
说明:
通常在HTTP请求结束时触发,不管是HTTP请求失败、成功、或超时之后都会触发此事件。 此事件在onreadystatechange事件触发状态4事件之后。
示例:
<!DOCTYPE HTML><html>
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0, user-scalable=no"/>
<meta name="HandheldFriendly" content="true"/>
<meta name="MobileOptimized" content="320"/>
<title>XMLHttpRequest</title>
<script type="text/javascript">var url="http://demo.dcloud.net.cn/test/xhr/json.php";var xhr=null;function xhrEvent(){
xhr = new plus.net.XMLHttpRequest();
xhr.onloadend=function(e){
var str="lengthComputable="+e.lengthComputable+"loaded="+e.loaded+";total="+e.total;
console.log("onloadend: "+str);
}
xhr.open( "GET", url );
xhr.send();}
</script>
</head>
<body>
<button onclick="xhrEvent()">XMLHttpRequest</button><br/>
</body></html>
ProgressEvent
HTTP请求进度事件
interface ProgressEvent : Event {
readonly attribute XMLHttpRequest target;
readonly attribute Boolean lengthComputable;
readonly attribute Number loaded;
readonly attribute Number total;};
属性:
target: (XMLHttpRequest 类型 )事件的目标对象
通知HTTP请求进度事件的XMLHttpRequest对象。
lengthComputable: (Number 类型 )进度信息是否可计算
HTTP请求进度信息是否有效,如果HTTP请求头中包含Content-Length头信息则为true,否则为false。
loaded: (XMLHttpRequest 类型 )当前已经接收到的数据长度
HTTP请求接收到的数据长度,单位为字节。
total: (XMLHttpRequest 类型 )总数据长度
HTTP请求返回的总数据长度,单位为字节。 如果无法获取则设置为0。
XhrStateChangeCallback
网络请求状态变化的回调函数
void onSuccess() {
// State changed code.}
参数:
无
返回值:
void : 无
示例:
<!DOCTYPE HTML><html>
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0, user-scalable=no"/>
<meta name="HandheldFriendly" content="true"/>
<meta name="MobileOptimized" content="320"/>
<title>XMLHttpRequest</title>
<script type="text/javascript">var url="http://demo.dcloud.net.cn/test/xhr/json.php";var xhr=null;function xhrEvent(){
xhr = new plus.net.XMLHttpRequest();
xhr.onreadystatechange = function () {
console.log("onreadystatechange: "+xhr.readyState);
}
xhr.open( "GET", url );
xhr.send();}
</script>
</head>
<body>
<button onclick="xhrEvent()">XMLHttpRequest</button><br/>
</body></html>
XhrProgressEventCallback
网络请求进度事件的回调函数
void onProgressEvent( ProgressEvent event ) {
// Progress changed code.}
参数:
event: ( ProgressEvent ) 必选 HTTP请求进度事件
返回值:
void : 无
示例:
<!DOCTYPE HTML><html>
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0, user-scalable=no"/>
<meta name="HandheldFriendly" content="true"/>
<meta name="MobileOptimized" content="320"/>
<title>XMLHttpRequest</title>
<script type="text/javascript">var url="http://demo.dcloud.net.cn/test/xhr/json.php";var xhr=null;function xhrEvent(){
xhr = new plus.net.XMLHttpRequest();
xhr.onloadend=function(e){
var str="lengthComputable="+e.lengthComputable+"loaded="+e.loaded+";total="+e.total;
console.log("onloadend: "+str);
}
xhr.open( "GET", url );
xhr.send();}
</script>
</head>
<body>
<button onclick="xhrEvent()">XMLHttpRequest</button><br/>
</body></html>
Zip
Zip模块管理文件压缩和解压,通过plus.zip可获取压缩管理对象。
方法:
compress: 压缩生成Zip文件
decompress: 解压缩Zip文件
compressImage: 图片压缩转换
对象:
CompressImageOptions: JSON对象,配置图片压缩转换的参数
ClipImageOptions: JSON对象,图片裁剪区域的参数
回调方法:
CompressImageSuccessCallback: 图片压缩转换操作成功回调接口
ZipSuccessCallback: 操作成功回调函数接口,在解压Zip文件或压缩成Zip文件成功时调用
ZipErrorCallback: 操作错误回调函数接口,在解压Zip文件或压缩成Zip文件失败时调用
权限:
permissions
"Zip": {
"description": "文件压缩与解压缩"}
compress
压缩生成Zip文件
void plus.zip.compress(src, zipfile, successCB, errorCB);
参数:
src: ( String ) 可选 要压缩的源文件路径,支持文件路径或目录
zipfile: ( String ) 可选 压缩后保存的Zip文件路径
successCB: ( ZipSuccessCallback ) 必选 压缩Zip文件操作成功回调,在压缩操作成功时调用
errorCB: ( ZipErrorCallback ) 必选 压缩Zip文件操作失败回调,在压缩操作失败时调用
返回值:
void : 无
示例:
<!DOCTYPE HTML><html>
<head>
<meta charset="UTF-8" />
<script type="text/javascript">//压缩function zipCompress(){
var zipfile = "_doc/text11.zip";
var targetPath = '_doc/dir/';
plus.zip.compress(targetPath,zipfile,
function() {
alert("Compress success!");
},function(error) {
alert("Compress error!");
});}
</script>
</head>
<body >
<input type='button' onclick='zipCompress()' value='zip压缩' />
</body></html>
decompress
解压缩Zip文件
void plus.zip.decompress( zipfile, target, successCB, errorCB);
参数:
zipfile: ( String ) 可选
需解压Zip文件路径
target: ( String ) 可选
解压Zip文件的目标路径,必须是路径
successCB: ( ZipSuccessCallback ) 必选
解压Zip文件操作成功回调,在解压操作成功时调用。
errorCB: ( ZipErrorCallback ) 必选
解压Zip文件操作失败回调,在解压操作失败时调用。
返回值:
void : 无
示例:
<!DOCTYPE HTML><html><head>
<meta charset="UTF-8" />
<script type="text/javascript">//解压缩function zipDecompress() {
var zipfile = "_doc/text.zip";
var targetPath = '_doc/dir/';
plus.zip.decompress(zipfile, targetPath,
function() {
alert("Decompress success!");
},function(error) {
alert("Compress error!");
});}
</script>
</head>
<body >
<input type='button' onclick='zipDecompress()' value='zip解压' />
</body></html>
compressImage
图片压缩转换
void plus.zip.compressImage( options, successCB, errorCB);
说明:
可用于图片的质量压缩、大小缩放、方向旋转、区域裁剪、格式转换等。
参数:
options: ( CompressImageOptions ) 必选
图片压缩转换的参数
successCB: ( CompressImageSuccessCallback ) 可选
图片压缩转换操作成功回调,操作成功时调用。
errorCB: ( ZipErrorCallback ) 可选
图片压缩转换操作失败回调,操作失败时调用。
返回值:
void : 无
示例:
<!DOCTYPE HTML><html><head>
<meta charset="UTF-8" />
<script type="text/javascript">//压缩图片function compressImage(){
plus.zip.compressImage({
src:"_www/a.jpg",
dst:"_doc/a.jpg",
quality:20
},
function() {
alert("Compress success!");
},function(error) {
alert("Compress error!");
});}//缩放图片function zoomImage(){
plus.zip.compressImage({
src:"_www/a.jpg",
dst:"_doc/a.jpg",
"50%" // 缩小到原来的一半
},
function() {
alert("Compress success!");
},function(error) {
alert("Compress error!");
});}//旋转图片function rotateImage(){
plus.zip.compressImage({
src:"_www/a.jpg",
dst:"_doc/a.jpg",
rotate:90 // 旋转90度
},
function() {
alert("Compress success!");
},function(error) {
alert("Compress error!");
});}//裁剪图片function clipImage(){
plus.zip.compressImage({
src:"_www/a.jpg",
dst:"_doc/a.jpg",
clip:{top:"25%",left:"25%","50%",height:"50%"} // 裁剪图片中心区域
},
function() {
alert("Compress success!");
},function(error) {
alert("Compress error!");
});}//格式转换function convertImage(){
plus.zip.compressImage({
src:"_www/a.jpg",
dst:"_doc/a.png",
format:"png" // 将jpg转换成png格式
},
function() {
alert("Compress success!");
},function(error) {
alert("Compress error!");
});}
</script>
</head>
<body >
<button onclick="compressImage()">压缩图片</button><br/>
<button onclick="zoomImage()">缩放图片</button><br/>
<button onclick="rotateImage()">旋转图片</button><br/>
<button onclick="clipImage()">裁剪图片</button><br/>
<button onclick="convertImage()">格式转换</button><br/>
</body></html>
CompressImageOptions
JSON对象,配置图片压缩转换的参数
说明:
设置width/height属性则表示需对图片进行缩放转换操作; 设置rotate属性则表示需对图片进行旋转转换操作; 设置clip属性则表示需对图片进行裁剪转换操作; 如同时设置了多个转换操作,则按缩放、旋转、裁剪顺序进行操作。
属性:
src: (String 类型 )压缩转换原始图片的路径
支持以下图片路径: 相对路径 - 相对于当前页面的host位置,如"a.jpg",注意当前页面为网络地址则不支持; 绝对路径 - 系统绝对路径,如Android平台"/storage/sdcard0/Android/data/io.dcloud.HBuilder/.HBuilder/apps/HBuilder/www/a.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://”开头,后面跟随系统绝对路径。
平台支持
Android - 2.2+ (支持): 支持jpg/jpeg、png等格式图片。
iOS - 5.0+ (支持): 支持jpg/jpeg、png、tif/tiff、gif、bmp、ico、cur、xbm等格式图片。
dst: (String 类型 )压缩转换目标图片的路径
支持以下图片路径: 绝对路径 - 系统绝对路径,如Android平台"/storage/sdcard0/Android/data/io.dcloud.HBuilder/.HBuilder/apps/HBuilder/doc/a.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",注意不支持"_www"开头的路径; 本地路径URL - 以“file://”开头,后面跟随系统绝对路径。 注意:如果设置的路径无权限访问,则返回失败。
overwrite: (Boolean 类型 )覆盖生成新文件
仅在dst制定的路径文件存在时有效: true表示覆盖存在的文件; false表示不覆盖,如果文件存在,则返回失败。 默认值为false。
format: (String 类型 )压缩转换后的图片格式
支持"jpg"、"png",如果未指定则使用源图片的格式。
quality: (Number 类型 )压缩图片的质量
取值范围为1-100,1表示使用最低的图片质量(转换后的图片文件最小)、100表示使用最高的图片质量(转换后的图片文件最大); 默认值为50。
(String 类型 )缩放图片的宽度
支持像素值(如"100px")、百分比(如"50%")、自动计算(如"auto",即根据height与源图高的缩放比例计算,若未设置height则使用源图高度); 默认值为"auto"。 注意:若设置了width属性值不合法(如"0px"),则不对图片进行缩放操作。
height: (String 类型 )缩放图片的高度
支持像素值(如"100px")、百分比(如"50%")、自动计算(如"auto",即根据width与源图宽的缩放比例计算,若未设置width则使用源图高度); 默认值为"auto"。 注意:若设置了height属性值不合法(如"0px"),则不对图片进行缩放操作。
rotate: (Number 类型 )旋转图片的角度
支持值:90-表示旋转90度;180-表示旋转180度;270-表示旋转270度。 注意:若设置rotate属性值不合法,则不对图片进行旋转操作。
clip: (ClipImageOptions 类型 )裁剪图片的区域
值参考ClipImageOptions定义,若设置clip属性值不合法,则不对图片进行裁剪操作。
ClipImageOptions
JSON对象,图片裁剪区域的参数
属性:
top: (String 类型 )图片裁剪区域与原图片上边界的偏移距离
支持像素值(如"10px")、百分比(如"10%");默认值为"0px"。 注意:如果top值超出原图片高度,则图片裁剪失败。
left: (Stirng 类型 )图片裁剪区域与原图片左边界的偏移距离
支持像素值(如"10px")、百分比(如"10%");默认值为"0px"。 注意:如果left值超出原图片宽度,则图片裁剪失败。
(String 类型 )图片裁剪区域的宽度
支持像素值(如"100px")、百分比(如"50%")、自动计算(如"auto",即从left位置到图片右边界的宽度);默认值为"auto"。 注意:如果left值加width值超出原图片宽度,则使用"auto"值进行裁剪。
height: (String 类型 )图片裁剪区域的高度
支持像素值(如"100px")、百分比(如"50%")、自动计算(如"auto",即从top位置到图片下边界的高度);默认值为"auto"。 注意:如果top值加height值超出原图片高度,则使用"auto"值进行裁剪。
CompressImageSuccessCallback
图片压缩转换操作成功回调接口
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/a.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 : 无
ZipSuccessCallback
操作成功回调函数接口,在解压Zip文件或压缩成Zip文件成功时调用
void onSuccess(){
// Code here}
参数:
无
返回值:
void : 无
ZipErrorCallback
操作错误回调函数接口,在解压Zip文件或压缩成Zip文件失败时调用
void onError(error){
// Handle the error
var code = error.code; // 错误编码
var message = error.message; // 错误描述信息}
参数:
error: ( Exception ) 可选 Zip操作的错误信息
可通过error.code(Number类型)获取错误编码; 可通过error.message(String类型)获取错误描述信息。
返回值:
void : 无