CKTIS / JavaScript
customElements.define — rejestrowanie elementu niestandardowego
customElements.define wiąże nazwę elementu z konstruktorem w rejestrze dokumentu. Poznaj różnicę między elementem autonomicznym a rozszerzeniem elementu wbudowanego oraz najważniejsze ograniczenia rejestracji.
Wersja: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support
Składnia
customElements.define(name, constructor);
customElements.define(name, constructor, { extends: baseLocalName });customElements.define(name, constructor, options) rejestruje definicję w rejestrze dostępnym przez window.customElements i zwraca undefined, nie instancję ani obietnicę. To API standardu HTML Living Standard, a nie funkcja określonej edycji ECMAScript. Autonomiczne elementy niestandardowe są obsługiwane przez współczesne silniki przeglądarek; obecność Node 24 w repozytorium nie dowodzi dostępności tego API.
Element autonomiczny używa klasy dziedziczącej po HTMLElement. Prosta poprawna nazwa, np. cktis-greeting, zaczyna się małą literą ASCII, zawiera łącznik i nie zawiera wielkich liter ASCII; istnieją też nazwy zastrzeżone. Rejestracja umożliwia tworzenie instancji i uaktualnianie pasujących elementów już obecnych w dokumencie. Sama nie wstawia nowego elementu do DOM.
Wariant { extends: "button" } definiuje rozszerzony element wbudowany: klasa dziedziczy po HTMLButtonElement, a instancję tworzy się przez document.createElement("button", { is: name }), nie przez document.createElement(name). Wsparcie tego wariantu należy sprawdzić osobno w docelowych przeglądarkach.
Niepoprawna nazwa powoduje SyntaxError, a ponowne użycie nazwy lub konstruktora w tym samym rejestrze — NotSupportedError; obie są wyjątkami DOMException. Argument niebędący konstruktorem powoduje TypeError. Przykład ustawia treść w connectedCallback, po dołączeniu elementu; nie dodawaj dzieci ani atrybutów w konstruktorze. Przed ponownym uruchomieniem przeładuj dokument: usunięcie instancji nie usuwa definicji.
Przykłady
(() => {
class CktisGreeting extends HTMLElement {
connectedCallback() {
this.textContent = "Hello!";
}
}
customElements.define("cktis-greeting", CktisGreeting);
const element = document.createElement("cktis-greeting");
document.body.append(element);
console.log(element.textContent);
console.log(element instanceof CktisGreeting);
element.remove();
})();Wynik
Hello! true
Wyświetlony kod i zadeklarowany wynik zweryfikowano w odizolowanym środowisku metodą zapisaną w dowodzie weryfikacji tej dokładnej wersji.