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

CKTIS / JavaScript

Window.getComputedStyle — ler estilos resolvidos

Window.getComputedStyle lê os valores CSS resolvidos de um elemento depois de aplicar as folhas de estilo. Devolve um objeto vivo e só de leitura, não uma cópia das declarações inline.

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

window.getComputedStyle(element)
window.getComputedStyle(element, pseudoElt)

Window.getComputedStyle, chamada como window.getComputedStyle(element, pseudoElt), é uma API do browser CSSOM, não uma função ECMAScript. O método é amplamente suportado; a presença do Node 24 não confirma a sua disponibilidade. element tem de ser um objeto Element. O argumento opcional pseudoElt, como "::before", seleciona um pseudoelemento; se for omitido ou for null, refere-se ao próprio elemento.

O resultado contém valores resolvidos: normalmente valores calculados, mas valores usados para algumas propriedades dependentes do layout. Não tem necessariamente de preservar a notação original da folha de estilo. A leitura das propriedades devolve cadeias de caracteres. Element.computedStyleMap() é diferente: expõe valores calculados como objetos tipados, em vez de cadeias de caracteres resolvidas.

O CSSStyleProperties devolvido herda de CSSStyleDeclaration; as especificações anteriores indicavam este último tipo. Lê valores, por exemplo, com styles.marginLeft ou styles.getPropertyValue('margin-left'). O objeto é vivo: uma leitura posterior reflete uma alteração de estilo. Para guardar uma captura, guarda a cadeia de caracteres lida. O resultado é só de leitura; altera os estilos através de element.style, que representa declarações inline e não o resultado das folhas de estilo.

Um argumento element inválido causa um TypeError. De acordo com o algoritmo do CSSOM, o método só tenta interpretar uma cadeia de caracteres passada em pseudoElt como seletor de pseudoelemento se começar por :. Se a análise sintática falhar ou se o seletor indicar ::part() ou ::slotted(), o algoritmo devolve um objeto de estilo com uma lista de declarações vazia. Segundo esse algoritmo, uma cadeia que não comece por dois pontos, como "before", é ignorada: o método lê os estilos do próprio elemento. A documentação do método na MDN indica, pelo contrário, que é lançado um TypeError para seletores de pseudoelemento inválidos e para ::part() e ::slotted(). Por motivos de privacidade, os valores relativos a :visited podem ser deliberadamente imprecisos — não uses este método para detetar o histórico de navegação.

Exemplos

(() => {
  const frame = document.createElement('iframe');
  document.body.append(frame);
  try {
    const doc = frame.contentDocument;
    const box = doc.createElement('div');
    box.style.cssText = 'margin-left: 12px;';
    doc.body.append(box);

    const styles = frame.contentWindow.getComputedStyle(box);
    console.log(styles.getPropertyValue('margin-left'));
    box.style.marginLeft = '24px';
    console.log(styles.marginLeft);
  } finally {
    frame.remove();
  }
})();

Resultado

12px
24px

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