Base de conocimientosCentro de exámenes
ESEspañol
Elegir idioma13

CKTIS / JavaScript

Arrastre con captura del puntero: confirmar o revertir cambios

Separa la vista previa del valor confirmado y finaliza el arrastre una sola vez, incluso si la captura se pierde después de soltar el puntero.

Versión: ECMAScript 2024 and the current web platform; runtime support varies

Sintaxis

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 el arrastre con captura como una transacción. En pointerdown, guarda el valor inicial y el pointerId, y llama a element.setPointerCapture(event.pointerId) para que los siguientes eventos de ese puntero lleguen al elemento incluso fuera de sus límites. Los eventos pointermove que coincidan solo actualizan la vista previa. El puntero también puede moverse sin pulsar ni tocar; pointermove puede indicar cambios como los de presión, y el navegador puede agrupar varias muestras en un evento.

Confirma la vista previa solo en pointerup. Restaura el valor inicial en pointercancel, por ejemplo, si el navegador toma el control del gesto para desplazar la página, o en lostpointercapture si el arrastre sigue activo. En la función de finalización compartida, comprueba el identificador y borra el estado activo antes de confirmar o restaurar el valor. Así, perder la captura después de pointerup o pointercancel no vuelve a cambiar el resultado. Perder la captura no significa que se haya soltado el puntero.

El contacto táctil directo puede iniciar una captura implícita. setPointerCapture() lanza NotFoundError si el identificador no corresponde a un puntero activo. Usa releasePointerCapture() para liberar antes la captura; el navegador la libera automáticamente tras pointerup o pointercancel. Define la propiedad CSS touch-action antes del gesto y limita touch-action: none a la zona necesaria, ya que puede bloquear el zoom táctil.

Estos eventos usan la API web PointerEvent del navegador y no requieren ECMAScript 2024. Para el dedo o la punta de un lápiz, pointerdown y pointerup marcan el inicio y el fin del contacto. Con el ratón, indican la pulsación del primer botón y la liberación del último, no cada pulsación o liberación como mousedown y mouseup.

Ejemplos

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

Ejecuta el ejemplo con Node.js y Playwright como se indica en las instrucciones de verificación. Playwright pulsa dentro del panel, mueve el ratón fuera y suelta el botón allí. Solo se registra el primer movimiento que coincide. La salida esperada muestra una finalización normal, no una cancelación ni una pérdida anticipada de la captura.

Lecciones relacionadas

  • JavaScript · Lección 35 · Avanzado · Versión: 4

Fuentes