Definiowanie elementów za pomocą customElements.define

Niestandardowe elementy pozwalają tworzyć własne tagi HTML obsługiwane przez klasę JavaScript. Po zdefiniowaniu element <my-card> zachowuje się jak każdy wbudowany element: można zapisać go w HTML, wyszukiwać, stylizować, obsługiwać za pomocą skryptów i używać w niezmienionej postaci we frameworkach.

Każda nazwa niestandardowego elementu musi zawierać co najmniej jeden łącznik — user-avatar, app-button, my-card. Łącznik odróżnia niestandardowe elementy od obecnych i przyszłych wbudowanych tagów HTML, a jego użycie jest wymagane przez specyfikację.

Niestandardowy element jest klasą rozszerzającą HTMLElement (lub wbudowaną klasę potomną). Klasa może deklarować konstruktor i metody cyklu życia. Publiczne właściwości i metody klasy stają się interfejsem skryptowym elementu.

customElements.define("my-card", MyCard) rejestruje klasę pod nazwą tagu. Po rejestracji każdy istniejący i przyszły element <my-card> w dokumencie zostaje uaktualniony do instancji tej klasy.

Konstruktor musi wywołać super() jako pierwszą instrukcję, zanim uzyska dostęp do this. Pominięcie super() powoduje błąd „Failed to construct 'HTMLElement'”. Należy traktować to jako standardową regułę konstruktora klasy JavaScript.

Konstruktor nie może odczytywać atrybutów ani elementów potomnych elementu — w chwili tworzenia mogą one nie być jeszcze sparsowane. Konfigurację korzystającą z DOM należy przenieść do connectedCallback, który jest wywoływany dopiero po umieszczeniu elementu w dokumencie.

Nazwę elementu można zarejestrować tylko raz na stronę. Ponowna definicja tej samej nazwy powoduje błąd NotSupportedError. Aby testować zmiany podczas tworzenia, należy ponownie załadować stronę; w produkcji każdy komponent należy rejestrować raz podczas uruchamiania.

Niestandardowe elementy są dostępne we wszystkich nowoczesnych przeglądarkach. W bardzo starych przeglądarkach (w większości już nieużywanych) polyfill webcomponents.js zapewnia rozwiązanie awaryjne. W nowych projektach można korzystać z natywnej obsługi i całkowicie pominąć polyfill.

customElements.get("my-card") zwraca klasę, jeśli została zdefiniowana, a w przeciwnym razie undefined. customElements.whenDefined("my-card") zwraca obietnicę, która zostaje rozstrzygnięta po zarejestrowaniu elementu — jest to przydatne w kodzie, który musi zaczekać na definicje ładowane z opóźnieniem.

Po zdefiniowaniu elementu używaj go dokładnie tak jak wbudowanego tagu: zapisz go w HTML (<my-card></my-card>), utwórz za pomocą document.createElement("my-card") albo utwórz instancję za pomocą new MyCard() i wstaw ją do dokumentu. Wszystkie trzy ścieżki tworzą tę samą uaktualnioną instancję.

Niestandardowe elementy należy poprzedzać nazwą projektu lub firmy (cd-card, app-modal), aby uniknąć kolizji z innymi bibliotekami na tej samej stronie. Ekosystem komponentów internetowych jest niezależny od bundlera — każdy element na stronie może zarejestrować dowolną nazwę, a pierwsza rejestracja ma pierwszeństwo.

Niestandardowe elementy to klasy JavaScript rozszerzające HTMLElement, rejestrowane za pomocą customElements.define("name", Class), przy czym nazwa musi zawierać łącznik. Konstruktor musi najpierw wywołać super() i nie może odczytywać DOM; prace z DOM należy odroczyć do connectedCallback. Zdefiniowane elementy zachowują się wszędzie dokładnie tak jak wbudowane tagi.