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

CKTIS / JavaScript

PointerEvent — eventos de ponteiro e captura

PointerEvent unifica a entrada de rato, toque e caneta. Descubra como os identificadores de ponteiro, as coordenadas da janela de visualização, o ciclo da interação e a captura se combinam na implementação de arrastamentos.

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

new PointerEvent(type, options)
element.addEventListener('pointerdown', handler)
element.setPointerCapture(event.pointerId)
element.releasePointerCapture(event.pointerId)

PointerEvent é uma interface da Web API do navegador que herda de MouseEvent e unifica a entrada de rato, toque e caneta. Não é uma funcionalidade de uma edição específica de ECMAScript. Verifique a disponibilidade com 'PointerEvent' in window; a presença de Node 24 num repositório não comprova o suporte do navegador.

PointerEvent.pointerId identifica um ponteiro ativo; os identificadores podem ser reutilizados posteriormente e não são identificadores permanentes de dispositivos. PointerEvent.isPrimary indica o ponteiro principal do seu tipo, não um único ponteiro global. Assim, o rato e o toque podem ter simultaneamente, cada um, um ponteiro principal. PointerEvent.clientX e PointerEvent.clientY, herdados de MouseEvent, fornecem coordenadas relativas à janela de visualização em píxeis CSS, não coordenadas relativas ao elemento ou à origem do documento.

O ciclo da interação inclui pointerdown, pointermove e a terminação através de pointerup ou pointercancel. Limpe também o estado da interação quando esta for cancelada, por exemplo, se o navegador assumir o controlo de um gesto. pointerover/pointerout e pointerenter/pointerleave descrevem os limites dos elementos; não substituem a terminação da interação.

Ao chamar element.setPointerCapture(event.pointerId) durante um pointerdown real, os eventos seguintes desse ponteiro são encaminhados para o elemento, mesmo fora dos seus limites. gotpointercapture e lostpointercapture assinalam a aquisição e a perda da captura; element.releasePointerCapture(event.pointerId) liberta-a explicitamente. A libertação também ocorre após pointerup ou pointercancel. A entrada por toque pode receber captura implícita. Trate a perda da captura para evitar que um arrastamento permaneça ativo.

Para gestos personalizados, declare o CSS touch-action adequado antes de a interação começar; preventDefault() por si só não impede o deslocamento nem o zoom da janela de visualização. O exemplo envia deliberadamente eventos sintéticos: verifica as propriedades e a limpeza do estado, mas não ativa entrada real de hardware nem a captura do ponteiro.

Exemplos

const target = document.createElement('div');
const active = new Map();
const lines = [];

for (const type of ['pointerdown', 'pointermove', 'pointerup', 'pointercancel']) {
  target.addEventListener(type, (event) => {
    const { pointerId, isPrimary, clientX, clientY } = event;
    if (type === 'pointerdown') active.set(pointerId, true);
    if (!active.has(pointerId)) return;
    lines.push(`${type} ${pointerId} ${isPrimary} ${clientX},${clientY}`);
    if (type === 'pointerup' || type === 'pointercancel') {
      active.delete(pointerId);
    }
  });
}

for (const [type, clientX, clientY] of [
  ['pointerdown', 10, 20],
  ['pointermove', 15, 25],
  ['pointerup', 15, 25]
]) {
  target.dispatchEvent(new PointerEvent(type, {
    pointerId: 7, pointerType: 'touch', isPrimary: true,
    clientX, clientY
  }));
}
console.log(lines.join('\n'));
console.log(`active=${active.size}`);

Resultado

pointerdown 7 true 10,20
pointermove 7 true 15,25
pointerup 7 true 15,25
active=0

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.

Fontes