Atributos observados e attributeChangedCallback

Os elementos HTML expõem seu estado por meio de atributos. Para reagir quando <my-card name="A"> se torna name="B", declare a lista de atributos observados e implemente attributeChangedCallback na classe.

Declare os atributos relevantes por meio de um acessador estático: static get observedAttributes() { return ["name", "open"]; }. Somente os atributos dessa lista acionam o retorno de chamada; os demais são ignorados para melhorar o desempenho.

attributeChangedCallback(name, oldValue, newValue) é acionado para cada mudança em um atributo observado. Os três parâmetros são cadeias de caracteres, ou nulos se o atributo estiver ausente. Use-os para atualizar o estado interno e executar o render.

O retorno de chamada é acionado uma vez para cada atributo observado que está presente quando o elemento é atualizado. Isso significa que um render em attributeChangedCallback trata tanto dos renders iniciais quanto dos posteriores, sem exigir um caminho separado em connectedCallback.

Para atributos booleanos, espelhe a propriedade no atributo e vice-versa: definir element.open = true deve definir o atributo open, e remover o atributo deve limpar a propriedade. Esse comportamento corresponde ao de elementos nativos como <details>.

Se attributeChangedCallback definir atributos que ele observa, o código poderá entrar em um loop infinito. Sempre proteja o código com if (oldValue === newValue) return; no início do retorno de chamada e evite alterar atributos observados dentro dele.

Por convenção do HTML, os atributos booleanos são “definidos” pela presença (disabled, open) e “não definidos” pela ausência. O valor deles é ignorado — disabled="false" ainda significa que o elemento está desativado. Verifique a presença com hasAttribute; nunca compare a cadeia de caracteres.

Os atributos são cadeias de caracteres. Para passar dados estruturados, use JSON.stringify na marcação e faça a análise em attributeChangedCallback: <my-chart data-points='[1,2,3]'>. Para grandes volumes de dados, prefira passá-los por meio da atribuição de uma propriedade JS.

O senhor poderia observar mudanças nos atributos com um MutationObserver, mas observedAttributes + attributeChangedCallback é mais rápido, pois não exige a configuração de um observador, é declarativo, já que a lista de nomes observados fica visível na classe, e segue o padrão dos componentes web.

Vários atributos alterados em rápida sucessão acionariam vários retornos de chamada e vários renders. Agrupe-os com queueMicrotask ou requestAnimationFrame para que o render real seja executado uma vez por microtarefa ou quadro, independentemente de quantos atributos tenham mudado.

Esquecer de adicionar um atributo a observedAttributes desativa silenciosamente o retorno de chamada para esse atributo. Se o componente não reagir a uma chamada de setAttribute, a primeira coisa a verificar é a lista de observedAttributes estáticos.

O que acontece se o senhor chamar attributeChangedCallback indiretamente ao definir um atributo observado dentro do próprio retorno de chamada?

Declare quais atributos devem ser acompanhados por meio do acessador estático observedAttributes; attributeChangedCallback(name, oldValue, newValue) é acionado para cada mudança, inclusive durante a análise inicial. Espelhe propriedades em atributos para estados booleanos, evite loops infinitos e agrupe os renders com requestAnimationFrame para melhorar o desempenho.