ui
优质
小牛编辑
122浏览
2023-12-01
UI模块管理应用界面，用于操作加载HTML页面的原生窗口，调用系统原生控件等。由于此模块功能太多，现已根据功能分拆更新为Key、NativeUI、Navigator、Webview等，并对接口和功能做了一些优化调整，请使用新API。
方法：
- alert: 弹出系统提示框
- closeSplashscreen: 关闭程序启动界面
- closeWindow: 关闭原生窗口
- confirm: 弹出系统确认对话框
- createView: 创建新的原生控件对象
- createWaiting: 创建等待对话框
- createWindow: 创建新的原生窗口
- enumWindow: 枚举所有原生窗口
- findWindowByName: 查找指定名称的窗口
- getSelfWindow: 获取自身窗口
- isFullscreen: 判断应用当前是否全屏模式运行
- pickDate: 弹出日期选择界面
- pickTime: 弹出时间选择界面
- prompt: 弹出系统输入框
- setFullscreen: 设置应用是否全屏模式运行
- toast: 显示自动消失的消息
对象：
- AnimationTypeShow: 一组用于定义页面或控件显示动画效果
- AnimationTypeClose: 一组用于定义页面或控件关闭的动画效果
- DateOption: JSON对象，选择日期界面设置的参数
- Metrics: JSON对象，窗口实际度量信息
- NView: 原生控件对象，用于操作页面中显示的原生控件
- NViewDock: 原生控件在窗口中停靠的方式
- NViewOption: JSON对象，原生控件元素要设置的参数
- NViewPosition: 原生控件在窗口中显示的位置
- NWaiting: NWaiting是等待控件对象，用于在界面中显示原生等待窗口
- NWaitingOption: JSON对象，原生等待控件要设置的参数
- NWindow: NWindow是窗口对象，用于操作加载html页面的原生窗口
- NWindowEvent: 窗口事件对象
- NWindowOption: JSON对象，原生窗口设置参数的对象
- PullToRefreshOption: JSON对象，原生窗口设置参数的对象
- TimeOption: JSON对象，选择时间界面设置的参数
- ToastOption: JSON对象，系统提示消息框要设置的参数
- Transform: 一组用于定义页面或控件变形的属性，暂不支持
- Transition: 一组用于定义页面或控件转换效果的属性
回调方法：
- AlertCallback: 系统提示框确认的回调函数
- ConfirmCallback: 系统确认框操作的回调函数
- PromptCallback: 系统输入框操作的回调函数
- ToastCallback: 系统消息框消失时的回调函数
- PickDatetimeSuccessCallback: 选择日期或时间操作成功的回调函数
- PickDatetimeErrorCallback: 选择日期或时间操作失败的回调函数
- MetricsCallback: 获取控件或窗口实际度量信息回调函数
- EventCallback: 窗口事件的回调函数
- HistoryQueryCallback: 历史记录记录查询的回调函数
- PullToRefreshCallback: 窗口刷新操作的回调函数
权限：
5+功能模块（permissions）
{
// ...
"permissions":{
// ...
"UI": {
"description": "访问系统原生窗口"
}
}
}
alert
弹出系统提示框
void plus.ui.alert( message, alertCB, title, buttonCapture );
说明：
弹出系统样式提示对话框，可设置弹出对话框的标题、内容、按钮文字。此API非阻塞模式，用户点击提示框上的按钮需通过alertCB回调函数返回。
参数：
- message: ( DOMString ) 必选 提示对话框上显示的内容
- alertCB: ( AlertCallback ) 可选 点击提示对话框上按钮后的回调函数
- title: ( DOMString ) 可选 提示对话框上显示的标题
- buttonCapture: ( DOMString ) 必选 提示对话框上按钮的名称
返回值：
void : 无平台支持：
- Android - 2.2+ (支持)
- iOS - 4.3+ (支持)
示例：
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>UI Example</title>
<script type="text/javascript">
// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );
// 扩展API加载完毕，现在可以正常调用扩展API
function onPlusReady() {
// 弹出提示信息框
plus.ui.alert( "Plus is ready!", function () {
alert( "User pressed OK!" );
}, "Hell0", "OK" );
}
</script>
</head>
<body>
Message notification
</body>
</html>
closeSplashscreen
关闭程序启动界面
void plus.ui.closeSplashscreen();
说明：
在某些情况下，程序启动后需要较长时间加载数据，为了避免界面显示空白内容，提高用户体验效果，这时可显示启动界面，直到数据加载完成后再关闭启动界面，通常在应用的首界面加载完成并更新显示内容后调用。
参数：
无
返回值：
void : 无示例：
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>UI Example</title>
<script type="text/javascript">
// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );
// 扩展API加载完毕，现在可以正常调用扩展API
function onPlusReady() {
// 页面内容加载完成，关闭程序启动界面
plus.ui.closeSplashscreen();
}
</script>
</head>
<body>
Message notification
</body>
</html>
closeWindow
关闭原生窗口
void plus.ui.closeWindow( win, aniClose, duration );
说明：
关闭已经打开的原生窗口。
参数：
- win: ( DOMString ) 必选 要关闭的原生窗口
可以是窗口对象，也可以是窗口的name值。
- aniClose: ( AnimationTypeClose ) 可选 关闭原生窗口的动画效果
- duration: ( Number ) 可选 关闭原生窗口的动画持续时间
单位为ms，默认为窗口show方法设定的动画时间。
返回值：
void : 无平台支持：
- Android - 2.2+ (支持)
- iOS - 4.3+ (支持)
示例：
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>UI Example</title>
<script type="text/javascript">
// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );
// 扩展API加载完毕，现在可以正常调用扩展API
function 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>
confirm
弹出系统确认对话框
void plus.ui.confirm( message, confirmCB, title, buttons );
说明：
弹出系统样式确认对话框，可设置弹出对话框的标题、内容、按钮数目及其文字。弹出的提示对话框为非阻塞模式，用户点击确认框上的按钮通过confirmCB回调函数返回。
参数：
- message: ( DOMString ) 必选 确认对话框上显示的内容
- confirmCB: ( ConfirmCallback ) 可选 点击确认对话框上按钮后的回调函数
- title: ( DOMString ) 可选 确认对话框上显示的标题
- buttons: ( DOMString[] ) 可选 确认对话框上显示的按钮数组
返回值：
void : 无平台支持：
- Android - 2.2+ (支持)
- iOS - 4.3+ (支持)
示例：
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>UI Example</title>
<script type="text/javascript">
// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );
// 扩展API加载完毕，现在可以正常调用扩展API
function 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>
createView
创建新的原生控件对象
NView plus.ui.createView( identity, options );
说明：
创建原生窗口显示元素，用于加载新的显示元素。可通过options设置原生窗口显示元素的属性。
参数：
- identity: ( DOMString ) 必选 新创建显示元素的标识，需通过原生UI扩展注册
- options: ( NViewOption ) 可选 新打开原生窗口显示元素的参数（如元素宽、高、位置等信息）
返回值：
NView : NView对象平台支持：
- Android - 2.2+ (支持)
- iOS - 4.3+ (支持)
示例：
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>UI Example</title>
<script type="text/javascript">
// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );
// 扩展API加载完毕，现在可以正常调用扩展API
function 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>
createWaiting
创建等待对话框
NWaiting plus.ui.createWaiting( title, options );
说明：
在程序中创建并显示等待对话框。
参数：
- title: ( DOMString ) 可选 等待框上显示的提示文字
- options: ( NWaitingOption ) 可选 等待框的显示参数
返回值：
NWaiting : NWaiting对象平台支持：
- Android - 2.2+ (支持)
- iOS - 4.3+ (支持)
示例：
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>UI Example</title>
<script type="text/javascript">
// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );
// 扩展API加载完毕，现在可以正常调用扩展API
function onPlusReady() {
// 打开新窗口
var w = plus.ui.createWaiting( "等待中..." );
}
</script>
</head>
<body>
等待对话框。
</body>
</html>
createWindow
创建新的原生窗口
NWindow plus.ui.createWindow( url, options );
说明：
创建原生窗口，用于加载新的系统原生窗口。可通过options设置原生窗口的属性。
参数：
- url: ( DOMString ) 必选 创建窗口要打开的页面地址
新打开原生窗口要加载html页面地址，可支持本地地址和网络地址。
- options: ( NWindowOption ) 可选 新打开原生窗口的参数（如窗口宽、高、位置等信息）
返回值：
NWindow : NWindow对象平台支持：
- Android - 2.2+ (支持)
- iOS - 4.3+ (支持)
示例：
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>UI Example</title>
<script type="text/javascript">
// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );
// 扩展API加载完毕，现在可以正常调用扩展API
function 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>
enumWindow
枚举所有原生窗口
Array[NWindow] plus.ui.enumWindow();
说明：
枚举所有未关闭的原生窗口。返回窗口对象数组中按窗口打开先后顺序排列，即数组中第一个窗口对象用通常是应用默认开启的窗口。
参数：
无
返回值：
NWindow : NWindow数组对象平台支持：
- Android - 2.2+ (支持)
- iOS - 4.3+ (支持)
示例：
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>UI Example</title>
<script type="text/javascript">
// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );
// 扩展API加载完毕，现在可以正常调用扩展API
function 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>
findWindowByName
查找指定名称的窗口
NWindow plus.ui.findWindowByName( name );
说明：
在已打开的窗口列表中查找指定名称的窗口并返回。若没有查找到指定名称的窗口则返回null。 对于应用的首页面，其窗口名称默认为应用的%APPID%。
参数：
- name: ( DOMString ) 必选 要查找的窗口名称
返回值：
NWindow : NWindow对象平台支持：
- Android - 2.2+ (支持)
- iOS - 4.3+ (支持)
示例：
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>UI Example</title>
<script type="text/javascript">
// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );
// 扩展API加载完毕，现在可以正常调用扩展API
function 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>
getSelfWindow
获取自身窗口
NWindow plus.ui.getSelfWindow();
说明：
获取当前运行脚本所属的原生窗口。
参数：
无
返回值：
NWindow : NWindow对象平台支持：
- Android - 2.2+ (支持)
- iOS - 4.3+ (支持)
示例：
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>UI Example</title>
<script type="text/javascript">
// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );
// 扩展API加载完毕，现在可以正常调用扩展API
function onPlusReady() {
// 打开新窗口
var sw = plus.ui.getSelfWindow();
alert( "I'am: " + sw.url );
}
</script>
</head>
<body>
Self Window
</body>
</html>
isFullscreen
判断应用当前是否全屏模式运行
boolean plus.ui.isFullscreen( fullscreen );
参数：
无
返回值：
Boolean : 当应用在全屏模式下运行时返回true，否则返回false。pickDate
弹出日期选择界面
void plus.ui.pickDate( successCB, errorCB, options );
说明：
弹出系统日期选择界面，用于选择日期。用户完成选择后通过successCB回调函数返回，若用户取消选择则通过errorCB回调。
参数：
- successCB: ( PickDatetimeSuccessCallback ) 必选 日期选择操作成功的回调函数
- errorCB: ( PickDatetimeErrorCallback ) 可选 日期选择操作失败的回调函数
- options: ( DateOption ) 可选 日期选择操作界面的参数
返回值：
void : 无平台支持：
- Android - 2.2+ (支持)
- iOS - 4.3+ (支持)
示例：
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>UI Example</title>
<script type="text/javascript">
// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );
// 扩展API加载完毕，现在可以正常调用扩展API
function 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>
pickTime
弹出时间选择界面
void plus.ui.pickTime( successCB, errorCB, options );
说明：
弹出系统时间选择界面，用于选择时间。用户完成选择后通过successCB回调函数返回，若用户取消选择则通过errorCB回调。
参数：
- successCB: ( PickDatetimeSuccessCallback ) 必选 时间选择操作成功的回调函数
- errorCB: ( PickDatetimeErrorCallback ) 可选 时间选择操作失败的回调函数
- options: ( TimeOption ) 可选 时间选择操作界面的参数
返回值：
void : 无平台支持：
- Android - 2.2+ (支持)
- iOS - 4.3+ (支持)
示例：
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>UI Example</title>
<script type="text/javascript">
// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );
// 扩展API加载完毕，现在可以正常调用扩展API
function 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>
prompt
弹出系统输入框
void plus.ui.confirm( message, promptCB, title, tip, buttons );
说明：
弹出系统样式输入对话框，可设置弹出对话框的标题、内容、提示输入信息、按钮数目及其文字。弹出的提示对话框为非阻塞模式，用户点击确认框上的按钮通过promptCB回调函数返回。
参数：
- message: ( DOMString ) 必选 输入对话框上显示的内容
- promptCB: ( PromptCallback ) 可选 点击输入对话框上按钮后的回调函数
- title: ( DOMString ) 可选 输入对话框上显示的标题
- tip: ( DOMString ) 可选 输入对话框上显示的提示文字
- buttons: ( DOMString[] ) 可选 输入对话框上显示的按钮数组
返回值：
void : 无平台支持：
- Android - 2.2+ (支持)
- iOS - 4.3+ (支持)
示例：
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>UI Example</title>
<script type="text/javascript">
// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );
// 扩展API加载完毕，现在可以正常调用扩展API
function 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>
setFullscreen
设置应用是否全屏模式运行
void plus.ui.setFullscreen( fullscreen );
说明：
当应用在全屏模式下运行时，将隐藏系统状态栏。通常游戏类应用在这种模式下运行。
参数：
- fullscreen: ( Boolean ) 必选 是否全屏模式运行，true表示全屏模式运行，false表示非全屏模式运行
返回值：
void : 无toast
显示自动消失的消息
void plus.ui.toast( message, options );
说明：
弹出系统样式提示消息框。弹出的提示对话框为非阻塞模式，显示指定时间后自动消失。
参数：
- message: ( DOMString ) 必选 提示消息框上显示的文字内容
- options: ( ToastOption ) 可选 提示消息框的设置参数
返回值：
void : 无平台支持：
- Android - 2.2+ (支持)
- iOS - 4.3+ (支持)
示例：
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>UI Example</title>
<script type="text/javascript">
// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );
// 扩展API加载完毕，现在可以正常调用扩展API
function onPlusReady() {
// 输入提示信息框
plus.ui.toast( "I'am toast information!", {duration:"long"} );
}
</script>
</head>
<body>
Message notification
</body>
</html>
AnimationTypeShow
一组用于定义页面或控件显示动画效果
常量：
- "none": (DOMString 类型 )无动画效果
立即显示页面，无任何动画效果，页面显示默认的动画效果。对应关闭动画"none"。
平台支持
- Android - 2.2+ (支持)
- iOS - 4.3+ (支持)
- "slide-in-right": (DOMString 类型 )从右侧横向滑动效果
页面从屏幕右侧外向内横向滑动显示。对应关闭动画"slide-out-right"。
平台支持
- Android - 2.2+ (支持)
- iOS - 4.3+ (支持)
- "slide-in-left": (DOMString 类型 )从上侧竖向滑动效果
页面从屏幕上侧向内竖向滑动显示。对应关闭动画"slide-out-top"。
平台支持
- Android - 2.2+ (支持)
- iOS - 4.3+ (支持)
- "slide-in-bottom": (DOMString 类型 )从下侧竖向滑动效果
页面从屏幕下侧向内竖向滑动显示。对应关闭动画"slide-out-bottom"。
平台支持
- Android - 2.2+ (支持)
- iOS - 4.3+ (支持)
- "fade-in": (DOMString 类型 )从透明到不透明逐渐显示效果
页面从完全透明到不透明逐渐显示。对应关闭动画"fade-out"。
平台支持
- Android - 2.2+ (支持)
- iOS - 4.3+ (支持)
- "zoom-out": (DOMString 类型 )从小到大逐渐放大显示效果
页面在屏幕中间从小到大逐渐放大显示。对应关闭动画"zoom-in"。
平台支持
- Android - 2.2+ (支持)
- iOS - 4.3+ (支持)
- "flip-x": (DOMString 类型 )以x轴从上到下翻转效果
页面以x轴从上到下翻转显示。对应关闭动画"flip-rx"。
平台支持
- Android - 2.2+ (支持)
- iOS - 4.3+ (支持)
- "flip-rx": (DOMString 类型 )以x轴从下到上翻转转效果
页面以x轴从下到上翻转显示。对应关闭动画"flip-x"。
平台支持
- Android - 2.2+ (支持)
- iOS - 4.3+ (支持)
- "flip-y": (DOMString 类型 )以y轴从左到右翻转效果
页面以y轴从左到右翻转显示。对应关闭动画"flip-ry"。
平台支持
- Android - 2.2+ (支持)
- iOS - 4.3+ (支持)
- "flip-ry": (DOMString 类型 )以y轴从右到左翻转效果
页面以y轴从右到左翻转显示。对应关闭动画"flip-y"。
平台支持
- Android - 2.2+ (支持)
- iOS - 4.3+ (支持)
- "page-forward": (DOMString 类型 )向前翻书动画效果
页面以向前翻书动画显示，翻书后显示新打开的页面。对应关闭动画"page-backward"。
平台支持
- Android - 2.2+ (支持)
- iOS - 4.3+ (支持)
AnimationTypeClose
一组用于定义页面或控件关闭的动画效果
常量：
- "none": (DOMString 类型 )无动画
立即关闭页面，无任何动画效果。
平台支持
- Android - 2.2+ (支持)
- iOS - 4.3+ (支持)
- "slide-out-right": (DOMString 类型 )横向向右侧滑出屏幕动画
页面从屏幕中横向向右侧滑动到屏幕外关闭。
平台支持
- Android - 2.2+ (支持)
- iOS - 4.3+ (支持)
- "slide-out-left": (DOMString 类型 )横向向左侧滑出屏幕动画
页面从屏幕中横向向左侧滑动到屏幕外关闭。
平台支持
- Android - 2.2+ (支持)
- iOS - 4.3+ (支持)
- "slide-out-top": (DOMString 类型 )竖向向上侧滑出屏幕动画
页面从屏幕中竖向向上侧滑动到屏幕外关闭。
平台支持
- Android - 2.2+ (支持)
- iOS - 4.3+ (支持)
- "slide-out-bottom": (DOMString 类型 )竖向向下侧滑出屏幕动画
页面从屏幕中竖向向下侧滑动到屏幕外关闭。
平台支持
- Android - 2.2+ (支持)
- iOS - 4.3+ (支持)
- "fade-out": (DOMString 类型 )从不透明到透明逐渐隐藏动画
页面从不透明到透明逐渐隐藏关闭。
平台支持
- Android - 2.2+ (支持)
- iOS - 4.3+ (支持)
- "zoom-in": (DOMString 类型 )从大逐渐缩小关闭动画
页面逐渐向页面中心缩小关闭。
平台支持
- Android - 2.2+ (支持)
- iOS - 4.3+ (支持)
- "flip-x": (DOMString 类型 )以x轴从上到下翻转动画
页面以x轴从上到下翻转关闭，翻转后显示以前显示的页面。
平台支持
- Android - 2.2+ (支持)
- iOS - 4.3+ (支持)
- "flip-rx": (DOMString 类型 )以x轴从下到上翻转转动画
页面以x轴从下到上翻转关闭，翻转后显示以前显示的页面。
平台支持
- Android - 2.2+ (支持)
- iOS - 4.3+ (支持)
- "flip-y": (DOMString 类型 )以y轴从左到右翻转动画
页面以y轴从左到右翻转关闭，翻转后显示以前显示的页面。
平台支持
- Android - 2.2+ (支持)
- iOS - 4.3+ (支持)
- "flip-ry": (DOMString 类型 )以y轴从右到左翻转动画
页面以y轴从右到左翻转关闭，翻转后显示以前显示的页面。
平台支持
- Android - 2.2+ (支持)
- iOS - 4.3+ (支持)
- "page-backward": (DOMString 类型 )向后翻书动画
页面以向后翻书动画关闭，翻书后显示以前显示的页面。
平台支持
- Android - 2.2+ (支持)
- iOS - 4.3+ (支持)
DateOption
JSON对象，选择日期界面设置的参数
属性：
- title: (DOMString 类型 )日期选择界面的标题
默认标题为当前的日期。
- date: (DOMDate 类型 )日期选择界面默认显示的日期
默认值为当前的日期。
- startYear: (Number 类型 )日期选择界面起始的年份
数字类型，如“1940”。
- endYear: (Number 类型 )日期选择界面结束的年份
数字类型，如“2024”，其值必须大于startYear，否则取系统默认值。
- minDate: (DOMDate 类型 )日期选择界面显示的最小日期
日期类型对象，其优先级高于startYear属性。
- maxDate: (DOMDate 类型 )日期选择界面显示的最大日期
日期类型对象，其值必须大于startYear，否则取系统默认值，优先级高于endYear属性。
- popover: (JSON 类型 )时间日期选择界面弹出指示区域
JSON类型对象，格式如{top:10;left:10;width:200;height:200;}，所有值为像素值，左上坐标相对于容器webview的位置。如未设置此值，默认在屏幕居中显示。仅在iPad上有效。
Metrics
JSON对象，窗口实际度量信息
属性：
- height: (Number 类型 )绝对像素值，窗口的高度
- left: (Number 类型 )绝对像素值，相对于屏幕或父容器左侧的偏移量
- top: (Number 类型 )绝对像素值，相对于屏幕或父容器上侧的偏移量
- width: (Number 类型 )绝对像素值，窗口的宽度
NView
原生控件对象，用于操作页面中显示的原生控件
方法：
- getMetrics: 获取窗口实际度量信息
getMetrics
获取窗口实际度量信息
vobj.getMetrics( callback );
说明：
用于获取原生控件的度量信息，包括控件的位置、大小等信息。获取成功后通过callback回调返回。
参数：
- callback: ( MetricsCallback ) 必选 获取度量信息的回调函数
返回值：
void : 无示例：
<!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加载完毕，现在可以正常调用扩展API
function 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>
NViewDock
原生控件在窗口中停靠的方式
常量：
- "top": (DOMString 类型 )控件停靠则页面顶部
- "bottom": (DOMString 类型 )控件停靠在页面中底部
- "right": (DOMString 类型 )控件停靠在页面右侧
- "left": (DOMString 类型 )控件停靠在页面左侧
NViewOption
JSON对象，原生控件元素要设置的参数
属性：
- id: (DOMString 类型 )控件的标识
- top: (DOMString 类型 )控件在所属窗口垂直向下的偏移量，可设置像素值或百分比，默认值为0px
- left: (DOMString 类型 )控件在所属窗口水平向右的偏移量，可设置像素值或百分比，默认值为0px
- width: (DOMString 类型 )控件的宽度，可设置像素值或百分比，默认为控件内部计算的高度（参考扩展自定义控件）
- height: (DOMString 类型 )控件的高度，可设置像素值或百分比，默认为控件内部计算的高度（参考扩展自定义控件）
- position: (NViewPosition 类型 )控件的排版位置，默认值为"static"
- dock: (NViewDock 类型 )控件的停靠方式，默认值为"top"
NViewPosition
原生控件在窗口中显示的位置
常量：
- "static": (DOMString 类型 )控件在页面中正常定位，如果页面存在滚动条则随窗口内容滚动
- "absolute": (DOMString 类型 )控件在页面中绝对定位，如果页面存在滚动条不随窗口内容滚动
- "dock": (DOMString 类型 )控件在页面中停靠，停靠的位置通过dock属性进行定义
NWaiting
NWaiting是等待控件对象，用于在界面中显示原生等待窗口
方法：
事件：
- onclose: 关闭等待控件事件
setTitle
设置等待控件上显示的文字
wobj.setTitle( title );
说明：
设置等待框上显示的文字信息，设置后文字内容将立即更新。
参数：
- title: ( DOMString ) 必选 要设置的文本信息
返回值：
void : 无示例：
<!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加载完毕，现在可以正常调用扩展API
function onPlusReady() {
w = plus.ui.createWaiting("请稍后");
setTimeout( function() {
w.setTitle( "正在更新" );
}, 2000 );
setTimeout( function() {
w.close();
}, 4000 );
}
</script>
</head>
<body>
</body>
</html>
close
关闭等待控件
wobj.close();
说明：
将原生等待控件关闭。一个等待控件只能关闭一次，多次调用将无任何作用。
参数：
无
返回值：
void : 无示例：
<!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加载完毕，现在可以正常调用扩展API
function 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>
onclose
关闭等待控件事件
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加载完毕，现在可以正常调用扩展API
function 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>
NWaitingOption
JSON对象，原生等待控件要设置的参数
属性：
- width: (DOMString 类型 )等待框背景区域的宽度，默认根据内容自动计算
- height: (DOMString 类型 )等待框背景区域的高度，默认根据内容自动计算
- color: (DOMString 类型 )等待框中文字的颜色
颜色值支持(参考CSS颜色规范)：颜色名称(参考CSS Color Names)/十六进制值/rgb值/rgba值，默认值为白色。
- textalign: (DOMString 类型 )等待框中的文字的水平对齐方式
对齐方式可选值包括："left"：水平居左对齐显示，"center"：水平居中对齐显示，"right"：水平居右对齐显示。默认值为水平居中对齐显示。
- padding: (DOMString 类型 )等待框的内边距
支持像素值和百分比，百分比相对于屏幕的宽计算，默认值为"3%"。
- background: (DOMString 类型 )等待框显示区域的背景色
背景色的值支持(参考CSS颜色规范)：颜色名称(参考CSS Color Names)/十六进制值/rgb值/rgba值，默认值为rgba(0,0,0,0.8)。
- style: (DOMString 类型 )等待框样式，可取值"black"、"white"
black表示等待框为黑色雪花样式，通常在背景主色为浅色时使用；white表示等待框为白色雪花样式，通常在背景主色为深色时使用；仅在iOS平台有效，其它平台忽略此值，默认值为white。
平台支持
- Android - (不支持) :
此属性不产生任何效果
- iOS - 4.5+ (支持) :
支持"black"、"white"两种样式
- Android - (不支持) :
- modal: (Boolen 类型 )等待框是否模态显示
模态显示则用户不可操作直到等待框关闭，否则用户在等待框显示时也可操作，默认为true。
- round: (Number 类型 )等待框显示区域的圆角，默认值为10px
- padlock: (Boolen 类型 )点击等待显示区域是否自动关闭，默认值为false
NWindow
NWindow是窗口对象，用于操作加载html页面的原生窗口
方法：
- addEventListener: 添加事件监听器
- append: 在窗口中添加原生界面控件
- appendPreloadJsFile: 添加页面预先加载的js文件
- back: 窗口后退到上次加载的页面内容
- canBack: 查询窗口是否可后退到上次加载的页面内容
- canForward: 查询窗口是否可前进到上次加载的页面内容
- clear: 清空原生窗口加载的内容
- close: 关闭创建新的原生窗口
- endPullToRefresh: 关闭原生窗口刷新状态
- evalJS: 在窗口中执行脚本
- findViewById: 在界面中通过id查找控件对象
- forward: 窗口前进到上次加载的页面内容
- getMetrics: 获取窗口实际度量信息
- getOption: 获取窗口当前的属性值
- getTitle: 获取窗口加载页面的标题
- getUrl: 获取窗口加载页面的地址
- load: 窗口加载新的页面
- reload: 重新加载窗口当前显示的页面
- removeEventListener: 移除事件监听器
- setContentVisible: 设置页面内容是否可见
- setOption: 设置原生窗口的参数
- setPreloadJsFile: 设置页面预先加载的js文件
- setPullToRefresh: 设置窗口的下拉刷新功能
- setVisible: 设置窗口是否可见
- show: 显示创建新的原生窗口
- stop: 窗口停止加载页面内容
addEventListener
添加事件监听器
wobj.addEventListener( event, listener, capture );
说明：
为窗口添加事件监听器，当指定的窗口事件发生时，回调函数将触发。可多次调用为同一事件添加多个监听器，触发时按照添加的顺序先后调用。
参数：
- event: ( NWindowEvent ) 必选 要监听的事件类型
- listener: ( EventCallback ) 必选 监听的事件发生时调用的回调函数
- capture: ( Boolean ) 可选 捕获事件流顺序，暂无效果
返回值：
void : 无示例：
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>UI Example</title>
<script type="text/javascript">
// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );
// 扩展API加载完毕，现在可以正常调用扩展API
function 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>
append
在窗口中添加原生界面控件
void wobj.append( view );
说明：
将原生控件添加到界面中，随界面一起显示。控件只能添加到一个界面中，多次调用将无任何作用。
参数：
- view: ( NView ) 必选 要添加的控件对象，需通过createView创建
返回值：
void : 无示例：
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>UI Example</title>
<script type="text/javascript">
// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );
// 扩展API加载完毕，现在可以正常调用扩展API
function 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>
appendPreloadJsFile
添加页面预先加载的js文件
wobj.appendPreloadJsFile( file );
说明：
添加页面加载时需要预先执行的js文件，以完成特殊的页面处理。在窗口页面跳转时也需要执行，添加多个js文件后将按照添加的先后顺序执行。
参数：
- file: ( DOMString ) 必选 要预先载入的js文件地址，仅支持本地文件
返回值：
void : 无back
窗口后退到上次加载的页面内容
void wobj.back();
说明：
窗口历史记录操作，后退到窗口上次加载的页面内容。如果窗口历史记录中没有可后退的页面则不触发任何操作。
参数：
无
返回值：
void : 无示例：
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>UI Example</title>
<script type="text/javascript">
// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );
// 扩展API加载完毕，现在可以正常调用扩展API
function onPlusReady() {
// Plus API
}
function goBack() {
var nw = plus.ui.getSelfWindow();
nw.back();
}
</script>
</head>
<body>
<button onclick="goBack();">返回</input>
</body>
</html>
canBack
查询窗口是否可后退到上次加载的页面内容
void wobj.canBack( queryCallback );
说明：
窗口历史记录操作，查询是否可后退到窗口上次加载的页面内容。查询成功将通过queryCallback回调方法返回结果。
参数：
- queryCallback: ( HistoryQueryCallback ) 必选 历史记录查询操作回调函数
返回值：
void : 无示例：
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>UI Example</title>
<script type="text/javascript">
// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );
// 扩展API加载完毕，现在可以正常调用扩展API
function 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>
canForward
查询窗口是否可前进到上次加载的页面内容
void wobj.canForward( queryCallback );
说明：
窗口历史记录操作，查询是否可前进到窗口上次加载的页面内容。查询成功将通过queryCallback回调方法返回结果。
参数：
- queryCallback: ( HistoryQueryCallback ) 必选 历史记录查询操作回调函数
返回值：
void : 无示例：
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>UI Example</title>
<script type="text/javascript">
// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );
// 扩展API加载完毕，现在可以正常调用扩展API
function 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>
clear
清空原生窗口加载的内容
void wobj.clear();
说明：
清除原生窗口的内容，用于重置重置原生窗口加载的内容，清除其加载的历史记录等内容。
参数：
无
返回值：
void : 无示例：
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>UI Example</title>
<script type="text/javascript">
// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );
// 扩展API加载完毕，现在可以正常调用扩展API
function 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>
close
关闭创建新的原生窗口
void wobj.close( aniClose, duration );
说明：
关闭原生窗口，用于销毁创建的系统原生窗口。原生窗口窗口只能关闭一次，关闭窗口后不可再操作窗口对象，操作后将无任何效果。窗口关闭时默认会使用窗口打开时设置的相反动画效果，也可通过aniClose设置原生窗口关闭动画，仅能使用动画类型中的关闭动画效果。
参数：
- aniClose: ( AnimationTypeClose ) 可选 关闭原生窗口的动画效果
- duration: ( Number ) 可选 关闭原生窗口的动画持续时间
单位为ms，默认为窗口show方法设定的动画时间。
返回值：
void : 无示例：
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>UI Example</title>
<script type="text/javascript">
// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );
// 扩展API加载完毕，现在可以正常调用扩展API
function 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>
endPullToRefresh
关闭原生窗口刷新状态
void wobj.endPullToRefresh();
说明：
通过setPullToRefresh方法可开启窗口的下拉刷新功能，当用户操作触发刷新回调事件后，可以通过此方法关闭窗口的刷新状态。 关闭刷新状态后，用于依然可以通过下拉操作继续触发刷新事件。
参数：
无
返回值：
void : 无平台支持：
- Android - 2.2+ (支持)
- iOS - 4.5+ (不支持) :
暂不支持，建议通过web技术实现
示例：
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>UI Example</title>
<script type="text/javascript">
// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );
// 扩展API加载完毕，现在可以正常调用扩展API
function 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>
evalJS
在窗口中执行脚本
void wobj.evalJS( js );
说明：
可在窗口中运行脚本，实现跨窗口间的数据操作。
参数：
- options: ( DOMString ) 必选 要在窗口中运行的脚本
返回值：
void : 无示例：
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>UI Example</title>
<script type="text/javascript">
// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );
// 扩展API加载完毕，现在可以正常调用扩展API
function 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>
findViewById
在界面中通过id查找控件对象
void wobj.findViewById( id );
说明：
在当前界面中查找控件对象，并返回控件对象的引用。其中控件的id在创建时通过NViewOption中的id字段设置。如果没有找到则返回null
参数：
- id: ( DOMString ) 必选 要查找控件的id值
返回值：
NView : 无示例：
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>UI Example</title>
<script type="text/javascript">
// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );
// 扩展API加载完毕，现在可以正常调用扩展API
var 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>
forward
窗口前进到上次加载的页面内容
void wobj.forward();
说明：
窗口历史记录操作，前进到窗口上次加载的页面内容。如果窗口历史记录中没有可前进的页面则不触发任何操作。
参数：
无
返回值：
void : 无示例：
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>UI Example</title>
<script type="text/javascript">
// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );
// 扩展API加载完毕，现在可以正常调用扩展API
function onPlusReady() {
// Plus API
}
function goForward() {
var nw = plus.ui.getSelfWindow();
nw.forward();
}
</script>
</head>
<body>
<button onclick="goForward();">返回</input>
</body>
</html>
getMetrics
获取窗口实际度量信息
void wobj.getMetrics( callback );
说明：
用于获取窗口实际度量信息，包括窗口的位置、大小等信息。获取度量信息成功后通过callback回调返回。/隐藏，再次调用显示/隐藏则无任何作用。
参数：
- callback: ( MetricsCallback ) 必选 获取度量信息的回调函数
返回值：
void : 无示例：
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>UI Example</title>
<script type="text/javascript">
// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );
// 扩展API加载完毕，现在可以正常调用扩展API
function 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>
getOption
获取窗口当前的属性值
NWindowOption wobj.getOption();
说明：
获取原生窗口的属性，如窗口位置、大小等信息。
参数：
无
返回值：
NWindowOption : NWindowOption对象示例：
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>UI Example</title>
<script type="text/javascript">
// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );
// 扩展API加载完毕，现在可以正常调用扩展API
function 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>
getTitle
获取窗口加载页面的标题
DOMString wobj.getTitle();
说明：
标题为窗口加载的html页面head节点下title节点中的文本内容，当窗口内容发生页面内跳转时可通过窗口触发的“loaded”事件中调用此方法来获取跳转后页面的标题。如果页面中午title节点则返回空字符串。
参数：
无
返回值：
DOMString : 窗口加载页面的标题示例：
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>UI Example</title>
<script type="text/javascript">
// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );
// 扩展API加载完毕，现在可以正常调用扩展API
function 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>
getUrl
获取窗口加载页面的地址
DOMString wobj.getUrl();
说明：
当窗口内容发生页面内跳转时可通过窗口触发的“loaded”事件中调用此方法来获取跳转后页面的地址。
参数：
无
返回值：
DOMString : 窗口加载页面的地址示例：
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>UI Example</title>
<script type="text/javascript">
// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );
// 扩展API加载完毕，现在可以正常调用扩展API
function 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>
load
窗口加载新的页面
void wobj.load( url );
说明：
触发原生窗口加载新的页面地址。如果新设置的url地址无效将导致页面显示失败。
参数：
- url: ( DOMString ) 必选 要加载的新的页面地址
返回值：
void : 无示例：
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>UI Example</title>
<script type="text/javascript">
// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );
// 扩展API加载完毕，现在可以正常调用扩展API
function onPlusReady() {
}
function jumpUrl() {
var nw = plus.ui.getSelfWindow();
nw.load( "http://www.test.com" ); // 跳转到新的页面
}
</script>
</head>
<body>
<button onclick="jumpUrl();">跳转到新页面</button>
</body>
</html>
reload
重新加载窗口当前显示的页面
void wobj.reload( force );
说明：
触发原生窗口重新加载当前显示的页面地址。如果当前页面未加载完则停止并重新加载，如果当前没有加载任何页面则无响应。
参数：
- force: ( Boolean ) 必选 是否强制不使用本地缓存
为加速页面加载速度，默认在重新加载时会使用缓存，若force设置为true则不使用缓存，重新从服务器加载所有页面内容。
返回值：
void : 无示例：
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>UI Example</title>
<script type="text/javascript">
// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );
// 扩展API加载完毕，现在可以正常调用扩展API
function onPlusReady() {
}
function refresh() {
var nw = plus.ui.getSelfWindow();
nw.reload( true );
}
</script>
</head>
<body>
<button onclick="refresh();">重新加载</button>
</body>
</html>
removeEventListener
移除事件监听器
wobj.removeEventListener( event, listener );
说明：
从窗口移除指定的事件监听器。若没有查找到对应的事件监听器，则无任何作用。
参数：
- event: ( NWindowEvent ) 必选 要移除的事件类型
- listener: ( EventCallback ) 必选 要移除回调函数对象
返回值：
void : 无示例：
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>UI Example</title>
<script type="text/javascript">
// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );
// 扩展API加载完毕，现在可以正常调用扩展API
function 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>
setContentVisible
设置页面内容是否可见
void wobj.setContentVisible( visible );
说明：
在某些特殊情况下需要对页面内容进行预处理，如对内容进行过滤转换，为了不让内容在转换完成之前显示，则可先通过此方法设置页面内容不可见，带内容转换完成后再设置页面内容可见。
参数：
- visible: ( Boolean ) 必选 设置页面是否可见的值
返回值：
void : 无setOption
设置原生窗口的参数
void wobj.setOption( options );
说明：
设置原生窗口的属性，如窗口位置、大小等信息。
参数：
- options: ( NWindowOption ) 必选 要设置新的窗口属性
返回值：
void : 无示例：
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>UI Example</title>
<script type="text/javascript">
// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );
// 扩展API加载完毕，现在可以正常调用扩展API
function onPlusReady() {
}
function moveWinTo() {
var nw = plus.ui.getSelfWindow();
nw.setOption( {left:50%} ); // 水平移动窗口到屏幕中间位置
}
</script>
</head>
<body>
<button onclick="moveWinTo();">移动窗口</button>
</body>
</html>
setPreloadJsFile
设置页面预先加载的js文件
wobj.setPreloadJsFile( file );
说明：
某些页面加载时预先执行插入的js文件，以完成特殊的页面处理。在窗口页面跳转时也需要执行，设置新的js文件后将清空之前设置的值。
参数：
- file: ( DOMString ) 必选 要预先载入的js文件地址，仅支持本地文件
返回值：
void : 无setPullToRefresh
设置窗口的下拉刷新功能
wobj.setPullToRefresh( PullToRefreshOption options, PullToRefreshCallback refreshCB );
说明：
窗口自带下拉刷新功能，当用户触发刷新操作时通过refreshCB函数通知应用执行刷新操作。 此时窗口进入刷新状态并一直显示下拉刷新控件，直到调用endPullToRefresh方法退出刷新状态。
参数：
- options: ( PullToRefreshOption ) 必选 设置下拉刷新功能的配置信息，如下拉区域的高度、上面显示的内容等
- refreshCB: ( PullToRefreshCallback ) 可选 用户触发刷新操作时的回调函数
返回值：
void : 无平台支持：
- Android - 2.2+ (支持)
- iOS - 4.5+ (不支持) :
暂不支持，建议通过web技术实现
示例：
<!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>
setVisible
设置窗口是否可见
void wobj.setVisible( visible );
说明：
用于隐藏原生窗口，减少显示的窗口数目，可降低占用的系统资源，通常在打开新窗口后隐藏不需要显示的窗口。窗口隐藏后，如果要显示则必须调用此方法将窗口显示，否则将导致窗口不显示。如果当前窗口已经显示/隐藏，再次调用显示/隐藏则无任何作用。
参数：
- visible: ( Boolean ) 必选 设置窗口是否可见的值
返回值：
void : 无示例：
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>UI Example</title>
<script type="text/javascript">
// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );
// 扩展API加载完毕，现在可以正常调用扩展API
function 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>
show
显示创建新的原生窗口
void wobj.show( aniShow, duration, assWin );
说明：
显示原生窗口，用于显示创建的系统原生窗口。原生窗口窗口只能显示一次，多次调用show方法将无任何作用。可通过aniShow设置原生窗口显示动画。
参数：
- aniShow: ( AnimationTypeShow ) 可选 显示原生窗口的动画效果
- duration: ( Number ) 可选 显示原生窗口的动画持续时间
单位为ms，默认为600ms。
- assWin: ( DOMString ) 可选 新打开原生窗口动画需要关联的窗口名称
返回值：
void : 无示例：
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>UI Example</title>
<script type="text/javascript">
// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );
// 扩展API加载完毕，现在可以正常调用扩展API
function 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>
stop
窗口停止加载页面内容
void wobj.stop();
说明：
触发原生窗口停止加载页面内容。如果已经加载部分内容则显示部分内容，如果加载完成则显示全部内容。
参数：
无
返回值：
void : 无示例：
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>UI Example</title>
<script type="text/javascript">
// 扩展API加载完毕后调用onPlusReady回调函数
document.addEventListener( "plusready", onPlusReady, false );
// 扩展API加载完毕，现在可以正常调用扩展API
function onPlusReady() {
}
function stopLoad() {
var nw = plus.ui.getSelfWindow();
nw.stop();
}
</script>
</head>
<body>
<button onclick="stopLoad();">停止加载</input>
</body>
</html>
NWindowEvent
窗口事件对象
常量：
- "close": (DOMString 类型 )当窗口关闭时触发此事件
- "loading": (DOMString 类型 )当窗口开始加载新内容时触发此事件
- "loaded": (DOMString 类型 )当窗口内容加载完成时触发此事件
- "failed": (DOMString 类型 )当窗口内容加载失败时触发此事件
- "back": (DOMString 类型 )设备“返回”按钮按键事件
- "menu": (DOMString 类型 )设备“菜单”按钮按键事件
- "search": (DOMString 类型 )设备“搜索”按钮按键事件
- "volumeup": (DOMString 类型 )设备“音量+”按钮按键事件
- "volumedown": (DOMString 类型 )设备“音量-”按钮按键事件
NWindowOption
JSON对象，原生窗口设置参数的对象
属性：
- background: (DOMString 类型 )窗口的背景颜色
窗口空白区域的背景，设置了background则窗口为独占模式显示（占整个屏幕区域），否则为非独占模式，目前仅支持背景色的设置(参考CSS颜色规范)：颜色名称(参考CSS Color Names)/十六进制值/rgb值/rgba值。
- bottom: (DOMString 类型 )窗口垂直向上的偏移量
支持百分比、像素值，当设置了top和height值时，此属性值忽略；当设置top和bottom属性则自动计算窗口的高度。
- bounce: (DOMString 类型 )窗口遇到边框是否有反弹效果
可取值：none表示没有反弹效果；vertical表示垂直方向有反弹效果；horizontal表示水平方向有反弹效果；all表示垂直和水平方向都有反弹效果。
平台支持
- Android - (不支持)
- iOS - (支持) :
默认值为none，垂直和水平方向都没有反弹效果。
- height: (DOMString 类型 )窗口的高度
支持百分比、像素值，默认为100%。
- left: (DOMString 类型 )窗口水平向右的偏移量
支持百分比、像素值，默认值为0px。
- margin: (DOMString 类型 )窗口的边距
用于定位窗口的位置，支持auto，auto表示居中。若设置了left、right、top、bottom则对应的边距值失效。
- name: (DOMString 类型 )窗口的名称
作为窗口的标识，可用于窗口的查找。
- opacity: (Number 类型 )窗口的不透明度
0为全透明，1为不透明，默认值为1，即不透明。
平台支持
- Android - 2.2+ (支持) :
需Android4.0及以上平台才支持，Android4.0以前平台忽略此属性。
- iOS - 4.3+ (支持)
- Android - 2.2+ (支持) :
- right: (DOMString 类型 )窗口水平向左的偏移量
支持百分比、像素值，默认无值。当设置了left和width值时，此属性值忽略；当设置left和right属性则自动计算窗口的宽度。
- scalable: (Boolean 类型 )窗口是否可缩放
默认值为true，即可缩放。 窗口设置为可缩放（scalable:true）时，用户可通过双指操作放大或缩小页面，这时html页面可通过meta节点name="viewport"来限制页面是否可缩放。 窗口设置为不可缩放（scalable:false）时，用户不可通过双指操作放大或缩小页面，即使页面中的meta节点也无法开启可缩放功能。 窗口的默认值为可缩放（scalable:true）。
- scrollIndicator: (DOMString 类型 )窗口是否显示滚动条
用于控制窗口滚动条样式，可取值："all"：垂直和水平滚动条都显示，"vertical"：仅显示垂直，"horizontal"：仅显示水平滚动条，"none"：垂直和水平滚动条都不显示。默认值为"all"，即垂直和水平滚动条都显示。 注意：显示滚动条的前提条件是窗口中的内容超过窗口显示的宽或高。
- top: (DOMString 类型 )窗口垂直向下的偏移量
支持百分比、像素值，默认值为0px。
- transition: (Transition 类型 )窗口定义窗口变换的动画效果，参考Transition
- transform: (Transform 类型 )窗口定义窗口变形效果，参考Transform
- width: (DOMString 类型 )窗口的宽度
支持百分比、像素值，默认为100%。
- zindex: (Number 类型 )窗口的堆叠顺序值
拥有更高堆叠顺序的窗口总是会处于堆叠顺序较低的窗口的前面，拥有相同堆叠顺序的窗口后调用show方法则在前面。
PullToRefreshOption
JSON对象，原生窗口设置参数的对象
属性：
- support: (Boolean 类型 )是否开启下拉刷新功能
true表示开启下拉刷新功能，false表示关闭下拉刷新功能，默认值为true。
- height: (String 类型 )下拉刷新控件的高度
当用户下拉操作的高度大于或等于此值事，松开后则进入刷新状态。 可支持像素值和百分比，像素值为绝对值，以px结尾；百分比相对窗口的高度，以%结尾；如“60px”、“10%”，默认值为“100px”。 注：当下拉的高度大于等于刷新控件的高度时，控件居底显示。
- range: (String 类型 )下拉刷新控件可下拉的最大高度
用户可下拉的最大高度，此值必须大于height值，否则将会导致无法触发刷新事件。 可支持像素值和百分比，像素值为绝对值，以px结尾；百分比相对窗口的高度，以%结尾； 如“60px”、“10%”，默认值为height值。
- contentdown: (JSON 类型 )下拉刷新控件在下拉状态时显示的内容
仅支持caption字段，用于设置下拉状态时显示的文本内容。
- contentover: (JSON 类型 )下拉刷新控件在达到可刷新状态时显示的内容
仅支持caption字段，用于设置可刷新状态时显示的文本内容。
- contentrefresh: (JSON 类型 )下拉刷新控件正在刷新状态时显示的内容
仅支持caption字段，用于设置在刷新状态时显示的文本内容。
平台支持：
- Android - 2.2+ (支持)
- iOS - 4.5+ (不支持) :
暂不支持，建议通过html技术实现
TimeOption
JSON对象，选择时间界面设置的参数
属性：
- title: (DOMString 类型 )时间选择操作界面显示的标题
字符串类型，默认标题为当前选择的时间。
- is24Hour: (Boolean 类型 )是否24小时制模式，默认值为true
- popover: (JSON 类型 )时间日期选择界面弹出指示区域
JSON对象，格式如{top:10;left:10;width:200;height:200;}，所有值为像素值，左上坐标相对于容器webview的位置。如未设置此值，默认在屏幕居中显示。
平台支持
- Android - 2.2+ (不支持)
- iOS - 4.3+ (支持) :
仅在iPad上有效，在iPhone上忽略此值。
ToastOption
JSON对象，系统提示消息框要设置的参数
属性：
- icon: (DOMString 类型 )提示消息框上显示的图标
- duration: (DOMString 类型 )提示消息框显示的时间
可选值为"long"、"short"，值为"long"约为3.5s，值为"short"时约为2s，默认值为"short"。
- align: (DOMString 类型 )提示消息框在屏幕中的水平位置
可选值为"left"、"center"、"right"，分别为水平居左、居中、居右，默认值为"center"。
- verticalAlign: (DOMString 类型 )提示消息框在屏幕中的垂直位置
可选值为"top"、"center"、"bottom"，分别为垂直居顶、居中、居底，默认值为"bottom"。
Transform
一组用于定义页面或控件变形的属性，暂不支持
属性：
- rotate: (DOMString 类型 )暂不支持
- translate: (DOMString 类型 )暂不支持
- scale: (DOMString 类型 )暂不支持
- skew: (DOMString 类型 )暂不支持
- matrix: (DOMString 类型 )暂不支持
Transition
一组用于定义页面或控件转换效果的属性
属性：
- property: (DOMString 类型 )产生变换效果的属性
默认值为"all"，暂不支持其它值。
平台支持
- Android - 2.2+ (支持)
- iOS - 4.3+ (支持)
- duration: (DOMString 类型 )变换持续的时间
默认值为0，即无动画效果。
平台支持
- Android - 2.2+ (支持)
- iOS - 4.3+ (支持)
- timingfunction: (DOMString 类型 )窗口变换效果
可取值linear、ease-in、ease-out、ease-in-out，默认值为linear。
平台支持
- Android - 2.2+ (支持)
- iOS - 4.3+ (支持)
AlertCallback
系统提示框确认的回调函数
void onAlerted() {
// Alert handled code.
}
参数：
无
返回值：
void : 无ConfirmCallback
系统确认框操作的回调函数
void onConfirmed( Number index ) {
// Confirm handled code.
}
参数：
- index: ( Number ) 必选 用户点击按钮的索引值，从0开始
返回值：
void : 无平台支持：
- Android - 2.2+ (支持) :
用户点击“返回”按钮则提示框消失，同时回调函数返回的index值为-1。
- iOS - 4.3+ (支持)
PromptCallback
系统输入框操作的回调函数
function void onPrompted( Number index, DOMString value ) {
// Prompt handled code.
}
参数：
- index: ( Number ) 必选 用户点击按钮的索引值，从0开始
- value: ( DOMString ) 可选 用户输入的内容，若没有输入则返回空字符串
返回值：
void : 无平台支持：
- Android - 2.2+ (支持) :
用户点击“返回”按钮则提示框消失，同时回调函数返回的index值为-1，value值为空字符串。
- iOS - 4.3+ (支持)
ToastCallback
系统消息框消失时的回调函数
void onToast() {
// Toast close handled code.
}
参数：
无
返回值：
void : 无PickDatetimeSuccessCallback
选择日期或时间操作成功的回调函数
function void onPickSuccess( DOMDate date ) {
// Date picked code.
}
参数：
- date: ( DOMDate ) 必选 用户选择的日期或时间数据
若调用的是日期选择操作则仅年、月、日信息有效，若调用的是时间选择操作则仅时、分信息有效。
返回值：
void : 无PickDatetimeErrorCallback
选择日期或时间操作失败的回调函数
function void onPickError( DOMException error ) {
// Date picked error.
alert( error.message );
}
参数：
- error: ( DOMException ) 必选 用户选择操作失败信息
返回值：
void : 无MetricsCallback
获取控件或窗口实际度量信息回调函数
void onMetricsCompleted( Metrics metrics ) {
// Get metrics completed code.
}
参数：
- metrics: ( Metrics ) 必选 获取到的窗口或控件的度量信息，参考Metrics
返回值：
void : 无EventCallback
窗口事件的回调函数
void onEvent() {
// Event handled code.
}
参数：
无
返回值：
void : 无HistoryQueryCallback
历史记录记录查询的回调函数
void onQuery( able ) {
// Event handled code.
}
参数：
- able: ( Boolean ) 必选 历史记录操作是否可用，true表示可用，false表示不可用
返回值：
void : 无PullToRefreshCallback
窗口刷新操作的回调函数
void onRefresh() {
// Event handled code.
}
参数：
无