ui
UI模块管理应用界面,用于操作加载HTML页面的原生窗口,调用系统原生控件等。由于此模块功能太多,现已根据功能分拆更新为Key、NativeUI、Navigator、Webview等,并对接口和功能做了一些优化调整,请使用新API。
方法:
对象:
回调方法:
权限:
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
原生控件对象,用于操作页面中显示的原生控件
方法:
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是等待控件对象,用于在界面中显示原生等待窗口
方法:
事件:
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页面的原生窗口
方法:
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对象,选择时间界面设置的参数
属性:
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
一组用于定义页面或控件转换效果的属性
属性:
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 : 无