jQuery Mobile 源码构建、定制与测试指南:从 AMD 模块裁剪到自定义主题编译

原创2026-10-09 12:56:231,431 阅读
文章标签:前端移动开发UI组件

jQuery Mobile 源码构建、定制与测试指南:从 AMD 模块裁剪到自定义主题编译

jQuery Mobile 是一套基于 HTML5 的统一移动端用户界面系统,构建在 jQuery 与 jQuery UI 之上,遵循渐进增强理念,并以"轻量、可主题化"为核心设计目标。本文基于仓库根目录 README.md 展开,结合 Gruntfile.js、build/tasks/alias.js、js/jquery.mobile.js 等源码文件,完整讲解该项目的构建体系:如何通过 AMD 模块裁剪 JavaScript 体积、如何通过 THEME 环境变量编译自定义 CSS 主题,以及如何搭建 PHP 开发环境并运行单元/集成测试。

状态提示:jQuery Mobile 官方已于 2021 年 10 月宣布停止维护(详见项目状态公告)。本仓库对应 1.4.x 之后的开发版本(package.json 中版本号为 1.5.0-pre),文中所有构建命令与源码路径以当前仓库实际内容为准,适用于需要在旧项目中维护、二次开发或学习其架构的读者。

项目定位与技术栈

README 对 jQuery Mobile 的定义是:"a unified, HTML5-based user interface system for all popular mobile device platforms, built on the rock-solid jQuery and jQuery UI foundation",即一个面向所有主流移动设备平台的统一 HTML5 用户界面系统,构建在 jQuery 与 jQuery UI 基础之上。其代码以渐进增强(progressive enhancement)方式编写,并提供灵活、易于主题化的设计。

从 package.json 可以确认项目的技术底座:

  • 运行依赖:仅 jquery >= 1.8.3。README 明确指出 1.4.x 版本支持 jQuery Core 1.8.3 至 1.11.1 / 2.1.1 的区间。
  • 开发依赖:grunt 0.4.5、requirejs 2.1.8、grunt-contrib-requirejs、grunt-contrib-jshint、grunt-contrib-qunit、grunt-contrib-uglify、grunt-contrib-cssmin 等,构成了"依赖解析 → 合并 → 压缩 → 校验 → 测试"的完整工具链。

仓库布局也与 README 的描述完全对应:JavaScript 模块位于 js(含 widgets、navigation、events、transitions 等子目录),CSS 结构样式位于 css/structure,主题样式位于 css/themes/default,示例文档位于 demos,测试套件位于 tests。

构建体系总览:四个核心目标

当前库在 CDN 上以"单个巨型 JavaScript 文件 + 打包 CSS"的形式发布:JavaScript 文件依赖 jQuery Core(不内置),CSS 为合并后的整体样式。README 为使用者列出四个构建目标:

目标 作用
js 解析依赖、构建、合并并压缩 jQuery Mobile 的 JavaScript
css 解析依赖、构建、合并并压缩全部 CSS(含纯结构 CSS 与纯主题 CSS)
demos 构建 js 与 css,并将文档站点准备为可直接静态消费的形态
lint 使用 JSHint 校验 JavaScript 文件

在 build/tasks/alias.js 中可以看到这些目标背后的真实任务链,例如:

  • build 依次执行 clean → config:fetchHeadHash(从 git log 抓取 HEAD hash 写入输出头注释,见 build/tasks/config.js)→ build:js → build:css → build:demos → compress:dist → compress:images;
  • build:js = modules → requirejs → concat:js → uglify → copy:sourcemap,即用 RequireJS 按 AMD 依赖树解析打包,再做合并与 Uglify 压缩,并复制 sourcemap;
  • build:css = cssbuild → csslint → cssmin;
  • default 目标 = build + test,与 README 中"从项目根目录直接执行 grunt"的行为一致。

环境要求与基础命令

构建工具链要求两个运行时组件:

  • Node.js
  • grunt-cli

安装依赖并执行默认构建(等价于 build + test 两条任务链):

npm install
grunt

更省事的定制入口:Download Builder

如果不想在本地跑完整构建,README 推荐使用官方的 Download Builder(下载构建器):在网页上勾选所需库的组成部分,系统会自动解析出对应的 CSS 与 JavaScript 依赖,并打包为整体/压缩形态交付。这种方式特别适合只需要部分组件的普通使用者。

JavaScript 定制:通过 AMD 模块裁剪"线重"

从 1.1 版本起,jQuery Mobile 在 JavaScript 构建中引入了 AMD 依赖管理。所有模块注册于核心 meta 模块 js/jquery.mobile.js,该文件以 define([...]) 形式列出一份完整的依赖清单,覆盖 loader、navigate/导航、pagecontainer、collapsible、grid、navbar、listview、表单控件(button/checkboxradio/slider/flipswitch/rangeslider/textinput/select 等)、popup、panel、table、filterable、tabs 与 zoom 等全部功能。

裁剪示例:移除表单控件

README 给出的经典场景是:为了减少移动端加载的"线重"(wire weight),把表单控件整体从 meta 模块中移除。修改 js/jquery.mobile.js 中的依赖清单,删去以下行:

-       './jquery.mobile.forms.checkboxradio',
-       './jquery.mobile.forms.button',
-       './jquery.mobile.forms.slider',
-       './jquery.mobile.forms.textinput',
-       './jquery.mobile.forms.select.custom',
-       './jquery.mobile.forms.select',

(注意:当前仓库中的真实模块路径已带有版本化后缀,例如 ./widgets/forms/checkboxradio、./widgets/forms/button、./widgets/forms/slider、./widgets/forms/textinput、./widgets/forms/select.custom、./widgets/forms/select,分别对应 js/widgets/forms 目录下的同名文件;README 中的 diff 展示的是旧命名下的等效操作。)

随后执行 JavaScript 构建:

grunt build:js

构建链路(modules → requirejs → concat:js → uglify → copy:sourcemap)会依据修改后的依赖清单重新解析并产出剪裁后的产物。这一机制的价值在于:自定义构建无需改动任何业务代码,只需增删 meta 模块的依赖条目,RequireJS 会自动完成依赖树的收缩。

CSS 定制:用 THEME 环境变量编译新主题

主题定制是 jQuery Mobile 最核心的可配置能力之一。README 给出三步流程,结合仓库中的 css/themes 目录可以完整复现。

新建主题目录

  1. 将 default 主题目录复制为新名称的目录(例如 my-theme),即复制 css/themes/default → css/themes/my-theme/;
  2. 在新目录的 jquery.mobile.theme.css 中加入自定义样式。

从仓库文件可以确认 default 主题目录的内容构成:jquery.mobile.theme.css 承载主题变量与全局样式(如字体、圆角 /*{global-radii-blocks}*/ 之类的占位标记即主题化钩子),其余文件如 jquery.mobile.css(结构+主题的合并束)、jquery.mobile.inline-svg.css、jquery.mobile.inline-png.css、jquery.mobile.external-png.css、jquery.mobile.icons.css 等则对应图标嵌入方式的多种变体。

执行构建

从项目根目录运行:

THEME=my-theme grunt build:css

前提是主题文件确实位于相对于项目根目录的 css/themes/$THEME/ 下(本例即 css/themes/my-theme/)。构建产物输出到 $PROJECT_ROOT/dist。

构建背后的 CSS 管线

build:css 对应三条 grunt 任务(build/tasks/alias.js):

  • cssbuild:使用 RequireJS 的 CSS 优化能力解析 @import 并合并文件(build/tasks/cssbuild.js)。其默认优化级别为 standard.keepComments.keepLines,即在合并 @import、移除多余空行压缩体积的同时保留注释与换行,规避 IE 下压缩 CSS 的兼容问题(详见 build/tasks/options/cssbuild.js 中的注释)。
  • csslint:对产物做 CSS 质量校验。
  • cssmin:最终压缩。

值得说明的是,CSS 构建实际覆盖的不止一套文件。从 build/files.js 可以看到 getCSSFiles() 输出的七类目标:

目标 源文件(位于 css/themes/default)
structure jquery.mobile.structure.css(结构样式,源在 css/structure)
theme jquery.mobile.theme.css
bundle jquery.mobile.css(结构+主题合并束)
inlinesvg jquery.mobile.inline-svg.css
inlinepng jquery.mobile.inline-png.css
externalpng jquery.mobile.external-png.css
icons jquery.mobile.icons.css

所有产物统一输出到 dist/,未压缩版与 .min.css 压缩版并存(minified 命名由 files.js 自动推导)。

开发环境搭建:PHP + Apache

README 明确:仓库根目录同时也是文档站点根目录,并与测试套件一起充当 bug 修复与功能开发的试验场。因此要参与补丁贡献,必须先起一个服务器并跑通测试套件。

服务器选型

大部分文档页与测试页依赖 PHP 5+,因此需要 Apache + PHP,README 给出三种安装方式:

  • 一键安装:OSX 使用 MAMP,OSX/Windows 使用 XAMPP;
  • 已有 Web 服务器:例如 OSX 的 ~/Sites 目录;
  • 虚拟机:安装 Vagrant 后可直接 vagrant up。

除原生 Apache 外,还需要以下三个模块(在对应配置中启用):

  • Rewrite(mod_rewrite.so)
  • Expire(mod_expires.so)
  • Header(mod_headers.so)

服务器就绪后将文档根指向项目目录即可访问文档与测试页。

测试套件结构

README 将测试定位为"jQuery Mobile 项目 QA 活动的支柱",并说明测试套件分为两类:

  • 单元测试(unit tests):聚焦库的单一组成部分(例如某个 widget),对应 tests/unit 下的 collapsible、filterable、slider、table、popup、navbar、zoom 等目录;
  • 集成测试(integration tests):需要库的多个部分协同工作,对应 tests/integration 下的 navigation、pagecontainer、page、dialog、listview、toolbar 等目录。

运行测试:grunt test 的完整用法

跑全部测试

grunt test

从 build/tasks/alias.js 可以看到该命令的任务链:clean:testsOutput → jshint → jscs:build → jscs:good → htmllint:tests → build:js → connect → qunit:http,即先做代码风格与 HTML 校验,再构建 JS,启动本地 connect 服务器后通过 QUnit 走 HTTP 跑测试。

只跑部分套件:--suites

grunt test --suites=table,slider

上面的命令只运行 tests/unit/table/ 与 tests/unit/slider/ 下的测试(这两个目录均真实存在于仓库中,分别见 tests/unit/table 与 tests/unit/slider)。

排除指定套件:!

grunt test --type=integration --suites=\!navigation

该命令运行除 navigation 套件以外的全部集成测试(navigation 集成测试目录为 tests/integration/navigation)。

指定 jQuery 版本:--jqueries

grunt test --jqueries=1.11.1,git

用于在多个 jQuery Core 版本(仓库 external/jquery 提供本地副本)下交叉验证兼容性——这与 README 声明的 1.8.3~1.11.1 / 2.1.1 支持区间直接呼应。

指定测试类型:--types

grunt test --types=unit
grunt test --types=integration
grunt test --types=unit,integration   # 默认值,等价于 grunt test

三种写法分别对应"仅单元测试""仅集成测试"与"全部测试"。需要说明的是,--suites 与 --types 的可组合使用(如上面的 --type=integration --suites=!navigation)为 CI 场景的定向回归提供了极大便利;项目 CI 脚本入口为 package.json 中的 scripts.ci(grunt ci),对应 alias.js 中按环境变量 CITYPE 分流的 ci:demos / ci:test 任务。

参与贡献的入口

README 欢迎以三种方式贡献:报告 issue、建议新特性、提交 pull request,并强调提交前先阅读 CONTRIBUTING.md。对贡献者的硬性要求是:必须为自己补丁所影响的代码运行测试套件,剩余部分由持续集成服务器兜底——这也是上面整套 grunt test 参数体系存在的意义。

小结

从本仓库的 README.md 可以完整还原 jQuery Mobile 的工程化思路:以 AMD 模块组织 JavaScript、以"结构样式/主题样式"分离组织 CSS、以 RequireJS 统一解析两类资源,并以 Grunt 串起构建、校验与测试。对于今天的开发者而言,这套"meta 模块裁剪 + THEME 环境变量 + 分层测试命令"的定制流程仍具有直接的参考价值——它展示了在不改动业务代码的前提下,如何通过依赖清单与构建参数精确控制框架产物体积,以及如何为一个庞大 UI 库建立可持续的 QA 体系。

登录后查看全文
jquery-mobile