CKTIS / JavaScript
PointerEvent: identificador do ponteiro e coordenadas da área de visualização
`pointerId` distingue ponteiros ativos em simultâneo; `clientX` e `clientY` indicam a posição do evento na área de visualização, em píxeis CSS.
Versão: Current web platform; runtime support varies
Sintaxe
event.pointerId
event.clientX
event.clientYpointerId, clientX e clientY são propriedades só de leitura de uma instância de PointerEvent. pointerId é um identificador numérico que distingue um ponteiro dos outros que estão ativos em simultâneo, por exemplo, dois dedos no ecrã. Um identificador pode ser reutilizado após o fim de uma interação. Não o uses como identificador permanente do dispositivo nem infiras a partir dele o tipo de dispositivo. Nos eventos gerados pelo navegador, -1 indica que o evento não foi gerado por um dispositivo apontador, como quando se ativa um botão com o teclado.
clientX (horizontal) e clientY (vertical) são herdadas de MouseEvent, mesmo em interações por toque ou com uma caneta. Indicam a posição do evento em píxeis CSS a partir do canto superior esquerdo da área de visualização (viewport) e aumentam, respetivamente, para a direita e para baixo. Ao contrário de pageX e pageY, não são relativas ao documento. Também não são relativas ao elemento de destino nem ao ecrã. Deslocar o documento altera as coordenadas de um ponto fixo do documento na área de visualização, mas não a origem dessa área.
Para acompanhar várias interações, guarda em pointerdown cada posição inicial num Map, usando pointerId como chave. Em pointermove, procura essa chave e ignora o evento se não houver uma entrada. Elimina a entrada tanto em pointerup como em pointercancel. PointerEvent e as propriedades de coordenadas herdadas de MouseEvent fazem parte das API da plataforma web. Nem estas propriedades nem o exemplo requerem ECMAScript 2024. A disponibilidade das API depende do ambiente de execução.
Exemplos
(() => {
const target = new EventTarget();
const starts = new Map();
target.addEventListener("pointerdown", ({ pointerId, clientX, clientY }) => {
starts.set(pointerId, { x: clientX, y: clientY });
});
target.addEventListener("pointermove", ({ pointerId, clientX, clientY }) => {
const start = starts.get(pointerId);
if (!start) return;
console.log(`${pointerId}: dx=${clientX - start.x}, dy=${clientY - start.y}`);
});
const end = ({ pointerId }) => { starts.delete(pointerId); };
target.addEventListener("pointerup", end);
target.addEventListener("pointercancel", end);
const send = (type, pointerId, clientX, clientY) => {
const fields = { pointerId, clientX, clientY };
// Without PointerEvent, use a plain Event to exercise the same listeners.
const event = typeof PointerEvent === "function"
? new PointerEvent(type, fields)
: Object.assign(new Event(type), fields);
target.dispatchEvent(event);
};
send("pointerdown", 7, 100, 80);
send("pointerdown", 8, 200, 150);
send("pointermove", 7, 112, 75);
send("pointermove", 8, 197, 159);
send("pointercancel", 8, 197, 159);
send("pointermove", 8, 198, 160);
send("pointerup", 7, 112, 75);
console.log(`tracked=${starts.size}`);
})();Resultado
7: dx=12, dy=-5 8: dx=-3, dy=9 tracked=0
Executa o código em Node.js ou na consola de um navegador. Se `PointerEvent` não estiver disponível, o código envia objetos `Event` simples com os três campos aos mesmos gestores de eventos. Os eventos sintéticos têm `isTrusted === false` e não movem um ponteiro físico. O código apresenta o deslocamento desde o início de cada interação. O movimento do ponteiro `8` após o cancelamento é ignorado; `tracked=0` indica que já não há entradas.
Lições relacionadas
- JavaScript · Lição 35 · Avançado · Versão: 4