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.