UI模块管理应用界面,用于操作加载HTML页面的原生窗口,调用系统原生控件等。由于此模块功能太多,现已根据功能分拆更新为Key、NativeUI、Navigator、Webview等,并对接口和功能做了一些优化调整,请使用新API。
permissions
"UI": { "description": "访问系统原生窗口"}
弹出系统提示框
void plus.ui.alert( message, alertCB, title, buttonCapture );
弹出系统样式提示对话框,可设置弹出对话框的标题、内容、按钮文字。此API非阻塞模式,用户点击提示框上的按钮需通过alertCB回调函数返回。
<!DOCTYPE html><html> <head> <meta charset="utf-8"> <title>UI Example</title> <script type="text/javascript">// 扩展API加载完毕后调用onPlusReady回调函数 document.addEventListener( "plusready", onPlusReady, false );// 扩展API加载完毕,现在可以正常调用扩展APIfunction onPlusReady() {// 弹出提示信息框plus.ui.alert( "Plus is ready!", function () { alert( "User pressed OK!" );}, "Hell0", "OK" );} </script> </head> <body> Message notification </body></html>
关闭程序启动界面
void plus.ui.closeSplashscreen();
在某些情况下,程序启动后需要较长时间加载数据,为了避免界面显示空白内容,提高用户体验效果,这时可显示启动界面,直到数据加载完成后再关闭启动界面,通常在应用的首界面加载完成并更新显示内容后调用。
无
<!DOCTYPE html><html> <head> <meta charset="utf-8"> <title>UI Example</title> <script type="text/javascript">// 扩展API加载完毕后调用onPlusReady回调函数document.addEventListener( "plusready", onPlusReady, false );// 扩展API加载完毕,现在可以正常调用扩展APIfunction onPlusReady() { // 页面内容加载完成,关闭程序启动界面 plus.ui.closeSplashscreen();} </script> </head> <body> Message notification </body></html>
关闭原生窗口
void plus.ui.closeWindow( win, aniClose, duration );
关闭已经打开的原生窗口。
<!DOCTYPE html><html> <head> <meta charset="utf-8"> <title>UI Example</title> <script type="text/javascript">// 扩展API加载完毕后调用onPlusReady回调函数document.addEventListener( "plusready", onPlusReady, false );// 扩展API加载完毕,现在可以正常调用扩展APIfunction onPlusReady() {}function winAutoClose() { // 打开新窗口 var nw = plus.ui.createWindow( "http://www.baidu.com" ); // 百度主页 nw.show(); // 显示窗口 // 十秒后自动关闭 setTimeout( function () { plus.ui.closeWindow( nw ); }, 10000 );} </script> </head> <body> <input id="create" type="button" value="Open Window And Close" onclick="winAutoClose();"></input> </body></html>
弹出系统确认对话框
void plus.ui.confirm( message, confirmCB, title, buttons );
弹出系统样式确认对话框,可设置弹出对话框的标题、内容、按钮数目及其文字。弹出的提示对话框为非阻塞模式,用户点击确认框上的按钮通过confirmCB回调函数返回。
<!DOCTYPE html><html> <head> <meta charset="utf-8"> <title>UI Example</title> <script type="text/javascript">// 扩展API加载完毕后调用onPlusReady回调函数document.addEventListener( "plusready", onPlusReady, false );// 扩展API加载完毕,现在可以正常调用扩展APIfunction onPlusReady() { // 弹出提示信息框 plus.ui.confirm( "Are you sure ready?", function ( i ) { alert( (i==0)?"Yes!":"No!" ); }, "Confirm", ["Yes","No"] );} </script> </head> <body> Message notification </body></html>
创建新的原生控件对象
NView plus.ui.createView( identity, options );
创建原生窗口显示元素,用于加载新的显示元素。可通过options设置原生窗口显示元素的属性。
<!DOCTYPE html><html> <head> <meta charset="utf-8"> <title>UI Example</title> <script type="text/javascript">// 扩展API加载完毕后调用onPlusReady回调函数document.addEventListener( "plusready", onPlusReady, false );// 扩展API加载完毕,现在可以正常调用扩展APIfunction onPlusReady() {}function createViewTest() { // 打开新窗口 var nv = plus.ui.createView('Navigator',{position:'dock',dock:'top'}); plus.ui.getSelfWindow().append( nv ); // 显示窗口} </script> </head> <body> <input id="create" type="button" value="Create New View" onclick="createViewTest();"></input> </body></html>
创建等待对话框
NWaiting plus.ui.createWaiting( title, options );
在程序中创建并显示等待对话框。
<!DOCTYPE html><html> <head> <meta charset="utf-8"> <title>UI Example</title> <script type="text/javascript">// 扩展API加载完毕后调用onPlusReady回调函数document.addEventListener( "plusready", onPlusReady, false );// 扩展API加载完毕,现在可以正常调用扩展APIfunction onPlusReady() { // 打开新窗口 var w = plus.ui.createWaiting( "等待中..." );} </script> </head> <body> 等待对话框。 </body></html>
创建新的原生窗口
NWindow plus.ui.createWindow( url, options );
创建原生窗口,用于加载新的系统原生窗口。可通过options设置原生窗口的属性。
<!DOCTYPE html><html> <head> <meta charset="utf-8"> <title>UI Example</title> <script type="text/javascript">// 扩展API加载完毕后调用onPlusReady回调函数document.addEventListener( "plusready", onPlusReady, false );// 扩展API加载完毕,现在可以正常调用扩展APIfunction onPlusReady() {}function createWinTest() { // 打开新窗口 var nw = plus.ui.createWindow( "http://www.baidu.com" ); // 百度主页 nw.show(); // 显示窗口} </script> </head> <body> <input id="create" type="button" value="Create New Window" onclick="createWinTest();"></input> </body></html>
枚举所有原生窗口
Array[NWindow] plus.ui.enumWindow();
枚举所有未关闭的原生窗口。返回窗口对象数组中按窗口打开先后顺序排列,即数组中第一个窗口对象用通常是应用默认开启的窗口。
无
<!DOCTYPE html><html> <head> <meta charset="utf-8"> <title>UI Example</title> <script type="text/javascript">// 扩展API加载完毕后调用onPlusReady回调函数document.addEventListener( "plusready", onPlusReady, false );// 扩展API加载完毕,现在可以正常调用扩展APIfunction onPlusReady() {}function enumWindow() { // 打开新窗口 var winary = plus.ui.enumWindow(); var mwin = winary[0]; // 获取主窗口 alert( "Main URL: " + mwin.url );} </script> </head> <body> <input id="enum" type="button" value="Enumerate Window" onclick="enumWindow();"></input> </body></html>
查找指定名称的窗口
NWindow plus.ui.findWindowByName( name );
在已打开的窗口列表中查找指定名称的窗口并返回。若没有查找到指定名称的窗口则返回null。 对于应用的首页面,其窗口名称默认为应用的%APPID%。
<!DOCTYPE html><html> <head> <meta charset="utf-8"> <title>UI Example</title> <script type="text/javascript">// 扩展API加载完毕后调用onPlusReady回调函数document.addEventListener( "plusready", onPlusReady, false );// 扩展API加载完毕,现在可以正常调用扩展APIfunction onPlusReady() { // 查找“test”窗口对象 var tw = plus.ui.findWindowByName( "test" ); if ( tw != null ) { alert( "Finded! " ); } // 查找应用首页窗口对象 var home = plus.ui.findWindowByName( plus.runtime.appid );} </script> </head> <body> Find "test" Window </body></html>
获取自身窗口
NWindow plus.ui.getSelfWindow();
获取当前运行脚本所属的原生窗口。
无
<!DOCTYPE html><html> <head> <meta charset="utf-8"> <title>UI Example</title> <script type="text/javascript">// 扩展API加载完毕后调用onPlusReady回调函数document.addEventListener( "plusready", onPlusReady, false );// 扩展API加载完毕,现在可以正常调用扩展APIfunction onPlusReady() { // 打开新窗口 var sw = plus.ui.getSelfWindow(); alert( "I'am: " + sw.url );} </script> </head> <body> Self Window </body></html>
判断应用当前是否全屏模式运行
boolean plus.ui.isFullscreen( fullscreen );
无
弹出日期选择界面
void plus.ui.pickDate( successCB, errorCB, options );
弹出系统日期选择界面,用于选择日期。用户完成选择后通过successCB回调函数返回,若用户取消选择则通过errorCB回调。
<!DOCTYPE html><html> <head> <meta charset="utf-8"> <title>UI Example</title> <script type="text/javascript">// 扩展API加载完毕后调用onPlusReady回调函数document.addEventListener( "plusready", onPlusReady, false );// 扩展API加载完毕,现在可以正常调用扩展APIfunction onPlusReady() { // 输入提示信息框 plus.ui.pickDate( function ( d ) { alert( d.getFullYear() + "-" + (d.getMonth()+1) + "-" + d.getDate() ); }, function ( e ) { }, {startYear:2010,endYear:} );} </script> </head> <body> Pick Date </body></html>
弹出时间选择界面
void plus.ui.pickTime( successCB, errorCB, options );
弹出系统时间选择界面,用于选择时间。用户完成选择后通过successCB回调函数返回,若用户取消选择则通过errorCB回调。
<!DOCTYPE html><html> <head> <meta charset="utf-8"> <title>UI Example</title> <script type="text/javascript">// 扩展API加载完毕后调用onPlusReady回调函数document.addEventListener( "plusready", onPlusReady, false );// 扩展API加载完毕,现在可以正常调用扩展APIfunction onPlusReady() { // 输入提示信息框 plus.ui.pickTime( function ( d ) { alert( d.getHours()() + ":" + d.getMinutes() ); }, function ( e ) { alert( "Pick time error: " + e.message ); }, {is24Hour:true} );} </script> </head> <body> Pick time </body></html>
弹出系统输入框
void plus.ui.confirm( message, promptCB, title, tip, buttons );
弹出系统样式输入对话框,可设置弹出对话框的标题、内容、提示输入信息、按钮数目及其文字。弹出的提示对话框为非阻塞模式,用户点击确认框上的按钮通过promptCB回调函数返回。
<!DOCTYPE html><html> <head> <meta charset="utf-8"> <title>UI Example</title> <script type="text/javascript">// 扩展API加载完毕后调用onPlusReady回调函数document.addEventListener( "plusready", onPlusReady, false );// 扩展API加载完毕,现在可以正常调用扩展APIfunction onPlusReady() { // 输入提示信息框 plus.ui.confirm( "Please input your name:", function ( i, v ) { alert( (i==0)?"Name:"+v:"No input!" ); }, "Input", ["Yes","No"] );} </script> </head> <body> Message notification </body></html>
设置应用是否全屏模式运行
void plus.ui.setFullscreen( fullscreen );
当应用在全屏模式下运行时,将隐藏系统状态栏。通常游戏类应用在这种模式下运行。
显示自动消失的消息
void plus.ui.toast( message, options );
弹出系统样式提示消息框。弹出的提示对话框为非阻塞模式,显示指定时间后自动消失。
<!DOCTYPE html><html> <head> <meta charset="utf-8"> <title>UI Example</title> <script type="text/javascript">// 扩展API加载完毕后调用onPlusReady回调函数document.addEventListener( "plusready", onPlusReady, false );// 扩展API加载完毕,现在可以正常调用扩展APIfunction onPlusReady() { // 输入提示信息框 plus.ui.toast( "I'am toast information!", {duration:"long"} );} </script> </head> <body> Message notification </body></html>
一组用于定义页面或控件显示动画效果
立即显示页面,无任何动画效果,页面显示默认的动画效果。对应关闭动画"none"。
页面从屏幕右侧外向内横向滑动显示。对应关闭动画"slide-out-right"。
页面从屏幕上侧向内竖向滑动显示。对应关闭动画"slide-out-top"。
页面从屏幕下侧向内竖向滑动显示。对应关闭动画"slide-out-bottom"。
页面从完全透明到不透明逐渐显示。对应关闭动画"fade-out"。
页面在屏幕中间从小到大逐渐放大显示。对应关闭动画"zoom-in"。
页面以x轴从上到下翻转显示。对应关闭动画"flip-rx"。
页面以x轴从下到上翻转显示。对应关闭动画"flip-x"。
页面以y轴从左到右翻转显示。对应关闭动画"flip-ry"。
页面以y轴从右到左翻转显示。对应关闭动画"flip-y"。
页面以向前翻书动画显示,翻书后显示新打开的页面。对应关闭动画"page-backward"。
一组用于定义页面或控件关闭的动画效果
立即关闭页面,无任何动画效果。
页面从屏幕中横向向右侧滑动到屏幕外关闭。
页面从屏幕中横向向左侧滑动到屏幕外关闭。
页面从屏幕中竖向向上侧滑动到屏幕外关闭。
页面从屏幕中竖向向下侧滑动到屏幕外关闭。
页面从不透明到透明逐渐隐藏关闭。
页面逐渐向页面中心缩小关闭。
页面以x轴从上到下翻转关闭,翻转后显示以前显示的页面。
页面以x轴从下到上翻转关闭,翻转后显示以前显示的页面。
页面以y轴从左到右翻转关闭,翻转后显示以前显示的页面。
页面以y轴从右到左翻转关闭,翻转后显示以前显示的页面。
页面以向后翻书动画关闭,翻书后显示以前显示的页面。
JSON对象,选择日期界面设置的参数
默认标题为当前的日期。
默认值为当前的日期。
数字类型,如“1940”。
数字类型,如“2024”,其值必须大于startYear,否则取系统默认值。
日期类型对象,其优先级高于startYear属性。
日期类型对象,其值必须大于startYear,否则取系统默认值,优先级高于endYear属性。
JSON类型对象,格式如{top:10;left:10;width:200;height:200;},所有值为像素值,左上坐标相对于容器webview的位置。如未设置此值,默认在屏幕居中显示。仅在iPad上有效。
JSON对象,窗口实际度量信息
原生控件对象,用于操作页面中显示的原生控件
获取窗口实际度量信息
vobj.getMetrics( callback );
用于获取原生控件的度量信息,包括控件的位置、大小等信息。获取成功后通过callback回调返回。
<!DOCTYPE html><html> <head> <meta charset="utf-8"> <title>UI Example</title> <script type="text/javascript">var vobj = null;// 扩展API加载完毕后调用onPlusReady回调函数document.addEventListener( "plusready", onPlusReady, false );// 扩展API加载完毕,现在可以正常调用扩展APIfunction onPlusReady() { var nv = plus.ui.createView( "navigator", {top:"0px",width:"100%",height:"50px"} ); plus.ui.getSelfWindow().append( nv ); // 显示窗口}function metricsTest() { // 获取控件信息 nv.getMetrics( function ( m ) { alert( "Left: " + m.left + "\n Top: " + m.top ); } );} </script> </head> <body> <input id="visible" type="button" value="View Metrics" onclick="metricsTest();"></input> </body></html>
原生控件在窗口中停靠的方式
JSON对象,原生控件元素要设置的参数
原生控件在窗口中显示的位置
NWaiting是等待控件对象,用于在界面中显示原生等待窗口
设置等待控件上显示的文字
wobj.setTitle( title );
设置等待框上显示的文字信息,设置后文字内容将立即更新。
<!DOCTYPE html><html> <head> <meta charset="utf-8"> <title>UI Example</title> <script type="text/javascript">// 扩展API加载完毕后调用onPlusReady回调函数document.addEventListener( "plusready", onPlusReady, false );var w = null;// 扩展API加载完毕,现在可以正常调用扩展APIfunction onPlusReady() { w = plus.ui.createWaiting("请稍后"); setTimeout( function() { w.setTitle( "正在更新" ); }, 2000 ); setTimeout( function() { w.close(); }, 4000 );} </script> </head> <body> </body></html>
关闭等待控件
wobj.close();
将原生等待控件关闭。一个等待控件只能关闭一次,多次调用将无任何作用。
无
<!DOCTYPE html><html> <head> <meta charset="utf-8"> <title>UI Example</title> <script type="text/javascript">// 扩展API加载完毕后调用onPlusReady回调函数document.addEventListener( "plusready", onPlusReady, false );var w = null;// 扩展API加载完毕,现在可以正常调用扩展APIfunction onPlusReady() { w = plus.ui.createWaiting("请稍后");}function closeWaiting() { if ( w == null ) { alert( "未创建等待框" ); } else { w.close(); }} </script> </head> <body> <input id="create" type="button" value="Close Waiting" onclick="closeWaiting();"></input> </body></html>
关闭等待控件事件
wobj.onclose = function () { alert( "Closed!" );};
function 类型
等待框关闭时触发。当调用close方法或用户点击操作导致等待框关闭时触发。
<!DOCTYPE html><html> <head> <meta charset="utf-8"> <title>UI Example</title> <script type="text/javascript">// 扩展API加载完毕后调用onPlusReady回调函数document.addEventListener( "plusready", onPlusReady, false );var w = null;// 扩展API加载完毕,现在可以正常调用扩展APIfunction onPlusReady() { w = plus.ui.createWaiting("请稍后"); w.onclose = function () { alert( "Closed!!" ); }}function closeWaiting() { if ( w == null ) { alert( "未创建等待框" ); } else { w.close(); }} </script> </head> <body> <input id="create" type="button" value="Close Waiting" onclick="closeWaiting();"></input> </body></html>
JSON对象,原生等待控件要设置的参数
颜色值支持(参考CSS颜色规范):颜色名称(参考CSS Color Names)/十六进制值/rgb值/rgba值,默认值为白色。
对齐方式可选值包括:"left":水平居左对齐显示,"center":水平居中对齐显示,"right":水平居右对齐显示。默认值为水平居中对齐显示。
支持像素值和百分比,百分比相对于屏幕的宽计算,默认值为"3%"。
背景色的值支持(参考CSS颜色规范):颜色名称(参考CSS Color Names)/十六进制值/rgb值/rgba值,默认值为rgba(0,0,0,0.8)。
black表示等待框为黑色雪花样式,通常在背景主色为浅色时使用;white表示等待框为白色雪花样式,通常在背景主色为深色时使用;仅在iOS平台有效,其它平台忽略此值,默认值为white。
模态显示则用户不可操作直到等待框关闭,否则用户在等待框显示时也可操作,默认为true。
NWindow是窗口对象,用于操作加载html页面的原生窗口
添加事件监听器
wobj.addEventListener( event, listener, capture );
为窗口添加事件监听器,当指定的窗口事件发生时,回调函数将触发。可多次调用为同一事件添加多个监听器,触发时按照添加的顺序先后调用。
<!DOCTYPE html><html> <head> <meta charset="utf-8"> <title>UI Example</title> <script type="text/javascript">// 扩展API加载完毕后调用onPlusReady回调函数document.addEventListener( "plusready", onPlusReady, false );// 扩展API加载完毕,现在可以正常调用扩展APIfunction onPlusReady() {}function eventTest() { // 打开新窗口 var nw = plus.ui.createWindow( "http://www.test.com" ); nw.addEventListener( "loaded", function () { alert( "New Window loaded!" ); }, false ); nw.show(); // 显示窗口} </script> </head> <body> <input id="event" type="button" value="Window Event" onclick="eventTest();"></input> </body></html>
在窗口中添加原生界面控件
void wobj.append( view );
将原生控件添加到界面中,随界面一起显示。控件只能添加到一个界面中,多次调用将无任何作用。
<!DOCTYPE html><html> <head> <meta charset="utf-8"> <title>UI Example</title> <script type="text/javascript">// 扩展API加载完毕后调用onPlusReady回调函数document.addEventListener( "plusready", onPlusReady, false );// 扩展API加载完毕,现在可以正常调用扩展APIfunction onPlusReady() {}function createViewTest() { // 创建控件 var nv = plus.ui.createView( "navigator" ); plus.ui.getSelfWindow().append( nv ); // 显示控件} </script> </head> <body> <input id="create" type="button" value="Create New View" onclick="createViewTest();"></input> </body></html>
添加页面预先加载的js文件
wobj.appendPreloadJsFile( file );
添加页面加载时需要预先执行的js文件,以完成特殊的页面处理。在窗口页面跳转时也需要执行,添加多个js文件后将按照添加的先后顺序执行。
窗口后退到上次加载的页面内容
void wobj.back();
窗口历史记录操作,后退到窗口上次加载的页面内容。如果窗口历史记录中没有可后退的页面则不触发任何操作。
无
<!DOCTYPE html><html> <head> <meta charset="utf-8"> <title>UI Example</title> <script type="text/javascript">// 扩展API加载完毕后调用onPlusReady回调函数document.addEventListener( "plusready", onPlusReady, false );// 扩展API加载完毕,现在可以正常调用扩展APIfunction onPlusReady() { // Plus API}function goBack() { var nw = plus.ui.getSelfWindow(); nw.back();} </script> </head> <body> <button onclick="goBack();">返回</input> </body></html>
查询窗口是否可后退到上次加载的页面内容
void wobj.canBack( queryCallback );
窗口历史记录操作,查询是否可后退到窗口上次加载的页面内容。查询成功将通过queryCallback回调方法返回结果。
<!DOCTYPE html><html> <head> <meta charset="utf-8"> <title>UI Example</title> <script type="text/javascript">// 扩展API加载完毕后调用onPlusReady回调函数document.addEventListener( "plusready", onPlusReady, false );// 扩展API加载完毕,现在可以正常调用扩展APIfunction onPlusReady() { // Plus API}function queryBack() { var nw = plus.ui.getSelfWindow(); nw.canBack( function ( able ) { if ( able ) { alert( "可以后退" ); } else { alert( "无法后退" ); } } );} </script> </head> <body> <button onclick="queryBack();">是否可后退</input> </body></html>
查询窗口是否可前进到上次加载的页面内容
void wobj.canForward( queryCallback );
窗口历史记录操作,查询是否可前进到窗口上次加载的页面内容。查询成功将通过queryCallback回调方法返回结果。
<!DOCTYPE html><html> <head> <meta charset="utf-8"> <title>UI Example</title> <script type="text/javascript">// 扩展API加载完毕后调用onPlusReady回调函数document.addEventListener( "plusready", onPlusReady, false );// 扩展API加载完毕,现在可以正常调用扩展APIfunction onPlusReady() { // Plus API}function queryForward() { var nw = plus.ui.getSelfWindow(); nw.canForward( function ( able ) { if ( able ) { alert( "可以前进" ); } else { alert( "无法前进" ); } } );} </script> </head> <body> <button onclick="queryForward();">是否可前进</input> </body></html>
清空原生窗口加载的内容
void wobj.clear();
清除原生窗口的内容,用于重置重置原生窗口加载的内容,清除其加载的历史记录等内容。
无
<!DOCTYPE html><html> <head> <meta charset="utf-8"> <title>UI Example</title> <script type="text/javascript">// 扩展API加载完毕后调用onPlusReady回调函数document.addEventListener( "plusready", onPlusReady, false );// 扩展API加载完毕,现在可以正常调用扩展APIfunction onPlusReady() {}function clearWin() { // 清除自身窗口 var nw = plus.ui.getSelfWindow(); nw.clear();} </script> </head> <body> <input id="close" type="button" value="Clear Window" onclick="clearWin();"></input> </body></html>
关闭创建新的原生窗口
void wobj.close( aniClose, duration );
关闭原生窗口,用于销毁创建的系统原生窗口。原生窗口窗口只能关闭一次,关闭窗口后不可再操作窗口对象,操作后将无任何效果。窗口关闭时默认会使用窗口打开时设置的相反动画效果,也可通过aniClose设置原生窗口关闭动画,仅能使用动画类型中的关闭动画效果。
<!DOCTYPE html><html> <head> <meta charset="utf-8"> <title>UI Example</title> <script type="text/javascript">// 扩展API加载完毕后调用onPlusReady回调函数document.addEventListener( "plusready", onPlusReady, false );// 扩展API加载完毕,现在可以正常调用扩展APIfunction onPlusReady() {}function closeWin() { // 关闭自身窗口 var nw = plus.ui.getSelfWindow(); nw.close(); // 关闭窗口} </script> </head> <body> <input id="close" type="button" value="Close Window" onclick="closeWin();"></input> </body></html>
关闭原生窗口刷新状态
void wobj.endPullToRefresh();
通过setPullToRefresh方法可开启窗口的下拉刷新功能,当用户操作触发刷新回调事件后,可以通过此方法关闭窗口的刷新状态。 关闭刷新状态后,用于依然可以通过下拉操作继续触发刷新事件。
无
<!DOCTYPE html><html> <head> <meta charset="utf-8"> <title>UI Example</title> <script type="text/javascript">// 扩展API加载完毕后调用onPlusReady回调函数document.addEventListener( "plusready", onPlusReady, false );// 扩展API加载完毕,现在可以正常调用扩展APIfunction onPlusReady() {}function closeWin() { // 关闭自身窗口 var nw = plus.ui.getSelfWindow(); nw.close(); // 关闭窗口} </script> </head> <body> <input id="close" type="button" value="Close Window" onclick="closeWin();"></input> </body></html>
在窗口中执行脚本
void wobj.evalJS( js );
可在窗口中运行脚本,实现跨窗口间的数据操作。
<!DOCTYPE html><html> <head> <meta charset="utf-8"> <title>UI Example</title> <script type="text/javascript">// 扩展API加载完毕后调用onPlusReady回调函数document.addEventListener( "plusready", onPlusReady, false );// 扩展API加载完毕,现在可以正常调用扩展APIfunction onPlusReady() {}function evalJSTest() { // 查找到只指定的界面 var nw = plus.ui.findWindowByName( "test" ); nw.evalJS( "var bt = document.getElementById('bt'); bt.value='NewValue';" );} </script> </head> <body> <input id="evaljs" type="button" value="Eval JS" onclick="evalJSTest();"></input> </body></html>
在界面中通过id查找控件对象
void wobj.findViewById( id );
在当前界面中查找控件对象,并返回控件对象的引用。其中控件的id在创建时通过NViewOption中的id字段设置。如果没有找到则返回null
<!DOCTYPE html><html> <head> <meta charset="utf-8"> <title>UI Example</title> <script type="text/javascript">// 扩展API加载完毕后调用onPlusReady回调函数document.addEventListener( "plusready", onPlusReady, false );// 扩展API加载完毕,现在可以正常调用扩展APIvar sw = null;function onPlusReady() { sw = plus.ui.getSelfWindow(); // 创建控件 var nv = plus.ui.createView( "navigator", {id:"nav"} ); sw.append( nv ); // 显示控件}var fnv = null;function findTest() { fnv = sw.findViewById( "nav" ); // 可通过fnv对象操作导航控件} </script> </head> <body> <input id="visible" type="button" value="Window Visible" onclick="visibleTest();"></input> </body></html>
窗口前进到上次加载的页面内容
void wobj.forward();
窗口历史记录操作,前进到窗口上次加载的页面内容。如果窗口历史记录中没有可前进的页面则不触发任何操作。
无
<!DOCTYPE html><html> <head> <meta charset="utf-8"> <title>UI Example</title> <script type="text/javascript">// 扩展API加载完毕后调用onPlusReady回调函数document.addEventListener( "plusready", onPlusReady, false );// 扩展API加载完毕,现在可以正常调用扩展APIfunction onPlusReady() { // Plus API}function goForward() { var nw = plus.ui.getSelfWindow(); nw.forward();} </script> </head> <body> <button onclick="goForward();">返回</input> </body></html>
获取窗口实际度量信息
void wobj.getMetrics( callback );
用于获取窗口实际度量信息,包括窗口的位置、大小等信息。获取度量信息成功后通过callback回调返回。/隐藏,再次调用显示/隐藏则无任何作用。
<!DOCTYPE html><html> <head> <meta charset="utf-8"> <title>UI Example</title> <script type="text/javascript">// 扩展API加载完毕后调用onPlusReady回调函数document.addEventListener( "plusready", onPlusReady, false );// 扩展API加载完毕,现在可以正常调用扩展APIfunction onPlusReady() {}function metricsTest() { // 获取窗口信息 var sw = plus.ui.getSelfWindow(); sw.getMetrics( function ( m ) { alert( "Left: " + m.left + "\n Top: " + m.top ); } );} </script> </head> <body> <input id="visible" type="button" value="Window Metrics" onclick="metricsTest();"></input> </body></html>
获取窗口当前的属性值
NWindowOption wobj.getOption();
获取原生窗口的属性,如窗口位置、大小等信息。
无
<!DOCTYPE html><html> <head> <meta charset="utf-8"> <title>UI Example</title> <script type="text/javascript">// 扩展API加载完毕后调用onPlusReady回调函数document.addEventListener( "plusready", onPlusReady, false );// 扩展API加载完毕,现在可以正常调用扩展APIfunction onPlusReady() {}function optionTest() { var nw = plus.ui.getSelfWindow(); alert( nw.getOption().left );} </script> </head> <body> <input id="option" type="button" value="Get Window Left" onclick="optionTest();"></input> </body></html>
获取窗口加载页面的标题
DOMString wobj.getTitle();
标题为窗口加载的html页面head节点下title节点中的文本内容,当窗口内容发生页面内跳转时可通过窗口触发的“loaded”事件中调用此方法来获取跳转后页面的标题。如果页面中午title节点则返回空字符串。
无
<!DOCTYPE html><html> <head> <meta charset="utf-8"> <title>UI Example</title> <script type="text/javascript">// 扩展API加载完毕后调用onPlusReady回调函数document.addEventListener( "plusready", onPlusReady, false );// 扩展API加载完毕,现在可以正常调用扩展APIfunction onPlusReady() {}function test() { // 打开新窗口 var nw = plus.ui.createWindow( "http://www.baidu.com" ); nw.addEventListener( "loaded", function () { alert( "标题:"+nw.getTitle() ); }, false ); nw.show(); // 显示窗口} </script> </head> <body> <button onclick="test()">打开新页面</button> </body></html>
获取窗口加载页面的地址
DOMString wobj.getUrl();
当窗口内容发生页面内跳转时可通过窗口触发的“loaded”事件中调用此方法来获取跳转后页面的地址。
无
<!DOCTYPE html><html> <head> <meta charset="utf-8"> <title>UI Example</title> <script type="text/javascript">// 扩展API加载完毕后调用onPlusReady回调函数document.addEventListener( "plusready", onPlusReady, false );// 扩展API加载完毕,现在可以正常调用扩展APIfunction onPlusReady() {}function test() { // 打开新窗口 var nw = plus.ui.createWindow( "http://www.baidu.com" ); nw.addEventListener( "loaded", function () { alert( "跳转地址:"+nw.getUrl() ); }, false ); nw.show(); // 显示窗口} </script> </head> <body> <button onclick="test()">打开新页面</button> </body></html>
窗口加载新的页面
void wobj.load( url );
触发原生窗口加载新的页面地址。如果新设置的url地址无效将导致页面显示失败。
<!DOCTYPE html><html> <head> <meta charset="utf-8"> <title>UI Example</title> <script type="text/javascript">// 扩展API加载完毕后调用onPlusReady回调函数document.addEventListener( "plusready", onPlusReady, false );// 扩展API加载完毕,现在可以正常调用扩展APIfunction onPlusReady() {}function jumpUrl() { var nw = plus.ui.getSelfWindow(); nw.load( "http://www.test.com" ); // 跳转到新的页面} </script> </head> <body> <button onclick="jumpUrl();">跳转到新页面</button> </body></html>
重新加载窗口当前显示的页面
void wobj.reload( force );
触发原生窗口重新加载当前显示的页面地址。如果当前页面未加载完则停止并重新加载,如果当前没有加载任何页面则无响应。
<!DOCTYPE html><html> <head> <meta charset="utf-8"> <title>UI Example</title> <script type="text/javascript">// 扩展API加载完毕后调用onPlusReady回调函数document.addEventListener( "plusready", onPlusReady, false );// 扩展API加载完毕,现在可以正常调用扩展APIfunction onPlusReady() {}function refresh() { var nw = plus.ui.getSelfWindow(); nw.reload( true );} </script> </head> <body> <button onclick="refresh();">重新加载</button> </body></html>
移除事件监听器
wobj.removeEventListener( event, listener );
从窗口移除指定的事件监听器。若没有查找到对应的事件监听器,则无任何作用。
<!DOCTYPE html><html> <head> <meta charset="utf-8"> <title>UI Example</title> <script type="text/javascript">// 扩展API加载完毕后调用onPlusReady回调函数document.addEventListener( "plusready", onPlusReady, false );// 扩展API加载完毕,现在可以正常调用扩展APIfunction onPlusReady() {}function onloaded () { alert( "New Window loaded!" );}var nw = null;function eventTest() { // 打开新窗口 nw = plus.ui.createWindow( "http://www.test.com" ); nw.addEventListener( "loaded",onloaded, false ); // 10s后显示窗口 setTimeout( function () { nw.show(); }, 10000 );}function removeEvent () { nw.removeEventListener( "loaded", onloaded );} </script> </head> <body> <input id="event" type="button" value="Window Event" onclick="eventTest();"></input> <input id="event" type="button" value="Remove Event" onclick="removeEvent();"></input> </body></html>
设置页面内容是否可见
void wobj.setContentVisible( visible );
在某些特殊情况下需要对页面内容进行预处理,如对内容进行过滤转换,为了不让内容在转换完成之前显示,则可先通过此方法设置页面内容不可见,带内容转换完成后再设置页面内容可见。
设置原生窗口的参数
void wobj.setOption( options );
设置原生窗口的属性,如窗口位置、大小等信息。
<!DOCTYPE html><html> <head> <meta charset="utf-8"> <title>UI Example</title> <script type="text/javascript">// 扩展API加载完毕后调用onPlusReady回调函数document.addEventListener( "plusready", onPlusReady, false );// 扩展API加载完毕,现在可以正常调用扩展APIfunction onPlusReady() {}function moveWinTo() { var nw = plus.ui.getSelfWindow(); nw.setOption( {left:50%} ); // 水平移动窗口到屏幕中间位置} </script> </head> <body> <button onclick="moveWinTo();">移动窗口</button> </body></html>
设置页面预先加载的js文件
wobj.setPreloadJsFile( file );
某些页面加载时预先执行插入的js文件,以完成特殊的页面处理。在窗口页面跳转时也需要执行,设置新的js文件后将清空之前设置的值。
设置窗口的下拉刷新功能
wobj.setPullToRefresh( PullToRefreshOption options, PullToRefreshCallback refreshCB );
窗口自带下拉刷新功能,当用户触发刷新操作时通过refreshCB函数通知应用执行刷新操作。 此时窗口进入刷新状态并一直显示下拉刷新控件,直到调用endPullToRefresh方法退出刷新状态。
<!DOCTYPE HTML><html> <head> <meta charset="utf-8"/> <meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0, user-scalable=no"/> <title>Pull to refresh</title> <script type="text/javascript" charset="utf-8">var ws=null;var list=null;// 扩展API加载完毕,现在可以正常调用扩展API function plusReady(){ ws=plus.ui.getSelfWindow(); ws.setPullToRefresh({ support:true, height:"100px", contentdown:{ caption:"下拉可以刷新" }, contentover:{ caption:"释放立即刷新" }, contentrefresh:{ caption:"正在刷新..." } },onRefresh);}// 判断扩展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 "+dateToStr(new Date())+"</span>"; list.insertBefore(item,list.firstChild); } ws.endPullToRefresh(); },2000);} </script> <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>
设置窗口是否可见
void wobj.setVisible( visible );
用于隐藏原生窗口,减少显示的窗口数目,可降低占用的系统资源,通常在打开新窗口后隐藏不需要显示的窗口。窗口隐藏后,如果要显示则必须调用此方法将窗口显示,否则将导致窗口不显示。如果当前窗口已经显示/隐藏,再次调用显示/隐藏则无任何作用。
<!DOCTYPE html><html> <head> <meta charset="utf-8"> <title>UI Example</title> <script type="text/javascript">// 扩展API加载完毕后调用onPlusReady回调函数document.addEventListener( "plusready", onPlusReady, false );// 扩展API加载完毕,现在可以正常调用扩展APIfunction onPlusReady() {}function visibleTest() { // 打开新窗口 var nw = plus.ui.createWindow( "http://www.test.com" ); var sw = plus.ui.getSelfWindow(); nw.show(); // 显示窗口 sw.setVisible( false ); // 隐藏当前窗口} </script> </head> <body> <input id="visible" type="button" value="Window Visible" onclick="visibleTest();"></input> </body></html>
显示创建新的原生窗口
void wobj.show( aniShow, duration, assWin );
显示原生窗口,用于显示创建的系统原生窗口。原生窗口窗口只能显示一次,多次调用show方法将无任何作用。可通过aniShow设置原生窗口显示动画。
<!DOCTYPE html><html> <head> <meta charset="utf-8"> <title>UI Example</title> <script type="text/javascript">// 扩展API加载完毕后调用onPlusReady回调函数document.addEventListener( "plusready", onPlusReady, false );// 扩展API加载完毕,现在可以正常调用扩展APIfunction onPlusReady() {}function createWinTest() { // 打开新窗口 var nw = plus.ui.createWindow( "http://www.baidu.com" ); // 百度主页 nw.show( "slide-in-right", 500 ); // 显示窗口,动画时间为500毫秒} </script> </head> <body> <input id="create" type="button" value="Create New Window" onclick="createWinTest();"></input> </body></html>
窗口停止加载页面内容
void wobj.stop();
触发原生窗口停止加载页面内容。如果已经加载部分内容则显示部分内容,如果加载完成则显示全部内容。
无
<!DOCTYPE html><html> <head> <meta charset="utf-8"> <title>UI Example</title> <script type="text/javascript">// 扩展API加载完毕后调用onPlusReady回调函数document.addEventListener( "plusready", onPlusReady, false );// 扩展API加载完毕,现在可以正常调用扩展APIfunction onPlusReady() {}function stopLoad() { var nw = plus.ui.getSelfWindow(); nw.stop();} </script> </head> <body> <button onclick="stopLoad();">停止加载</input> </body></html>
窗口事件对象
JSON对象,原生窗口设置参数的对象
窗口空白区域的背景,设置了background则窗口为独占模式显示(占整个屏幕区域),否则为非独占模式,目前仅支持背景色的设置(参考CSS颜色规范):颜色名称(参考CSS Color Names)/十六进制值/rgb值/rgba值。
支持百分比、像素值,当设置了top和height值时,此属性值忽略;当设置top和bottom属性则自动计算窗口的高度。
可取值:none表示没有反弹效果;vertical表示垂直方向有反弹效果;horizontal表示水平方向有反弹效果;all表示垂直和水平方向都有反弹效果。
支持百分比、像素值,默认为100%。
支持百分比、像素值,默认值为0px。
用于定位窗口的位置,支持auto,auto表示居中。若设置了left、right、top、bottom则对应的边距值失效。
作为窗口的标识,可用于窗口的查找。
0为全透明,1为不透明,默认值为1,即不透明。
支持百分比、像素值,默认无值。当设置了left和width值时,此属性值忽略;当设置left和right属性则自动计算窗口的宽度。
默认值为true,即可缩放。 窗口设置为可缩放(scalable:true)时,用户可通过双指操作放大或缩小页面,这时html页面可通过meta节点name="viewport"来限制页面是否可缩放。 窗口设置为不可缩放(scalable:false)时,用户不可通过双指操作放大或缩小页面,即使页面中的meta节点也无法开启可缩放功能。 窗口的默认值为可缩放(scalable:true)。
用于控制窗口滚动条样式,可取值:"all":垂直和水平滚动条都显示,"vertical":仅显示垂直,"horizontal":仅显示水平滚动条,"none":垂直和水平滚动条都不显示。默认值为"all",即垂直和水平滚动条都显示。 注意:显示滚动条的前提条件是窗口中的内容超过窗口显示的宽或高。
支持百分比、像素值,默认值为0px。
支持百分比、像素值,默认为100%。
拥有更高堆叠顺序的窗口总是会处于堆叠顺序较低的窗口的前面,拥有相同堆叠顺序的窗口后调用show方法则在前面。
JSON对象,原生窗口设置参数的对象
true表示开启下拉刷新功能,false表示关闭下拉刷新功能,默认值为true。
当用户下拉操作的高度大于或等于此值事,松开后则进入刷新状态。 可支持像素值和百分比,像素值为绝对值,以px结尾;百分比相对窗口的高度,以%结尾;如“60px”、“10%”,默认值为“100px”。 注:当下拉的高度大于等于刷新控件的高度时,控件居底显示。
用户可下拉的最大高度,此值必须大于height值,否则将会导致无法触发刷新事件。 可支持像素值和百分比,像素值为绝对值,以px结尾;百分比相对窗口的高度,以%结尾; 如“60px”、“10%”,默认值为height值。
仅支持caption字段,用于设置下拉状态时显示的文本内容。
仅支持caption字段,用于设置可刷新状态时显示的文本内容。
仅支持caption字段,用于设置在刷新状态时显示的文本内容。
JSON对象,选择时间界面设置的参数
字符串类型,默认标题为当前选择的时间。
JSON对象,格式如{top:10;left:10;width:200;height:200;},所有值为像素值,左上坐标相对于容器webview的位置。如未设置此值,默认在屏幕居中显示。
JSON对象,系统提示消息框要设置的参数
可选值为"long"、"short",值为"long"约为3.5s,值为"short"时约为2s,默认值为"short"。
可选值为"left"、"center"、"right",分别为水平居左、居中、居右,默认值为"center"。
可选值为"top"、"center"、"bottom",分别为垂直居顶、居中、居底,默认值为"bottom"。
一组用于定义页面或控件变形的属性,暂不支持
一组用于定义页面或控件转换效果的属性
默认值为"all",暂不支持其它值。
默认值为0,即无动画效果。
可取值linear、ease-in、ease-out、ease-in-out,默认值为linear。
系统提示框确认的回调函数
void onAlerted() { // Alert handled code.}
无
系统确认框操作的回调函数
void onConfirmed( Number index ) { // Confirm handled code.}
系统输入框操作的回调函数
function void onPrompted( Number index, DOMString value ) { // Prompt handled code.}
系统消息框消失时的回调函数
void onToast() { // Toast close handled code.}
无
选择日期或时间操作成功的回调函数
function void onPickSuccess( DOMDate date ) { // Date picked code.}
选择日期或时间操作失败的回调函数
function void onPickError( DOMException error ) { // Date picked error. alert( error.message );}
获取控件或窗口实际度量信息回调函数
void onMetricsCompleted( Metrics metrics ) { // Get metrics completed code.}
窗口事件的回调函数
void onEvent() { // Event handled code.}
无
历史记录记录查询的回调函数
void onQuery( able ) { // Event handled code.}
窗口刷新操作的回调函数
void onRefresh() { // Event handled code.}
无
联系客服