.data() | jQuery API 文件

儲存與已配對元素相關的任意資料，或傳回已配對元素集合中第一個元素的命名資料儲存中的值。

內容

.data( key, value )
- .data( key, value )
- .data( obj )
.data( key )
- .data( key )
- .data()

.data( key, value )傳回：jQuery

說明：儲存與已配對元素相關的任意資料。

新增版本：1.2.3.data( key, value )
- key
  
  類型：字串
  
  命名要設定的資料片段的字串。
- value
  
  類型：任何
  
  新的資料值；這可以是任何 JavaScript 類型，但不可為 undefined。
新增版本：1.4.3.data( obj )
- obj
  
  類型：物件
  
  一個用於更新資料的鍵值對物件。

.data() 方法允許我們將任何類型的資料附加到 DOM 元素，這種方式可以避免循環參照，因此可以避免記憶體外洩。

我們可以為單一元素設定多個不同的值，並在稍後擷取這些值。

	
					$( "body" ).data( "foo", 52 );
$( "body" ).data( "bar", { isManual: true } );
$( "body" ).data( { baz: [ 1, 2, 3 ] } );
$( "body" ).data( "foo" ); // 52
$( "body" ).data(); // { foo: 52, bar: { isManual: true }, baz: [ 1, 2, 3 ] }

使用 data() 方法來更新資料不會影響 DOM 中的屬性。若要設定 data-* 屬性值，請使用 attr。

在 jQuery 1.4.3 之前，.data( obj ) 會完全取代所有資料。自 jQuery 1.4.3 之後，資料會改為透過淺層合併來擴充。

自 jQuery 3 起，每個由連字符號「-」（U+002D）後接小寫 ASCII 字母組成的兩個字元序列，在鍵值中會被替換為該字母的大寫版本，這與 HTML 資料集 API 保持一致。像 $( "body" ).data( { "my-name": "aValue" } ).data(); 這樣的陳述式會傳回 { myName: "aValue" }。

由於瀏覽器與外掛程式和外部程式碼互動的方式，.data() 方法無法用於 <object>（除非它是 Flash 外掛程式）、<applet> 或 <embed> 元素。

其他注意事項

請注意，此方法目前不支援跨平台設定 XML 文件的資料，因為 Internet Explorer 不允許透過擴充屬性附加資料。
undefined 不會被辨識為資料值。像 .data( "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-3.7.0.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>

				
			

	

示範

.data( key )傳回值： Object

說明：傳回與 jQuery 集合中第一個元素相關的任意資料，由 data() 或 HTML5 data-* 屬性設定。

新增版本：1.2.3.data( key )
- key
  
  類型：字串
  
  儲存資料的名稱。
新增版本：1.4.data()
- 此簽章不接受任何引數。

.data() 方法讓我們可以讀取先前與 DOM 元素相關聯的資料。我們可以一次或一次設定取得單一元素的幾個不同值。

	
					var elem = document.createElement( "span" );
$( elem ).data( "foo" ); // undefined
$( elem ).data(); // {}
 
$( elem ).data( "foo", 42 );
$( elem ).data( "foo" ); // 42
$( elem ).data(); // { foo: 42 }

呼叫不帶任何參數的 .data() 會傳回一個 JavaScript 物件，其中包含每個儲存值作為一個屬性。此物件可以用於直接取得資料值（但請注意，原本包含破折號的屬性名稱會經過修改，如下所述）。

HTML5 `data-*` 屬性

自 jQuery 1.4.3 起，data-* 屬性用於初始化 jQuery 資料。元素的 data-* 屬性會在第一次對其呼叫 data() 方法時擷取，然後不再存取或變更（所有值都由 jQuery 內部儲存）。

會盡力將屬性的字串值轉換為 JavaScript 值（包括布林值、數字、物件、陣列和 null）。只有在轉換不會變更其表示時，字串才會轉換為數字（例如，字串「100」會轉換為數字 100，但「1E02」和「100.000」會保留為字串，因為它們的數字值 100 會序列化為「100」）。當字串以「{」或「[」開頭時，會使用 jQuery.parseJSON 來剖析它；它必須遵循有效的 JSON 語法，包括引號屬性名稱。無法剖析為 JavaScript 值的字串不會轉換。

若要以未轉換字串的形式擷取 data-* 屬性值，請使用 attr() 方法。

自 jQuery 1.6 起，data-* 屬性名稱中的破折號已依據 HTML 資料集 API 進行處理。

例如，假設有以下 HTML

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

以下比較全部為真

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

其他注意事項

請注意，此方法目前不支援跨平台設定 XML 文件的資料，因為 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-3.7.0.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" ).on( "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>

				
			

	

jQuery API 文件

內容

.data( key, value )傳回：jQuery

新增版本：1.2.3.data( key, value )

新增版本：1.4.3.data( obj )

其他注意事項

示範

.data( key )傳回值： Object

新增版本：1.2.3.data( key )

新增版本：1.4.data()

HTML5 data-* 屬性

其他注意事項

示範

HTML5 `data-*` 屬性