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.