jQuery数据操作参考手册

.data()存储与获取数据

.data()方法用于在匹配元素上存储或获取任意类型的数据。该方法设计的核心目标是提供一个安全、便捷的途径，将信息与特定的DOM节点关联起来，而无需使用可能导致内存泄漏或命名冲突的自定义属性。从jQuery 1.2.3版本引入后，它已成为管理元素相关状态的核心工具。在jQuery 1.4.3版本中，该方法的功能得到重要增强，开始自动获取并同步元素上data-*属性的值，这使得从HTML向JavaScript传递初始化数据变得极为简单。其基本行为表现为：当仅传入一个字符串参数时，返回该键名对应的已存储数据值；当传入一个键值对或一个包含多个键值对的对象时，则执行存储操作。jQuery数据手册中对此方法的详细阐述，是掌握元素级数据管理的关键。

参数详解与使用示例

.data()方法根据传入参数的不同，表现出不同的行为。理解这些参数组合，是灵活运用该方法的前提。

• 获取数据：$(selector).data(key) 或 $(selector).data()
  • key（可选）：一个字符串，指定要获取的数据键名。如果提供了key，则返回集合中第一个元素上与该键名关联的数据。如果集合为空，或元素上不存在该键名的数据，则返回undefined。
  • 如果不提供任何参数，则返回一个包含集合中第一个元素所有已存储数据的Object（对象）。这个对象包含了通过.data()设置的所有键值对，以及从data-*属性自动转换来的数据。
• 存储数据：$(selector).data(key, value) 或 $(selector).data(obj)
  • key：一个字符串，作为存储数据的键名。
  • value：要存储的任意JavaScript值（包括数组、对象、函数等）。此前版本的jQuery要求此值不能是undefined。
  • obj：一个包含多个键值对的普通对象，用于同时存储多项数据。

// 存储单个数据
$('#element').data('lastSelected', new Date());

// 存储多个数据
$('#element').data({
  status: 'active',
  config: { theme: 'dark', editable: true }
});

// 获取单个数据
var status = $('#element').data('status'); // 返回 'active'

// 获取所有数据
var allData = $('#element').data(); 
// allData 是一个对象，包含了 'lastSelected', 'status', 'config' 等所有项

// 利用 HTML5 data-* 属性
// <div id="user" data-user-id="12345" data-role="admin"></div>
var userId = $('#user').data('userId'); // 返回数字 12345 (自动类型转换)
var role = $('#user').data('role'); // 返回字符串 'admin'

关键行为与规范

在实际应用中，需要明确数据存储的生命周期以及它与HTML属性的区别。数据是直接存储在jQuery内部的一个缓存对象中，而非作为元素的属性存在，这避免了循环引用和潜在的内存泄漏。这种方法确保了数据与DOM节点的关联是干净且安全的。

1. 数据存储位置：通过.data()存储的数据并非直接写入DOM元素的attribute。它被保存在jQuery内部的一个缓存对象中，并由元素自身的一个唯一键值与之关联。这样做的好处是避免了在DOM上添加难以管理的自定义属性，并且可以存储任何JavaScript数据类型。
2. 与data-*属性的关系：这是一个核心特性。当使用.data()获取一个键，且在内部缓存中未找到时，jQuery会尝试查找元素上对应的data-*属性。如果找到，该属性的值会被自动转换（如字符串”true”、”false”、”123″、”123.45″、”null”会被转换为相应的布尔值、数字或null，而JSON格式的字符串如{"key":"value"}则会被解析为对象），并将其存入内部缓存。需要注意的是：这个同步过程是单向的。后续通过.data(key, value)修改数据，只会影响内部缓存，而不会更新DOM元素上的data-*属性。反之，使用.attr()或.prop()修改data-*属性，也不会自动更新通过.data()获取到的值，除非重新调用.data(key)触发同步。

.removeData()移除数据

.removeData()方法用于移除通过.data()在元素上存储的数据。与存储行为对应，移除数据同样作用于jQuery的内部缓存。在jQuery 1.4.3版本之后，当使用.removeData()移除某个键时，如果对应的data-*属性存在，之后再次尝试通过.data()获取该键的值时，会重新从data-*属性读取并同步。

参数详解与使用示例

.removeData()的参数指定了需要移除哪些数据项。

• $(selector).removeData(name)
  • name（可选）：一个字符串或数组，指定要移除的数据键名。
    • 如果传入的是字符串，则仅移除集合中每个元素上该键名对应的数据。
    • 如果传入的是包含多个键名的数组，例如['key1', 'key2']，则同时移除这些键名对应的数据。
    • 如果不传入任何参数，则移除集合中每个元素上的所有通过.data()存储的数据。注意：此操作不会影响从data-*属性自动同步过来的值，因为这些值只在首次获取时被缓存。

// 假设元素上已存储了 'status' 和 'config' 两项数据
$('#element').data('status', 'active');
$('#element').data('config', {theme: 'light'});

// 移除单个数据项 'status'
$('#element').removeData('status');
var status = $('#element').data('status'); 
// status 现在为 undefined，但 config 数据仍然存在

// 移除多个数据项
$('#element').removeData(['status', 'config']); 
// 此时该元素上已没有通过 .data() 存储的数据

// 结合 data-* 属性的行为
// <div id="panel" data-mode="editable"></div>
var mode = $('#panel').data('mode'); // 返回 'editable' (内部缓存并同步了 'mode': 'editable')
$('#panel').removeData('mode');       // 移除内部缓存中的 'mode'
var modeAfterRemove = $('#panel').data('mode'); 
// 由于内部缓存中已无 'mode'，jQuery 重新从 data-mode 属性读取，返回 'editable'

jQuery.data()低级接口

jQuery.data()是一个底层工具函数，用于直接操作与DOM元素关联的数据存储。与实例方法.data()不同，它是一个全局函数，更接近于数据存储系统的核心API。此方法主要用于特殊场景，例如在操作非由jQuery包装的DOM元素时。需要注意的是，在jQuery 1.4之前的版本中，此方法仅用于获取数据，而从1.4版本开始，其行为被扩展为通用性的获取/设置接口。

参数详解与使用示例

jQuery.data()的参数明确指定了操作的DOM元素、键名和值。

• 获取数据：jQuery.data(element, key)
  • element：一个DOM元素（非jQuery对象），用于从中获取数据。
  • key：一个字符串，指定要获取的数据键名。
  • 返回指定键名对应的值，如果元素上无此数据，则返回undefined。
• 存储数据：jQuery.data(element, key, value)
  • element：一个DOM元素，用于关联数据。
  • key：一个字符串，作为存储数据的键名。
  • value：要存储的任意JavaScript值。
• 获取所有数据：jQuery.data(element)
  • 如果不传入key，则返回一个包含该元素所有已存储数据的Object。

var element = document.getElementById('info');

// 使用底层接口存储数据
jQuery.data(element, 'timestamp', Date.now());

// 使用底层接口获取数据
var ts = jQuery.data(element, 'timestamp'); 

// 获取该元素上的所有数据
var allElementData = jQuery.data(element); 

// 对比实例方法 .data()，它也操作同一个内部缓存
var $info = $('#info');
var tsViaInstance = $info.data('timestamp'); // tsViaInstance 与 ts 的值相同

jQuery.hasData()存在性检测

jQuery.hasData()函数用于检测一个DOM元素是否关联有任何jQuery数据。这包括通过.data()或jQuery.data()存储的数据，也包括jQuery内部为元素管理的事件队列等数据。此方法在需要判断元素是否被jQuery内部机制（如事件监听）处理过时非常有用，例如在清理操作或插件开发中，用于避免意外移除正在使用的元素。

参数详解与使用示例

此方法只接受一个参数，并返回一个布尔值。

• jQuery.hasData(element)
  • element：要检查的DOM元素。
  • 返回值：如果元素上存在任何jQuery相关数据（包括事件、数据等），返回true；否则返回false。

var div = document.getElementById('container');

// 初始状态，尚未附加任何数据或事件
jQuery.hasData(div); // 返回 false

// 附加一个点击事件
$('#container').on('click', function() { console.log('clicked'); });
jQuery.hasData(div); // 返回 true (因为jQuery为元素存储了事件处理函数)

// 存储一条数据
$('#container').data('key', 'value');
jQuery.hasData(div); // 仍然返回 true

// 移除所有数据和事件 (需使用 .off() 和 .removeData())
$('#container').off().removeData();
jQuery.hasData(div); // 返回 false

数据操作的实践原则与版本演进总结

理解和运用jQuery的数据操作，关键在于把握其“缓存存储”和“与data-*属性单向同步”的核心设计。这套机制从1.x版本至今，核心接口保持稳定，为开发者提供了一个可靠的状态管理方案。下表汇总了本节涉及的主要方法及其演进，是jQuery数据手册中不可或缺的参考。

通过对.data()、.removeData()等方法的合理运用，可以在不污染DOM结构的前提下，高效地管理页面状态。从jQuery 1.4.3开始对HTML5 data-*属性的无缝支持，更是强化了其作为数据交互桥梁的角色。这份jQuery数据手册所涵盖的内容，为构建数据驱动、易于维护的交互界面奠定了坚实基础。

本文关键要点

本文作为jQuery数据手册的核心章节，系统阐述了在jQuery中管理元素级数据的方法体系。从用于日常数据读写的.data()与.removeData()实例方法，到底层操作的jQuery.data()工具函数，再到存在性检测的jQuery.hasData()，全面覆盖了数据操作的各种场景。理解这些方法与HTML5 data-*属性的协同机制以及版本演进细节，是有效利用jQuery进行状态管理的核心。