CKTIS / JavaScript
customElements.define — registrare un elemento personalizzato
customElements.define associa il nome di un elemento a un costruttore nel registro del documento. Scopri la differenza tra elementi personalizzati autonomi ed elementi integrati personalizzati, oltre ai principali vincoli di registrazione.
Versione: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support
Sintassi
customElements.define(name, constructor);
customElements.define(name, constructor, { extends: baseLocalName });customElements.define(name, constructor, options) registra una definizione nel registro accessibile tramite window.customElements e restituisce undefined, non un’istanza né una promessa. È un’API dell’HTML Living Standard, non una funzionalità di una specifica edizione di ECMAScript. Gli elementi personalizzati autonomi sono supportati dai moderni motori dei browser; la presenza di Node 24 in un repository non dimostra che questa API sia disponibile.
Un elemento autonomo usa una classe che estende HTMLElement. Un nome semplice valido, come cktis-greeting, inizia con una lettera ASCII minuscola, contiene un trattino e non contiene lettere ASCII maiuscole; alcuni nomi sono inoltre riservati. La registrazione consente di creare istanze e aggiornare gli elementi corrispondenti già presenti nel documento. Da sola non inserisce un nuovo elemento nel DOM.
La variante { extends: "button" } definisce un elemento integrato personalizzato: la sua classe estende HTMLButtonElement e un’istanza viene creata con document.createElement("button", { is: name }), non con document.createElement(name). Verifica separatamente il supporto di questa variante nei browser di destinazione.
Un nome non valido causa SyntaxError, mentre riutilizzare un nome o un costruttore nello stesso registro causa NotSupportedError; entrambi sono eccezioni DOMException. Un argomento che non è un costruttore causa TypeError. L’esempio imposta il contenuto in connectedCallback, dopo l’aggiunta dell’elemento; non aggiungere figli o attributi nel costruttore. Ricarica il documento prima di eseguirlo di nuovo: rimuovere un’istanza non rimuove la sua definizione.
Esempi
(() => {
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();
})();Risultato
Hello! true
Il codice mostrato e il risultato dichiarato sono stati verificati in un ambiente isolato con il metodo registrato nella prova di verifica di questa versione esatta.