عرض مصدر HTML/input/checkbox

<noinclude>{{DISPLAYTITLE:الحقل <code>checkbox</code>}}</noinclude>
عناصر <code>[[HTML/input|<input>]]</code> ذات النوع <code>checkbox</code> تُعرَض افتراضيًا كصناديق مربعة يمكن التأشير عليها لتفعيله، كالتي قد تراها في بعض الأوراق الحكومية. فهي تسمح لك باختيار قيم لإرسالها مع النموذج.

أزرار الانتقاء ([[HTML/input/radio|radio buttons]]) تشبه صناديق التأشير (checkboxes) لكن هنالك فرق مهم بينهما، فأزرار الانتقاء تستخدم لاختيار قيمة من مجموعة قيم، بينما صناديق التأشير تسمح لك بتفعيل أو تعطيل القيم. فلو كانت هنالك عدِّة خيارات، فتسمح أزرار الانتقاء باختيار قيمة منها، بينما صناديق التأشير تسمح بتحديد عدِّة قيم.<syntaxhighlight lang="html">
<label for="checkbox">صندوق تأشير</label>
<input type="checkbox" name="checkbox" id="checkbox">

</syntaxhighlight>

== الخاصية <code>value</code> ==
تحتوي الخاصية <code>value</code> على سلسلة نصية (<code>DOMString</code>)، وهذه القيمة لا تظهر للمستخدم وإنما ستُرسَل إلى الخادوم مرتبطةً مع اسم صندوق التأشير (الخاصية <code>name</code>):<syntaxhighlight lang="html">
<form>
  <div>
    <input type="checkbox" id="subscribeNews" name="subscribe" value="newsletter">
    <label for="subscribeNews">الاشتراك في قائمة الأخبار</label>
  </div>
  <div>
    <button type="submit">اشترك</button>
  </div>
</form>
</syntaxhighlight>صندوق التأشير في المثال السابق له الاسم <code>subscribe</code> والقيمة <code>newsletter</code>، واللتان سترسلان إلى الخادوم عند إرسال النموذج على الشكل <code>subscribe=newsletter</code>.

إذا لم تُحدَّد قيمة للخاصية <code>value</code> فستُعطى القيمة الافتراضية <code>on</code>، أي ستكون البيانات التي ستُرسَل إلى النموذج على الشكل <code>subscribe=on</code>.

إذا كان صندوق التأشير غير مُفعّل عند إرسال النموذج، فلن تُرسَل أيّة قيمة إلى الخادوم لتقول أنَّ الصندوق غير مُفعّل.
== استخدام صناديق التأشير ==
شرحنا الاستعمال الأساسي لصناديق التأشير أعلاه، لكن دعنا نلقي نظرة على الميزات والتقنيات الشائعة والتي تستخدم مع صناديق التأشير.

=== التعامل مع أكثر من صندوق تأشير ===
رأينا في المثال السابق صندوق تأشير وحيد، لكن من الشائع في النماذج العملية أن يكون هنالك عدِّة صناديق تأشير.

إذا كانت صناديق التأشير غير متعلقة ببعضها، فيمكنك التعامل معها بسهولة كما بيّنا أعلاه، لكن إن كانت متعلقة مع بعضها فالأمر يحتاج إلى تفصيل...

سنضع في المثال الآتي عدِّة صناديق تأشير للسماح للمستخدم باختيار ما هي الأمور التي يهتم بها:<syntaxhighlight lang="html">
<fieldset>
  <legend>اختر هواياتك</legend>
  <div>
    <input type="checkbox" id="coding" name="interest" value="coding">
    <label for="coding">البرمجة</label>
  </div>
  <div>
    <input type="checkbox" id="cooking" name="interest" value="cooking">
    <label for="cooking">الطبخ</label>
  </div>
</fieldset>
</syntaxhighlight>أعطينا -في الشيفرة السابقة- صناديق التأشير نفس القيمة للخاصية <code>name</code>، فلو كان الصندوقان مفعلين عند إرسال النموذج فستكون القيمة المُرسَلة إلى الخادوم على الشكل <code>interest=coding&interest=cooking</code>، وعندما تصل هذه البيانات إلى الخادوم فعليك الحصول عليها على شكل مصفوفة من القيم المرتبطة ببعضها والتعامل معها وفق ذلك.
=== تفعيل صناديق التأشير افتراضيًا ===
لجعل أحد صناديق التأشير مُفعّلًا افتراضيًا، فاستخدم الخاصية <code>checked</code> عليه، كما في المثال الآتي:<syntaxhighlight lang="html">
<fieldset>
  <legend>اختر هواياتك</legend>
  <div>
    <input type="checkbox" id="coding" name="interest" value="coding" checked>
    <label for="coding">البرمجة</label>
  </div>
  <div>
    <input type="checkbox" id="cooking" name="interest" value="cooking">
    <label for="cooking">الطبخ</label>
  </div>
</fieldset>
</syntaxhighlight>
=== توفير منطقة أكبر لتسهيل الضغط على صندوق التأشير ===
ربما لاحظتَ في الأمثلة السابقة أنَّ بإمكانك تفعيل صندوق التأشير بالضغط على عنصر <code>[[HTML/label|<label>]]</code> المرتبط به أو على صندوق التأشير نفسه، وهذه الميزة مفيدة جدًا إذ تجعل من السهل الضغط على الخيار الذي تريده، خصوصًا في الأجهزة ذات الشاشات الصغيرة مثل الهواتف المحمولة.

=== صناديق التأشير ذات الحالة غير المعروفة ===
هنالك حالة غير معروفة (indeterminate) لصناديق التأشير، التي يمكن ضبطها عبر الخاصية <code>indeterminate</code> على الكائن <code>HTMLInputElement</code> في JavaScript (لا يمكن ضبط هذه القيمة في HTML مباشرةً):<syntaxhighlight lang="javascript">
inputInstance.indeterminate = true;

</syntaxhighlight>الحالة غير المعروفة لصناديق التأشير تُعرَض عادةً على شكل خط أفقي في أغلبية المتصفحات بدلًا من إشارة «صح».

لا توجد هنالك حالات استخدام كثيرة لهذه الخاصيةـ لكن المثال التالي سيبيّن إحداها. حيث يتتبع هذا المثال مكوِّنات إحدى الوصفات التي تحاول جمعها، ويمكنك التأشير على صناديق التأشير للمكونات، وستتحقق دالة JavaScript من العدد الكلي للمكونات التي حصلتَ عليها:
* إذا لم يتم التأشير على أيّ مكوِّن، فسيترك صندوق التأشير المرتبط باسم الوصفة غير مؤشر.
* إذا تم التأشير على مكوِّن واحد أو مكوِّنين، فسيُضبَط صندوق التأشير المرتبط باسم الوصفة إلى <code>indeterminate</code>.
* إذا تم التأشير على المكونات كلها، فسيُضبَط صندوق التأشير المرتبط باسم الوصفة إلى <code>checked</code>.
أي أنَّ الحالة <code>indeterminate</code> تعني أنَّنا بدأنا بجمع مكوِّنات الوصفة لكنها لم تكتمل بعد:<syntaxhighlight lang="html">
<fieldset>
  <legend>أكمل الوصفة</legend>
    <div>
    <input type="checkbox" id="pizza" name="pizza">
    <label for="pizza">بيتزا</label>
    <ul>
      <li>
        <input type="checkbox" id="tomato" name="ingredient" value="tomato">
        <label for="tomato">بندورة (طماطم)</label>
      </li>
      <li>
        <input type="checkbox" id="cheese" name="ingredient" value="cheese">
        <label for="cheese">جبنة</label>
      </li>
      <li>
        <input type="checkbox" id="dough" name="ingredient" value="dough">
        <label for="dough">عجينة</label>
      </li>
    </ul>
    </div>
</fieldset>
</syntaxhighlight>شيفرة JavaScript:<syntaxhighlight lang="javascript">
// تحديد العنصر الرئيسي
var overall = document.querySelector('input[id="pizza"]');
// تحديد جميع حقول الإدخال
var ingredients = document.querySelectorAll('ul input');

// منع إجراء أيّة عمليات عند النقر على العنصر الرئيسي
overall.addEventListener('click', function(e) {
  e.preventDefault();
});

// معالجة النقرات التي تحدث على مكوِّنات الوصفة
for(var i = 0; i < ingredients.length; i++) {
  ingredients[i].addEventListener('click', updateDisplay);
}

// الدالة التي ستستدعى عند النقر على مكوانات الوصفة
// تنظر هذه الدالة إلى عدد العناصر المختارة
// إذا كانت كلها مختارة فسيصبح العنصر الرئيسي مختارًا

// إذا كان بعضها مختارًا وبعضها لم ينقر عليه المستخدم بعد، فستكون
// حالة العنصر الرئيسي غير معروفة 
function updateDisplay() {
  var checkedCount = 1;
  for(var i = 0; i < ingredients.length; i++) {
    if(ingredients[i].checked) {
      checkedCount++;
    }
  }

  if(checkedCount === ingredients.length + 1) {
    overall.checked = true;
    overall.indeterminate = false;
  } else if(checkedCount <= ingredients.length + 1 && checkedCount > 1) {
    overall.checked = false;
    overall.indeterminate = true;
  } else {
    overall.checked = false;
    overall.indeterminate = false;
  }
}
</syntaxhighlight>لاحظ أنَّك إذا أرسلتَ نموذجًا فيه صندوق تأشير حالته غير معروفة فسيُعامل كانه غير مُفعّل، أي لن تُرسَل أيّة بيانات إلى الخادوم لتمثيله.

== التحقق من الحقل ==
تدعم صناديق التأشير التحقق من الحقل (validation)، لكن أغلبية حالات <code>ValidyState</code> ستكون <code>false</code>.

إذا كان لصندوق التأشير الخاصية <code>required</code> لكنه ليس مفعّلًا فستكون قيمة <code>ValidityState.valueMissing</code> مساويةً إلى <code>true</code>.
== دعم المتصفحات ==
{| class="wikitable" style="width: 50%;"
 !| Chrome
 ! Firefox
 ! Edge
 ! Safari
 ! Opera
|-
|مدعوم
|مدعوم
|مدعوم
|مدعوم
|مدعوم
|}
[[تصنيف:HTML|{{SUBPAGENAME}}]]
[[تصنيف:HTML Forms|{{SUBPAGENAME}}]]
[[تصنيف:HTML Input Types|{{SUBPAGENAME}}]]