# [ui]() UI模块管理应用界面,用于操作加载HTML页面的原生窗口,调用系统原生控件等。由于此模块功能太多,现已根据功能分拆更新为Key、NativeUI、Navigator、Webview等,并对接口和功能做了一些优化调整,请使用新API。 ### 方法: - [alert](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.alert): 弹出系统提示框 - [closeSplashscreen](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.closeSplashscreen): 关闭程序启动界面 - [closeWindow](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.closeWindow): 关闭原生窗口 - [confirm](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.confirm): 弹出系统确认对话框 - [createView](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.createView): 创建新的原生控件对象 - [createWaiting](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.createWaiting): 创建等待对话框 - [createWindow](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.createWindow): 创建新的原生窗口 - [enumWindow](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.enumWindow): 枚举所有原生窗口 - [findWindowByName](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.findWindowByName): 查找指定名称的窗口 - [getSelfWindow](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.getSelfWindow): 获取自身窗口 - [isFullscreen](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.isFullscreen): 判断应用当前是否全屏模式运行 - [pickDate](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.pickDate): 弹出日期选择界面 - [pickTime](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.pickTime): 弹出时间选择界面 - [prompt](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.prompt): 弹出系统输入框 - [setFullscreen](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.setFullscreen): 设置应用是否全屏模式运行 - [toast](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.toast): 显示自动消失的消息 ### 对象: - [AnimationTypeShow](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.AnimationTypeShow): 一组用于定义页面或控件显示动画效果 - [AnimationTypeClose](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.AnimationTypeClose): 一组用于定义页面或控件关闭的动画效果 - [DateOption](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.DateOption): JSON对象,选择日期界面设置的参数 - [Metrics](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.Metrics): JSON对象,窗口实际度量信息 - [NView](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.NView): 原生控件对象,用于操作页面中显示的原生控件 - [NViewDock](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.NViewDock): 原生控件在窗口中停靠的方式 - [NViewOption](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.NViewOption): JSON对象,原生控件元素要设置的参数 - [NViewPosition](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.NViewPosition): 原生控件在窗口中显示的位置 - [NWaiting](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.NWaiting): NWaiting是等待控件对象,用于在界面中显示原生等待窗口 - [NWaitingOption](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.NWaitingOption): JSON对象,原生等待控件要设置的参数 - [NWindow](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.NWindow): NWindow是窗口对象,用于操作加载html页面的原生窗口 - [NWindowEvent](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.NWindowEvent): 窗口事件对象 - [NWindowOption](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.NWindowOption): JSON对象,原生窗口设置参数的对象 - [PullToRefreshOption](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.PullToRefreshOption): JSON对象,原生窗口设置参数的对象 - [TimeOption](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.TimeOption): JSON对象,选择时间界面设置的参数 - [ToastOption](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.ToastOption): JSON对象,系统提示消息框要设置的参数 - [Transform](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.Transform): 一组用于定义页面或控件变形的属性,暂不支持 - [Transition](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.Transition): 一组用于定义页面或控件转换效果的属性 ### 回调方法: - [AlertCallback](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.AlertCallback): 系统提示框确认的回调函数 - [ConfirmCallback](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.ConfirmCallback): 系统确认框操作的回调函数 - [PromptCallback](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.PromptCallback): 系统输入框操作的回调函数 - [ToastCallback](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.ToastCallback): 系统消息框消失时的回调函数 - [PickDatetimeSuccessCallback](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.PickDatetimeSuccessCallback): 选择日期或时间操作成功的回调函数 - [PickDatetimeErrorCallback](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.PickDatetimeErrorCallback): 选择日期或时间操作失败的回调函数 - [MetricsCallback](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.MetricsCallback): 获取控件或窗口实际度量信息回调函数 - [EventCallback](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.EventCallback): 窗口事件的回调函数 - [HistoryQueryCallback](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.HistoryQueryCallback): 历史记录记录查询的回调函数 - [PullToRefreshCallback](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.PullToRefreshCallback): 窗口刷新操作的回调函数 ### 权限: permissions ~~~ "UI": { "description": "访问系统原生窗口" } ~~~ # [alert]() 弹出系统提示框 ~~~ void plus.ui.alert( message, alertCB, title, buttonCapture ); ~~~ ### 说明: 弹出系统样式提示对话框,可设置弹出对话框的标题、内容、按钮文字。此API非阻塞模式,用户点击提示框上的按钮需通过alertCB回调函数返回。 ### 参数: - message: *( DOMString ) 必选 *提示对话框上显示的内容 - alertCB: *( [AlertCallback](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.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](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.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](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.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](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.NViewOption) ) 可选 *新打开原生窗口显示元素的参数(如元素宽、高、位置等信息) ### 返回值: [NView](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.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](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.NWaitingOption) ) 可选 *等待框的显示参数 ### 返回值: [NWaiting](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.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](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.NWindowOption) ) 可选 *新打开原生窗口的参数(如窗口宽、高、位置等信息) ### 返回值: [NWindow](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.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](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.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](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.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](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.PickDatetimeSuccessCallback) ) 必选 *日期选择操作成功的回调函数 - errorCB: *( [PickDatetimeErrorCallback](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.PickDatetimeErrorCallback) ) 可选 *日期选择操作失败的回调函数 - options: *( [DateOption](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.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](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.PickDatetimeSuccessCallback) ) 必选 *时间选择操作成功的回调函数 - errorCB: *( [PickDatetimeErrorCallback](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.PickDatetimeErrorCallback) ) 可选 *时间选择操作失败的回调函数 - options: *( [TimeOption](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.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](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.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](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.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](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.NView.getMetrics): 获取窗口实际度量信息 # [getMetrics]() 获取窗口实际度量信息 ~~~ vobj.getMetrics( callback ); ~~~ ### 说明: 用于获取原生控件的度量信息,包括控件的位置、大小等信息。获取成功后通过callback回调返回。 ### 参数: - callback: *( [MetricsCallback](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.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](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.NViewPosition) 类型 )*控件的排版位置,默认值为"static" - dock: *([NViewDock](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.NViewDock) 类型 )*控件的停靠方式,默认值为"top" # [NViewPosition]() 原生控件在窗口中显示的位置 ### 常量: - "static": *(DOMString 类型 )*控件在页面中正常定位,如果页面存在滚动条则随窗口内容滚动 - "absolute": *(DOMString 类型 )*控件在页面中绝对定位,如果页面存在滚动条不随窗口内容滚动 - "dock": *(DOMString 类型 )*控件在页面中停靠,停靠的位置通过dock属性进行定义 # [NWaiting]() NWaiting是等待控件对象,用于在界面中显示原生等待窗口 ### 方法: - [setTitle](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.NWaiting.setTitle): 设置等待控件上显示的文字 - [close](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.NWaiting.close): 关闭等待控件 ### 事件: - [onclose](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.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"两种样式 - modal: *(Boolen 类型 )*等待框是否模态显示 模态显示则用户不可操作直到等待框关闭,否则用户在等待框显示时也可操作,默认为true。 - round: *(Number 类型 )*等待框显示区域的圆角,默认值为10px - padlock: *(Boolen 类型 )*点击等待显示区域是否自动关闭,默认值为false # [NWindow]() NWindow是窗口对象,用于操作加载html页面的原生窗口 ### 方法: - [addEventListener](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.NWindow.addEventListener): 添加事件监听器 - [append](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.NWindow.append): 在窗口中添加原生界面控件 - [appendPreloadJsFile](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.NWindow.appendPreloadJsFile): 添加页面预先加载的js文件 - [back](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.NWindow.back): 窗口后退到上次加载的页面内容 - [canBack](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.NWindow.canBack): 查询窗口是否可后退到上次加载的页面内容 - [canForward](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.NWindow.canForward): 查询窗口是否可前进到上次加载的页面内容 - [clear](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.NWindow.clear): 清空原生窗口加载的内容 - [close](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.NWindow.close): 关闭创建新的原生窗口 - [endPullToRefresh](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.NWindow.endPullToRefresh): 关闭原生窗口刷新状态 - [evalJS](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.NWindow.evalJS): 在窗口中执行脚本 - [findViewById](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.NWindow.findViewById): 在界面中通过id查找控件对象 - [forward](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.NWindow.forward): 窗口前进到上次加载的页面内容 - [getMetrics](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.NWindow.getMetrics): 获取窗口实际度量信息 - [getOption](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.NWindow.getOption): 获取窗口当前的属性值 - [getTitle](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.NWindow.getTitle): 获取窗口加载页面的标题 - [getUrl](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.NWindow.getUrl): 获取窗口加载页面的地址 - [load](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.NWindow.load): 窗口加载新的页面 - [reload](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.NWindow.reload): 重新加载窗口当前显示的页面 - [removeEventListener](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.NWindow.removeEventListener): 移除事件监听器 - [setContentVisible](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.NWindow.setContentVisible): 设置页面内容是否可见 - [setOption](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.NWindow.setOption): 设置原生窗口的参数 - [setPreloadJsFile](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.NWindow.setPreloadJsFile): 设置页面预先加载的js文件 - [setPullToRefresh](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.NWindow.setPullToRefresh): 设置窗口的下拉刷新功能 - [setVisible](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.NWindow.setVisible): 设置窗口是否可见 - [show](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.NWindow.show): 显示创建新的原生窗口 - [stop](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.NWindow.stop): 窗口停止加载页面内容 # [addEventListener]() 添加事件监听器 ~~~ wobj.addEventListener( event, listener, capture ); ~~~ ### 说明: 为窗口添加事件监听器,当指定的窗口事件发生时,回调函数将触发。可多次调用为同一事件添加多个监听器,触发时按照添加的顺序先后调用。 ### 参数: - event: *( [NWindowEvent](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.NWindowEvent) ) 必选 *要监听的事件类型 - listener: *( [EventCallback](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.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](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.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](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.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](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.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](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.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](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.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](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.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](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.NWindowEvent) ) 必选 *要移除的事件类型 - listener: *( [EventCallback](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.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](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.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](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.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+ (支持) - 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](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.Transition) 类型 )*窗口定义窗口变换的动画效果,参考Transition - transform: *([Transform](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.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字段,用于设置在刷新状态时显示的文本内容。 # [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](http://www.dcloud.io/docs/api/zh_cn/ui.shtml#plus.ui.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. } ~~~ ### 参数: 无 ### 返回值: void : 无