HOWTO · jQuery

用 jQuery 檢查核取方塊是否被選中

在本教程中學習 jQuery 檢查核取方塊是否被選中的所有很酷的方法。我們展示了使用直接 DOM 操作、提取 JavaScript 屬性的 jQuery 方法以及使用 jQuery 選擇器的不同方法。你還將找到許多有用的快捷方式和用於常見用例的現成指令碼。

本頁內容

若要使用 jQuery 檢查核取方塊目前的狀態,請讀取其 DOM checked 屬性。可用 .prop('checked') 直接取得值、用 .is(':checked') 依選擇器測試,或透過 .get(0).checked(或 [0].checked)存取選取到的 DOM 節點。HTML 的 checked 屬性表示核取方塊的初始狀態,不會追蹤使用者之後的變更。(.get())

使用直接 DOM 存取檢查核取方塊是否已勾選

jQuery 選取結果是符合條件的元素集合。.get(0) 會傳回底層 DOM 元素中的第一個,其 checked 屬性是表示目前狀態的布林值。陣列式的 [0] 存取方式也相同。只有在選取結果包含你要檢查的核取方塊時,才使用其中一種方式。

執行這個範例:

本節中的程式碼以及顯示的標籤或輸出仍為英文。

const checkbox = { checked: true };
console.log(checkbox.checked ? "Checked" : "Not checked");

範例輸出中的標籤是英文「Checked」;程式碼與輸出區塊維持原樣。

Checked

在已載入 jQuery 的頁面中,等效的檢查方式是 $("#terms").get(0).checked。接下來的瀏覽器原始碼以核取方塊和按鈕示範這種寫法;這裡提供的是頁面原始碼,不是執行時輸出。

<!doctype html>
<html lang="en">
<body>
  <label><input id="terms" type="checkbox"> Accept the terms</label>
  <button id="check" type="button">Check state</button>
  <p id="result" aria-live="polite"></p>

  <script src="https://code.jquery.com/jquery-3.7.1.min.js"></script>
  <script>
    $("#check").on("click", function () {
      const isChecked = $("#terms").get(0).checked;
      $("#result").text(isChecked ? "The box is checked." : "The box is not checked.");
    });
  </script>
</body>
</html>

如果選取結果可能包含多個元素,.get(0) 仍只會傳回第一個符合項目。若沒有符合項目,索引 0 就沒有核取方塊可供讀取。若要檢查每個符合項目,可以逐一走訪集合,或使用 .is(':checked') 測試是否有任一項符合。

使用 .prop() 檢查核取方塊是否已勾選

使用 .prop('checked') 讀取所選元素目前的勾選狀態:

$("#terms").prop("checked")

對單一核取方塊而言,勾選時這個 getter 會傳回 true,未勾選時則傳回 false。jQuery 集合可能包含多個元素;getter 會讀取第一個符合項目的屬性。若結果必須代表特定控制項,請明確選取該核取方塊。

setter 形式會變更即時狀態:$("#terms").prop("checked", true) 會勾選它,傳入 false 則會取消勾選。要查詢目前狀態時使用 getter;要變更狀態時使用 setter。同樣的屬性存取方式也適用於其他即時控制項屬性,例如按鈕的 disabled。 jQuery .prop() 文件說明了這種屬性存取方式。

使用 .is() 與 :checked 檢查核取方塊是否已勾選

:checked 選擇器會符合已勾選的核取方塊與單選按鈕;請參閱 jQuery 選擇器文件。.is(':checked') 會傳回布林值,指出所選 jQuery 集合中是否至少有一個元素符合該選擇器。詳見 .is() 文件:

$("#terms").is(":checked")

如果要判斷所選的核取方塊是否已勾選,這種寫法一目了然。例如,若名稱為 choice 的群組中有任一核取方塊已勾選,$("input[name='choice']").is(":checked") 就會是 true。另一方面,選擇器 $("input:checked") 會建立一個包含所有已勾選輸入項目的 jQuery 集合,本身不會傳回布林值。

依 ID 選取時,屬性值中不要加井字號:請使用 $("#terms") 或 $("input[id='terms']"),不要使用 $("input[id='#terms']")。# 屬於 ID 選擇器語法,不是元素 id 屬性值的一部分。

使用 jQuery 處理核取方塊的常見情境

以下模式會讀取目前的 checked 屬性,可依自己的 ID、類別與表單結構調整。

依 ID 或類別選取

若要檢查一個已知的核取方塊,可使用 ID:$("#terms").prop("checked")。若一組核取方塊共用同一個類別,可逐一走訪符合項目並查看各控制項的狀態:

例如,$(".option").each(function () { console.log(this.id + ": " + (this.checked ? "checked" : "not checked")); }); 會走訪每個符合項目。在頁面中,請確認這個類別套用在核取方塊輸入項目上,且程式碼是在這些輸入項目存在後才執行。在 .each() 內,this 是目前的 DOM 元素,因此它的 checked 屬性代表該核取方塊的狀態。

僅在已勾選時取消勾選

setter 可以直接取消控制項的勾選;如果目的只是確保它未勾選,就不必先檢查:

$("#terms").prop("checked", false)

如果只有在核取方塊原本已勾選時才要執行其他動作,請先用 if ($("#terms").is(":checked")) { ... } 檢查,再將它的屬性設為 false。

檢查集合中的項目是否全部或任一已勾選

對一組核取方塊而言,.is(':checked') 可判斷是否有任一符合項目已勾選。若要確認全部項目都已勾選,請比較已勾選項目的數量與群組核取方塊總數:

例如,const $options = $("input.option[type='checkbox']"); const allChecked = $options.length > 0 && $options.filter(":checked").length === $options.length; const anyChecked = $options.is(":checked"); 會計算這兩種結果。

length > 0 條件會讓選擇器未找到任何核取方塊時,「全部已勾選」仍為 false;對表單群組而言,這通常是較實用的解讀。只有在應用程式明確需要時,才採用其他空集合處理方式。

根據核取方塊狀態啟用提交按鈕

核取方塊變更時就更新按鈕,不要等到使用者按下可能已停用的按鈕才處理:

例如,定義 const update = () => $("#submit").prop("disabled", !$("#terms").is(":checked"));,用 $("#terms").on("change", update) 綁定,並在綁定後呼叫一次 update()。這會在頁面載入時套用初始狀態,並在使用者切換核取方塊時讓按鈕保持同步。請將 #submit 換成表單中實際的提交控制項。

HTML 的 checked 屬性會在頁面初始化時設定核取方塊的預設勾選狀態。即時 DOM checked 屬性則反映使用者互動或程式變更後的目前狀態。.attr('checked') 讀取的是屬性;若要取得目前狀態,請使用 .prop('checked') 或 .is(':checked')。因此,對核取方塊而言,.attr() 與 .prop() 回答的是不同問題。