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

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 = bitmapHeight

HTMLCanvasElement é 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

Fontes