بهترین شیوه های عنصر سفارشی

عناصر سفارشی به شما امکان می دهند تگ های 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 مدل خود را به ویژگی checkbox در 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;
}

اما این می تواند یک حلقه بی نهایت ایجاد کند اگر تنظیم کننده ویژگی نیز به ویژگی منعکس شود.

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