Mendefinisikan Elemen dengan customElements.define

Elemen kustom memungkinkan Anda membuat tag HTML sendiri yang didukung oleh sebuah kelas JavaScript. Setelah didefinisikan, <my-card> berperilaku seperti elemen bawaan apa pun: dapat ditulis dalam HTML, dicari, ditata, diprogram, dan digunakan di dalam kerangka kerja tanpa perubahan.

Setiap nama elemen kustom harus menyertakan setidaknya satu tanda hubung — user-avatar, app-button, my-card. Tanda hubung membedakan elemen kustom dari tag HTML bawaan saat ini dan mendatang, serta diwajibkan oleh spesifikasi.

Elemen kustom adalah kelas yang mewarisi HTMLElement (atau subkelas bawaan). Kelas tersebut dapat mendeklarasikan konstruktor dan panggilan balik siklus hidup. Properti publik dan metode pada kelas menjadi antarmuka pemrograman elemen.

customElements.define("my-card", MyCard) mendaftarkan kelas dengan nama tag tersebut. Setelah pendaftaran, setiap <my-card> yang sudah ada maupun yang dibuat kemudian dalam dokumen diubah menjadi instans kelas tersebut.

Konstruktor harus memanggil super() sebagai pernyataan pertamanya sebelum mengakses this. Melewati super() akan menimbulkan "Failed to construct 'HTMLElement'". Perlakukan hal ini sebagai aturan standar konstruktor kelas JavaScript.

Konstruktor tidak boleh membaca atribut atau anak elemen — keduanya mungkin belum diuraikan saat konstruksi. Pindahkan penyiapan yang menyentuh DOM ke dalam connectedCallback, yang hanya dijalankan setelah elemen berada di dalam dokumen.

Nama elemen hanya dapat didaftarkan sekali per halaman. Mendefinisikan ulang nama yang sama akan menimbulkan NotSupportedError. Muat ulang halaman untuk menguji perubahan selama pengembangan; dalam produksi, daftarkan setiap komponen sekali saat mulai.

Elemen kustom tersedia di setiap peramban modern. Untuk peramban yang sangat lama (sebagian besar sudah tidak digunakan), polifil webcomponents.js menyediakan cadangan. Proyek baru dapat menggunakan dukungan bawaan dan melewatkan polifil sepenuhnya.

customElements.get("my-card") mengembalikan kelas jika sudah didefinisikan, dan undefined jika belum. customElements.whenDefined("my-card") mengembalikan promise yang diselesaikan setelah elemen didaftarkan — berguna untuk kode yang perlu menunggu definisi yang dimuat terlambat.

Setelah didefinisikan, gunakan elemen tersebut persis seperti tag bawaan: tuliskan dalam HTML (<my-card></my-card>), buat melalui document.createElement("my-card"), atau buat instans melalui new MyCard() lalu sisipkan. Ketiga jalur tersebut menghasilkan instans yang sama setelah ditingkatkan.

Beri awalan pada elemen kustom dengan nama proyek atau perusahaan (cd-card, app-modal) untuk menghindari benturan dengan pustaka lain di halaman yang sama. Ekosistem komponen web tidak dibundel — siapa pun di halaman Anda dapat mendaftarkan nama apa pun, dan pendaftaran pertama yang berlaku.

Elemen kustom adalah kelas JavaScript yang mewarisi HTMLElement dan didaftarkan melalui customElements.define("name", Class), dengan nama yang harus mengandung tanda hubung. Konstruktor harus memanggil super() terlebih dahulu dan tidak boleh membaca DOM; tunda pekerjaan DOM ke connectedCallback. Elemen yang telah didefinisikan berperilaku persis seperti tag bawaan di mana pun digunakan.