使用 jQuery Mobile 与 HTML5 开发 Web App (十三) —— jQuery Mobile 方法上

本篇介绍的，是 jQuery Mobile 的方法。对比于 jQuery 方法可以实现 DOM 遍历，动画，Ajax 等各种丰富的操作，jQuery Mobile 的方法更像是 jQuery Mobile 的配置方案，它的主要功能是调整 jQuery Mobile 的效果或运行方式，尤其是页面加载和解析 URL 的部分，而 jQuery Mobile 方法基本都会在 jQuery Mobile 的默认执行中被内部调用，当然作为一系列完整的方法，开发者也可以手动执行它们，以创建更灵活的 Web Apps 。下面 Kayo 详细介绍 jQuery Mobile 的方法，由于方法较多，会分为两篇文章介绍，本文介绍的是与页面加载相关的方法。

一. $.mobile.changePage() & $.mobile.loadPage()

$.mobile.changePage() 与 $.mobile.loadPage() 方法是 jQuery Mobile 用于加载页面的方法，由于与页面事件有紧密的关联，因此在上一篇系列文章《使用 jQuery Mobile 与 HTML5 开发 Web App —— jQuery Mobile 页面事件与 deferred》中已经作了详细介绍，包括这两个方法的具体流程和及其技术原理，这些内容可以浏览前文的第一、二部分。而本文中会补充这两个方法的参数及对两个方法稍作总结。

$.mobile.changePage()

$.mobile.changePage() 方法会在页面加载时自动调用，若这个页面为当前文档中的不同 "page"，则会转到这个新页面隐藏旧页面；若这个页面为外部页面，即页面与当前页面不在同一文档中（本质上是新页面不在当前 DOM 中），$.mobile.changePage() 首先会调用 $.mobile.loadPage() 把外部页面的元素插入到 DOM 中，再显示新页面。这也是对页面加载过程的简单复述。

$.mobile.changePage() 有两个参数 to (string or object, 必须) 和 options (object, 可选)，具体如下：

—— to (string or object, 必须)

to 为必要参数，其值可以为 string(字符串，如 "about/us.html") 或 object(对象，如 $("#about"))，这主要是面向两种不同的页面，string 形式的为外部页面链接，而 object 为同一文档中的不同 "page" ，如 "#page2" ，$.mobile.changePage() 会把其处理成包含这个 DOM 的 jQuery 对象，即 $('#page2') 这种形式，而 $.mobile.changePage() 内部会判断 to 参数的形式，若是 string 则调用 $.mobile.loadPage() 把外部页面的元素插入到 DOM 中，再显示页面。

—— options (object, 可选)

options 为可选参数，其值为 object （对象），这个 object 包含多个属性，这些属性储存一个页面的各种参数，jQuery Mobile 会根据这些参数来控制如何加载页面，以及对页面进行初始化。具体属性值如下：

allowSamePageTransition (boolean, 默认值: false) 默认情况下，$.mobile.changePage() 是不会理会跳转到当前页面的请求。把这个属性设置为 "true" ，则可以允许这种请求
changeHash (boolean, 默认值: true) 判断地址栏上的哈希值是否应该被更新。
data (object 或 string, 默认值: undefined) Ajax 请求时发送的数据。仅当 to 参数的值为一个 URL 时可用。
dataUrl (string, 默认值: undefined) 当浏览器完成页面转换时要更新浏览器的地址栏上的 URL 。如不特别指定，则使用 data-url 的属性值。
pageContainer (jQuery collection, 默认值: $.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() 的使用方法，手动调用该方法可以触发跳转到一个新页面，例如，在 Web Apps 发生错误时可以跳转到一个提示错误的页面。

// 转入到 "about us" 页面并使用 "slideup" 转场动画
$.mobile.changePage( "about/us.html", { transition: "slideup"} );
 
// 转入到 "search results" 页面, 使用 来自 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"
    });
});

$.mobile.loadPage()

如上面所述，$.mobile.loadPage() 用于加载一个外部页面，但这里的加载是指把外部页面的元素插入到当前 DOM 中，并在插入之前对页面内容进行 jQuery Mobile 增强。该方法会被 $.mobile.changePage() 调用，条件是 $.mobile.loadPage() 的第一个参数 to 为 string （即加载的页面为外部页面）。这个方法仅仅是进行插入 DOM 操作，不会影响当前激活的页面，所以它可以用于在后台加载页面（只插入 DOM 而不显示页面），该方法会返回一个 deferred 对象，包含页面请求成功与否等相关信息，并会在页面增强和插入 DOM 后分解这个对象。

$.mobile.loadPage() 有两个参数 url (string or object, 必须) 和 options (object, 可选)，具体情况如下：

—— url (string or object, 必须)

该参数的值可以为 string 或 object ，无论是何种形式，必须为一个绝对或相对 URL 。若是由 $.mobile.changePage() 调用本方法时，则该参数值为 $.mobile.changePage() 的 to 参数值。

—— options (object, 可选)

options 为可选参数，其值为 object （对象），实际上如由 $.mobile.changePage() 调用本方法时，该参数值为 $.mobile.changePage() 的 options 参数值。因此这个 object 与 $.mobile.changePage() 的 options 选项值相同，其具体属性值请参考 $.mobile.changePage() 中 options 的属性值。

这里引用例子说明一下 $.mobile.loadPage() 的使用方法，手动调用该方法可以在后台加载外部页面的元素并且不影响当前激活页面。

// 把 "about us" 页面加载到 DOM
$.mobile.loadPage('about/us.html');
 
// 转入到 "search results" 页面, 使用来自 id 为 search 的表单数据，并把页面请求方式改为 "post"
$.mobile.loadPage('searchresults.php', {
    type: "post",
    data: $('form#search').serialize()
});

二. $.fn.jqmData() & $.fn.jqmRemoveData()

当页面中使用了 jQuery Mobile ，jQuery Mobile 会使用 jqmData 和 jqmRemoveData 代替 jQuery 核心的 data 和 removeData 方法（注意，这包括了 jQuery 中的 $.fn.data , $.fn.removeData , $.data , $.removeData 和 $.hasData），这两个方法会自动获取和设置 data 属性的命名空间（即使当前没有使用命名空间）。

这两个方法的参数对应着 jQuery 的 data 和 removeData 方法的参数，具体如下：

—— jqmData( jQuery.data() )

element 与该 data 属性相关联的 DOM 对象
key data 的命名字符串
value data 属性的值

—— jqmRemoveData ( jQuery.removeData() )

element 与需要移除 data 属性相关联的 DOM 对象
name 需要移除的 data 的命名字符串

注意：当通过 jQuery Mobile data 属性寻找元素时，请使用自定义选择器：jqmData() ，它会在查询元素时自动合并 data 属性的命名空间。例如，你应该使用 $('div:jqmData(role="page")') 代替 $('div[data-role="page"]') ，因为前者会自动映射到 $("div[data-"+ $.mobile.ns +'role="page"]') ，而不需要强制把选择器与命名空间连接起来。例如：命名空间为 rn ，若使用后者即为 $('div[data-rn-role="page"]') ，这时如果更改了命名空间，则这个选择器便会失效，而使用前者则会自动映射到当前选择器中，即使更改命名空间也不会造成这个选择器失效。

但是也有例外的情况，就是根据 URL 值在命名空间中选择 data 属性，例如，jQuery Mobile 可以使用 :jqmData(url) 跟踪一个页面来自哪里，根据 URL 中的命名空间来选择空间内的 data 属性。这要求需要在选择器的括号内填写一个有效的 URL 。

三. $.fn.jqmEnhanceable()

这是判断元素是否要进行 jQuery Mobile 增强的方法，默认情况下，所有 jQuery Mobile 组件都会通过此方法放入 jQuery Mobile 增强集，以交给另一函数进行 jQuery Mobile 增强，包括添加相应的 HTML , CSS class 和交互。这是 jQuery Mobile 默认调用的方法，并且没有任何可选参数，但该方法仍有一个很值得注意的地方，在方法的实现函数内部，会判断默认配置 $.mobile.ignoreContentEnabled 的值，若为 true ，则会对调用该方法的 jQuery 对象的 DOM 父节点遍历，若父节点标签上设置了 data-enhance = "false" ，则不让该 DOM 对象加入增强集。事实上 jQuery Mobile 的官方文档并没有阐述 $.fn.jqmEnhanceable() 的具体使用方法，反而用了不少篇幅介绍这个注意事项。

另外还需要注意的是，遍历操作会设计元素的所有父节点，因此即使遍历一个很小的 jQuery 对象集的父节点也会消耗很多资源，开发则需要谨慎使用。若开发时已经明确不需要对某元素进行增强，建议还是直接不使用 data-role 触发相应的组件。

而如何设置 $.mobile.ignoreContentEnabled 的值，可以参考《使用 jQuery Mobile 与 HTML5 开发 Web App —— jQuery Mobile 默认配置与事件基础》

四. $.fn.jqmHijackable()

这是判断元素是否加入 jQuery Mobile Ajax 导航，即使用 Ajax 进行处理的方法，与 $.fn.jqmEnhanceable() 相似，默认情况下这也是会为所有链接和表单提交执行，使到它们可以加入 jQuery Mobile Ajax 处理集合，交给另一函数处理。在 jQuery Mobile 内部，本方法与 $.fn.jqmEnhanceable() 最终都是调用了 haveParents 方法，来判断元素是否应该加入相应的集合。因此，本方法执行时会判断默认配置 $.mobile.ignoreContentEnabled ，若为 true ，则会对调用该方法的 jQuery 对象的 DOM 父节点遍历，若父节点上标签上设置了 data-ajax = "false" ，则不让该 DOM 对象加入 Ajax 导航集。当然，在使用这个特性时也需要注意遍历带来的大量资源消耗。

五. $.mobile.loading()

该方法从 jQuery Mobile 1.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 });

以下两个方法在 jQuery Mobile 1.2 中不赞成使用

六. $.mobile.hidePageLoadingMsg()

显示页面加载信息，基于 $.mobile.loadingMessage 配置出来，具体有三个参数

- theme (string, default: "a") The theme swatch for the message.
- msgText (string, default: "loading") The text of the message.
- textonly (boolean, default: false) If true, the "spinner" image will be hidden when the message is shown.

例子：

// 使用主题样式 "b" ，自定义提示文字内容，隐藏 "spinner" 图片
$.mobile.showPageLoadingMsg('b', 'This is only a test', true);

在 jQuery Mobile 1.2 中，建议使用 $.mobile.loading('show') 代替。

七. $.mobile.hidePageLoadingMsg()

隐藏页面加载信息，基于 $.mobile.loadingMessage 配置出来，没有参数。

例子：

// 隐藏页面加载提示信息
$.mobile.hidePageLoadingMsg();

在 jQuery Mobile 1.2 中，建议使用 $.mobile.loading('hide') 代替。

观察以上的方法，可以看出以上方法跟页面加载的过程都有关联。不过，以上只是 jQuery Mobile 里的一部分方法，另外一部分方法主要跟页面 URL 解析有关，还有一些其他的实用方法，将会在下一篇文章中详细介绍。

原文由 Kayo Lee 发表，原文链接：http://kayosite.com/web-app-by-jquery-mobile-and-html5-methods-part-one.html

使用 jQuery Mobile 与 HTML5 开发 Web App (十三) —— jQuery Mobile 方法上

一. $.mobile.changePage() & $.mobile.loadPage()

$.mobile.changePage()

—— to (string or object, 必须)

—— options (object, 可选)

$.mobile.loadPage()

—— url (string or object, 必须)

—— options (object, 可选)

二. $.fn.jqmData() & $.fn.jqmRemoveData()

—— jqmData( jQuery.data() )

—— jqmRemoveData ( jQuery.removeData() )

三. $.fn.jqmEnhanceable()

四. $.fn.jqmHijackable()

五. $.mobile.loading()

六. $.mobile.hidePageLoadingMsg()

七. $.mobile.hidePageLoadingMsg()

相关推荐