مكوّنات طريقة التنفيذ - مربّع اختيار طريقة التنفيذ

إيوا غاسبيرويكز

روب دودسون

سوما

ملخّص

تمثّل السمة <howto-checkbox> خيارًا منطقيًا في نموذج. النوع الأكثر شيوعًا من مربعات الاختيار هو النوع المزدوج الذي يسمح للمستخدم بالتبديل بين خيارين: التحديد وغير المحدد.

يحاول العنصر أن يطبّق السمتَين role="checkbox" وtabindex="0" ذاتيًا عند إنشائه لأول مرة. تساعد السمة role التكنولوجيا المساعِدة، مثل قارئ الشاشة في تحديد نوع التحكّم. تفعِّل السمة tabindex العنصر في ترتيب التنقل بـ Tab، ما يجعله قابلاً للتركيز والتشغيل من خلال لوحة المفاتيح. للمزيد من المعلومات حول هذين الموضوعَين، يمكنك الاطّلاع على القسم ما الذي يمكن أن يفعله ARIA؟ وباستخدام tabindex.

عند وضع علامة في مربّع الاختيار، تتم إضافة سمة منطقية checked وضبط سمة checked مقابلة على true. بالإضافة إلى ذلك، يضبط العنصر السمة aria-checked إما على "true" أو "false"، حسب حالتها. يؤدي النقر على مربع الاختيار باستخدام الماوس أو مفتاح المسافة إلى تبديل الحالات المحددة هذه.

يدعم مربّع الاختيار أيضًا حالة disabled. في حال ضبط السمة disabled على "صحيح" أو تطبيق السمة disabled، يتم ضبط السمة aria-disabled="true" على مربّع الاختيار وإزالة السمة tabindex وإعادة التركيز على المستند إذا كان مربّع الاختيار هو activeElement الحالي.

يتم إقران مربّع الاختيار بعنصر howto-label للتأكّد من أنّه يتضمّن اسمًا يسهل الوصول إليه.

تحذير: لا يعني مجرّد إنشاء مربّع اختيار عنصر مخصّص أنّه عليك إجراء ذلك. كما هو موضح في هذا المثال، ستحتاج إلى إضافة لوحة المفاتيح الخاصة بك، والتصنيفات، ودعم ARIA. من المهم أيضًا ملاحظة أنّ عنصر <form> الأصلي لن يرسل قيمًا من عنصر مخصّص. عليك توصيله بنفسك باستخدام AJAX أو حقل <input> مخفي. لهذه الأسباب، قد يكون من الأفضل في كثير من الأحيان استخدام <input type="checkbox"> المدمَجة بدلاً من ذلك.

مَراجع

• طريقة التنفيذ: المكوّنات على GitHub
• نمط مربّع الاختيار في الإصدار 1.1 من ممارسات تأليف ARIA
• ما هي مهام ARIA؟
• استخدام فهرس Tab

تجريبي

مشاهدة العرض التوضيحي المباشر على GitHub

مثال للاستخدام

<style>
  howto-checkbox {
    vertical-align: middle;
  }
  howto-label {
    vertical-align: middle;
    display: inline-block;
    font-weight: bold;
    font-family: sans-serif;
    font-size: 20px;
    margin-left: 8px;
  }
</style>

<howto-checkbox id="join-checkbox"></howto-checkbox>
<howto-label for="join-checkbox">Join Newsletter</howto-label>

الرمز

(function() {

يمكنك تحديد رموز المفاتيح للمساعدة في التعامل مع أحداث لوحة المفاتيح.

  const KEYCODE = {
    SPACE: 32,
  };

إنّ استنساخ المحتوى من عنصر <template> أكثر فعالية من استخدام innerHTML لأنّه يتجنّب التكاليف الإضافية لتحليل HTML.

  const template = document.createElement('template');

  template.innerHTML = `
    <style>
      :host {
        display: inline-block;
        background: url('../images/unchecked-checkbox.svg') no-repeat;
        background-size: contain;
        width: 24px;
        height: 24px;
      }
      :host([hidden]) {
        display: none;
      }
      :host([checked]) {
        background: url('../images/checked-checkbox.svg') no-repeat;
        background-size: contain;
      }
      :host([disabled]) {
        background:
          url('../images/unchecked-checkbox-disabled.svg') no-repeat;
        background-size: contain;
      }
      :host([checked][disabled]) {
        background:
          url('../images/checked-checkbox-disabled.svg') no-repeat;
        background-size: contain;
      }
    </style>
  `;


  class HowToCheckbox extends HTMLElement {
    static get observedAttributes() {
      return ['checked', 'disabled'];
    }

يتم تشغيل الدالة الإنشائية للعنصر في أي وقت يتم فيه إنشاء مثيل جديد. يتم إنشاء المثيلات إما عن طريق تحليل HTML، أو استدعاء document.createElement('howto-checkbox')، أو استدعاء HowToCheckbox() جديد؛ وتُعد الدالة الإنشائية مكانًا جيدًا لإنشاء shadow DOM، على الرغم من أنّه يجب تجنّب لمس أي سمات أو عناصر فرعية لـ light DOM لأنها قد لا تكون متاحة بعد.

    constructor() {
      super();
      this.attachShadow({mode: 'open'});
      this.shadowRoot.appendChild(template.content.cloneNode(true));
    }

يتم تنشيط connectedCallback() عند إدراج العنصر في DOM. ويفضَّل ضبط الإعدادات الأولية role وtabindex والحالة الداخلية وتثبيت أدوات معالجة الأحداث.

    connectedCallback() {
      if (!this.hasAttribute('role'))
        this.setAttribute('role', 'checkbox');
      if (!this.hasAttribute('tabindex'))
        this.setAttribute('tabindex', 0);

قد يقوم المستخدم بتعيين خاصية على مثيل عنصر ما، قبل ربط نموذجه الأولي بهذه الفئة. ستتحقّق الطريقة _upgradeProperty() من أيّ خصائص للمثيل وتجريها من خلال أدوات ضبط الفئة المناسبة. لمزيد من التفاصيل، يمكنك الاطّلاع على قسم المواقع الإلكترونية الكسولة.

      this._upgradeProperty('checked');
      this._upgradeProperty('disabled');

      this.addEventListener('keyup', this._onKeyUp);
      this.addEventListener('click', this._onClick);
    }

    _upgradeProperty(prop) {
      if (this.hasOwnProperty(prop)) {
        let value = this[prop];
        delete this[prop];
        this[prop] = value;
      }
    }

يتم تنشيط disconnectedCallback() عند إزالة العنصر من DOM. يُعدّ هذا الخيار وسيلة جيدة للقيام بأعمال تنظيم مثل إصدار المراجع وإزالة أدوات معالجة الأحداث.

    disconnectedCallback() {
      this.removeEventListener('keyup', this._onKeyUp);
      this.removeEventListener('click', this._onClick);
    }

يجب أن تتطابق الخصائص والسمات المقابلة لها مع بعضها. تتعامل سمة تعيين السمة المحددة مع القيم الصادقة/الزائفة وتعكس هذه القيم إلى حالة السمة. راجِع قسم تجنُّب إعادة الانضمام للحصول على مزيد من التفاصيل.

    set checked(value) {
      const isChecked = Boolean(value);
      if (isChecked)
        this.setAttribute('checked', '');
      else
        this.removeAttribute('checked');
    }

    get checked() {
      return this.hasAttribute('checked');
    }

    set disabled(value) {
      const isDisabled = Boolean(value);
      if (isDisabled)
        this.setAttribute('disabled', '');
      else
        this.removeAttribute('disabled');
    }

    get disabled() {
      return this.hasAttribute('disabled');
    }

يتم استدعاء attributeChangedCallback() عندما يتم تغيير أي من السمات في مصفوفة لعبة ExploreAttributes. ويُعدّ هذا الملف مكانًا جيدًا للتعامل مع الآثار الجانبية، مثل ضبط سمات ARIA.

    attributeChangedCallback(name, oldValue, newValue) {
      const hasValue = newValue !== null;
      switch (name) {
        case 'checked':
          this.setAttribute('aria-checked', hasValue);
          break;
        case 'disabled':
          this.setAttribute('aria-disabled', hasValue);

لا توفّر السمة tabindex طريقة لإزالة إمكانية التركيز بالكامل من عنصر. سيظلّ بإمكانك التركيز على العناصر التي تتضمّن tabindex=-1 باستخدام الماوس أو من خلال طلب الرقم focus(). للتأكّد من إيقاف عنصر وعدم إمكانية التركيز عليه، أزِل السمة tabindex.

          if (hasValue) {
            this.removeAttribute('tabindex');

إذا كان التركيز حاليًا على هذا العنصر، يمكنك إلغاء التركيز عليه من خلال استدعاء طريقة HTMLElement.blur().

            this.blur();
          } else {
            this.setAttribute('tabindex', '0');
          }
          break;
      }
    }

    _onKeyUp(event) {

لا تتعامل مع اختصارات التعديل التي تستخدمها عادةً التكنولوجيا المساعدة.

      if (event.altKey)
        return;

      switch (event.keyCode) {
        case KEYCODE.SPACE:
          event.preventDefault();
          this._toggleChecked();
          break;

ويتم تجاهل أي ضغطة أخرى على المفاتيح وتمريرها مرة أخرى إلى المتصفّح.

        default:
          return;
      }
    }

    _onClick(event) {
      this._toggleChecked();
    }

يستدعي _toggleChecked() أداة الضبط التي تم وضع علامة عليها ويقلب حالتها. بما أنّ _toggleChecked() لا يحدث إلا بسبب إجراء من جانب المستخدم، سيتم أيضًا إرسال حدث تغيير. يظهر هذا الحدث كفقاعات لمحاكاة سلوك <input type=checkbox> الأصلي.

    _toggleChecked() {
      if (this.disabled)
        return;
      this.checked = !this.checked;
      this.dispatchEvent(new CustomEvent('change', {
        detail: {
          checked: this.checked,
        },
        bubbles: true,
      }));
    }
  }

  customElements.define('howto-checkbox', HowToCheckbox);
})();