WindowTools

维护人:戴荔春 (6016)

说明

Window操作相关工具类，包括H5模式下的window,iframe以及plus模式下的webview操作,以及一些便捷方法

初始化引入

工具类需要手动引入才会生效

//其中WindowTools_Core 是路径在sea中对应的别名
var WindowTools = require('WindowTools_Core');

方法:

setOption: 设置默认的页面样式
getExtraDataByKey: 获取页面初始化参数,通过传入key,得到对应key的值
createWin: 创建或打开一个新的页面
openWinWithTemplate: 以webview模板优化方式打开页面
preloadTemplate: 在需要使用到 webview优化的页面中,初始化调用这个函数,可以提前创建好模板页面
showWin: 显示一个页面
hideWin: 隐藏一个页面
createSubWins: 生成多个子页面
dbClickExit: 双击返回键退出APP
lockOrientation:锁住屏幕方向
unlockOrientation:解锁屏幕方向
firePageEvent: 触发页面的自定义事件
closeCurrentPage: 关闭当前页面
trigger: 触发事件
getHashParams: 获取url hash值
setUrlHash: 设置url hash值
clearHtml: 去除html标签中的换行符和空格
getWinSize: 得到窗口的宽和高,返回JSON配对
isExternalUrl: url是否属于绝对路径

setOption

设置默认的页面样式

// 替换默认设置
WindowTools.setOption(options)

说明:

WindowTools里有一个 DefaultStyle,用来控制页面创建显示时的样式,这个函数可以替换默认样式(实际上只有5+的webview才会应用默认样式)

参数:

options:( DefaultStyle )必选需要设置的新默认样式

返回值:

void:无

平台支持:

Html5 (支持)
Html5+ (支持)

DefaultStyle

WindowTools中webview的默认style

{
    "top": "0px",
    "bottom": "0px",
    "scrollIndicator": "none",
    "scalable": false,
    "popGesture": "close",
    "aniShow": "none",
    "aniHide": "none",
    "duration": 300,
    "waiting": {
        "autoShow": false,
        "title": "正在打开页面...",
        "options": {
            "size": "20px",
            "padlock": false,
            "modal": false,
            "color": "#ffff00",
            "background": "rgba(0,0,0,0.8)",
            "loading": {
                "display": "inline"
            }
        }
    },
    "extras": {
		"acceleration": "auto"
	}
}

说明:

里面配置了一些WindowTools的默认样式。

参数:

top:( String ) 子页面距离顶部距离
bottom:( String ) 子页面距离底部距离
scrollIndicator:( String ) 窗口是否显示滚动条
用于控制窗口滚动条样式，可取值： "all"：垂直和水平滚动条都显示； "vertical"：仅显示垂直滚动条； "horizontal"：仅显示水平滚动条； "none"：垂直和水平滚动条都不显示。默认值为"all"，即垂直和水平滚动条都显示。注意：显示滚动条的前提条件是窗口中的内容超过窗口显示的宽或高。
popGesture:( String ) 窗口的侧滑返回功能
可取值"none"：无侧滑返回功能；"close"：侧滑返回关闭Webview窗口；"hide"：侧滑返回隐藏webview窗口。仅iOS平台支持。
aniShow:( String ) 显示Webview窗口的动画效果
如果没有指定窗口动画，则使用默认无动画效果“none”。
aniHide:( String ) 隐藏Webview窗口的动画效果
如果没有指定窗口动画，则使用默认无动画效果“none”。
duration:( number ) Webview窗口动画的持续时间
默认时间为300ms
waiting.autoShow:( Boolean ) 是否自动显示等待框,为true代表显示
waiting.title:( String ) 等待对话框上显示的提示内容
waiting.options:( JSON ) 控制对话框的其它样式
extras:( JSON ) 窗口的拓展参数,控制窗口优化,如acceleration为auto表示自动使用窗口优化

getExtraDataByKey

获取页面初始化参数,通过传入key,得到对应key的值

// 获取初始化参数
var value =  WindowTools.getExtraDataByKey(key)

说明:

通过传入key值,得到页面key的初始化传值
plus情况为plus.webview.currentWebview.***
h5情况为 window.location.href 中的参数的值

参数:

key:( String )必选目标参数值的key

返回值:

String:返回对应的参数值

平台支持:

Html5 (支持)
Html5+ (支持)

createWin

创建或打开一个新的页面

// 新建页面
WindowTools.createWin(id,url,extras, styles, openCallback, closeCallBack);

说明:

创建一个新的页面
h5下为用href跳转
plus下为通过5+API新建新的webview(如果已经存在,则变为打开)

参数:

id:( String )可选页面的id,如果不穿,默认使用下个参数url作为id
url:( String )必选页面的路径,支持相对路径,以及绝对路径
例如,打开绝对网络路径: http:***.html
extras:( JSON )可选额外参数(传给下一个页面的参数)
styles:( JSON )可选页面样式,不传则使用默认样式
参数设置参考: DefaultStyle

完整的参数设置参考: plus的WebviewStyles
openCallback:( function )可选页面正常打开后的回调(plus下才有用)
closeCallBack:( function )可选页面关闭后的回调(plus下才有用)

返回值:

Void:无

平台支持:

Html5 (支持)
Html5+ (支持)

openWinWithTemplate

以webview模板优化方式打开页面

//以webview模板优化方式打开页面,前提是要基于框架,并且有模板页面
WindowTools.openWinWithTemplate(id,url,extras, styles, openCallback, closeCallBack);

说明:

h5或者ios的情况下,内部使用createWin来创建

plus并且Android的情况下,以Webview模板优化的方式来打开页面。这时候要求使用最新的框架,并且符合对应的目录结构(比如需要存在RayApp.Template.html等)。详情参考 Android Webview优化技巧

推荐使用这种方式(在Android机型上,性能的提升会很明显)

参数:

参考: createWin参数
特别说明,其中styles参数下,可以多一个 templateOptions 参数,如 styles.templateOptions = { title: linkUrl === '测试页面' };

返回值:

Void:无

平台支持:

Html5 (支持)
Html5+ (支持)

templateOptions

webview优化时,styles里面的一个子参数

{
    "title": "模板页面显示的标题"
}

说明:

主要作用是用来控制模板header页面的显示,可以通过一些自定义参数,让header页面和目标页面更像,从而过渡更自然

参数:

title:( String ) 模板页面之header页面显示的标题

preloadTemplate

预加载模版页面,webview优化时可以用到

//在需要使用到 webview优化的页面中,初始化调用这个函数,可以提前创建好模板页面
CommonTools.initReady(function(){
	//预加载模板页面
	WindowTools.preloadTemplate();
});

说明:

只有plus且Android下会生效,其它情况相当于一个空函数

如果没有预加载模版页面,那么第一次调用 openWinWithTemplate时,会触发预加载事件,预加载页面。等预加载完毕后,第二次调用才能正常打开页面。

参数:

返回值:

Void:无

平台支持:

Html5 (支持)
Html5+ (支持)

showWin

显示一个页面

// 显示页面,plus下可以使用动画样式
WindowTools.showWin(id, aniShow, duration, showedCB, extras);

说明:

显示一个页面,使用默认样式,传入参数可以是webview对象或者是webview的id

参数:

id:( String||Webview )必选 webview对象或者是webview的id,或者是Iframe的id
aniShow:( String )可选显示时的动画,不传则使用默认设置
duration:( Number )可选显示动画的时间,不传则使用默认设置
showedCB:( function )可选显示完毕后的回调
extras:( JSON )可选窗口的拓展参数,参考 WebviewExtraOptions

返回值:

Void:无

平台支持:

Html5 (部分支持-只支持子Iframe显示)
Html5+ (支持)

hideWin

隐藏一个页面

// 隐藏页面,plus下可以使用动画样式
WindowTools.hideWin(id, aniHide, duration,  extras);

说明:

显示一个页面,使用默认样式,传入参数可以是webview对象或者是webview的id

参数:

id:( String||Webview )必选 webview对象或者是webview的id,或者Iframe的id
aniHide:( String )可选隐藏时的动画,不传则使用默认设置
duration:( Number )可选隐藏动画的时间,不传则使用默认设置
extras:( JSON )可选窗口的拓展参数,参考 WebviewExtraOptions

返回值:

Void:无

平台支持:

Html5 (部分支持-只支持子Iframe显示)
Html5+ (支持)

createSubWins

生成多个子页面

// 生成子页面
var pagesStr = WindowTools.createSubWins(options, styles, loadedCallback);

说明:

生成多个子页面
h5下为生成iframe
h5+下为生成webview

参数:

options:( SubWinOptions )必选子页面的option
styles:( SubWinStyles )可选子页面的style
loadedCallback:( function )可选子页面生成并加载完毕后的回调

返回值:

String:生成子页面的id拼接的字符串,以","隔开

平台支持:

Html5 (支持)
Html5+ (支持)

SubWinOptions

生成子页面的options选项

[
    {
        "url": "url1",
        "id": "id1",
        "styles": {
            "top": "45px",
            "bottom": "0px",
            "...":"其它style,参考webview style样式",
            "其它":"比如是否显示dialog,duration由DefaultStyle控制"
        },
        "extras":{
        	
        }
    },
    {
        "url": "url2",
        "id": "id2",
        "styles": {
            "top": "45px",
            "bottom": "0px"
        },
        "extras":{
        	
        }
    }
]

说明:

数组的每一个item对应一个子页面的style。
styles里面一样可以添加 webview的style
extras里是额外参数

参数:

url:( String ) 子页面的地址,支持相对地址和绝对地址
id:( String ) 子页面的id,为null代表默认使用url作为地址
styles.top:( String ) 子页面距离顶部距离
styles.bottom:( String ) 子页面距离底部距离

SubWinStyles

生成子页面的styles选项

 {
    "isShowFirst": true,
    "parentDom": "#frameWrap"
}

说明:

创建子页面时的通用style

参数:

isShowFirst:( Boolean ) 是否显示第一个子页面,默认为true
parentDom:( String ) h5中,iframe的父级dom(如果没有,默认添加进body中)

dbClickExit

双击返回键退出APP

// 双击退出,可以自定义提示语句和间隔时间
WindowTools.dbClickExit(tips, intervalTime);

说明:

双击返回键退出APP-仅支持Android平台
一般每个应用的首页会执行这句代码

参数:

tips:( String )可选退出时的提示语句,默认为“再按一次退出应用”
intervalTime:( number )可选双击退出的间隔时间,单位毫秒,默认为"1000"毫秒

返回值:

Void:无

平台支持:

Html5 (不支持)
Html5+ (支持)

lockOrientation

锁住屏幕方向

//锁住为竖屏
CommonTools.lockOrientation(true);

说明:

锁住屏幕方向
可以锁住屏幕为竖屏或者横屏
只在plus下有效

参数:

isPortrait( Boolean )可选是否是竖屏,默认为true

返回值:

Void:无

平台支持:

Html5 (不支持)
Html5+ (支持)

lockOrientation

解锁屏幕方向

//解锁屏幕方向
CommonTools.unlockOrientation(true);

说明:

解锁屏幕方向
解锁后,屏幕又恢复最初的设置了,比如又可以正常横屏和竖屏切换
只在plus下有效

参数:

返回值:

Void:无

平台支持:

Html5 (不支持)
Html5+ (支持)

firePageEvent

触发页面的自定义事件

// 触发某个页面的自定义事件
WindowTools.firePageEvent(id, refreshEventName, extras);

说明:

plus中,可以触发任意页面的任意自定义事件
h5中,只能触发本页面的事件或者是本页面的子页面的事件

参数:

id:( String )必选对应页面的id
refreshEventName:( String )必选自定义事件的名称
extras:( JSON )可选额外的参数

返回值:

Void:无

平台支持:

Html5 (部分支持)
Html5+ (支持)

closeCurrentPage

关闭当前页面

// 关闭当前页面
WindowTools.closeCurrentPage();

说明:

plus下为使用mui的back,关闭当前页面和子页面
h5下,如果当前页面是open打开的,则关闭整个opener,否则history.back()

参数:

返回值:

Void:无

平台支持:

Html5 (支持)
Html5+ (支持)

trigger

触发事件

// 触发事件
WindowTools.trigger(element, eventType, eventData);

说明:

通过h5实现触发事件

参数:

element:( HTMLElement )可选目标元素,默认为document
eventType:( String )必选事件类别
eventData:( JSON )可选触发事件时的额外数据

返回值:

Void:无

平台支持:

Html5 (支持)
Html5+ (支持)

getHashParams

获取url hash值

// 得到hash值
var hashValue =  WindowTools.getHashParams(key);

说明:

格式：#key1=val1|key2=val2|key3=val3

参数:

key:( String )必选对应的key值

返回值:

String:返回对应的Hash值

平台支持:

Html5 (支持)
Html5+ (支持)

setUrlHash

设置url hash值

// 设置url hash值
WindowTools.setUrlHash(key,value);

说明:

格式：#key=value
设置后会清除以前hash

参数:

key:( String )必选对应的key值
value:( String )必选对应的value值

返回值:

Void:无

平台支持:

Html5 (支持)
Html5+ (支持)

clearHtml

去除html标签中的换行符和空格

// 去除html标签中的换行符和空格
var html = WindowTools.clearHtml(html);

说明:

通过正则表达式,去除html标签中的换行符和空格

参数:

html:( String )必选目标html字符串

返回值:

String:过滤后的html字符串

平台支持:

Html5 (支持)
Html5+ (支持)

getWinSize

得到窗口的宽和高,返回JSON配对

// 获得宽高
var winSize = WindowTools.getWinSize();
var width = winSize.width;
var height = winSize.height;

说明:

宽和高都是整数

参数:

返回值:

JSON:返回获取的宽高JSON对

平台支持:

Html5 (支持)
Html5+ (支持)

isExternalUrl

url是否属于外部url

// 判断是否外部
var isExternalUrl = WindowTools.isExternalUrl(url);

说明:

判断url是否属于外部url
/^(http|https|ftp|file)/g为外部地址

参数:

url:( String )必须目标地址字符串

返回值:

Boolean:是否是外部地址

平台支持:

Html5 (支持)
Html5+ (支持)