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

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.

Fontes