ui

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: 窗口刷新操作的回调函数

权限：

permissions

"UI": {
	"description": "访问系统原生窗口"
}
			

AnimationTypeShow

一组用于定义页面或控件显示动画效果

常量：

• "none": (DOMString 类型 )无动画效果
  

  立即显示页面，无任何动画效果，页面显示默认的动画效果。对应关闭动画"none"。

• "slide-in-right": (DOMString 类型 )从右侧横向滑动效果
  

  页面从屏幕右侧外向内横向滑动显示。对应关闭动画"slide-out-right"。

• "slide-in-left": (DOMString 类型 )从上侧竖向滑动效果
  

  页面从屏幕上侧向内竖向滑动显示。对应关闭动画"slide-out-top"。

• "slide-in-bottom": (DOMString 类型 )从下侧竖向滑动效果
  

  页面从屏幕下侧向内竖向滑动显示。对应关闭动画"slide-out-bottom"。

• "fade-in": (DOMString 类型 )从透明到不透明逐渐显示效果
  

  页面从完全透明到不透明逐渐显示。对应关闭动画"fade-out"。

• "zoom-out": (DOMString 类型 )从小到大逐渐放大显示效果
  

  页面在屏幕中间从小到大逐渐放大显示。对应关闭动画"zoom-in"。

• "flip-x": (DOMString 类型 )以x轴从上到下翻转效果
  

  页面以x轴从上到下翻转显示。对应关闭动画"flip-rx"。

• "flip-rx": (DOMString 类型 )以x轴从下到上翻转转效果
  

  页面以x轴从下到上翻转显示。对应关闭动画"flip-x"。

• "flip-y": (DOMString 类型 )以y轴从左到右翻转效果
  

  页面以y轴从左到右翻转显示。对应关闭动画"flip-ry"。

• "flip-ry": (DOMString 类型 )以y轴从右到左翻转效果
  

  页面以y轴从右到左翻转显示。对应关闭动画"flip-y"。

• "page-forward": (DOMString 类型 )向前翻书动画效果
  

  页面以向前翻书动画显示，翻书后显示新打开的页面。对应关闭动画"page-backward"。

AnimationTypeClose

一组用于定义页面或控件关闭的动画效果

常量：

• "none": (DOMString 类型 )无动画
  

  立即关闭页面，无任何动画效果。

• "slide-out-right": (DOMString 类型 )横向向右侧滑出屏幕动画
  

  页面从屏幕中横向向右侧滑动到屏幕外关闭。

• "slide-out-left": (DOMString 类型 )横向向左侧滑出屏幕动画
  

  页面从屏幕中横向向左侧滑动到屏幕外关闭。

• "slide-out-top": (DOMString 类型 )竖向向上侧滑出屏幕动画
  

  页面从屏幕中竖向向上侧滑动到屏幕外关闭。

• "slide-out-bottom": (DOMString 类型 )竖向向下侧滑出屏幕动画
  

  页面从屏幕中竖向向下侧滑动到屏幕外关闭。

• "fade-out": (DOMString 类型 )从不透明到透明逐渐隐藏动画
  

  页面从不透明到透明逐渐隐藏关闭。

• "zoom-in": (DOMString 类型 )从大逐渐缩小关闭动画
  

  页面逐渐向页面中心缩小关闭。

• "flip-x": (DOMString 类型 )以x轴从上到下翻转动画
  

  页面以x轴从上到下翻转关闭，翻转后显示以前显示的页面。

• "flip-rx": (DOMString 类型 )以x轴从下到上翻转转动画
  

  页面以x轴从下到上翻转关闭，翻转后显示以前显示的页面。

• "flip-y": (DOMString 类型 )以y轴从左到右翻转动画
  

  页面以y轴从左到右翻转关闭，翻转后显示以前显示的页面。

• "flip-ry": (DOMString 类型 )以y轴从右到左翻转动画
  

  页面以y轴从右到左翻转关闭，翻转后显示以前显示的页面。

• "page-backward": (DOMString 类型 )向后翻书动画
  

  页面以向后翻书动画关闭，翻书后显示以前显示的页面。

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: 获取窗口实际度量信息

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是等待控件对象，用于在界面中显示原生等待窗口

方法：

• setTitle: 设置等待控件上显示的文字
• close: 关闭等待控件

事件：

• onclose: 关闭等待控件事件

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。

• 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: 窗口停止加载页面内容

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表示垂直和水平方向都有反弹效果。

• height: (DOMString 类型 )窗口的高度
  

  支持百分比、像素值，默认为100%。

• left: (DOMString 类型 )窗口水平向右的偏移量
  

  支持百分比、像素值，默认值为0px。

• margin: (DOMString 类型 )窗口的边距
  

  用于定位窗口的位置，支持auto，auto表示居中。若设置了left、right、top、bottom则对应的边距值失效。

• name: (DOMString 类型 )窗口的名称
  

  作为窗口的标识，可用于窗口的查找。

• opacity: (Number 类型 )窗口的不透明度
  

  0为全透明，1为不透明，默认值为1，即不透明。

• 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字段，用于设置在刷新状态时显示的文本内容。

TimeOption

JSON对象，选择时间界面设置的参数

属性：

• title: (DOMString 类型 )时间选择操作界面显示的标题
  

  字符串类型，默认标题为当前选择的时间。

• is24Hour: (Boolean 类型 )是否24小时制模式，默认值为true
  
• popover: (JSON 类型 )时间日期选择界面弹出指示区域
  

  JSON对象，格式如{top:10;left:10;width:200;height:200;}，所有值为像素值，左上坐标相对于容器webview的位置。如未设置此值，默认在屏幕居中显示。

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"，暂不支持其它值。

• duration: (DOMString 类型 )变换持续的时间
  

  默认值为0，即无动画效果。

• timingfunction: (DOMString 类型 )窗口变换效果
  

  可取值linear、ease-in、ease-out、ease-in-out，默认值为linear。

AlertCallback

系统提示框确认的回调函数

void onAlerted() {
	// Alert handled code.
}
				

参数：

无

返回值：

void : 无

ConfirmCallback

系统确认框操作的回调函数

void onConfirmed( Number index ) {
	// Confirm handled code.
}
				

参数：

• index: ( Number ) 必选 用户点击按钮的索引值，从0开始
  

返回值：

void : 无

PromptCallback

系统输入框操作的回调函数

function void onPrompted( Number index, DOMString value ) {
	// Prompt handled code.
}
				

参数：

• index: ( Number ) 必选 用户点击按钮的索引值，从0开始
  
• value: ( DOMString ) 可选 用户输入的内容，若没有输入则返回空字符串
  

返回值：

void : 无

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.
}
				

参数：

无

返回值：

void : 无