jQuery Mobile Data 属性详解：从入门到实战

原创于 2026-09-14 08:54:45 发布 · 107 阅读

本内容遵循CC 4.0 BY-SA版权协议

1. 引言

jQuery Mobile 是一个基于 HTML5 的移动端 UI 框架，它的核心设计理念之一就是「约定优于配置」。开发者无需编写大量 JavaScript 代码，只需在 HTML 标签中添加特定的 data-* 属性，框架就会自动完成组件的初始化、样式美化和交互增强。这种声明式开发方式极大降低了移动端页面的开发门槛。

本文将从基础概念出发，系统梳理 jQuery Mobile 中常用的 data-* 属性，并结合丰富的代码实例，帮助读者快速掌握这些属性的用法和适用场景。

2. 什么是 data 属性

data-* 属性是 HTML5 规范中定义的一组自定义属性，用于在标准 HTML 元素上存储额外的信息。jQuery Mobile 充分利用了这一机制，通过读取这些属性来决定如何渲染和增强页面组件。

一个典型的例子是页面容器：

<div data-role="page" id="home">
    <div data-role="header">
        <h1>首页</h1>
    </div>
    <div data-role="content">
        <p>欢迎使用 jQuery Mobile！</p>
    </div>
    <div data-role="footer">
        <h4>版权信息</h4>
    </div>
</div>

当 jQuery Mobile 加载页面时，它会扫描 DOM 中的 data-role 属性，并自动将对应的 div 元素增强为页面、页头、内容区和页脚组件。

3. 页面结构相关属性

页面结构是 jQuery Mobile 应用的基础，以下属性用于定义页面的基本骨架。

3.1 data-role

data-role 是最核心的属性，用于指定元素的角色。常见取值包括：

page：定义一个页面容器。
header：定义页头区域。
content：定义内容区域。
footer：定义页脚区域。
navbar：定义导航栏。
listview：定义列表视图。
collapsible：定义可折叠内容块。

<div data-role="page" id="about">
    <div data-role="header">
        <h1>关于我们</h1>
    </div>
    <div data-role="content">
        <div data-role="collapsible">
            <h3>公司简介</h3>
            <p>我们是一家专注于移动端开发的科技公司。</p>
        </div>
    </div>
</div>

3.2 data-title

data-title 用于设置页面在浏览器标签栏中显示的标题，尤其在多页（multi-page）应用中非常实用。

<div data-role="page" data-title="产品列表" id="products">
    <div data-role="header">
        <h1>产品中心</h1>
    </div>
    <div data-role="content">
        <p>这里是产品列表页面。</p>
    </div>
</div>

当用户切换到该页面时，浏览器标签栏会显示「产品列表」，而不是默认的文档标题。

3.3 data-url

data-url 用于指定页面的唯一标识 URL，在多页应用中用于控制页面切换时的地址栏显示。

<div data-role="page" data-url="/contact" id="contact">
    <div data-role="header">
        <h1>联系我们</h1>
    </div>
    <div data-role="content">
        <p>电话：400-123-4567</p>
    </div>
</div>

4. 列表组件属性

列表是移动端最常见的 UI 组件之一，jQuery Mobile 提供了丰富的 data-* 属性来定制列表的外观和行为。

4.1 data-inset

data-inset="true" 可以将列表设置为内嵌样式，使列表带有圆角和外边距，视觉上更像一个独立的卡片。

<ul data-role="listview" data-inset="true">
    <li><a href="#">苹果</a></li>
    <li><a href="#">香蕉</a></li>
    <li><a href="#">橙子</a></li>
</ul>

4.2 data-filter

data-filter="true" 可以为列表添加搜索过滤框，用户输入关键字时列表会自动筛选匹配项。

<ul data-role="listview" data-filter="true" data-filter-placeholder="搜索城市...">
    <li><a href="#">北京</a></li>
    <li><a href="#">上海</a></li>
    <li><a href="#">广州</a></li>
    <li><a href="#">深圳</a></li>
    <li><a href="#">杭州</a></li>
</ul>

其中 data-filter-placeholder 用于自定义搜索框的提示文字。

4.3 data-dividertheme

data-dividertheme 用于设置列表分隔条的主题色。

<ul data-role="listview" data-dividertheme="b">
    <li data-role="list-divider">水果</li>
    <li><a href="#">苹果</a></li>
    <li><a href="#">香蕉</a></li>
    <li data-role="list-divider">蔬菜</li>
    <li><a href="#">白菜</a></li>
    <li><a href="#">萝卜</a></li>
</ul>

4.4 data-count

在列表项中添加 data-count 属性可以显示数字角标，常用于消息数量、商品数量等场景。

<ul data-role="listview" data-inset="true">
    <li><a href="#">收件箱<span class="ui-li-count">12</span></a></li>
    <li><a href="#">草稿箱<span class="ui-li-count">3</span></a></li>
    <li><a href="#">已发送<span class="ui-li-count">45</span></a></li>
</ul>

5. 表单组件属性

表单是移动应用中用户交互的重要入口，jQuery Mobile 通过 data-* 属性让表单控件更易用、更美观。

5.1 data-role 在表单中的应用

表单控件同样使用 data-role 来声明组件类型，例如滑块、开关、选择菜单等。

<form>
    <label for="slider">音量：</label>
    <input type="range" name="slider" id="slider" value="50" min="0" max="100" data-role="slider">

    <label for="switch">开启通知：</label>
    <select name="switch" id="switch" data-role="slider">
        <option value="off">关</option>
        <option value="on">开</option>
    </select>
</form>

5.2 data-mini

data-mini="true" 可以将表单控件切换为紧凑的小尺寸模式，适合在空间有限的工具栏中使用。

<form>
    <label for="search">搜索：</label>
    <input type="search" name="search" id="search" data-mini="true" placeholder="输入关键字">
</form>

5.3 data-clear-btn

data-clear-btn="true" 可以为文本输入框添加一键清空按钮。

<form>
    <label for="username">用户名：</label>
    <input type="text" name="username" id="username" data-clear-btn="true" placeholder="请输入用户名">
</form>

5.4 data-theme

data-theme 用于设置组件的主题色，jQuery Mobile 默认提供 a、b、c、d、e 五种主题。

<form>
    <label for="email">邮箱：</label>
    <input type="email" name="email" id="email" data-theme="b" placeholder="请输入邮箱地址">
</form>

6. 导航与对话框属性

页面导航和对话框是移动应用的重要组成部分，以下属性用于控制页面切换和弹窗行为。

6.1 data-transition

data-transition 用于设置页面切换时的过渡动画效果，可选值包括 slide、fade、pop、flip、turn 等。

<a href="#about" data-transition="slide">关于我们（滑动切换）</a>
<a href="#contact" data-transition="pop">联系我们（弹出切换）</a>
<a href="#home" data-transition="fade">返回首页（淡入淡出）</a>

6.2 data-rel

data-rel="dialog" 可以将目标页面以对话框的形式打开，data-rel="back" 则模拟浏览器后退行为。

<a href="#confirm" data-rel="dialog" data-transition="pop">打开确认对话框</a>
<a href="#" data-rel="back">返回上一页</a>

对应的对话框页面定义如下：

<div data-role="page" id="confirm">
    <div data-role="header">
        <h1>确认操作</h1>
    </div>
    <div data-role="content">
        <p>确定要删除这条记录吗？</p>
        <a href="#" data-role="button" data-rel="back">取消</a>
        <a href="#" data-role="button" data-theme="b">确定</a>
    </div>
</div>

6.3 data-ajax

data-ajax="false" 可以禁用链接的 AJAX 加载行为，强制浏览器进行整页刷新，适用于需要完整页面加载的场景。

<a href="full-page.html" data-ajax="false">整页加载</a>

7. 按钮与图标属性

按钮是用户触发操作的主要方式，jQuery Mobile 提供了灵活的按钮定制属性。

7.1 data-icon

data-icon 用于为按钮添加图标，框架内置了丰富的图标库。

<a href="#" data-role="button" data-icon="home">首页</a>
<a href="#" data-role="button" data-icon="search">搜索</a>
<a href="#" data-role="button" data-icon="delete">删除</a>
<a href="#" data-role="button" data-icon="plus">新增</a>

7.2 data-iconpos

data-iconpos 用于控制图标在按钮中的位置，可选值包括 left、right、top、bottom、notext。

<a href="#" data-role="button" data-icon="arrow-r" data-iconpos="right">下一步</a>
<a href="#" data-role="button" data-icon="gear" data-iconpos="notext">设置</a>

7.3 data-inline

data-inline="true" 可以将按钮设置为内联模式，多个按钮可以并排显示。

<a href="#" data-role="button" data-inline="true">确定</a>
<a href="#" data-role="button" data-inline="true">取消</a>

7.4 data-corners

data-corners="false" 可以去除按钮的圆角效果，使其变为直角样式。

<a href="#" data-role="button" data-corners="false">直角按钮</a>

8. 可折叠内容属性

可折叠内容块（Collapsible）是移动端节省空间的有效方式，jQuery Mobile 提供了简洁的属性配置。

8.1 data-collapsed

data-collapsed="true" 可以设置内容块默认处于折叠状态。

<div data-role="collapsible" data-collapsed="true">
    <h3>常见问题</h3>
    <p>这里是常见问题的详细解答内容。</p>
</div>

8.2 data-collapsed-icon 与 data-expanded-icon

这两个属性分别用于设置折叠和展开状态的图标。

<div data-role="collapsible" data-collapsed-icon="arrow-r" data-expanded-icon="arrow-d">
    <h3>产品详情</h3>
    <p>这里是产品详情介绍。</p>
</div>

8.3

标签

#jquery #前端 #javascript