前言
jQuery Mobile (jQM) 為移動 Web 應用提供了豐富的專屬事件與方法,涵蓋觸控手勢、裝置方向、滾動監控、頁面轉場生命週期等。雖然 jQM 已停止維護,但其事件設計思想在現代觸控開發中仍具參考價值。本文系統整理核心 API 並給出現代替代方案。
一、觸控手勢事件
| 事件 | 觸發條件 | 典型用途 |
tap | 快速輕觸(< 250ms,位移 < 10px) | 替代 click 消除 300ms 延遲 |
taphold | 長按(~750ms) | 長按選單、刪除確認 |
swipe | 水平滑動 ≥ 30px 且垂直 < 20px,1s 內 | 左右導航、刪除滑出 |
swipeleft | 向左滑動 | 下一頁、刪除動作 |
swiperight | 向右滑動 | 上一頁、展開側欄 |
綁定方式(jQM 1.4+ 推薦 on)
// 頁面內元素
$('#list').on('swipeleft', 'li', function () {
$(this).find('.delete-btn').show();
});
$('#list').on('swiperight', 'li', function () {
$(this).find('.edit-btn').show();
});
// 頁面級手勢
$(document).on('swipeleft', '.ui-page', function () {
navigate('next');
});
$(document).on('swiperight', '.ui-page', function () {
navigate('prev');
});
二、裝置方向事件
$(window).on('orientationchange', function (e) {
// e.orientation: 'portrait' | 'landscape'
// 也會自動在 <html> 添加 .ui-orientation-portrait / .ui-orientation-landscape 類
console.log('方向變更:', e.orientation);
adjustLayout(e.orientation);
});
// 現代替代:Screen Orientation API
if (screen.orientation) {
screen.orientation.addEventListener('change', function () {
console.log('現代 API:', screen.orientation.type); // portrait-primary, landscape-primary 等
});
}
三、滾動事件
| 事件 | 觸發時機 | 注意事項 |
scrollstart | 開始滾動 | iOS 凍結 DOM 操作,需謹慎 |
scrollstop | 滾動結束(停止 ~100ms) | 適合載入更多、記錄位置 |
滾動位置持久化實戰
$(document).on('scrollstop', function () {
var scrollTop = $(this).scrollTop();
sessionStorage.setItem('scrollPos_' + location.pathname, scrollTop);
});
$(document).on('pagebeforeshow', function () {
var pos = sessionStorage.getItem('scrollPos_' + location.pathname);
if (pos) {
// 需在渲染後執行
setTimeout(function () { $(window).scrollTop(parseInt(pos, 10)); }, 0);
}
});
四、頁面顯示/隱藏生命週期
| 事件 | 階段 | 典型用途 |
pagebeforecreate | 頁面初始化前(DOM 尚未增強) | 注入動態內容、修改結構 |
pagecreate | 頁面初始化後(已增強為 jQM 樣式) | 綁定事件、初始化插件 |
pagebeforeshow | 頁面即將顯示(轉場前) | 顯示 Loading、預載數據 |
pageshow | 頁面顯示完成(轉場後) | 隱藏 Loading、啟動動畫、聚焦 |
pagebeforehide | 頁面即將隱藏(轉場前) | 暫停視頻、保存狀態 |
pagehide | 頁面隱藏完成(轉場後) | 清理定時器、移除監聽 |
Loading 控制範例
$(document).on('pagebeforeshow', '.ui-page', function () {
$.mobile.loading('show', { text: '載入中...', textVisible: true });
});
$(document).on('pageshow', '.ui-page', function () {
$.mobile.loading('hide');
});
// AJAX 錯誤時也要隱藏
$(document).on('ajaxError', function () {
$.mobile.loading('hide');
});
頁面初始化傳參模式
// 列表頁跳轉到詳情頁,攜帶參數
$(document).on('click', '.item-link', function () {
var id = $(this).data('id');
$.mobile.navigate('#detail-page', { data: { itemId: id } });
});
// 詳情頁接收
$('#detail-page').on('pagebeforecreate', function (e, data) {
var itemId = data.options.data.itemId;
loadDetail(itemId);
});
五、頁面初始化事件(僅首次)
pagebeforecreate / pagecreate 僅在頁面首次注入 DOM 時觸發,適合一次性初始化。注意:AJAX 載入的頁面會成為當前頁的 div[data-role="page"],ID 會變為 URL 路徑(如 id="dialog/search.php"),綁定時需用類選擇器或動態 ID。
六、常用工具方法
| 方法 | 說明 | 示例 |
$.mobile.changePage(url, transition, reverse, changeHash) | 程式化頁面跳轉 | $.mobile.changePage('detail.html', 'slide', false, true) |
$.mobile.loading(show/hide) | 顯示/隱藏載入指示器 | $.mobile.loading('show'); $.mobile.loading('hide'); |
$.mobile.silentScroll(y) | 無動畫滾動到指定 Y | $.mobile.silentScroll(100); |
$.mobile.addResolutionBreakpoints(px...) | 添加響應式斷點類 | $.mobile.addResolutionBreakpoints([480, 768, 1024]); |
$.mobile.path | URL 路徑工具集 | $.mobile.path.parseUrl() |
$.mobile.activePage | 當前活躍頁面 jQuery 物件 | $.mobile.activePage.find('.content') |
現代替代方案對照
結語
jQuery Mobile 的事件體系展示了移動端交互的完整圖譜:手勢識別 → 裝置感知 → 滾動同步 → 頁面生命週期 → 導航控制。雖然庫本身已成為歷史,但這套概念模型在現代 PWA、混合應用、小程序開發中依然適用。建議新專案採用原生標準 + 輕量庫組合,舊專案維護時參考本文快速定位 API。