שיטות מומלצות לשימוש ברכיבים מותאמים אישית

רכיבים מותאמים אישית מאפשרים לכם ליצור תגי HTML משלכם. רשימת המשימות הזו כוללת שיטות מומלצות שיעזרו לכם ליצור רכיבים באיכות גבוהה.

רכיבים מותאמים אישית מאפשרים לכם להרחיב HTML ולהגדיר תגים משלכם. אלה היא תכונה חזקה מאוד, אבל היא גם ברמה נמוכה, ברור תמיד מהי הדרך הטובה ביותר ליישם את הרכיב שלך.

כדי לעזור לך ליצור את החוויה הטובה ביותר, ריכזנו כאן ברשימת המשימות. הוא מפרט את כל הדברים שלדעתנו צריכים כדי רכיב מותאם אישית עם התנהגות טובה.

רשימת המשימות

DOM של הצללה

מאפיינים ומאפיינים

אירועים

הסברים

לא לשנות את מחבר הדף

ייתכן שמפתח שמשתמש ברכיב שלך ירצה לבטל חלק את המצב הראשוני שלו. לדוגמה, שינוי ה-role של ARIA או של יכולת המיקוד באמצעות tabindex. בודקים אם המאפיינים האלה ומאפיינים גלובליים אחרים הוגדרו לפני שתחילו את הערכים שלכם.

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

הפיכת נכסים למתקדמים

יכול להיות שמפתח ינסה להגדיר מאפיין ברכיב שלכם לפני נטענה. במיוחד נכון אם המפתח משתמש המטפלת ברכיבים בטעינה, מכניסה אותם לדף שמקשרות את המאפיינים שלהן למודל.

בדוגמה הבאה, חברת Angular מקשרת באופן הצהרתי את המודל של המודל מאפיין isChecked למאפיין checked של תיבת הסימון. אם ההגדרה של הוראות הסימון המאפיין המסומן לפני שהרכיב שודרג.

<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;
}

אבל הפעולה הזו יכולה ליצור לולאה אינסופית אם המרכיב של המאפיין ישקף גם את את המאפיין.

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');
}

אפשרות אחרת היא לאפשר לרכיב המגדיר של הנכסים לשקף את המאפיין. שהמקבל יקבע את הערך שלו על סמך המאפיין.

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;
    ...
  }
}