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