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

CKTIS / JavaScript

Dimensões naturais da imagem e estado `complete`

Consulta as dimensões naturais de uma imagem em píxeis CSS e distingue o fim de um pedido de um carregamento ou de uma descodificação bem-sucedidos.

Versão: ECMAScript 2024 and the current web platform; runtime support varies

Sintaxe

img.naturalWidth  // number: natural width
img.naturalHeight // number: natural height
img.complete      // boolean: completion state, not success

naturalWidth e naturalHeight são propriedades só de leitura de HTMLImageElement. Devolvem a largura e a altura naturais da imagem atual como números inteiros em píxeis CSS. Têm em conta a densidade de píxeis do recurso selecionado e a orientação indicada nos metadados, pelo que podem diferir das dimensões guardadas no ficheiro. Num elemento apresentado na página, width e height descrevem antes o seu tamanho na página.

Quando as dimensões da imagem atual ainda não estão disponíveis, ambas as propriedades devolvem 0. As dimensões podem ser conhecidas antes de a transferência terminar, pelo que valores positivos não provam que toda a imagem tenha sido carregada ou descodificada. Verifica se ambas as dimensões são positivas antes de calcular img.naturalWidth / img.naturalHeight.

complete é uma propriedade booleana só de leitura. Tem o valor true se faltarem src e srcset, ou se src estiver vazio e srcset estiver ausente. Também tem o valor true se a imagem do pedido atual estiver totalmente disponível ou se o pedido tiver falhado, desde que não haja um pedido de substituição pendente. Nos restantes casos, devolve false. Mostra o estado no momento da leitura, não o sucesso do carregamento.

Regista os manipuladores de load e error antes de definir src para distinguir o sucesso da falha. Se precisares da imagem descodificada, usa await img.decode() depois de definires a origem e trata a rejeição da promessa. Estas API Web pertencem à plataforma do navegador, não ao núcleo do ECMAScript.

Exemplos

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Natural image dimensions and completion</title>
</head>
<body>
<script>
(async () => {
  function report(label, img) {
    console.log(`${label}: ${img.complete} ${img.naturalWidth} ${img.naturalHeight}`);
  }

  async function inspect(src) {
    const img = new Image();
    const eventType = await new Promise((resolve) => {
      img.onload = img.onerror = (event) => resolve(event.type);
      img.src = src;
    });
    report(eventType, img);
  }

  const svg = '<svg xmlns="http://www.w3.org/2000/svg" width="24" height="16"><rect width="24" height="16"/></svg>';
  report('no source', new Image());
  await inspect('data:image/svg+xml,' + encodeURIComponent(svg));
  await inspect('data:image/svg+xml,not-an-svg');
})();
</script>
</body>
</html>

Resultado

no source: true 0 0
load: true 24 16
error: true 0 0

As três linhas mostram uma imagem sem origem, um SVG válido de 24 × 16 e um SVG inválido. `complete` devolve `true` nos três casos. Abre o ficheiro HTML num navegador que permita imagens `data:` e tenha o carregamento de imagens ativado; depois, consulta a consola de programador.

Lições relacionadas

  • JavaScript · Lição 33 · Avançado · Versão: 4

Fontes