Base di conoscenzaCentro esami
ITItaliano
Scegli la lingua13

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.

Fonti