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

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

Fontes