jQuery Mobile 教程

jQuery Mobile 是一个基于 HTML5 的移动端用户界面框架,专为智能手机和平板电脑设计,提供一套统一的触控友好的 UI 组件。

本教程包含

入门篇:框架介绍、环境安装、页面结构
组件篇:按钮、列表、表单、导航等常用组件
进阶篇:主题定制、事件处理、API 详解

学习目标

掌握 jQuery Mobile 的核心概念,能够独立开发响应式移动端页面,理解其主题系统和事件机制,为后续学习其他移动端框架打下基础。

适合人群

有一定 HTML/CSS/JavaScript 基础,希望快速开发移动端 Web 应用的开发者。

jQuery Mobile 简介

jQuery Mobile 是 jQuery 基金会推出的移动端 Web UI 框架,是目前最流行的移动 Web 开发框架之一。

核心特点

基于 HTML5:使用语义化标签,符合 Web 标准
触控优化:所有组件都针对手指操作优化
跨平台:支持 iOS、Android、Windows Phone 等主流平台
渐进增强:在不支持的设备上优雅降级
主题化:内置 5 套主题,可快速定制外观

为什么选择 jQuery Mobile

与其他移动框架相比,jQuery Mobile 学习曲线平缓,文档完善,社区庞大,适合中小型移动网站和混合应用的快速开发。

jQuery Mobile 入门

学习 jQuery Mobile 最简单的途径是在 HTML 中引入它的 CSS 和 JavaScript 文件。

引入方式

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <link rel="stylesheet" href="https://code.jquery.com/mobile/1.4.5/jquery.mobile-1.4.5.min.css">
  <script src="https://code.jquery.com/jquery-1.11.3.min.js"></script>
  <script src="https://code.jquery.com/mobile/1.4.5/jquery.mobile-1.4.5.min.js"></script>
</head>
<body>
  <div data-role="page">
    <h1>Hello jQuery Mobile</h1>
  </div>
</body>
</html>

关键点

必须先引入 jQuery,再引入 jQuery Mobile
data-role="page" 是页面容器,所有内容放在其中
viewport 元标签保证移动端正确渲染

jQuery Mobile 安装

jQuery Mobile 有两种常见的使用方式:CDN 引入和本地下载。

方式一:CDN 引入(推荐)

<link rel="stylesheet" href="https://code.jquery.com/mobile/1.4.5/jquery.mobile-1.4.5.min.css">
<script src="https://code.jquery.com/mobile/1.4.5/jquery.mobile-1.4.5.min.js"></script>

方式二:本地文件

从官网下载 jQuery Mobile 压缩包
解压后包含 jquery.mobile-1.4.5.css / js 及 images 目录
将文件复制到项目目录,相对路径引用

版本说明

当前稳定版本为 1.4.5,jQuery 需使用 1.x 系列(如 1.11.3)以保持兼容。jQuery Mobile 已进入维护模式,新项目建议评估其他框架,但现有项目仍可长期稳定使用。

jQuery Mobile 页面结构

jQuery Mobile 使用 data-role 属性定义页面结构,核心是 page、header、content、footer 四个区域。

标准页面结构

<div data-role="page">
  <div data-role="header">
    <h1>页头</h1>
  </div>

  <div data-role="main" class="ui-content">
    <p>页面主体内容</p>
  </div>

  <div data-role="footer">
    <h4>页脚</h4>
  </div>
</div>

页面规则

每个页面必须以 data-role="page" 的 div 包裹
header/footer 是可选的,content 是核心
1.4 版本 content 区推荐加 class="ui-content"
多页面文件可在同一个 HTML 中定义多个 page

jQuery Mobile 对话框与弹窗

对话框(对话框页面)和弹窗(popup)是 jQuery Mobile 提供的信息展示组件。

对话框

<a href="#dialog-page" data-rel="dialog">打开对话框</a>

<div data-role="page" id="dialog-page">
  <div data-role="header"><h1>对话框标题</h1></div>
  <div role="main" class="ui-content">
    <p>这是对话框内容,以浮层形式显示</p>
  </div>
</div>

弹窗(Popup)

<a href="#myPopup" data-rel="popup" class="ui-btn ui-corner-all ui-shadow">显示弹窗</a>
<div data-role="popup" id="myPopup">
  <p>这是一个弹窗,可包含任意内容</p>
</div>

区别

对话框:整个页面作为浮层,可交互、可返回
弹窗:轻量级浮层,适合提示、菜单、图片展示
弹窗支持过渡动画和定位属性(position-to)

jQuery Mobile 过渡效果

jQuery Mobile 内置多种页面过渡动画,让页面切换更加流畅自然。

支持的过渡效果

fade:淡入淡出(默认)
pop:弹出效果
slide:左右滑动
slideup/slidedown:上下滑动
flip:翻转效果
turn:旋转效果
flow:流动效果
none:无过渡

使用方式

<a href="#page2" data-transition="slide">滑动切换</a>
<a href="#page3" data-transition="pop" data-direction="reverse">反向弹出</a>

编程方式切换

$.mobile.changePage("#page2", { transition: "slideup", reverse: false });

注意:过多的动画可能影响低端设备性能,建议默认使用 fade 或 none。

jQuery Mobile 按钮

按钮是移动端最常用的交互元素,jQuery Mobile 提供了统一的按钮样式。

基础按钮

<a href="#" class="ui-btn">普通按钮</a>
<button class="ui-btn">button 元素</button>
<input type="button" value="输入型按钮">

按钮增强

<a href="#" class="ui-btn ui-btn-inline">内联按钮</a>
<a href="#" class="ui-btn ui-corner-all">圆角按钮</a>
<a href="#" class="ui-btn ui-shadow">带阴影按钮</a>

主题色按钮

<a href="#" class="ui-btn ui-btn-a">主题A(黑)</a>
<a href="#" class="ui-btn ui-btn-b">主题B(蓝)</a>

图标按钮

<a href="#" class="ui-btn ui-icon-home ui-btn-icon-left">首页</a>
<a href="#" class="ui-btn ui-icon-search ui-btn-icon-notext">仅图标</a>

图标使用 ui-icon-xxx 类,位置通过 ui-btn-icon-left/right/top/bottom/notext 控制。

jQuery Mobile 图标

jQuery Mobile 内置了 50 多个 SVG 图标,通过 CSS 类即可使用,无需图片文件。

常用图标

ui-icon-home      首页
ui-icon-search    搜索
ui-icon-delete    删除
ui-icon-edit      编辑
ui-icon-plus      加号
ui-icon-minus     减号
ui-icon-arrow-l   左箭头
ui-icon-arrow-r   右箭头
ui-icon-check     对勾
ui-icon-gear      设置
ui-icon-user      用户
ui-icon-star      星标

图标与按钮结合

<a href="#" class="ui-btn ui-icon-delete ui-btn-icon-left">删除</a>
<a href="#" class="ui-btn ui-icon-plus ui-btn-icon-notext"></a>

图标定位类

ui-btn-icon-left:图标在左侧(默认)
ui-btn-icon-right:图标在右侧
ui-btn-icon-top:图标在上方
ui-btn-icon-notext:只显示图标,隐藏文字

jQuery Mobile 工具栏

工具栏是放置在页面头部或底部的导航区域,用于放置标题、按钮和导航元素。

头部工具栏

<div data-role="header">
  <a href="#" class="ui-btn ui-btn-left ui-btn-icon-notext ui-corner-all ui-icon-back">返回</a>
  <h1>页面标题</h1>
  <a href="#" class="ui-btn ui-btn-right ui-btn-icon-notext ui-corner-all ui-icon-home">首页</a>
</div>

底部工具栏

<div data-role="footer">
  <h4>© 2026 版权所有</h4>
</div>

固定工具栏

<div data-role="header" data-position="fixed">
  <h1>固定头部</h1>
</div>

data-position="fixed" 让工具栏固定在视口顶部/底部,滚动时不消失;data-fullscreen="true" 可实现全屏沉浸效果。

jQuery Mobile 导航栏

导航栏(Navbar)是底部常用的选项卡式导航,最多支持 5 个标签页。

基础导航栏

<div data-role="navbar">
  <ul>
    <li><a href="#" class="ui-btn-active">首页</a></li>
    <li><a href="#">分类</a></li>
    <li><a href="#">购物车</a></li>
    <li><a href="#">我的</a></li>
  </ul>
</div>

带图标的导航栏

<div data-role="navbar">
  <ul>
    <li><a href="#" data-icon="home" class="ui-btn-active">首页</a></li>
    <li><a href="#" data-icon="grid">分类</a></li>
    <li><a href="#" data-icon="cart">购物</a></li>
    <li><a href="#" data-icon="user">我的</a></li>
  </ul>
</div>

注意

当前激活项加 ui-btn-active 类
通常与底部固定工具栏(data-position="fixed")配合
超过 5 项会自动换行显示

jQuery Mobile 列表

列表(Listview)是移动端展示数据的核心组件,支持多种样式和交互。

基础列表

<ul data-role="listview">
  <li><a href="#">列表项 1</a></li>
  <li><a href="#">列表项 2</a></li>
</ul>

带描述和图标

<ul data-role="listview">
  <li>
    <a href="#">
      <img src="icon.png" class="ui-li-thumb">
      <h2>标题</h2>
      <p>描述文字</p>
      <p class="ui-li-aside">右侧信息</p>
    </a>
  </li>
</ul>

列表分隔与计数

<ul data-role="listview">
  <li data-role="list-divider">分组标题</li>
  <li><a href="#">项目<span class="ui-li-count">12</span></a></li>
</ul>

自动换行优化

较长的列表建议加 data-inset="true" 变为内嵌样式,并配合 li 的 data-filter="true" 启用搜索过滤。

jQuery Mobile 列表过滤

列表过滤功能可以在列表上方自动添加搜索框,实现客户端即时过滤,非常适合长列表。

启用过滤

<ul data-role="listview" data-filter="true">
  <li><a href="#">Apple</a></li>
  <li><a href="#">Banana</a></li>
  <li><a href="#">Cherry</a></li>
</ul>

自定义过滤行为

<ul data-role="listview" data-filter="true" data-filter-placeholder="搜索水果..." data-filter-theme="a">

只过滤指定字段

<li data-filtertext="custom keyword">
  <a href="#">显示文本</a>
</li>

注意

过滤默认忽略大小写
过滤不匹配时显示"无匹配结果"提示
大量数据建议配合 data-autodividers 自动分组

jQuery Mobile 表单

jQuery Mobile 会自动增强标准 HTML 表单控件,使其在移动端有更好的触控体验。

文本框

<label for="name">姓名:</label>
<input type="text" name="name" id="name">

文本域

<label for="msg">留言:</label>
<textarea name="msg" id="msg"></textarea>

下拉选择

<label for="city">城市:</label>
<select name="city" id="city">
  <option>北京</option>
  <option>上海</option>
</select>

表单增强属性

<input type="text" data-clear-btn="true" placeholder="可清除的输入框">
<input type="range" min="0" max="100" value="50">

表单提交

<form action="submit.php" method="post" data-ajax="false">
  <input type="submit" value="提交">
</form>

注意:jQuery Mobile 默认通过 AJAX 提交表单,若需传统提交加 data-ajax="false"。

jQuery Mobile 表单输入类型

jQuery Mobile 全面支持 HTML5 的输入类型,并在移动端调用对应的系统控件。

常用输入类型

<input type="text" placeholder="文本">
<input type="search" placeholder="搜索">
<input type="tel" placeholder="电话">
<input type="url" placeholder="网址">
<input type="email" placeholder="邮箱">
<input type="password" placeholder="密码">
<input type="number" placeholder="数字">
<input type="date">
<input type="time">
<input type="color">

滑块与开关

<input type="range" min="0" max="100" value="30">
<input type="checkbox" data-role="flipswitch">

说明

移动端浏览器会根据 type 调起对应键盘(数字、邮箱等)
date/time 在 iOS/Android 上显示原生选择器
flipswitch 是 jQuery Mobile 特有的开关控件

jQuery Mobile 复选框与单选按钮

复选框和单选按钮在 jQuery Mobile 中被增强为触控友好的大按钮样式。

复选框

<fieldset data-role="controlgroup">
  <legend>爱好:</legend>
  <label for="c1"><input type="checkbox" name="hobby" id="c1">阅读</label>
  <label for="c2"><input type="checkbox" name="hobby" id="c2">运动</label>
  <label for="c3"><input type="checkbox" name="hobby" id="c3">音乐</label>
</fieldset>

单选按钮

<fieldset data-role="controlgroup">
  <legend>性别:</legend>
  <label for="m"><input type="radio" name="gender" id="m" value="m">男</label>
  <label for="f"><input type="radio" name="gender" id="f" value="f">女</label>
</fieldset>

水平排列

<fieldset data-role="controlgroup" data-type="horizontal">
  <legend>评分:</legend>
  <label for="s1"><input type="radio" name="score" id="s1" value="1">1 星</label>
  <label for="s2"><input type="radio" name="score" id="s2" value="2">2 星</label>
</fieldset>

data-type="horizontal" 让控件组水平排列,节省垂直空间。

jQuery Mobile 选择菜单

选择菜单(select)在移动端会以原生方式呈现,或显示为自定义样式的菜单。

基础选择菜单

<label for="sel">选择城市:</label>
<select name="sel" id="sel">
  <option>北京</option>
  <option>上海</option>
  <option>广州</option>
  <option>深圳</option>
</select>

分组选择菜单

<select name="food">
  <optgroup label="中餐">
    <option>川菜</option>
    <option>粤菜</option>
  </optgroup>
  <optgroup label="西餐">
    <option>意面</option>
    <option>牛排</option>
  </optgroup>
</select>

多选与自定义样式

<select multiple>...</select>  <!-- 多选 -->
<select data-native-menu="false">...</select>  <!-- 自定义菜单 -->
<select data-icon="gear">...</select>  <!-- 自定义图标 -->

data-native-menu="false" 会使用 jQuery Mobile 自定义的菜单样式而非系统原生菜单。

jQuery Mobile 面板

面板(Panel)是侧滑菜单,可以从屏幕左侧或右侧滑出,非常适合放置导航菜单。

面板结构

<div data-role="panel" id="mypanel">
  <h2>菜单</h2>
  <ul data-role="listview">
    <li><a href="#">首页</a></li>
    <li><a href="#">关于</a></li>
  </ul>
</div>

<div data-role="page">
  <a href="#mypanel" class="ui-btn">打开菜单</a>
</div>

面板属性

<div data-role="panel" data-position="right" data-display="overlay" id="mypanel">

data-position:left(默认)/ right
data-display:overlay(覆盖)/ reveal(推出)/ push(推动)
data-dismissible:点击页面关闭面板
data-swipe-close:滑动关闭

固定面板

<div data-role="panel" data-position-fixed="true">

配合 data-position-fixed="true" 面板随页面滚动保持固定。

jQuery Mobile 折叠面板

折叠面板(Collapsibles)用于在有限空间内展示可展开/收起的内容块。

基础折叠

<div data-role="collapsible">
  <h3>点击展开</h3>
  <p>这里是折叠内容</p>
</div>

默认展开

<div data-role="collapsible" data-collapsed="false">
  <h3>默认展开的内容</h3>
  <p>内容直接可见</p>
</div>

手风琴效果

<div data-role="collapsibleset">
  <div data-role="collapsible">
    <h3>第一项</h3><p>内容 1</p>
  </div>
  <div data-role="collapsible">
    <h3>第二项</h3><p>内容 2</p>
  </div>
</div>

用 collapsibleset 包裹多个折叠块,一次只展开一个,形成手风琴。

jQuery Mobile 表格

jQuery Mobile 提供两种响应式表格:重排式(reflow)和列切换式(column toggle)。

重排式表格

<table data-role="table" data-mode="reflow" class="ui-responsive">
  <thead>
    <tr>
      <th>姓名</th>
      <th>职位</th>
      <th>城市</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>张三</td>
      <td>工程师</td>
      <td>北京</td>
    </tr>
  </tbody>
</table>

列切换式表格

<table data-role="table" data-mode="columntoggle" class="ui-responsive" id="myTable">
  <thead>
    <tr>
      <th data-priority="1">姓名</th>
      <th data-priority="3">职位</th>
      <th data-priority="2">城市</th>
    </tr>
  </thead>
</table>

说明

reflow:窄屏时每行变为块状堆叠显示
columntoggle:窄屏隐藏低优先级列,可通过按钮切换显示
data-priority 1 最高,优先保留

jQuery Mobile 网格布局

网格布局(Grid)用于将内容按行列排列,基于 CSS 百分比实现自适应。

两列布局

<div class="ui-grid-a">
  <div class="ui-block-a">
    <div class="ui-bar ui-bar-a">左列</div>
  </div>
  <div class="ui-block-b">
    <div class="ui-bar ui-bar-a">右列</div>
  </div>
</div>

三列布局

<div class="ui-grid-b">
  <div class="ui-block-a">第 1 列</div>
  <div class="ui-block-b">第 2 列</div>
  <div class="ui-block-c">第 3 列</div>
</div>

网格类型

ui-grid-a:两列,块 a/b
ui-grid-b:三列,块 a/b/c
ui-grid-c:四列,块 a/b/c/d
ui-grid-d:五列,块 a-e

注意:网格的列宽是固定的 50%/33%/25%/20%,同一网格内的块需配对使用。

jQuery Mobile 事件

jQuery Mobile 在 jQuery 事件基础上扩展了移动端专属事件,包括触摸、滚动、翻页等。

触摸事件

$(document).on("tap", "#btn", function() {
  alert("单击");
});
$(document).on("taphold", "#btn", function() {
  alert("长按");
});
$(document).on("swipe", "#list", function(e) {
  alert("滑动");
});
$(document).on("swipeleft swiperight", "#list", function(e) {
  alert(e.type);  // 左滑或右滑
});

滚动事件

$(document).on("scrollstart", function() {
  console.log("开始滚动");
});
$(document).on("scrollstop", function() {
  console.log("停止滚动");
});

页面事件

$(document).on("pagecreate", "#page1", function() {
  console.log("页面初始化完成");
});
$(document).on("pagebeforeshow", "#page1", function() {
  console.log("页面即将显示");
});

页面生命周期事件:pagebeforecreate → pagecreate → pageinit → pagebeforeshow → pageshow。

jQuery Mobile 触摸事件

触摸事件是 jQuery Mobile 针对触屏设备封装的底层事件,用于替代 click 以消除 300ms 延迟。

核心触摸事件

tap:快速点击,替代 click
taphold:长按(约 750ms)
swipe:滑动
swipeleft / swiperight:定向滑动
vclick:虚拟点击(兼容鼠标)

示例

$(document).on("taphold", "#del-btn", function() {
  // 长按删除按钮,弹出确认
  if (confirm("确认删除?")) {
    $(this).closest("li").remove();
  }
});

注意事项

tap 事件在滚动时可能被误触发,重要操作建议用 taphold
swipe 默认阈值:水平位移 30px、垂直位移 75px
事件绑定建议使用委托形式(on),兼容动态元素

jQuery Mobile 滚动事件

jQuery Mobile 提供 scrollstart 和 scrollstop 事件,方便在滚动前后执行操作(如懒加载)。

基本用法

$(document).on("scrollstart", function() {
  console.log("滚动开始");
  $("#loading").show();
});

$(document).on("scrollstop", function() {
  console.log("滚动停止");
  $("#loading").hide();
});

配合懒加载

$(document).on("scrollstop", function() {
  // 判断是否滚动到底部
  var doc = $(document);
  if (doc.scrollTop() + $(window).height() >= doc.height() - 50) {
    loadMoreData();  // 加载下一页数据
  }
});

注意

scrollstart 在惯性滚动期间只触发一次
滚动事件与触摸事件互斥,避免绑定过多导致卡顿
长列表建议配合虚拟滚动或分页

jQuery Mobile 主题

主题系统是 jQuery Mobile 的核心特性之一,通过字母(A-E)定义 5 套配色方案。

默认主题

主题 A:黑色系,对比度最高
主题 B:蓝色系,强调色
主题 C:灰色系(默认)
主题 D:浅灰色系
主题 E:黄色系,警示色

使用主题

<div data-role="page" data-theme="b">  <!-- 页面主题 -->
  <div data-role="header" data-theme="a">  <!-- 头部主题 -->
    <h1>标题</h1>
  </div>
  <a href="#" class="ui-btn" data-theme="b">主题 B 按钮</a>
  <a href="#" class="ui-btn" data-theme="a">主题 A 按钮</a>
</div>

全局默认主题

$(document).on("mobileinit", function() {
  $.mobile.page.prototype.options.theme = "a";
});

mobileinit 事件需在 jQuery Mobile 加载前绑定,用于修改全局默认配置。

jQuery Mobile API

jQuery Mobile 提供了丰富的方法和全局配置,通过 $.mobile 命名空间访问。

常用方法

// 页面跳转
$.mobile.changePage("#page2", { transition: "slide" });

// 页面加载外部 HTML
$.mobile.pageContainer.pagecontainer("change", "detail.html", { transition: "fade" });

// 启用/禁用 AJAX 导航
$.mobile.ajaxEnabled = false;

全局配置

$(document).on("mobileinit", function() {
  $.mobile.page.prototype.options.domCache = true;   // 缓存页面 DOM
  $.mobile.defaultPageTransition = "slide";          // 默认过渡
  $.mobile.defaultDialogTransition = "pop";          // 对话框过渡
  $.mobile.loadingMessage = "加载中...";             // 加载提示
});

控件方法

$("#mylist").listview("refresh");        // 刷新列表
$("#mypanel").panel("open");              // 打开面板
$("#mycollapse").collapsible("collapse"); // 收起折叠
$("#myselect").selectmenu("refresh");     // 刷新选择菜单

动态修改组件内容后,必须调用对应的 refresh 方法重新渲染。

jQuery Mobile 总结

恭喜你完成了 jQuery Mobile 教程的学习!

知识回顾

页面结构:page / header / content / footer 四大区域
导航:按钮、图标、工具栏、导航栏、面板、弹窗
内容:列表(过滤)、网格、折叠、表格(响应式)
表单:文本、选择、复选框、单选、滑块、开关
事件:tap、taphold、swipe、滚动、页面生命周期
主题:A-E 五套主题与 mobileinit 全局配置

适用场景

移动端信息展示站点
企业内部移动应用原型
混合应用(Hybrid App)的 Web 层

注意事项

jQuery Mobile 已进入维护模式(1.4.5 为最终版本),新项目建议评估 Bootstrap、Framework7 或原生方案。但掌握其思想(渐进增强、触控优先、主题化)对理解移动端开发仍很有价值。

第 1 / 27 节