Praktik Terbaik Elemen Kustom

Elemen kustom memungkinkan Anda membuat tag HTML sendiri. Checklist ini mencakup praktik terbaik untuk membantu Anda membuat elemen berkualitas tinggi.

Elemen khusus memungkinkan Anda memperluas HTML dan menentukan tag Anda sendiri. Mereka adalah fitur yang sangat kuat, tetapi mereka juga tingkat rendah, yang berarti itu tidak selalu mengetahui cara terbaik untuk mengimplementasikan elemen Anda sendiri.

Untuk membantu Anda menciptakan pengalaman terbaik, kami telah menyusun {i>checklist<i} ini. Ini menguraikan semua hal yang kita pikir diperlukan untuk menjadi elemen kustom yang berperilaku baik.

Checklist

DOM Bayangan

Atribut dan properti

Acara

Penjelasan

Jangan ganti penulis halaman

Mungkin saja pengembang yang menggunakan elemen Anda ingin mengganti beberapa ke keadaan awal. Misalnya, mengubah role ARIA atau kemampuan fokusnya dengan tabindex. Periksa untuk melihat apakah atribut ini dan atribut global lainnya telah ditetapkan, sebelum menerapkan nilai Anda sendiri.

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

Membuat properti menjadi lambat

Pengembang mungkin mencoba untuk menetapkan properti pada elemen Anda sebelum telah dimuat. Terutama jika pengembang menggunakan yang menangani pemuatan komponen, memasukkannya ke dalam halaman, dan mengikat propertinya ke model.

Pada contoh berikut, Angular secara deklaratif mengikat elemen isChecked ke properti checked kotak centang. Jika definisi untuk kotak centang petunjuk dimuat dengan lambat, mungkin saja Angular mungkin mencoba menetapkan properti yang dicentang sebelum elemen diupgrade.

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

Elemen khusus harus menangani skenario ini dengan memeriksa apakah ada properti yang sudah ditetapkan pada instance-nya. <howto-checkbox> menunjukkan pola ini menggunakan metode yang disebut _upgradeProperty().

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

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

_upgradeProperty() mengambil nilai dari instance yang belum diupgrade dan menghapusnya properti agar tidak membayangi penyetel properti elemen kustom itu sendiri. Dengan cara ini, ketika definisi elemen akhirnya dimuat, ia bisa segera menunjukkan keadaan yang benar.

Menghindari masalah reentransi

Anda mungkin ingin menggunakan attributeChangedCallback() untuk mencerminkan status ke properti pokok, misalnya:

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

Namun, hal ini bisa menimbulkan loop tak terbatas jika penyetel properti juga mencerminkan atribut ini.

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

Alternatifnya adalah dengan memungkinkan penyetel properti untuk tercermin ke atribut, dan meminta pengambil menentukan nilainya berdasarkan atribut.

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

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

Dalam contoh ini, menambahkan atau menghapus atribut juga akan menetapkan properti.

Terakhir, attributeChangedCallback() dapat digunakan untuk menangani efek samping seperti menerapkan status 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;
    ...
  }
}