CKTIS / JavaScript
Web Components: elementos personalizados e ciclo de vida
Os Web Components são mecanismos da plataforma Web para criar elementos de interface personalizados. Aprende a registar uma classe que estende HTMLElement, a responder à ligação e à desligação e a observar atributos. São APIs do browser, não funcionalidades fornecidas pelo próprio ECMAScript.
Versão: Web-platform APIs, not tied to an ECMAScript edition. The example's exact console output was verified in isolated Chromium 157.0.8103.51 only; this does not establish broader browser compatibility. Node 24 in the repository does not establish browser API support.
Sintaxe
class ExampleElement extends HTMLElement {
static get observedAttributes() { return ['label']; }
connectedCallback() { /* initialize or resume */ }
disconnectedCallback() { /* release external resources */ }
attributeChangedCallback(name, oldValue, newValue) { /* react to an observed attribute */ }
}
customElements.define('example-element', ExampleElement);Os Web Components incluem elementos personalizados (custom elements), Shadow DOM, templates e slots. Estes mecanismos podem ser combinados, mas um elemento personalizado não precisa de Shadow DOM. Um elemento personalizado autónomo é uma instância de uma classe que estende HTMLElement. customElements.define() regista o construtor dessa classe com o nome do elemento. Um nome válido tem de conter um hífen, como cktis-greeting.
No construtor, chama super() antes de usar this; é possível criar aí uma shadow root com attachShadow(). connectedCallback() trata da ligação ao documento, enquanto disconnectedCallback() trata da desligação. A ligação pode ocorrer várias vezes: evita duplicar listeners ou temporizadores e liberta os recursos externos quando o elemento é desligado. Shadow DOM encapsula a estrutura e os estilos, mas não é uma fronteira de segurança.
A propriedade estática observedAttributes especifica os nomes dos atributos observados. attributeChangedCallback(name, oldValue, newValue) reage à sua adição, alteração ou remoção; pode ser executado antes de o elemento estar ligado. Um valor em falta é representado por null. Alterar uma propriedade JavaScript normal não altera automaticamente um atributo. O exemplo usa textContent para apresentar texto sem o interpretar como HTML.
As fontes indicadas centram-se nos elementos personalizados e em HTMLElement: a norma HTML do WHATWG define os elementos personalizados, e a documentação da MDN descreve HTMLElement e explica como utilizar os elementos personalizados. O resultado exato do exemplo na consola foi verificado apenas numa instância isolada do Chromium 157.0.8103.51. Isto não comprova a compatibilidade com outros browsers ou versões; verifica se os browsers de destino suportam estas APIs. Nenhuma edição de ECMAScript garante, por si só, os Web Components; a presença do Node 24 no repositório também não comprova a disponibilidade das APIs. O exemplo requer um ambiente de browser.
Exemplos
(() => {
class CktisGreeting extends HTMLElement {
static get observedAttributes() {
return ['label'];
}
constructor() {
super();
this.attachShadow({ mode: 'open' });
}
connectedCallback() {
this.render();
}
disconnectedCallback() {
console.log('disconnected');
}
attributeChangedCallback(name, oldValue, newValue) {
if (oldValue !== newValue) this.render();
}
render() {
this.shadowRoot.textContent = `Hello, ${this.getAttribute('label') ?? 'world'}!`;
}
}
if (customElements.get('cktis-greeting')) {
throw new Error('Reload the page before running this example again.');
}
customElements.define('cktis-greeting', CktisGreeting);
const element = document.createElement('cktis-greeting');
document.body.append(element);
console.log(element.shadowRoot.textContent);
element.setAttribute('label', 'Ada');
console.log(element.shadowRoot.textContent);
element.remove();
})();Resultado
Hello, world! Hello, Ada! disconnected
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.