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

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.clientY

pointerId, 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

Fontes