Znalostní bázeCentrum zkoušek
CSČeština
Vybrat jazyk13

CKTIS / JavaScript

customElements.define — registrace vlastního prvku

customElements.define přiřadí název prvku ke konstruktoru v registru dokumentu. Seznamte se s rozdílem mezi samostatnými vlastními prvky a upravenými vestavěnými prvky i s hlavními omezeními registrace.

Verze: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Syntaxe

customElements.define(name, constructor);
customElements.define(name, constructor, { extends: baseLocalName });

customElements.define(name, constructor, options) zaregistruje definici v registru dostupném přes window.customElements a vrátí undefined, nikoli instanci nebo příslib. Jde o API standardu HTML Living Standard, nikoli o funkci konkrétní edice ECMAScriptu. Moderní prohlížečové enginy podporují samostatné vlastní prvky; přítomnost Node 24 v repozitáři nedokazuje dostupnost tohoto API.

Samostatný prvek používá třídu dědící z HTMLElement. Jednoduchý platný název, například cktis-greeting, začíná malým písmenem ASCII, obsahuje spojovník a neobsahuje velká písmena ASCII; některé názvy jsou také vyhrazené. Registrace umožňuje vytvářet instance a aktualizovat odpovídající prvky, které už jsou v dokumentu. Sama o sobě nový prvek do DOM nevloží.

Varianta { extends: "button" } definuje upravený vestavěný prvek: jeho třída dědí z HTMLButtonElement a instance se vytvoří pomocí document.createElement("button", { is: name }), nikoli pomocí document.createElement(name). Podporu této varianty ověřte zvlášť v cílových prohlížečích.

Neplatný název způsobí SyntaxError, zatímco opětovné použití názvu nebo konstruktoru ve stejném registru způsobí NotSupportedError; obě chyby jsou výjimky DOMException. Argument, který není konstruktorem, způsobí TypeError. Příklad nastavuje obsah v connectedCallback až po připojení; do konstruktoru nepřidávejte potomky ani atributy. Před dalším spuštěním dokument znovu načtěte: odebráním instance se její definice neodstraní.

Příklady

(() => {
  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();
})();

Výsledek

Hello!
true

Zobrazený kód a uvedený výsledek byly ověřeny v izolovaném prostředí metodou zaznamenanou v dokladu o ověření této přesné verze.

Zdroje