CKTIS / JavaScript
customElements.define — een aangepast element registreren
customElements.define koppelt een elementnaam aan een constructor in het register van het document. Lees meer over het verschil tussen autonome aangepaste elementen en aangepaste ingebouwde elementen, en over de belangrijkste beperkingen bij registratie.
Versie: 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) registreert een definitie in het register dat beschikbaar is via window.customElements en geeft undefined terug, geen instantie of promise. Dit is een API van de HTML Living Standard, geen functie van een bepaalde ECMAScript-editie. Moderne browser-engines ondersteunen autonome aangepaste elementen; de aanwezigheid van Node 24 in een repository bewijst niet dat deze API beschikbaar is.
Een autonoom element gebruikt een klasse die HTMLElement uitbreidt. Een eenvoudige geldige naam, zoals cktis-greeting, begint met een kleine ASCII-letter, bevat een koppelteken en bevat geen hoofdletters uit de ASCII-tekenset; sommige namen zijn ook gereserveerd. Registratie maakt het mogelijk instanties te maken en overeenkomende elementen bij te werken die al in het document staan. De registratie voegt zelf geen nieuw element toe aan de DOM.
De variant { extends: "button" } definieert een aangepast ingebouwd element: de klasse ervan breidt HTMLButtonElement uit en een instantie wordt gemaakt met document.createElement("button", { is: name }), niet met document.createElement(name). Controleer de ondersteuning voor deze variant afzonderlijk in de browsers waarop je mikt.
Een ongeldige naam veroorzaakt SyntaxError; een naam of constructor opnieuw gebruiken in hetzelfde register veroorzaakt NotSupportedError. Beide zijn DOMException-uitzonderingen. Een argument dat geen constructor is, veroorzaakt TypeError. Het voorbeeld stelt de inhoud in connectedCallback in, nadat het element is toegevoegd; voeg geen kinderen of attributen toe in de constructor. Laad het document opnieuw voordat je de code nogmaals uitvoert: een instantie verwijderen verwijdert de definitie niet.
Voorbeelden
(() => {
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();
})();Resultaat
Hello! true
De getoonde code en het opgegeven resultaat zijn in een geïsoleerde omgeving geverifieerd met de methode die in het verificatiebewijs voor exact deze versie is vastgelegd.