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

CKTIS / JavaScript

Arrasto com captura do ponteiro: confirmar ou repor o valor

Separa a pré-visualização do valor confirmado e termina o arrasto uma só vez, mesmo que a captura se perca depois de largares o ponteiro.

Versão: ECMAScript 2024 and the current web platform; runtime support varies

Sintaxe

let drag = null;

// beginDrag saves the pointer ID and a snapshot, then captures the pointer.
// updatePreview changes only the preview for the matching pointer ID.
element.addEventListener('pointerdown', beginDrag);
element.addEventListener('pointermove', updatePreview);
element.addEventListener('pointerup', (event) => settle(event, true));
element.addEventListener('pointercancel', (event) => settle(event, false));
element.addEventListener('lostpointercapture', (event) => settle(event, false));

function settle(event, commit) {
  if (drag === null || event.pointerId !== drag.pointerId) return;
  const current = drag;
  drag = null;
  if (commit) commitPreview(current);
  else restoreSnapshot(current);
}

Trata o arrasto com captura como uma transação. Em pointerdown, guarda o valor inicial e o pointerId, e chama element.setPointerCapture(event.pointerId) para que os eventos seguintes desse ponteiro cheguem ao elemento mesmo fora dos seus limites. Os eventos pointermove com o identificador correspondente só atualizam a pré-visualização. Também pode haver movimento sem contacto ou sem botões premidos. pointermove pode indicar alterações como a pressão, e o navegador pode agrupar várias amostras num evento.

Confirma a pré-visualização apenas em pointerup. Repõe o valor inicial em pointercancel, por exemplo, quando o navegador assume o gesto para deslocar a página, ou em lostpointercapture se o arrasto ainda estiver ativo. Na função de finalização comum, verifica o identificador e limpa o estado ativo antes de confirmar ou repor o valor. Assim, a perda de captura após pointerup ou pointercancel não volta a alterar o resultado. Perder a captura não significa que o ponteiro tenha sido largado.

O toque direto pode iniciar uma captura implícita. setPointerCapture() lança NotFoundError se o identificador não corresponder a um ponteiro ativo. Usa releasePointerCapture() para libertar a captura mais cedo; o navegador liberta-a automaticamente após pointerup ou pointercancel. Define a propriedade CSS touch-action antes do gesto e limita touch-action: none à zona necessária, pois pode bloquear a ampliação por toque.

Estes eventos usam a API Web PointerEvent do navegador e não precisam de ECMAScript 2024. Para um dedo ou a ponta de uma caneta, pointerdown e pointerup marcam o início e o fim do contacto. Com o rato, assinalam a pressão do primeiro botão e a libertação do último, não cada pressão ou libertação como mousedown e mouseup.

Exemplos

const assert = require('node:assert/strict');
const { chromium } = require('playwright');

async function main() {
  const browser = await chromium.launch();
  try {
    const page = await browser.newPage({ viewport: { width: 480, height: 240 } });
    page.on('console', (message) => {
      if (message.type() === 'log') console.log(message.text());
    });
    await page.setContent(`
      <div id="pad" style="position:fixed;top:16px;left:16px;box-sizing:border-box;
        width:180px;height:84px;padding:16px;background:#def;color:#123;
        touch-action:none;user-select:none">Press here, move outside, then release</div>
      <output id="position" data-committed="0"
        style="position:fixed;top:116px;left:16px">0</output>
    `);

    await page.evaluate(() => {
      const pad = document.querySelector('#pad');
      const position = document.querySelector('#position');
      let committed = 0;
      let drag = null;
      let capturedId = null;

      pad.addEventListener('pointerdown', (event) => {
        if (!event.isTrusted || event.button !== 0 || capturedId !== null) return;
        pad.setPointerCapture(event.pointerId);
        capturedId = event.pointerId;
        drag = {
          pointerId: event.pointerId,
          startX: event.clientX,
          snapshot: committed,
          preview: committed,
          loggedMove: false
        };
        console.log(event.type);
      });

      pad.addEventListener('pointermove', (event) => {
        if (drag === null || event.pointerId !== drag.pointerId) return;
        drag.preview = drag.snapshot + event.clientX - drag.startX;
        position.textContent = String(drag.preview);
        if (!drag.loggedMove) {
          drag.loggedMove = true;
          console.log(event.type);
        }
      });

      function settle(event, commit) {
        if (drag === null || event.pointerId !== drag.pointerId) return false;
        const current = drag;
        drag = null;
        if (commit) committed = current.preview;
        position.dataset.committed = String(committed);
        position.textContent = String(commit ? committed : current.snapshot);
        return true;
      }

      pad.addEventListener('pointerup', (event) => {
        if (settle(event, true)) console.log(event.type);
      });
      pad.addEventListener('pointercancel', (event) => {
        if (settle(event, false)) console.log(event.type);
      });
      pad.addEventListener('lostpointercapture', (event) => {
        if (event.pointerId !== capturedId) return;
        capturedId = null;
        settle(event, false);
        console.log(event.type);
      });
    });

    // Drive Chromium's mouse rather than dispatching synthetic pointer events.
    await page.mouse.move(40, 40);
    await page.mouse.down();
    await page.mouse.move(320, 40);
    await page.mouse.move(340, 40);

    const position = page.locator('#position');
    assert.equal(await position.textContent(), '300');
    assert.equal(await position.getAttribute('data-committed'), '0');

    await page.mouse.up();
    assert.equal(await position.getAttribute('data-committed'), '300');
    assert.equal(await position.textContent(), '300');
  } finally {
    await browser.close();
  }
}

main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});

Resultado

pointerdown
pointermove
pointerup
lostpointercapture

Executa o exemplo com Node.js e Playwright conforme as instruções de verificação. O Playwright prime o botão dentro do painel, move o rato para fora e larga o botão nesse ponto. Só é registado o primeiro movimento correspondente. O resultado esperado mostra uma conclusão normal, não um cancelamento nem uma perda antecipada da captura.

Lições relacionadas

  • JavaScript · Lição 35 · Avançado · Versão: 4

Fontes