.data()| jqueryAPI 2.2 中文手册- AspRain.cn 致力于Web开发技术翻译整理

jQuery API 2.2.0

.data()

分类:数据 | 杂项 > 数据存储

返回: jQuery

.data( key, value )

描述:存储与匹配的元素相关的任意数据。

加入于: 1.2.3
.data( key, value )
  • key
    类型:String
    一个字符串,用来命名要设置的数据段。
  • value
    类型:Anything
    新的数据值;这可以是任何JavaScript类型,除了undefined
加入于: 1.4.3
.data( obj )
  • obj
    类型:Object
    一个用来更新数据的键值对对象。

.data()方法允许我们把任何数据类型附加到DOM元素上,不会循环引用,因此不会内存泄漏。

我们可以为一个元素设置若干个不同的值,然后在以后检索它们:

$( "body" ).data( "foo", 52 );
$( "body" ).data( "bar", { myType: "test", count: 40 } );
$( "body" ).data( { baz: [ 1, 2, 3 ] } );
$( "body" ).data( "foo" ); // 52
$( "body" ).data(); // { foo: 52, bar: { myType: "test", count: 40 }, baz: [ 1, 2, 3 ] }

在jQuery 1.4.3中,利用.data(obj)设置一个元素的数据对象,扩展了先前存储在元素上的数据。

在jQuery 1.4.3以前的版本中(从jQuery 1.4开始),.data()方法彻底代替了所有数据,而不是扩展数据对象。如果你正在使用第三方的插件,可能不建议你完全替代元素的数据对象,因为插件可能也设置了数据。

由于浏览器与插件和外部代码交互的方式,.data()方法不能用在<object>上(除非它是一个Flash插件),也不能用在<applet><embed;>元素上。

其它说明

  • 注意,这个方法目前不能为在XML document上设置数据提供一个跨平台的支持,因为Internet Explorer不允许通过自定义属性附加数据。
  • undefined不能被识别为一个数据值。调用诸如.code( "name", undefined )将返回调用它的jQuery对象,允许连缀。

示例

在一个DIV元素上存储一个值,然后检索它。

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>data demo</title>
  <style>
  div {
    color: blue;
  }
  span {
    color: red;
  }
  </style>
  <script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
 
<div>
  The values stored were
  <span></span>
  and
  <span></span>
</div>
 
<script>
$( "div" ).data( "test", { first: 16, last: "pizza!" } );
$( "span:first" ).text( $( "div" ).data( "test" ).first );
$( "span:last" ).text( $( "div" ).data( "test" ).last );
</script>
 
</body>
</html>

演示结果

返回: Object

.data( key, value )

描述:返回匹配的元素集合中第一个元素的某段已存储的命名数据值,通过.data( name, value )设置,或者通过HTML5元素属性data-*设置。

加入于: 1.2.3
.data( key )
  • key
    类型:String
    存储的数据的名称。
加入于: 1.4
.data()

该签名不接受任何参数。

.data()方法允许我们把任何类型的数据附加到DOM元素上,不会循环引用,因此不会内存泄漏。我们在同一时间里对一个元素可以检索几个不同的值,或者设置几个不同的值:

alert( $( "body" ).data( "foo" ) );
alert( $( "body" ).data() );

上面的行提醒了设置在body元素上的数据值。如果根本没有数据设置在那个元素上,将返回undefined

alert( $( "body" ).data( "foo" ) ); // undefined
$( "body" ).data( "bar", "foobar" );
alert( $( "body" ).data( "bar" ) ); // foobar

HTML5 data-*元素属性

自从jQuery 1.4.3,HTML 5的元素属性data-会自动推加到jQuery的数据对象上。带嵌入的破折号的元素属性的这种对待方式在jQuery 1.6中被改变了,以顺从W3C HTML5 规范文档

举个例子,给定以下HTML:

<div data-role="page" data-last-value="43" data-hidden="true" data-options='{"name":"John"}'></div>

所有下面的jQuery代码都能起作用:

$( "div" ).data( "role" ) === "page";
$( "div" ).data( "lastValue" ) === 43;
$( "div" ).data( "hidden" ) === true;
$( "div" ).data( "options" ).name === "John";

上面代码中的第二句正确地写到了元素的data-last-value元素属性上了。万一没有数据通过关键词存储,jQuery会在元素的元素属性中搜索,把驼峰大小写的字符串转换成一个破折号字符串,然后在结果中前插入data-。因此,字符串lastValue被转换成了data-last-value

会作各种尝试,以把字符串转换成一个JavaScript值(这包括了布尔值、数字、对象、数组和null)。一个值一定会转换成数字,如果这样做不会改变值的表达法。例如,“1E02”和“100.00”等同于数字(数量值为100),但是把它们转换成数字会更改它们的表达法,所以它们被留作字符串。字符串值“100”会被转换成数字100。

当data元素属性是一个对象时(以'{'开始)或者是一个数组时(以'['开始),则jQuery.parseJSON将用来解析这个字符串;它必须遵守有效的JSON句法。如果这个值不能解析为一个JavaScript值,它被留作一个字符串。

要想把元素属性的值检索为字符串,而不试图转换它,请使用attr()方法。

该data-元素属性在data属性第一次访问的时候推加进去,然后不再访问或者改变(所有的data值都存储在jQuery内部对象中)。

不带参数地调用.data()会检索所有的值,作是一个JavaScript对象。该对象可以安全地缓存在变量中,只要不用.data(obj)设置一个新对象。使用该对象直接读取或设置值比对.data()作单个调用来读取或设置每个值更快。

var mydata = $( "#mydiv" ).data();
if ( mydata.count < 9 ) {
  mydata.count = 43;
  mydata.status = "embiggened";
}

其它说明

  • 注意,对于在XML document上设置数据,这个方法目前并不提供跨平台支持,因为Internet Explorer不允许通过自定义属性附加数据。

示例

获得存储在一个元素上,名称为“blah”的数据。

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>data demo</title>
  <style>
  div {
    margin: 5px;
    background: yellow;
  }
  button {
    margin: 5px;
    font-size: 14px;
  }
  p {
    margin: 5px;
    color: blue;
  }
  span {
    color: red;
  }
  </style>
  <script src="https://code.jquery.com/jquery-1.10.2.js"></script>
</head>
<body>
 
<div>A div</div>
<button>Get "blah" from the div</button>
<button>Set "blah" to "hello"</button>
<button>Set "blah" to 86</button>
<button>Remove "blah" from the div</button>
<p>The "blah" value of this div is <span>?</span></p>
 
<script>
$( "button" ).click(function() {
  var value;
 
  switch ( $( "button" ).index( this ) ) {
    case 0 :
      value = $( "div" ).data( "blah" );
      break;
    case 1 :
      $( "div" ).data( "blah", "hello" );
      value = "Stored!";
      break;
    case 2 :
      $( "div" ).data( "blah", 86 );
      value = "Stored!";
      break;
    case 3 :
      $( "div" ).removeData( "blah" );
      value = "Removed!";
      break;
  }
 
  $( "span" ).text( "" + value );
});
</script>
 
</body>
</html>

演示结果

如果网页上不能运行示例,请点击http://www.asprain.cn/jQueryAPI/data1.htm查看示例。

如果你觉得本文档对你有用,欢迎给翻译作者支付宝打赏,支持翻译作者源源不断翻译更多有用的技术文档。