CKTIS / JavaScript
Trascinamento con cattura del puntatore: confermare o ripristinare il valore
Separa l’anteprima dal valore confermato e concludi il trascinamento una sola volta, anche se la cattura si perde dopo il rilascio.
Versione: ECMAScript 2024 and the current web platform; runtime support varies
Sintassi
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);
}Tratta il trascinamento con cattura come una transazione. Su pointerdown memorizza il valore iniziale e il pointerId, poi chiama element.setPointerCapture(event.pointerId) per inviare all’elemento gli eventi successivi di quel puntatore anche fuori dai suoi confini. Gli eventi pointermove con l’identificatore corrispondente aggiornano solo l’anteprima. Il puntatore può muoversi anche senza contatto o pulsanti premuti; pointermove può segnalare variazioni come quelle della pressione e il browser può unire più campioni in un evento.
Conferma l’anteprima solo su pointerup. Ripristina il valore iniziale su pointercancel, per esempio se il browser prende il controllo del gesto per scorrere la pagina, oppure su lostpointercapture se il trascinamento è ancora attivo. Nella funzione di chiusura condivisa, controlla l’identificatore e azzera lo stato attivo prima di confermare o ripristinare il valore. In questo modo la perdita della cattura dopo pointerup o pointercancel non cambia di nuovo il risultato. Perdere la cattura non significa che il puntatore sia stato rilasciato.
Il tocco diretto può avviare la cattura implicita. setPointerCapture() genera NotFoundError se l’identificatore non corrisponde a un puntatore attivo. Usa releasePointerCapture() per rilasciare la cattura in anticipo; il browser la rilascia automaticamente dopo pointerup o pointercancel. Imposta la proprietà CSS touch-action prima del gesto e limita touch-action: none all’area necessaria, perché può bloccare lo zoom tramite tocco.
Questi eventi usano l’API web PointerEvent del browser e non richiedono ECMAScript 2024. Per un dito o la punta di una penna, pointerdown e pointerup segnano l’inizio e la fine del contatto. Con il mouse indicano la pressione del primo pulsante e il rilascio dell’ultimo, non ogni singola pressione o rilascio come mousedown e mouseup.
Esempi
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;
});Risultato
pointerdown pointermove pointerup lostpointercapture
Esegui l’esempio con Node.js e Playwright come indicato nelle istruzioni di verifica. Playwright preme il pulsante nel riquadro, sposta il mouse all’esterno e rilascia il pulsante lì. Viene registrato solo il primo movimento corrispondente. L’output atteso mostra una conclusione normale, non un annullamento o una perdita anticipata della cattura.
Lezioni correlate
- JavaScript · Lezione 35 · Avanzato · Versione: 4