jQuery Mobile操作HTML5的常用函数总结
一.$.mobile.changePage()&$.mobile.loadPage()
1.$.mobile.changePage()
$.mobile.changePage()方法会在页面加载时自动调用,若这个页面为当前文档中的不同"page",则会转到这个新页面隐藏旧页面;若这个页面为外部页面,即页面与当前页面不在同一文档中(本质上是新页面不在当前DOM中),$.mobile.changePage()首先会调用$.mobile.loadPage()把外部页面的元素插入到DOM中,再显示新页面。这也是对页面加载过程的简单复述。
$.mobile.changePage()有两个参数to(stringorobject,必须)和options(object,可选),具体如下:
(1)——to(stringorobject,必须)
to为必要参数,其值可以为string(字符串,如"about/us.html")或object(对象,如$("#about")),这主要是面向两种不同的页面,string形式的为外部页面链接,而object为同一文档中的不同"page",如"#page2",$.mobile.changePage()会把其处理成包含这个DOM的jQuery对象,即$('#page2')这种形式,而$.mobile.changePage()内部会判断to参数的形式,若是string则调用$.mobile.loadPage()把外部页面的元素插入到DOM中,再显示页面。
(2)——options(object,可选)
options为可选参数,其值为object(对象),这个object包含多个属性,这些属性储存一个页面的各种参数,jQueryMobile会根据这些参数来控制如何加载页面,以及对页面进行初始化。具体属性值如下:
allowSamePageTransition(boolean,默认值:false)默认情况下,$.mobile.changePage()是不会理会跳转到当前页面的请求。把这个属性设置为"true",则可以允许这种请求
changeHash(boolean,默认值:true)判断地址栏上的哈希值是否应该被更新。
data(object或string,默认值:undefined)Ajax请求时发送的数据。仅当to参数的值为一个URL时可用。
dataUrl(string,默认值:undefined)当浏览器完成页面转换时要更新浏览器的地址栏上的URL。如不特别指定,则使用data-url的属性值。
pageContainer(jQuerycollection,默认值:$.mobile.pageContainer)指定包含页面的DOM对象的jQuery对象。
reloadPage(boolean,默认值:false)强制刷新页面,即使页面容器的DOM已经准备好仍然会执行刷新。仅当to参数的值为一个URL时可用。
reverse(boolean,默认值:false)设置页面转场动画的方向。当该属性设置为"true"时页面转场反向。
role(string,默认值:undefined)显示页面的时候使用data-role值。默认情况下为undefined,即取决于元素的@data-role属性值(标签上data-role的值)。
showLoadMsg(boolean,默认值:true)设置当加载外部页面时是否显示加载提示信息。
transition(string, 默认值:$.mobile.defaultPageTransition) 设置页面加载时使用的过场动画。
type(string,default:"get")设置请求页面时使用的方法("get"或"post")。仅当to参数的值为一个URL时可用。
这里引用例子说明一下$.mobile.changePage()的使用方法,手动调用该方法可以触发跳转到一个新页面,例如,在WebApps发生错误时可以跳转到一个提示错误的页面。
//转入到"aboutus"页面并使用"slideup"转场动画 $.mobile.changePage("about/us.html",{transition:"slideup"}); //转入到"searchresults"页面,使用来自id为search的表单数据,并把页面请求方式改为"post" $.mobile.changePage('searchresults.php',{ type:"post", data:$("form#search").serialize() }); //转入到"confirm"页面并使用"pop"转场动画,不更新历史记录(地址栏哈希值不更新) $.mobile.changePage('../alerts/confirm.html',{ transition:"pop", reverse:false, changeHash:false });
发生错误时可以跳转到一个提示错误的页面。
$(function(){ //发生错误 //已"slideup"的方式弹出对话框提示发生了错误 $.mobile.changePage('../alerts/confirm.html',{ transition:"slideup", role:"dialog" }); });
2.$.mobile.loadPage()
如上面所述,$.mobile.loadPage()用于加载一个外部页面,但这里的加载是指把外部页面的元素插入到当前DOM中,并在插入之前对页面内容进行jQueryMobile增强。该方法会被$.mobile.changePage()调用,条件是$.mobile.loadPage()的第一个参数to为string(即加载的页面为外部页面)。这个方法仅仅是进行插入DOM操作,不会影响当前激活的页面,所以它可以用于在后台加载页面(只插入DOM而不显示页面),该方法会返回一个deferred对象,包含页面请求成功与否等相关信息,并会在页面增强和插入DOM后分解这个对象。
$.mobile.loadPage()有两个参数url(stringorobject,必须)和options(object,可选),具体情况如下:
(1)——url(stringorobject,必须)
该参数的值可以为string或object,无论是何种形式,必须为一个绝对或相对URL。若是由$.mobile.changePage()调用本方法时,则该参数值为$.mobile.changePage()的to参数值。
(2)——options(object,可选)
options为可选参数,其值为object(对象),实际上如由$.mobile.changePage()调用本方法时,该参数值为$.mobile.changePage()的options参数值。因此这个object与$.mobile.changePage()的options选项值相同,其具体属性值请参考$.mobile.changePage()中options的属性值。
这里引用例子说明一下$.mobile.loadPage()的使用方法,手动调用该方法可以在后台加载外部页面的元素并且不影响当前激活页面。
//把"aboutus"页面加载到DOM $.mobile.loadPage('about/us.html'); //转入到"searchresults"页面,使用来自id为search的表单数据,并把页面请求方式改为"post" $.mobile.loadPage('searchresults.php',{ type:"post", data:$('form#search').serialize() });
二.$.fn.jqmData()&$.fn.jqmRemoveData()
当页面中使用了jQueryMobile,jQueryMobile会使用jqmData和jqmRemoveData代替jQuery核心的data和removeData方法(注意,这包括了jQuery中的$.fn.data,$.fn.removeData,$.data,$.removeData和$.hasData),这两个方法会自动获取和设置data属性的命名空间(即使当前没有使用命名空间)。
这两个方法的参数对应着jQuery的data和removeData方法的参数,具体如下:
(1)——jqmData(jQuery.data())
element与该data属性相关联的DOM对象
keydata的命名字符串
valuedata属性的值
(2)——jqmRemoveData(jQuery.removeData())
element与需要移除data属性相关联的DOM对象
name需要移除的data的命名字符串
注意:当通过jQueryMobiledata属性寻找元素时,请使用自定义选择器:jqmData(),它会在查询元素时自动合并data属性的命名空间。例如,你应该使用$('div:jqmData(role="page")')代替$('div[data-role="page"]'),因为前者会自动映射到$("div[data-"+$.mobile.ns+'role="page"]'),而不需要强制把选择器与命名空间连接起来。例如:命名空间为rn,若使用后者即为$('div[data-rn-role="page"]'),这时如果更改了命名空间,则这个选择器便会失效,而使用前者则会自动映射到当前选择器中,即使更改命名空间也不会造成这个选择器失效。
但是也有例外的情况,就是根据URL值在命名空间中选择data属性,例如,jQueryMobile可以使用:jqmData(url)跟踪一个页面来自哪里,根据URL中的命名空间来选择空间内的data属性。这要求需要在选择器的括号内填写一个有效的URL。
三.$.fn.jqmEnhanceable()
这是判断元素是否要进行jQueryMobile增强的方法,默认情况下,所有jQueryMobile组件都会通过此方法放入jQueryMobile增强集,以交给另一函数进行jQueryMobile增强,包括添加相应的HTML,CSSclass和交互。这是jQueryMobile默认调用的方法,并且没有任何可选参数,但该方法仍有一个很值得注意的地方,在方法的实现函数内部,会判断默认配置$.mobile.ignoreContentEnabled的值,若为true,则会对调用该方法的jQuery对象的DOM父节点遍历,若父节点标签上设置了data-enhance="false",则不让该DOM对象加入增强集。事实上jQueryMobile的官方文档并没有阐述$.fn.jqmEnhanceable()的具体使用方法,反而用了不少篇幅介绍这个注意事项。
另外还需要注意的是,遍历操作会设计元素的所有父节点,因此即使遍历一个很小的jQuery对象集的父节点也会消耗很多资源,开发则需要谨慎使用。若开发时已经明确不需要对某元素进行增强,建议还是直接不使用data-role触发相应的组件。
而如何设置$.mobile.ignoreContentEnabled的值,可以参考《使用jQueryMobile与HTML5开发WebApp——jQueryMobile默认配置与事件基础》
四.$.fn.jqmHijackable()
这是判断元素是否加入jQueryMobileAjax导航,即使用Ajax进行处理的方法,与$.fn.jqmEnhanceable()相似,默认情况下这也是会为所有链接和表单提交执行,使到它们可以加入jQueryMobileAjax处理集合,交给另一函数处理。在jQueryMobile内部,本方法与$.fn.jqmEnhanceable()最终都是调用了haveParents方法,来判断元素是否应该加入相应的集合。因此,本方法执行时会判断默认配置$.mobile.ignoreContentEnabled,若为true,则会对调用该方法的jQuery对象的DOM父节点遍历,若父节点上标签上设置了data-ajax="false",则不让该DOM对象加入Ajax导航集。当然,在使用这个特性时也需要注意遍历带来的大量资源消耗。
五.$.mobile.loading()
该方法从jQueryMobile1.2开始正式引进,控制显示或隐藏页面加载信息,包含两个参数,第一个是控制页面信息加载与否,只有"show"和"hide"两个值,第二个参数为多属性对象,具体的属性如下:
theme(string,默认值:"a")加载信息条的主题样式
text(string,默认值:"loading")加载信息条的文字内容
textonly(boolean,默认值:false)若设置为true,则加载页面时"spinner"图片(即旋形加载提示图,1.0及之前版本为条形加载图)会被隐藏。
textVisible(boolean,默认值:false)若设置为true,提示的文字内容会置于spinner之下
html(string,默认值:"")如果个属性值不为空,则这个值会替代整个加载信息条的HTML
下面引用例子说明$.mobile.loading的使用方法。
//提示页面正在加载 $.mobile.loading('show'); //加载信息条使用主题样式"b",自定义提示文字内容,隐藏"spinner"图片 $.mobile.loading('show',{theme:'b',text:'给力的加载中',textonly:true});
以下两个方法在jQueryMobile1.2中不赞成使用
六.$.mobile.hidePageLoadingMsg()
显示页面加载信息,基于$.mobile.loadingMessage配置出来,具体有三个参数
theme(string,default:"a")Thethemeswatchforthemessage.
msgText(string,default:"loading")Thetextofthemessage.
textonly(boolean,default:false)Iftrue,the"spinner"imagewillbehiddenwhenthemessageisshown.
例子:
//使用主题样式"b",自定义提示文字内容,隐藏"spinner"图片 $.mobile.showPageLoadingMsg('b','Thisisonlyatest',true);
在jQueryMobile1.2中,建议使用$.mobile.loading('show')代替。
七.$.mobile.hidePageLoadingMsg()
隐藏页面加载信息,基于$.mobile.loadingMessage配置出来,没有参数。
例子:
//隐藏页面加载提示信息 $.mobile.hidePageLoadingMsg();
在jQueryMobile1.2中,建议使用$.mobile.loading('hide')代替。
八.$.mobile.fixedToolbars.show()
固定工具栏(包括固定的头部栏和尾部栏)可以通过点击屏幕在显示与隐藏之间切换,而这个方法则是手动显示一次工具栏。
它具有一个参数immediately(boolean,可选)。把它设置为true,当前激活页面的所有固定工具栏都会立即显示出来。若设置为false或者没有指定,则会通过100ms的渐变显示出来。注意如document的resize和scroll等事件会导致额外的延时显示。
例子:
//显示固定工具栏并且显示默认的渐变动画 $.mobile.fixedToolbars.show(); //立即显示固定工具栏 $.mobile.fixedToolbars.show(true);
在jQueryMobile1.1中,不建议使用该方法,jQueryMobile并没有明确原因,但根据jQueryMobile的习惯,这很可能是因为这个方法有很多不稳定性,如上面提到的遇到某些方法会出现额外的延时显示,这对于建立WebApps是很不好的影响因素,它会从底层部分为WebApps带来不可预知的问题。
九.$.mobile.fixedToolbars.hide()
固定工具栏(包括固定的头部栏和尾部栏)可以通过点击屏幕在显示与隐藏之间切换,而这个方法则是手动隐藏一次工具栏。
与$.mobile.fixedToolbars.show()相似,它具有一个参数immediately(boolean,可选)。把它设置为true,当前激活页面的所有固定的工具栏都会立即隐藏。若设置为false或者没有指定,则会通过100ms的渐变隐藏起来。注意如document的resize和scroll等事件也会增加隐藏动画的时间。
例子:
//隐藏固定工具栏并显示默认的渐变动画 $.mobile.fixedToolbars.hide(); //立即隐藏固定工具栏 $.mobile.fixedToolbars.hide(true);
在jQueryMobile1.1中,也不建议使用该方法。
十.$.mobile.path.parseUrl()
本方法用于解析一个URL和它的相对形式,并且它的相关成分放入一个对象中,方便访问这些URL相关成分。当解析相对形式的URL时,返回的对象会自动为绝对形式URL中没有的成分(如protocol,host,etc)添加空字符串作为值。另外,当解析的URL没有authority(见下面的列表),返回的对象中的pathname属性会包含通信协议冒号后的数据。
$.mobile.path.parseUrl()只有一个参数URL(string,可选),其值为一个URL的相对或绝对形式。
另外,$.mobile.path.parseUrl()会返回一个包含URL相关成分的对象,这个对象的属性是模仿浏览器中的location对象。具体的属性如下:
hashURL中的一个部分,从URL中第一个"#"开始的部分。
hostURL的主机名及端口。
hostnameURL的主机名。
href被解析的原始URL。
pathnameURL所引用的文件或目录的路径。
portURL中指定的端口。大多数URLs依赖于数据传输协议所用的默认端口,所以这个值在大多数时候都可能是空字符串。
protocol数据传输协议,URL中':'之前的部分。
searchURL中的从"?"字符开始的部分,代表URL查询。另外它也包括提供给入口的额外成分,如一些常见形式的开发者访问。
authorityURL的用户名,密码,主机名
directorypathname中的目录部分,并且不包括任何文件名。
domainURL中的数据传输协议和用户名,密码,主机名等信息,即域。
filenamepathname中的文件部分,并且不包括任何目录名。
hrefNoHash从原始URL中减去hash部分。
hrefNoSearch从原始URL中减去hash和search部分。
passwordauthority中的password部分。
usernameauthority中的username部分。
例子:
//解析一个URL varobj=$.mobile.path.parseUrl("http://jblas:password@mycompany.com:8080/mail/inbox?msg=1234"); //解析这个URL会返回一个包含以下属性的对象 //obj.href:http://jblas:password@mycompany.com:8080/mail/inbox?msg=1234&type=unread#msg-content //obj.hrefNoHash:http://jblas:password@mycompany.com:8080/mail/inbox?msg=1234&type=unread //obj.hrefNoSearch:http://jblas:password@mycompany.com:8080/mail/inbox //obj.domain:http://jblas:password@mycompany.com:8080 //obj.protocol:http: //obj.authority:jblas:password@mycompany.com:8080 //obj.username:jblas //obj.password:password //obj.host:mycompany.com:8080 //obj.hostname:mycompany.com //obj.port:8080 //obj.pathname:/mail/inbox //obj.directory:/mail/ //obj.filename:inbox //obj.search:?msg=1234&type=unread //obj.hash:#msg-content
十一.$.mobile.path.makePathAbsolute()
把一个相对的文件或目录路径转化为绝对路径。
具有两个参数relPath(string,必须)和absPath(string,必须),具体如下:
(1)——relPath(string,必须)
其值为一个相对的文件或目录路径。
(2)——absPath(string,必须)
用于解析的一个绝对的文件或相对的路径。
$.mobile.path.makePathAbsolute()会返回一个包含相对路径的绝对路径版本的字符串。
例子:
//返回:/a/b/c/file.html varabsPath=$.mobile.path.makePathAbsolute("file.html","/a/b/c/bar.html"); //返回:/a/foo/file.html varabsPath=$.mobile.path.makePathAbsolute("../../foo/file.html","/a/b/c/bar.html");
十二.$.mobile.path.makeUrlAbsolute()
把一个相对URL转化为绝对URL。
具有两个参数relUrl(string,必选)和absUrl(string,必选),具体如下:
——relUrl(string,必选)
一个相对形式的URL。
——absUrl(string,必选)
用于解析的一个绝对的文件或相对的路径。
$.mobile.path.makeUrlAbsolute()会返回一个包含相对URL的绝对URL版本的字符串。
例子:
//返回:http://foo.com/a/b/c/file.html varabsUrl=$.mobile.path.makeUrlAbsolute("file.html","http://foo.com/a/b/c/test.html"); //返回:http://foo.com/a/foo/file.html varabsUrl=$.mobile.path.makeUrlAbsolute("../../foo/file.html","http://foo.com/a/b/c/test.html"); //返回:http://foo.com/bar/file.html varabsUrl=$.mobile.path.makeUrlAbsolute("//foo.com/bar/file.html","http://foo.com/a/b/c/test.html"); //返回:http://foo.com/a/b/c/test.html?a=1&b=2 varabsUrl=$.mobile.path.makeUrlAbsolute("?a=1&b=2","http://foo.com/a/b/c/test.html"); //返回:http://foo.com/a/b/c/test.html#bar varabsUrl=$.mobile.path.makeUrlAbsolute("#bar","http://foo.com/a/b/c/test.html");
十三.$.mobile.path.isSameDomain()
比较两个URL的域。
具有两个参数url1(string,可选)和url2(string,可选)具体情况如下:
——url1(string,可选)
一个相对URL。
——url2(string,可选)
url2(string,required)一个需要解析的绝对URL。
返回值为boolean型变量,若两个域匹配,则返回"true",否则返回"false"。
例子:
//返回:true varsame=$.mobile.path.isSameDomain("http://foo.com/a/file.html","http://foo.com/a/b/c/test.html"); //返回:false varsame=$.mobile.path.isSameDomain("file://foo.com/a/file.html","http://foo.com/a/b/c/test.html"); //返回:false varsame=$.mobile.path.isSameDomain("https://foo.com/a/file.html","http://foo.com/a/b/c/test.html"); //返回:false varsame=$.mobile.path.isSameDomain("http://foo.com/a/file.html","http://bar.com/a/b/c/test.html");
十四.$.mobile.path.isRelativeUrl()
判断一个URL是否是相对URL。
它具有一个参数URL(string,必选),其值为一个相对或绝对的URL。
返回值为boolean型变量,若URL为相对形式的URL,则返回"true",否则返回"false"。
例子:
//返回:false varisRel=$.mobile.path.isRelativeUrl("http://foo.com/a/file.html"); //返回:true varisRel=$.mobile.path.isRelativeUrl("//foo.com/a/file.html"); //返回:true varisRel=$.mobile.path.isRelativeUrl("/a/file.html"); //返回:true varisRel=$.mobile.path.isRelativeUrl("file.html"); //返回:true varisRel=$.mobile.path.isRelativeUrl("?a=1&b=2"); //返回:true varisRel=$.mobile.path.isRelativeUrl("#foo");
十五.$.mobile.path.isAbsoluteUrl()
判断一个URL是否是绝对URL。
它具有一个参数URL(string,必选),其值为一个相对或绝对的URL。
返回值为boolean型变量,若URL为绝对形式的URL,则返回"true",否则返回"false"。
例子:
//返回:true varisAbs=$.mobile.path.isAbsoluteUrl("http://foo.com/a/file.html"); //返回:false varisAbs=$.mobile.path.isAbsoluteUrl("//foo.com/a/file.html"); //返回:false varisAbs=$.mobile.path.isAbsoluteUrl("/a/file.html"); //返回:false varisAbs=$.mobile.path.isAbsoluteUrl("file.html"); //返回:false varisAbs=$.mobile.path.isAbsoluteUrl("?a=1&b=2"); //返回:false varisAbs=$.mobile.path.isAbsoluteUrl("#foo");
十六.$.mobile.path.get()
该方法可以判断一个URL的目录部分。如果URL末尾没有反斜杠,则URL最后的部分会被认为是文件名。这个情况对于站长来说应该不陌生,如http://kayosite.com/aaa/,URL中最后的部分"aaa/"应该是一个目录,而http://kayosite.com/aaa/xxx.zip中最后的部分"xxx.zip"则应该是一个文件名。这也是Kayo之前建议注意网址末尾是否需要添加反斜杠的原因。
这个方法具有一个参数url(string,必选),其值是一个相对或绝对的URL。
返回值为URL中的目录部分。
例子:
//返回:http://foo.com/a/ vardirName=$.mobile.path.get("http://foo.com/a/file.html"); //返回:http://foo.com/a/ vardirName=$.mobile.path.get("http://foo.com/a/"); //返回:http://foo.com/a vardirName=$.mobile.path.get("http://foo.com/a"); //返回://foo.com/a/ vardirName=$.mobile.path.get("//foo.com/a/file.html"); //返回:/a/ vardirName=$.mobile.path.get("/a/file.html"); //返回:"" vardirName=$.mobile.path.get("file.html"); //返回:/ vardirName=$.mobile.path.get("/file.html"); //返回:?a=1&b=2 vardirName=$.mobile.path.get("?a=1&b=2"); //返回:foo vardirName=$.mobile.path.isAbsoluteUrl("#foo");
十七.$.mobile.base
获取根元素。
十八.$.mobile.silentScroll()
静默滚动到某个Y值处,并且不触发任何事件。
它具有一个参数,yPos(number,默认为0),其值为需要滚动到的Y位置。
十九.$.mobile.activePage
引用当前激活的页面。
二十.关于方法的调用
1.方法调用相应JavaScript的引入
在介绍自定义jQueryMobile默认配置时,曾经说明了相应的JavaScript语句需要放置在jQuery库和jQueryMobile库之间,而jQueryMobile方法是对jQueryMobile的调用,因此需要在引入jQueryMobile库之后调用,具体如下:
<scriptsrc="jquery.min.js"></script> <!--引入自定义jQueryMobile默认配置相应的JavaScript--> <scriptsrc="custom-mobile.js"></script> <scriptsrc="jquery-mobile.min.js"></script> <!--引入jQueryMobile的调用,包括jQueryMobile的方法、事件检测等全部应用性JavaScript--> <scriptsrc="my-site.js"></script>
2.方法的调用
对于jQuery开发者,应该比较习惯在触发ready事件后执行JavaScript,例如:
$(document).ready(function(){ //执行JavaScript });
或简写为,
$(function(){ //执行JavaScript });
这里说明一下,当DOM已经加载,并且页面(包括图像)已经完全呈现出时,会触发ready事件。
而在系列文章的上一篇中,Kayo介绍了pageinit事件,它在DOM加载完成后(包括jQueryMobile对元素的DOM增强),就会触发,即它比ready更早的触发。
但由于jQueryMobile驱动的网站由Ajax导航,因此即使一个文档中包含多个'page',当第一个'page'的DOM和内容加载完毕后就会触发ready事件,而pageint也只需第一个'page'的DOM加载完毕后即触发。
而最终利用那种事件作为开始调用方法的合适时机,会涉及很多方便的考虑,开发者应该根据实际情况作出选择。
下面例举一个例子说明如何调用jQueryMobile方法,由于jQueryMobile的方法很多,这里只使用$.mobile.changePage()方法演示如何调用方法。例子中的JavaScript代码如下:
$(function(){ $("#home").bind('swipeleft',function(){ $.mobile.changePage('./page-2.html',{ transition:"slide", role:"dialog" }); }); });
上例中通过检测向左划动事件触发跳转到一个外部页面,同时使用'slide'转场动画并以对话框形式显示新页面。