CKTIS / JavaScript
customElements.define — ein benutzerdefiniertes Element registrieren
customElements.define verknüpft einen Elementnamen im Dokumentregister mit einem Konstruktor. Erfahre, worin sich autonome benutzerdefinierte Elemente und angepasste eingebaute Elemente unterscheiden und welche wichtigen Einschränkungen bei der Registrierung gelten.
Version: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support
Syntax
customElements.define(name, constructor);
customElements.define(name, constructor, { extends: baseLocalName });customElements.define(name, constructor, options) registriert eine Definition im Register, das über window.customElements verfügbar ist, und gibt undefined zurück, keine Instanz und kein Promise. Dies ist eine API des HTML Living Standard und keine Funktion einer bestimmten ECMAScript-Version. Autonome benutzerdefinierte Elemente werden von modernen Browser-Engines unterstützt; dass sich Node 24 in einem Repository befindet, belegt nicht, dass diese API verfügbar ist.
Ein autonomes Element verwendet eine Klasse, die HTMLElement erweitert. Ein einfacher gültiger Name wie cktis-greeting beginnt mit einem kleingeschriebenen ASCII-Buchstaben, enthält einen Bindestrich und keine großgeschriebenen ASCII-Buchstaben; einige Namen sind außerdem reserviert. Die Registrierung ermöglicht das Erstellen von Instanzen und das Aktualisieren passender Elemente, die bereits im Dokument vorhanden sind. Sie fügt selbst kein neues Element in das DOM ein.
Die Variante { extends: "button" } definiert ein angepasstes eingebautes Element: Seine Klasse erweitert HTMLButtonElement, und eine Instanz wird mit document.createElement("button", { is: name }) erstellt, nicht mit document.createElement(name). Prüfe die Unterstützung dieser Variante in deinen Zielbrowsern separat.
Ein ungültiger Name verursacht SyntaxError; die Wiederverwendung eines Namens oder Konstruktors im selben Register verursacht NotSupportedError. Beide sind DOMException-Ausnahmen. Ein Argument, das kein Konstruktor ist, verursacht TypeError. Das Beispiel setzt den Inhalt in connectedCallback, nachdem das Element eingefügt wurde; füge im Konstruktor keine Kinder oder Attribute hinzu. Lade das Dokument neu, bevor du es erneut ausführst: Das Entfernen einer Instanz entfernt nicht ihre Definition.
Beispiele
(() => {
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();
})();Ergebnis
Hello! true
Der angezeigte Code und das angegebene Ergebnis wurden in einer isolierten Umgebung mit der im Prüfnachweis für genau diese Version dokumentierten Methode verifiziert.