CKTIS / JavaScript
HTMLCanvasElement: contexto de desenho e dimensões
HTMLCanvasElement disponibiliza uma superfície de desenho no navegador. Saiba como utilizar getContext(), width e height. Num contexto 2D, atribuir um valor a qualquer uma destas propriedades apaga o desenho e repõe o estado do contexto, mesmo que o valor não mude.
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
canvas.getContext(contextType, contextAttributes)
canvas.width = width;
canvas.height = height;HTMLCanvasElement representa um elemento canvas no navegador. O próprio elemento contém a superfície de desenho; um contexto disponibiliza as operações de desenho. Trata-se de uma Web API, não de uma parte de ECMAScript. A presença do Node 24 num repositório não comprova a disponibilidade desta API.
Chame HTMLCanvasElement.getContext numa instância como canvas.getContext("2d") para obter um CanvasRenderingContext2D. Um segundo argumento opcional especifica as definições do contexto. Verifique o resultado: o método devolve null se o tipo não for suportado, se o elemento já tiver outro modo de contexto ou se não for possível criar o contexto. Por exemplo, mesmo que o tipo de contexto WebGL seja suportado, uma chamada com a opção failIfMajorPerformanceCaveat ativada pode devolver null, ao passo que uma nova tentativa no mesmo canvas com a opção desativada pode ser bem-sucedida. Depois de o contexto ser criado com êxito, as chamadas seguintes no mesmo canvas com o mesmo tipo de contexto devolvem o mesmo objeto. Depois de o controlo ser transferido através de transferControlToOffscreen(), o método lança InvalidStateError.
HTMLCanvasElement.width e HTMLCanvasElement.height refletem os atributos das dimensões e determinam o tamanho da superfície de desenho interna. Os valores predefinidos são, respetivamente, 300 e 150. O tamanho de apresentação definido através de CSS é distinto: dimensiona a imagem e pode torná-la desfocada ou distorcida.
Num contexto 2D, atribuir um valor a width ou height limpa a superfície, elimina o caminho atual e repõe os valores predefinidos das definições do contexto, incluindo fillStyle, mesmo quando se atribui o valor atual. Defina as dimensões antes de configurar o contexto 2D e desenhar; após redimensionar, reponha o estado e desenhe novamente. Alterar o tamanho do buffer de desenho do WebGL não repõe o estado do contexto WebGL. Depois de transferir o controlo para um OffscreenCanvas através de transferControlToOffscreen(), atribuir um valor a width ou height no elemento original lança InvalidStateError. A API base está amplamente disponível nos navegadores, mas o suporte para tipos de contexto e opções específicos varia.
Exemplos
(() => {
const canvas = document.createElement("canvas");
console.log(canvas.width, canvas.height);
canvas.width = 4;
canvas.height = 2;
const ctx = canvas.getContext("2d");
if (ctx === null) {
throw new Error("2D context unavailable");
}
console.log(canvas.getContext("2d") === ctx);
ctx.fillStyle = "#ff0000";
ctx.fillRect(0, 0, canvas.width, canvas.height);
canvas.width = canvas.width;
console.log(canvas.width, canvas.height, ctx.fillStyle);
})();Resultado
300 150 true 4 2 #000000
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.