Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

CKTIS / JavaScript

customElements.define — registar um elemento personalizado

customElements.define associa o nome de um elemento a um construtor no registo do documento. Saiba distinguir elementos personalizados autónomos de elementos incorporados personalizados e conheça as principais restrições de registo.

Versão: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Sintaxe

customElements.define(name, constructor);
customElements.define(name, constructor, { extends: baseLocalName });

customElements.define(name, constructor, options) regista uma definição no registo acessível através de window.customElements e devolve undefined, não uma instância nem uma promessa. Esta é uma API do HTML Living Standard, não uma funcionalidade de uma edição específica do ECMAScript. Os elementos personalizados autónomos são suportados pelos motores de navegador modernos; a presença do Node 24 num repositório não comprova que esta API esteja disponível.

Um elemento autónomo utiliza uma classe que estende HTMLElement. Um nome simples válido, como cktis-greeting, começa por uma letra ASCII minúscula, contém um hífen e não contém letras ASCII maiúsculas; alguns nomes também são reservados. O registo permite criar instâncias e atualizar elementos correspondentes que já estejam no documento. Por si só, não insere um elemento novo no DOM.

A variante { extends: "button" } define um elemento incorporado personalizado: a sua classe estende HTMLButtonElement e uma instância é criada com document.createElement("button", { is: name }), não com document.createElement(name). Verifique separadamente o suporte desta variante nos navegadores de destino.

Um nome inválido causa SyntaxError, enquanto reutilizar um nome ou construtor no mesmo registo causa NotSupportedError; ambos são exceções DOMException. Um argumento que não seja um construtor causa TypeError. O exemplo define o conteúdo em connectedCallback, depois de o elemento ser anexado; não adicione filhos nem atributos no construtor. Volte a carregar o documento antes de executar novamente: remover uma instância não remove a sua definição.

Exemplos

(() => {
  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();
})();

Resultado

Hello!
true

O código apresentado e o resultado declarado foram verificados num ambiente isolado pelo método registado na prova de verificação desta versão exata.

Fontes