Elemen Khusus v1 - Komponen Web yang Dapat Digunakan Kembali

Elemen khusus memungkinkan developer web mendefinisikan tag HTML baru, memperluas yang sudah ada, dan membuat komponen web yang dapat digunakan kembali.

Dengan Elemen Khusus, developer web dapat membuat tag HTML baru, meningkatkan kualitas tag HTML yang ada, atau memperluas komponen yang ditulis developer lain. API adalah dasar dari komponen web. Elemen khusus menghadirkan cara berbasis standar web untuk membuat komponen yang dapat digunakan kembali dengan hanya menggunakan JS/HTML/CSS biasa. Hasilnya irit kode, kode modular, dan lebih bisa digunakan kembali di aplikasi kita.

{i>Browser<i} memberi kita alat yang sangat baik untuk menyusun aplikasi web. Ini disebut HTML. Anda mungkin pernah mendengarnya! Deklaratif, portabel, didukung dengan baik, dan mudah digunakan. Mungkin sehebat HTML, kosakata dan ekstensibilitasnya terbatas. Standar hidup HTML selalu tidak memiliki cara untuk mengaitkan perilaku JS dengan markup Anda secara otomatis… hingga sekarang.

Elemen kustom adalah jawaban untuk memodernisasi HTML, mengisi bagian yang hilang, dan membundel struktur dengan perilaku. Jika HTML tidak memberikan solusi untuk masalah, kita dapat membuat elemen khusus yang akan melakukannya. Elemen kustom mengajari browser trik baru sekaligus mempertahankan manfaat HTML.

Menentukan elemen baru

Untuk mendefinisikan elemen HTML baru, kita memerlukan kemampuan JavaScript.

customElements global digunakan untuk menentukan elemen kustom dan memberi tahu browser tentang tag baru. Panggil customElements.define() dengan nama tag yang ingin Anda buat dan class JavaScript yang memperluas HTMLElement dasar.

Contoh - menentukan panel panel samping seluler, <app-drawer>:

class AppDrawer extends HTMLElement {...}
window.customElements.define('app-drawer', AppDrawer);

// Or use an anonymous class if you don't want a named constructor in current scope.
window.customElements.define('app-drawer', class extends HTMLElement {...});

Contoh penggunaan:

<app-drawer></app-drawer>

Perlu diingat bahwa menggunakan elemen khusus tidak ada bedanya dengan menggunakan <div> atau elemen lainnya. Instance dapat dideklarasikan di halaman, dibuat secara dinamis di JavaScript, pemroses peristiwa dapat dilampirkan, dll. Lanjutkan membaca untuk mengetahui contoh lainnya.

Menentukan JavaScript API elemen

Fungsi elemen kustom ditentukan menggunakan class ES2015 yang memperluas HTMLElement. Memperluas HTMLElement memastikan elemen kustom mewarisi seluruh DOM API dan berarti properti/metode apa pun yang Anda tambahkan ke class menjadi bagian dari antarmuka DOM elemen. Pada dasarnya, gunakan class untuk membuat JavaScript API publik untuk tag Anda.

Contoh - menentukan antarmuka DOM <app-drawer>:

class AppDrawer extends HTMLElement {

  // A getter/setter for an open property.
  get open() {
    return this.hasAttribute('open');
  }

  set open(val) {
    // Reflect the value of the open property as an HTML attribute.
    if (val) {
      this.setAttribute('open', '');
    } else {
      this.removeAttribute('open');
    }
    this.toggleDrawer();
  }

  // A getter/setter for a disabled property.
  get disabled() {
    return this.hasAttribute('disabled');
  }

  set disabled(val) {
    // Reflect the value of the disabled property as an HTML attribute.
    if (val) {
      this.setAttribute('disabled', '');
    } else {
      this.removeAttribute('disabled');
    }
  }

  // Can define constructor arguments if you wish.
  constructor() {
    // If you define a constructor, always call super() first!
    // This is specific to CE and required by the spec.
    super();

    // Setup a click listener on <app-drawer> itself.
    this.addEventListener('click', e => {
      // Don't toggle the drawer if it's disabled.
      if (this.disabled) {
        return;
      }
      this.toggleDrawer();
    });
  }

  toggleDrawer() {
    // ...
  }
}

customElements.define('app-drawer', AppDrawer);

Dalam contoh ini, kita membuat panel samping yang memiliki properti open, properti disabled, dan metode toggleDrawer(). Ini juga merefleksikan properti sebagai atribut HTML.

Fitur rapi dari elemen kustom adalah this di dalam definisi class merujuk ke elemen DOM itu sendiri, yaitu instance class. Dalam contoh kita, this merujuk ke <app-drawer>. (😉) ini adalah cara elemen dapat melampirkan pemroses click ke dirinya sendiri. Dan Anda tidak dibatasi pada pemroses peristiwa. Seluruh DOM API tersedia di dalam kode elemen. Gunakan this untuk mengakses properti elemen, memeriksa turunannya (this.children), membuat kueri node (this.querySelectorAll('.items')), dll.

Aturan mengenai pembuatan elemen khusus

  1. Nama elemen kustom harus berisi tanda hubung (-). Jadi, <x-tags>, <my-element>, dan <my-awesome-app> semuanya adalah nama yang valid, sedangkan <tabs> dan <foo_bar> tidak valid. Persyaratan ini agar HTML parser dapat membedakan elemen kustom dari elemen biasa. Hal ini juga memastikan kompatibilitas ke depan saat tag baru ditambahkan ke HTML.
  2. Anda tidak dapat mendaftarkan tag yang sama lebih dari sekali. Mencoba melakukannya akan menampilkan DOMException. Setelah Anda memberi tahu browser tentang tag baru, selesailah urusan. Tidak ada pengembalian.
  3. Elemen kustom tidak dapat menutup sendiri karena HTML hanya mengizinkan beberapa elemen untuk menutup sendiri. Selalu tulis tag penutup (<app-drawer></app-drawer>).

Reaksi elemen kustom

Elemen kustom dapat menentukan hook siklus proses khusus untuk menjalankan kode selama waktu menarik dari keberadaannya. Ini disebut reaksi elemen kustom.

Nama Dipanggil saat
constructor Instance elemen dibuat atau diupgrade. Berguna untuk melakukan inisialisasi status, menyiapkan pemroses peristiwa, atau membuat shadow DOM. Lihat spesifikasi untuk mengetahui batasan terhadap hal yang dapat Anda lakukan di constructor.
connectedCallback Dipanggil setiap kali elemen disisipkan ke dalam DOM. Berguna untuk menjalankan kode penyiapan, seperti mengambil resource atau rendering. Secara umum, Anda harus mencoba menunda pekerjaan hingga waktu ini.
disconnectedCallback Dipanggil setiap kali elemen dihapus dari DOM. Berguna untuk menjalankan kode pembersihan.
attributeChangedCallback(attrName, oldVal, newVal) Dipanggil saat atribut yang diamati telah ditambahkan, dihapus, diperbarui, atau diganti. Juga dipanggil untuk nilai awal saat elemen dibuat oleh parser, atau diupgrade. Catatan: hanya atribut yang tercantum dalam properti observedAttributes yang akan menerima callback ini.
adoptedCallback Elemen kustom telah dipindahkan ke document baru (misalnya, seseorang bernama document.adoptNode(el)).

Callback reaksi bersifat sinkron. Jika seseorang memanggil el.setAttribute() pada elemen Anda, browser akan segera memanggil attributeChangedCallback(). Demikian pula, Anda akan menerima disconnectedCallback() tepat setelah elemen dihapus dari DOM (misalnya, pengguna memanggil el.remove()).

Contoh: menambahkan reaksi elemen kustom ke <app-drawer>:

class AppDrawer extends HTMLElement {
  constructor() {
    super(); // always call super() first in the constructor.
    // ...
  }

  connectedCallback() {
    // ...
  }

  disconnectedCallback() {
    // ...
  }

  attributeChangedCallback(attrName, oldVal, newVal) {
    // ...
  }
}

Tentukan reaksi jika/bila memang logis. Jika elemen Anda cukup kompleks dan membuka koneksi ke IndexedDB di connectedCallback(), lakukan pekerjaan pembersihan yang diperlukan di disconnectedCallback(). Namun, hati-hati. Anda tidak dapat mengandalkan elemen Anda yang akan dihapus dari DOM dalam semua situasi. Misalnya, disconnectedCallback() tidak akan pernah dipanggil jika pengguna menutup tab.

Properti dan atribut

Mencerminkan properti ke atribut

Sudah umum bagi properti HTML merefleksikan kembali nilainya ke DOM sebagai atribut HTML. Misalnya, saat nilai hidden atau id diubah di JS:

div.id = 'my-id';
div.hidden = true;

nilai-nilai tersebut diterapkan ke DOM live sebagai atribut:

<div id="my-id" hidden>

Hal ini disebut "merefleksikan properti ke atribut". Hampir setiap properti di HTML melakukan hal ini. Mengapa? Atribut juga berguna untuk mengonfigurasi elemen secara deklaratif dan API tertentu seperti aksesibilitas dan pemilih CSS bergantung pada atribut agar dapat berfungsi.

Merefleksikan properti berguna di mana pun Anda ingin membuat representasi DOM elemen tetap sinkron dengan status JavaScript-nya. Salah satu alasan Anda mungkin ingin merefleksikan properti adalah agar gaya visual yang ditentukan pengguna diterapkan saat status JS berubah.

Ingat kembali <app-drawer> kita. Konsumen komponen ini mungkin ingin memudarkannya dan/atau mencegah interaksi pengguna saat dinonaktifkan:

app-drawer[disabled] {
  opacity: 0.5;
  pointer-events: none;
}

Saat properti disabled diubah di JS, kita ingin atribut tersebut ditambahkan ke DOM agar pemilih pengguna cocok. Elemen dapat menyediakan perilaku tersebut dengan merefleksikan nilai ke atribut yang sama namanya:

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

set disabled(val) {
  // Reflect the value of `disabled` as an attribute.
  if (val) {
    this.setAttribute('disabled', '');
  } else {
    this.removeAttribute('disabled');
  }
  this.toggleDrawer();
}

Mengamati perubahan pada atribut

Atribut HTML adalah cara praktis bagi pengguna untuk mendeklarasikan status awal:

<app-drawer open disabled></app-drawer>

Elemen dapat bereaksi terhadap perubahan atribut dengan menentukan attributeChangedCallback. Browser akan memanggil metode ini untuk setiap perubahan pada atribut yang tercantum dalam array observedAttributes.

class AppDrawer extends HTMLElement {
  // ...

  static get observedAttributes() {
    return ['disabled', 'open'];
  }

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

  set disabled(val) {
    if (val) {
      this.setAttribute('disabled', '');
    } else {
      this.removeAttribute('disabled');
    }
  }

  // Only called for the disabled and open attributes due to observedAttributes
  attributeChangedCallback(name, oldValue, newValue) {
    // When the drawer is disabled, update keyboard/screen reader behavior.
    if (this.disabled) {
      this.setAttribute('tabindex', '-1');
      this.setAttribute('aria-disabled', 'true');
    } else {
      this.setAttribute('tabindex', '0');
      this.setAttribute('aria-disabled', 'false');
    }
    // TODO: also react to the open attribute changing.
  }
}

Dalam contoh, kita menetapkan atribut tambahan pada <app-drawer> saat atribut disabled berubah. Meskipun kita tidak melakukannya di sini, Anda juga dapat menggunakan attributeChangedCallback untuk membuat properti JS tetap sinkron dengan atributnya.

Upgrade elemen

HTML yang disempurnakan secara progresif

Kita telah mempelajari bahwa elemen kustom ditentukan dengan memanggil customElements.define(). Namun, ini tidak berarti Anda harus mendefinisikan + mendaftarkan elemen kustom sekaligus.

Elemen kustom dapat digunakan sebelum definisinya didaftarkan.

Peningkatan progresif adalah fitur elemen kustom. Dengan kata lain, Anda dapat mendeklarasikan sekumpulan elemen <app-drawer> di halaman dan tidak akan pernah memanggil customElements.define('app-drawer', ...) hingga nanti. Hal ini karena browser memperlakukan elemen kustom yang potensial secara berbeda berkat tag yang tidak dikenal. Proses memanggil define() dan memberikan elemen yang ada dengan definisi class disebut "peningkatan versi elemen".

Untuk mengetahui kapan nama tag menjadi ditentukan, Anda dapat menggunakan window.customElements.whenDefined(). Metode ini menampilkan Promise yang akan di-resolve saat elemen ditentukan.

customElements.whenDefined('app-drawer').then(() => {
  console.log('app-drawer defined');
});

Contoh - menunda pekerjaan hingga satu set elemen turunan diupgrade

<share-buttons>
  <social-button type="twitter"><a href="...">Twitter</a></social-button>
  <social-button type="fb"><a href="...">Facebook</a></social-button>
  <social-button type="plus"><a href="...">G+</a></social-button>
</share-buttons>
// Fetch all the children of <share-buttons> that are not defined yet.
let undefinedButtons = buttons.querySelectorAll(':not(:defined)');

let promises = [...undefinedButtons].map((socialButton) => {
  return customElements.whenDefined(socialButton.localName);
});

// Wait for all the social-buttons to be upgraded.
Promise.all(promises).then(() => {
  // All social-button children are ready.
});

Konten yang ditentukan elemen

Elemen kustom dapat mengelola kontennya sendiri dengan menggunakan DOM API di dalam kode elemen. Reaksi sangat berguna untuk hal ini.

Contoh - buat elemen dengan beberapa HTML default:

customElements.define('x-foo-with-markup', class extends HTMLElement {
  connectedCallback() {
    this.innerHTML = "<b>I'm an x-foo-with-markup!</b>";
  }
  // ...
});

Mendeklarasikan tag ini akan menghasilkan:

<x-foo-with-markup>
  <b>I'm an x-foo-with-markup!</b>
</x-foo-with-markup>

// TODO: DevSite - Contoh kode dihapus karena menggunakan pengendali peristiwa inline

Membuat elemen yang menggunakan Shadow DOM

Shadow DOM menyediakan cara bagi elemen untuk memiliki, merender, dan menata gaya suatu potongan DOM yang terpisah dari bagian halaman lainnya. Anda bahkan dapat menyembunyikan keseluruhan aplikasi dalam satu tag:

<!-- chat-app's implementation details are hidden away in Shadow DOM. -->
<chat-app></chat-app>

Untuk menggunakan Shadow DOM di elemen kustom, panggil this.attachShadow di dalam constructor:

let tmpl = document.createElement('template');
tmpl.innerHTML = `
  <style>:host { ... }</style> <!-- look ma, scoped styles -->
  <b>I'm in shadow dom!</b>
  <slot></slot>
`;

customElements.define('x-foo-shadowdom', class extends HTMLElement {
  constructor() {
    super(); // always call super() first in the constructor.

    // Attach a shadow root to the element.
    let shadowRoot = this.attachShadow({mode: 'open'});
    shadowRoot.appendChild(tmpl.content.cloneNode(true));
  }
  // ...
});

Contoh penggunaan:

<x-foo-shadowdom>
  <p><b>User's</b> custom text</p>
</x-foo-shadowdom>

<!-- renders as -->
<x-foo-shadowdom>
  #shadow-root
  <b>I'm in shadow dom!</b>
  <slot></slot> <!-- slotted content appears here -->
</x-foo-shadowdom>

Teks kustom pengguna

// TODO: DevSite - Contoh kode dihapus karena menggunakan pengendali peristiwa inline

Membuat elemen dari <template>

Bagi yang belum familier, elemen <template> memungkinkan Anda mendeklarasikan fragmen DOM yang telah di-parse, membekukan pemuatan halaman, dan dapat diaktifkan nanti saat waktu proses. Ini adalah primitif API yang lain dalam keluarga komponen web. Template adalah placeholder ideal untuk mendeklarasikan struktur elemen kustom.

Contoh: mendaftarkan elemen dengan konten Shadow DOM yang dibuat dari <template>:

<template id="x-foo-from-template">
  <style>
    p { color: green; }
  </style>
  <p>I'm in Shadow DOM. My markup was stamped from a &lt;template&gt;.</p>
</template>

<script>
  let tmpl = document.querySelector('#x-foo-from-template');
  // If your code is inside of an HTML Import you'll need to change the above line to:
  // let tmpl = document.currentScript.ownerDocument.querySelector('#x-foo-from-template');

  customElements.define('x-foo-from-template', class extends HTMLElement {
    constructor() {
      super(); // always call super() first in the constructor.
      let shadowRoot = this.attachShadow({mode: 'open'});
      shadowRoot.appendChild(tmpl.content.cloneNode(true));
    }
    // ...
  });
</script>

Beberapa baris kode ini sangat menarik. Mari kita pahami hal-hal penting yang terjadi:

  1. Kita menentukan elemen baru dalam HTML: <x-foo-from-template>
  2. Shadow DOM elemen dibuat dari <template>
  3. DOM elemen bersifat lokal pada elemen berkat Shadow DOM
  4. CSS internal elemen tercakup ke elemen berkat Shadow DOM

I'm in Shadow DOM. Markup saya diberi stempel dari <template>.

// TODO: DevSite - Contoh kode dihapus karena menggunakan pengendali peristiwa inline

Menata gaya elemen kustom

Meskipun elemen Anda menentukan gayanya sendiri menggunakan Shadow DOM, pengguna dapat menata gaya elemen khusus Anda dari halaman mereka. Ini disebut "gaya yang ditentukan pengguna".

<!-- user-defined styling -->
<style>
  app-drawer {
    display: flex;
  }
  panel-item {
    transition: opacity 400ms ease-in-out;
    opacity: 0.3;
    flex: 1;
    text-align: center;
    border-radius: 50%;
  }
  panel-item:hover {
    opacity: 1.0;
    background: rgb(255, 0, 255);
    color: white;
  }
  app-panel > panel-item {
    padding: 5px;
    list-style: none;
    margin: 0 7px;
  }
</style>

<app-drawer>
  <panel-item>Do</panel-item>
  <panel-item>Re</panel-item>
  <panel-item>Mi</panel-item>
</app-drawer>

Anda mungkin bertanya-tanya bagaimana kekhususan CSS akan berfungsi jika elemen memiliki gaya yang ditentukan dalam Shadow DOM. Dalam konteks kekhususan, gaya pengguna yang akan menang. Gaya tersebut akan selalu menggantikan gaya visual yang ditentukan elemen. Lihat bagian tentang Membuat elemen yang menggunakan Shadow DOM.

Pra-gaya visual elemen yang tidak terdaftar

Sebelum elemen diupgrade, Anda dapat menargetkannya di CSS menggunakan class semu :defined. Hal ini berguna untuk pra-penataan gaya komponen. Misalnya, Anda mungkin ingin mencegah tata letak atau FOUC visual lainnya dengan menyembunyikan komponen yang tidak ditentukan dan memudarkannya saat telah ditentukan.

Contoh - sembunyikan <app-drawer> sebelum didefinisikan:

app-drawer:not(:defined) {
  /* Pre-style, give layout, replicate app-drawer's eventual styles, etc. */
  display: inline-block;
  height: 100vh;
  opacity: 0;
  transition: opacity 0.3s ease-in-out;
}

Setelah <app-drawer> ditentukan, pemilih (app-drawer:not(:defined)) tidak lagi cocok.

Memperluas elemen

Custom Elements API berguna untuk membuat elemen HTML baru, tetapi juga berguna untuk memperluas elemen kustom lainnya atau bahkan HTML bawaan browser.

Memperluas elemen kustom

Memperluas elemen khusus lain dilakukan dengan memperluas definisi class-nya.

Contoh - membuat <fancy-app-drawer> yang memperluas <app-drawer>:

class FancyDrawer extends AppDrawer {
  constructor() {
    super(); // always call super() first in the constructor. This also calls the extended class' constructor.
    // ...
  }

  toggleDrawer() {
    // Possibly different toggle implementation?
    // Use ES2015 if you need to call the parent method.
    // super.toggleDrawer()
  }

  anotherMethod() {
    // ...
  }
}

customElements.define('fancy-app-drawer', FancyDrawer);

Memperluas elemen HTML native

Misalnya Anda ingin membuat <button> yang lebih bagus. Daripada mereplikasi perilaku dan fungsi <button>, opsi yang lebih baik adalah secara bertahap meningkatkan elemen yang ada menggunakan elemen kustom.

Elemen bawaan yang disesuaikan adalah elemen kustom yang memperluas salah satu tag HTML bawaan browser. Manfaat utama memperluas elemen yang sudah ada adalah untuk mendapatkan semua fiturnya (properti DOM, metode, aksesibilitas). Tidak ada cara yang lebih baik untuk menulis aplikasi web progresif daripada meningkatkan elemen HTML yang ada secara progresif.

Untuk memperluas elemen, Anda harus membuat definisi class yang diwarisi dari antarmuka DOM yang benar. Misalnya, elemen kustom yang memperluas <button> harus mewarisi dari HTMLButtonElement, bukan HTMLElement. Demikian pula, elemen yang memperluas <img> perlu memperluas HTMLImageElement.

Contoh - memperluas <button>:

// See https://html.spec.whatwg.org/multipage/indices.html#element-interfaces
// for the list of other DOM interfaces.
class FancyButton extends HTMLButtonElement {
  constructor() {
    super(); // always call super() first in the constructor.
    this.addEventListener('click', e => this.drawRipple(e.offsetX, e.offsetY));
  }

  // Material design ripple animation.
  drawRipple(x, y) {
    let div = document.createElement('div');
    div.classList.add('ripple');
    this.appendChild(div);
    div.style.top = `${y - div.clientHeight/2}px`;
    div.style.left = `${x - div.clientWidth/2}px`;
    div.style.backgroundColor = 'currentColor';
    div.classList.add('run');
    div.addEventListener('transitionend', (e) => div.remove());
  }
}

customElements.define('fancy-button', FancyButton, {extends: 'button'});

Perhatikan bahwa panggilan ke define() sedikit berubah saat memperluas elemen native. Parameter ketiga yang diperlukan memberi tahu browser tag yang akan Anda perluas. Hal ini diperlukan karena banyak tag HTML yang berbagi antarmuka DOM yang sama. <section>, <address>, dan <em> (di antara yang lainnya) semuanya memiliki HTMLElement yang sama; <q> dan <blockquote> memiliki HTMLQuoteElement yang sama; dll. Dengan menentukan {extends: 'blockquote'}, browser akan mengetahui bahwa Anda membuat <blockquote> yang ditingkatkan, bukan <q>. Lihat spesifikasi HTML untuk mengetahui daftar lengkap antarmuka DOM HTML.

Konsumen elemen bawaan yang disesuaikan dapat menggunakannya dalam beberapa cara. Tag tersebut dapat mendeklarasikan dengan menambahkan atribut is="" pada tag native:

<!-- This <button> is a fancy button. -->
<button is="fancy-button" disabled>Fancy button!</button>

membuat instance di JavaScript:

// Custom elements overload createElement() to support the is="" attribute.
let button = document.createElement('button', {is: 'fancy-button'});
button.textContent = 'Fancy button!';
button.disabled = true;
document.body.appendChild(button);

atau menggunakan operator new:

let button = new FancyButton();
button.textContent = 'Fancy button!';
button.disabled = true;

Berikut adalah contoh lain yang memperluas <img>.

Contoh - memperluas <img>:

customElements.define('bigger-img', class extends Image {
  // Give img default size if users don't specify.
  constructor(width=50, height=50) {
    super(width * 10, height * 10);
  }
}, {extends: 'img'});

Pengguna mendeklarasikan komponen ini sebagai:

<!-- This <img> is a bigger img. -->
<img is="bigger-img" width="15" height="20">

atau membuat instance di JavaScript:

const BiggerImage = customElements.get('bigger-img');
const image = new BiggerImage(15, 20); // pass constructor values like so.
console.assert(image.width === 150);
console.assert(image.height === 200);

Detail lainnya

Elemen tidak dikenal vs. elemen kustom yang belum ditentukan

HTML toleran dan fleksibel untuk digunakan. Misalnya, deklarasikan <randomtagthatdoesntexist> di halaman dan browser akan menerimanya dengan senang hati. Mengapa tag non-standar bisa berfungsi? Jawabannya adalah spesifikasi HTML mengizinkannya. Elemen yang tidak ditentukan oleh spesifikasi akan diuraikan sebagai HTMLUnknownElement.

Hal yang sama tidak berlaku untuk elemen kustom. Elemen kustom yang potensial akan diuraikan sebagai HTMLElement jika dibuat dengan nama yang valid (menyertakan "-"). Anda dapat memeriksanya di browser yang mendukung elemen kustom. Buka Konsol: Ctrl+Shift+J (atau Cmd+Opt+J di Mac), lalu tempelkan baris kode berikut:

// "tabs" is not a valid custom element name
document.createElement('tabs') instanceof HTMLUnknownElement === true

// "x-tabs" is a valid custom element name
document.createElement('x-tabs') instanceof HTMLElement === true

Referensi API

customElements global menentukan metode yang berguna untuk menangani elemen kustom.

define(tagName, constructor, options)

Mendefinisikan elemen khusus baru di browser.

Contoh

customElements.define('my-app', class extends HTMLElement { ... });
customElements.define(
    'fancy-button', class extends HTMLButtonElement { ... }, {extends: 'button'});

get(tagName)

Dengan nama tag elemen kustom yang valid, akan menampilkan konstruktor elemen. Menampilkan undefined jika tidak ada definisi elemen yang terdaftar.

Contoh

let Drawer = customElements.get('app-drawer');
let drawer = new Drawer();

whenDefined(tagName)

Menampilkan Promise yang ditetapkan saat elemen kustom ditentukan. Jika elemen sudah ditentukan, segera tetapkan. Menolak jika nama tag bukan nama elemen kustom yang valid.

Contoh

customElements.whenDefined('app-drawer').then(() => {
  console.log('ready!');
});

Dukungan histori dan browser

Jika Anda telah mengikuti komponen web selama beberapa tahun terakhir, Anda akan mengetahui bahwa Chrome 36+ mengimplementasikan versi Custom Elements API yang menggunakan document.registerElement(), bukan customElements.define(). Sekarang, versi tersebut dianggap sebagai versi standar yang tidak digunakan lagi, yang disebut v0. customElements.define() adalah hal baru yang sedang populer dan mulai diterapkan oleh vendor browser. Elemen ini disebut Custom Elements v1.

Jika Anda tertarik dengan spesifikasi v0 lama, lihat artikel html5rocks.

Dukungan browser

Chrome 54 (status), Safari 10.1 (status), dan Firefox 63 (status) memiliki Elemen Khusus v1. Edge telah memulai pengembangan.

Agar fitur mendeteksi elemen khusus, periksa keberadaan window.customElements:

const supportsCustomElementsV1 = 'customElements' in window;

Polyfill

Sebelum dukungan browser tersedia secara luas, tersedia polyfill mandiri untuk Custom Elements v1. Namun, sebaiknya gunakan loader webcomponents.js untuk memuat polyfill komponen web secara optimal. Loader menggunakan deteksi fitur untuk memuat secara asinkron hanya pollyfill yang diperlukan yang diperlukan oleh browser.

Instal:

npm install --save @webcomponents/webcomponentsjs

Penggunaan:

<!-- Use the custom element on the page. -->
<my-element></my-element>

<!-- Load polyfills; note that "loader" will load these async -->
<script src="node_modules/@webcomponents/webcomponentsjs/webcomponents-loader.js" defer></script>

<!-- Load a custom element definitions in `waitFor` and return a promise -->
<script type="module">
  function loadScript(src) {
    return new Promise(function(resolve, reject) {
      const script = document.createElement('script');
      script.src = src;
      script.onload = resolve;
      script.onerror = reject;
      document.head.appendChild(script);
    });
  }

  WebComponents.waitFor(() => {
    // At this point we are guaranteed that all required polyfills have
    // loaded, and can use web components APIs.
    // Next, load element definitions that call `customElements.define`.
    // Note: returning a promise causes the custom elements
    // polyfill to wait until all definitions are loaded and then upgrade
    // the document in one batch, for better performance.
    return loadScript('my-element.js');
  });
</script>

Kesimpulan

Elemen khusus memberi kita alat baru untuk mendefinisikan tag HTML baru di browser dan membuat komponen yang dapat digunakan kembali. Kombinasikan semua itu dengan primitif platform baru lainnya seperti Shadow DOM dan <template>, dan kita mulai menyadari gambaran besar Komponen Web:

  • Lintas-browser (standar web) untuk membuat dan memperluas komponen yang dapat digunakan kembali.
  • Tidak memerlukan library atau framework untuk memulai. JS/HTML FTW biasa!
  • Menyediakan model pemrograman yang familier. Ini hanya DOM/CSS/HTML.
  • Berfungsi dengan baik bersama fitur platform web baru lainnya (Shadow DOM, <template>, properti khusus CSS, dll.)
  • Terintegrasi erat dengan DevTools browser.
  • Memanfaatkan fitur aksesibilitas yang sudah ada.