أفضل الممارسات المتعلقة بالعناصر المخصّصة

تتيح لك العناصر المخصصة إنشاء علامات HTML الخاصة بك. تتناول قائمة التحقق هذه أفضل الممارسات لمساعدتك في إنشاء عناصر عالية الجودة.

تتيح لك العناصر المخصصة توسيع HTML وتحديد العلامات الخاصة بك. إنها ميزات قوية للغاية، لكنها أيضًا منخفضة المستوى، مما يعني أنها توضح دائمًا أفضل السبل لتنفيذ العنصر الخاص بك.

ولمساعدتك على تكوين أفضل التجارب الممكنة، جمعنا هذا قائمة التحقق. فهو يحلل كل الأشياء التي نعتقد أنها مطلوبة عنصر مخصص ذي سلوك جيد.

قائمة التحقق

نموذج Shadow DOM

السمات والخصائص

فعاليات

تفسيرات

عدم تجاوز مؤلف الصفحة

من المحتمل أن يرغب مطوّر البرامج الذي يستخدم العنصر في إلغاء بعض حالتها الأولية. على سبيل المثال، تغيير ARIA role أو إمكانية التركيز باستخدام tabindex تحقق لتتحقق مما إذا كانت هذه السمات وأي سمات عمومية أخرى قد تم تعيينها. قبل تطبيق قيمك الخاصة.

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

تفعيل الوضع "كسول" في المواقع

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

في المثال التالي، تُجري Angular ربط نموذجها صراحةً isChecked إلى السمة checked في مربّع الاختيار. إذا كان تعريف طريقة التحميل الكسول في مربّع الاختيار، فمن المحتمل أن يحاول Angular ضبط الخاصية المحددة قبل ترقية العنصر.

<howto-checkbox [checked]="defaults.isChecked"></howto-checkbox>

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

connectedCallback() {
  ...
  this._upgradeProperty('checked');
}

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

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

تجنُّب مشاكل إعادة الدخول

من المغري استخدام attributeChangedCallback() لتعكس الحالة الموقع الأساسي، مثل:

// When the [checked] attribute changes, set the checked property to match.
attributeChangedCallback(name, oldValue, newValue) {
  if (name === 'checked')
    this.checked = newValue;
}

ولكن هذا يمكن أن ينشئ تكرارًا لا نهائي إذا انعكست دالة setter أيضًا على السمة.

set checked(value) {
  const isChecked = Boolean(value);
  if (isChecked)
    // OOPS! This will cause an infinite loop because it triggers the
    // attributeChangedCallback() which then sets this property again.
    this.setAttribute('checked', '');
  else
    this.removeAttribute('checked');
}

البديل هو السماح لدالة setter بالانعكاس على السمة، يحدد دالة getter قيمته بناءً على التصنيف.

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

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

في هذا المثال، ستؤدي إضافة السمة أو إزالتها إلى تحديد السمة أيضًا.

أخيرًا، يمكن استخدام attributeChangedCallback() لمعالجة الآثار الجانبية. مثل تطبيق حالات ARIA.

attributeChangedCallback(name, oldValue, newValue) {
  const hasValue = newValue !== null;
  switch (name) {
    case 'checked':
      // Note the attributeChangedCallback is only handling the *side effects*
      // of setting the attribute.
      this.setAttribute('aria-checked', hasValue);
      break;
    ...
  }
}