CKTIS / JavaScript
Canvas 2D: transformações, retângulos e caminhos
Distingue a transformação, os píxeis e o caminho predefinido. Aprende quando se transformam as coordenadas, que chamadas alteram logo os píxeis e o que fica após `stroke()`.
Versão: ECMAScript 2024 and the current web platform; runtime support varies
Sintaxe
ctx.setTransform(a, b, c, d, e, f)
ctx.setTransform(matrix)
ctx.setTransform()
ctx.clearRect(x, y, width, height)
ctx.fillRect(x, y, width, height)
ctx.beginPath()
ctx.moveTo(x, y)
ctx.lineTo(x, y)
ctx.stroke()
ctx.stroke(path)CanvasRenderingContext2D é uma interface de uma API Web, não de ECMAScript 2024. Invoca os métodos no contexto ctx devolvido por canvas.getContext('2d'), que pode ser null. O suporte das diferentes formas de chamada depende do ambiente de execução. Os sete métodos devolvem undefined numa chamada normal.
setTransform(a, b, c, d, e, f) substitui a matriz atual, ao contrário de transform(), que a multiplica. O ponto (x, y) passa a (a*x + c*y + e, b*x + d*y + f). A sobrecarga com objeto aceita um dicionário para uma matriz 2D (DOMMatrix2DInit): os componentes omitidos assumem os valores da matriz identidade e valores incompatíveis para dois nomes equivalentes, como a e m11, provocam TypeError. A norma permite chamar o método sem argumentos para repor a identidade. Na sobrecarga com seis números, se algum argumento for NaN ou infinito, a matriz atual mantém-se inalterada. A sobrecarga com dicionário cria uma DOMMatrix a partir de um dicionário válido e define-a como matriz atual sem essa verificação.
fillRect(x, y, width, height) pinta imediatamente um retângulo com fillStyle. Com os mesmos parâmetros, clearRect() limpa os píxeis para preto transparente (preto opaco com alpha: false), independentemente do estilo, de globalAlpha e do modo de composição. Ambos respeitam a transformação e a região de recorte atuais sem alterar o caminho. Uma dimensão nula não tem efeito; uma dimensão negativa prolonga o retângulo no sentido oposto a partir de (x, y).
beginPath() esvazia o caminho predefinido sem apagar píxeis. moveTo(x, y) inicia um novo subcaminho sem o ligar ao anterior. lineTo(x, y) acrescenta um segmento reto a partir do último ponto; se não houver subcaminho, apenas fixa o ponto inicial. Nenhum destes três métodos pinta. moveTo(), lineTo() e ambos os métodos de retângulo ignoram chamadas com coordenadas ou dimensões infinitas ou NaN.
stroke() pinta o contorno do caminho predefinido com strokeStyle e definições de linha como lineWidth. Não fecha subcaminhos abertos nem esvazia o caminho. As coordenadas do caminho predefinido são transformadas ao serem adicionadas, não novamente ao pintar; a matriz atual ainda afeta o traço, por exemplo a sua espessura. Com stroke(path), a geometria do Path2D fornecido é transformada ao pintar, sem modificar o objeto. save() e restore() guardam e restauram o estado de desenho, incluindo a matriz, mas não o caminho predefinido nem os píxeis.
Exemplos
<!doctype html>
<meta charset="utf-8">
<title>Canvas 2D</title>
<canvas id="demo" width="32" height="24" hidden></canvas>
<script>
(() => {
const canvas = document.getElementById('demo');
const ctx = canvas.getContext('2d');
if (!ctx) throw new Error('Canvas 2D is unavailable');
ctx.setTransform(1, 0, 0, 1, 8, 4);
ctx.fillStyle = '#000';
ctx.fillRect(0, 0, 16, 8);
ctx.beginPath();
ctx.moveTo(2, 12);
ctx.lineTo(14, 12);
ctx.clearRect(0, 0, 4, 8);
ctx.setTransform(1, 0, 0, 1, 0, 0);
ctx.strokeStyle = '#000';
ctx.lineWidth = 4;
ctx.stroke();
const alphaAt = (x, y) => ctx.getImageData(x, y, 1, 1).data[3];
console.log([alphaAt(9, 6), alphaAt(15, 6), alphaAt(15, 16), alphaAt(5, 12)].join(', '));
})();
</script>Resultado
0, 255, 255, 0
Guarda o exemplo como ficheiro HTML, abre-o num navegador e consulta a consola. Os valores alfa esperados `0, 255, 255, 0` correspondem à zona limpa, ao preenchimento restante, ao segmento deslocado e a um ponto intacto no referencial sem deslocamento. `getImageData()` lê em coordenadas do mapa de bits. As definições de privacidade podem alterar o resultado; a leitura de um canvas contaminado por conteúdo não autorizado de outra origem pode lançar `SecurityError`.
Lições relacionadas
- JavaScript · Lição 34 · Avançado · Versão: 4
Fontes
- HTML Standard — The canvas settings
- HTML Standard — The canvas state
- HTML Standard — Building paths
- HTML Standard — Transformations
- HTML Standard — Drawing rectangles to the bitmap
- HTML Standard — Drawing paths to the canvas
- CanvasRenderingContext2D: setTransform() method
- CanvasRenderingContext2D: getImageData() method