CKTIS / JavaScript
Captura do ponteiro: confirmar ou interromper um arrastamento
Acompanha um arrastamento através de `pointerId` e termina-o uma só vez: confirma o resultado ao largar ou descarta-o em caso de cancelamento ou perda antecipada de captura.
Versão: Current web platform; runtime support varies
Sintaxe
// Handler sketch: supply the element and the five callbacks in your application.
element.addEventListener("pointerdown", onDown);
element.addEventListener("pointermove", onMove);
element.addEventListener("pointerup", onUp);
element.addEventListener("pointercancel", onCancel);
element.addEventListener("lostpointercapture", onLostCapture);
// In onDown, after accepting the pointer for the drag:
// element.setPointerCapture(event.pointerId);
// In onMove, only if the active drag should release capture early:
// element.releasePointerCapture(event.pointerId);No início do arrastamento, guarda o pointerId do ponteiro aceite em pointerdown. Este evento ocorre quando é premido o primeiro botão do rato ou quando um dedo ou a ponta da caneta toca na superfície. Atualiza o estado do arrastamento apenas com eventos pointermove que tenham esse identificador. pointermove pode indicar uma alteração da posição ou de outra propriedade, como a pressão, e pode ocorrer sem contacto nem botões premidos.
Chama element.setPointerCapture(pointerId) para continuar a acompanhar o arrastamento fora do elemento. O toque direto pode ativar implicitamente a captura. Se precisares de a libertar antecipadamente, usa releasePointerCapture(). Ambos os métodos podem lançar NotFoundError se o identificador não corresponder a um ponteiro ativo.
Confirma o resultado em pointerup: levanta-se o dedo ou a caneta, ou larga-se o último botão do rato que estava premido. Ao contrário de mousedown e mouseup, pointerdown e pointerup não ocorrem a cada mudança de estado de um botão. Descarta o estado temporário em pointercancel: o navegador interrompeu a interação, por exemplo para assumir o controlo de um gesto de deslocamento ou zoom.
Em ambos os casos, limpa o identificador guardado para que a libertação automática da captura após pointerup ou pointercancel não termine o arrastamento uma segunda vez. lostpointercapture indica que se perdeu a captura, não necessariamente que o contacto terminou. Interrompe o arrastamento apenas se ainda estiver ativo e o evento tiver o mesmo identificador.
A captura não bloqueia os gestos do navegador: configura-os antecipadamente com a propriedade CSS touch-action e limita none à área que precisa desse valor. Estas API pertencem à plataforma Web, não ao ECMAScript 2024; a disponibilidade depende do ambiente de execução.
Exemplos
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Drag with pointer capture</title>
<style>
#pad {
position: fixed;
top: 16px;
left: 16px;
z-index: 9999;
width: 220px;
height: 100px;
padding: 12px;
background: #def;
color: #123;
border: 2px solid #246;
touch-action: none;
user-select: none;
}
</style>
</head>
<body>
<div id="pad">Start dragging here</div>
<script>
(() => {
const pad = document.getElementById('pad');
let activeId = null;
let moved = false;
pad.addEventListener('pointerdown', (event) => {
if (activeId !== null || event.button !== 0) return;
pad.setPointerCapture(event.pointerId);
activeId = event.pointerId;
moved = false;
console.log('pointerdown');
});
pad.addEventListener('pointermove', (event) => {
if (event.pointerId !== activeId) return;
if (!moved) {
moved = true;
console.log('pointermove');
}
if (event.shiftKey && pad.hasPointerCapture(event.pointerId)) {
pad.releasePointerCapture(event.pointerId);
}
});
function finish(event, result) {
if (event.pointerId !== activeId) return;
activeId = null;
console.log(`${event.type}: ${result}`);
}
pad.addEventListener('pointerup', (event) => finish(event, 'commit'));
pad.addEventListener('pointercancel', (event) => finish(event, 'abort'));
pad.addEventListener('lostpointercapture', (event) => finish(event, 'abort'));
})();
</script>
</body>
</html>Resultado
pointerdown pointermove pointerup: commit
Guarda o exemplo num ficheiro HTML, abre-o num navegador e observa a consola de desenvolvimento. Começa a arrastar dentro da caixa com o botão principal do rato e larga-o fora sem premir Shift. Noutro arrastamento, inicia o movimento, mantém a tecla Shift premida e continua a mover o rato sem largar o botão para testar a perda antecipada da captura. A linha `pointermove` aparece no máximo uma vez por arrastamento.
Lições relacionadas
- JavaScript · Lição 35 · Intermédio · Versão: 3