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.