Baza wiedzyCentrum egzaminacyjne
PLPolski
Wybierz język13

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.

Źródła