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 successnaturalWidth 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