.prop()

分類： 屬性 | 操作 > 一般屬性
取得匹配元素集合中第一個元素的屬性值，或為每個匹配元素設定一個或多個屬性。

內容

.prop( propertyName )傳回： 任何東西

說明： 取得匹配元素集合中第一個元素的屬性值。

.prop() 方法僅取得相符集合中第一個元素的屬性值。如果屬性值尚未設定，或相符集合中沒有任何元素，則會傳回 undefined。若要個別取得每個元素的值，請使用迴圈結構，例如 jQuery 的 .each() 或 .map() 方法。

注意：嘗試變更透過 HTML 建立或已存在於 HTML 文件中的 input 元素的 type 屬性（或特徵）會導致 Internet Explorer 6、7 或 8 擲回錯誤。

特徵與屬性

在特定情況下，特徵和屬性之間的差異非常重要。在 jQuery 1.6 之前，.attr() 方法在擷取某些特徵時，有時會考量屬性值，這可能會導致行為不一致。從 jQuery 1.6 開始，.prop() 方法提供一種明確擷取屬性值的方法，而 .attr() 則擷取特徵。

例如，selectedIndex、tagName、nodeName、nodeType、ownerDocument、defaultChecked 和 defaultSelected 應使用 .prop() 方法來擷取和設定。在 jQuery 1.6 之前，這些屬性可以用 .attr() 方法來擷取，但這不屬於 attr 的範圍。這些屬性沒有對應的特徵，只有屬性。

關於布林特徵，請考慮由 HTML 標記 <input type="checkbox" checked="checked" /> 定義的 DOM 元素，並假設它在名為 elem 的 JavaScript 變數中

elem.checked true (布林) 會隨著核取方塊狀態而變更
$( elem ).prop( "checked" ) true (布林) 會隨著核取方塊狀態而變更
elem.getAttribute( "checked" ) "checked" (字串) 核取方塊的初始狀態；不會變更
$( elem ).attr( "checked" ) (1.6+) "checked" (字串) 核取方塊的初始狀態；不會變更
$( elem ).attr( "checked" ) (1.6 之前) true (布林值) 隨核取方塊狀態變更

根據 W3C 表單規範，checked 屬性是一個布林屬性，表示如果屬性存在，則對應的屬性為 true，即使屬性沒有值或設定為空字串值，甚至是「false」。所有布林屬性皆是如此。

不過，關於 checked 屬性最重要的觀念是，它並不對應於 checked 屬性。該屬性實際上對應於 defaultChecked 屬性，且只能用於設定核取方塊的初始值。checked 屬性值不會隨核取方塊的狀態變更，但 checked 屬性會。因此，判斷核取方塊是否已勾選的跨瀏覽器相容方式是使用屬性

  • if ( elem.checked )
  • if ( $( elem ).prop( "checked" ) )
  • if ( $( elem ).is( ":checked" ) )

其他動態屬性，例如 selected 和 value，也適用相同的原則。

其他注意事項

  • 在 Internet Explorer 9 之前的版本中，使用 .prop() 將 DOM 元素屬性設定為非單一基本值（數字、字串或布林值）可能會導致記憶體外洩，如果在從文件中移除 DOM 元素之前，未移除屬性（使用 .removeProp()）。若要在 DOM 物件上安全地設定值，且不產生記憶體外洩，請使用 .data()。

範例

顯示核取方塊的 checked 屬性和屬性，當它變更時。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
 
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>prop demo</title>
  <style>
  p {
    margin: 20px 0 0;
  }
  b {
    color: blue;
  }
  </style>
  <script src="https://code.jquery.com/jquery-3.7.0.js"></script>
</head>
<body>
 
<input id="check1" type="checkbox" checked="checked">
<label for="check1">Check me</label>
<p></p>
 
<script>
$( "input" ).on( "change", function() {
  var $input = $( this );
  $( "p" ).html(
    ".attr( \"checked\" ): <b>" + $input.attr( "checked" ) + "</b><br>" +
    ".prop( \"checked\" ): <b>" + $input.prop( "checked" ) + "</b><br>" +
    ".is( \":checked\" ): <b>" + $input.is( ":checked" ) + "</b>" );
} ).trigger( "change" );
</script>
 
</body>
</html>

示範

.prop( propertyName, value )傳回： jQuery

說明： 設定一組已配對元素的一個或多個屬性。

.prop() 方法是設定屬性值的一種便利方式，特別是在設定多個屬性、使用函式傳回的值，或一次設定多個元素的值時。應在設定 selectedIndex、tagName、nodeName、nodeType、ownerDocument、defaultChecked 或 defaultSelected 時使用。自 jQuery 1.6 起，這些屬性無法再使用 .attr() 方法設定。它們沒有對應的屬性，而且僅是屬性。

屬性通常會影響 DOM 元素的動態狀態，而不會變更序列化 HTML 屬性。範例包括輸入元素的 value 屬性、輸入和按鈕的 disabled 屬性，或核取方塊的 checked 屬性。應使用 .prop() 方法設定 disabled 和 checked，而不是 .attr() 方法。應使用 .val() 方法取得和設定值。

1
2
3
 
$( "input" ).prop( "disabled", false );
$( "input" ).prop( "checked", true );
$( "input" ).val( "someValue" );

重要：.removeProp() 方法不應使用於移除原生屬性。這將導致意外行為。更多資訊請參閱 .removeProp()。

計算屬性值

透過使用函式設定屬性，您可以根據元素的其他屬性來計算值。例如，根據個別值切換所有核取方塊

1
2
3
 
$( "input[type='checkbox']" ).prop( "checked", function( i, val ) {
  return !val;
});

注意：如果在 setter 函式中沒有傳回任何值（即 function( index, prop ){})），或傳回 undefined，則不會變更目前值。這對於僅在符合特定條件時有選擇地設定值很有用。

其他注意事項

  • 在 Internet Explorer 9 之前的版本中，使用 .prop() 將 DOM 元素屬性設定為非單一基本值（數字、字串或布林值）可能會導致記憶體外洩，如果在從文件中移除 DOM 元素之前，未移除屬性（使用 .removeProp()）。若要在 DOM 物件上安全地設定值，且不產生記憶體外洩，請使用 .data()。

範例

停用頁面上的所有核取方塊。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
 
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>prop demo</title>
  <style>
  img {
    padding: 10px;
  }
  div {
    color: red;
    font-size: 24px;
  }
  </style>
  <script src="https://code.jquery.com/jquery-3.7.0.js"></script>
</head>
<body>
 
  <input type="checkbox" checked="checked">
  <input type="checkbox">
  <input type="checkbox">
  <input type="checkbox" checked="checked">
 
<script>
$( "input[type='checkbox']" ).prop({
  disabled: true
});
</script>
 
</body>
</html>

示範