CKTIS / JavaScript
HTMLCanvasElement: contexto de renderização e dimensões do mapa de bits
Escolhe um contexto com `getContext()` e define as dimensões do mapa de bits com `width` e `height`. Ao contrário de uma alteração em CSS, a atribuição limpa o mapa de bits e repõe o estado de desenho em 2D.
Versão: Current web platform; runtime support varies
Sintaxe
canvas.getContext(contextId)
canvas.getContext(contextId, options)
canvas.width
canvas.height
canvas.width = bitmapWidth
canvas.height = bitmapHeightHTMLCanvasElement é uma interface do navegador definida pelo HTML, não pelo ECMAScript 2024. canvas.getContext(contextId, options) recebe um identificador de texto e opções facultativas específicas de cada modo. "2d" seleciona CanvasRenderingContext2D, "bitmaprenderer" seleciona ImageBitmapRenderingContext, "webgl" seleciona WebGLRenderingContext, "webgl2" seleciona WebGL2RenderingContext e "webgpu" seleciona GPUCanvasContext. A disponibilidade dos modos e das opções depende do ambiente de execução.
A primeira chamada bem-sucedida fixa o modo do elemento. Uma nova chamada com o mesmo identificador devolve o mesmo objeto sem aplicar novas opções. Um modo não suportado ou indisponível, ou o pedido de um modo diferente, devolve null. Após uma chamada bem-sucedida a transferControlToOffscreen(), o elemento passa a servir apenas de marcador: chamar getContext() ou atribuir um valor a width ou height lança InvalidStateError.
canvas.width e canvas.height refletem os atributos HTML com os mesmos nomes. Indicam a largura e a altura do mapa de bits como números inteiros não negativos. Se faltar um atributo ou a sua interpretação falhar, aplica-se o valor predefinido correspondente, 300 ou 150. Alterar apenas canvas.style.width ou canvas.style.height muda o tamanho de apresentação, não a resolução do mapa de bits; o redimensionamento visual pode tornar a imagem desfocada.
Em modo 2D, atribuir um valor a qualquer das dimensões, mesmo que seja o valor atual, limpa o mapa de bits e repõe o estado de desenho, incluindo o traçado atual, a transformação e os estilos, sem substituir o contexto. Define as dimensões antes de desenhar; depois de redimensionar, repõe o estado necessário e volta a desenhar. Não pressuponhas o mesmo comportamento nos outros modos.
Desenhar uma imagem de outra origem sem a autorização CORS adequada pode fazer com que o mapa de bits deixe de estar origin-clean. Nesse caso, getImageData() lança SecurityError; redimensionar o mapa de bits 2D elimina o seu conteúdo em vez de expor os píxeis bloqueados.
Exemplos
<!doctype html>
<meta charset="utf-8">
<title>Canvas 2D resize reset</title>
<script>
(() => {
const canvas = document.createElement("canvas");
console.log(`${canvas.width}x${canvas.height}`);
canvas.width = 4;
canvas.height = 3;
console.log(`${canvas.width}x${canvas.height}`);
const ctx = canvas.getContext("2d");
if (ctx === null) throw new Error("2D canvas context unavailable");
ctx.fillRect(0, 0, 1, 1);
ctx.globalAlpha = 0.5;
const alphaAtOrigin = () => ctx.getImageData(0, 0, 1, 1).data[3];
console.log(`${alphaAtOrigin()} ${ctx.globalAlpha}`);
canvas.width = canvas.width;
console.log(`${alphaAtOrigin()} ${ctx.globalAlpha}`);
console.log(canvas.getContext("2d") === ctx);
console.log(canvas.getContext("bitmaprenderer") === null);
})();
</script>Resultado
300x150 4x3 255 0.5 0 1 true true
Guarda o exemplo como ficheiro HTML, abre-o num navegador e consulta os resultados na consola de desenvolvimento. As duas primeiras linhas mostram as dimensões. Atribuir novamente a mesma largura muda o alfa do píxel de `255` para `0` e repõe `globalAlpha` de `0.5` para `1`. Os dois resultados `true` mostram que o contexto se mantém e que outro modo é rejeitado.
Lições relacionadas
- JavaScript · Lição 12 · Avançado · Versão: 4
- JavaScript · Lição 33 · Avançado · Versão: 4
- JavaScript · Lição 34 · Avançado · Versão: 4