CKTIS / JavaScript
Element.setPointerCapture — capturar um ponteiro
O método setPointerCapture(pointerId) encaminha os eventos seguintes de um ponteiro específico para um elemento escolhido, mesmo quando o ponteiro sai dos seus limites. Facilita o arrastamento com rato, toque ou caneta.
Versão: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support
Sintaxe
element.setPointerCapture(pointerId)Chama Element.setPointerCapture num elemento, normalmente dentro de um gestor pointerdown, passando event.pointerId. A captura substitui a seleção normal do destino com base na posição, pelo que o elemento continua a receber eventos como pointermove fora dos seus limites. O método devolve undefined; não move nem bloqueia o cursor.
A chamada define uma captura pendente: hasPointerCapture(pointerId) pode devolver true imediatamente, antes de gotpointercapture. releasePointerCapture(pointerId) liberta-a explicitamente; após pointerup ou pointercancel, o browser liberta-a automaticamente. Usa lostpointercapture para limpar o estado da interação. O toque pode já ter captura implícita.
Um identificador que não corresponda a nenhum ponteiro ativo provoca NotFoundError. Um elemento desligado ou um Pointer Lock ativo no respetivo documento provoca InvalidStateError. Só depois de validar o identificador do ponteiro, a ligação do elemento e o estado de Pointer Lock é que o método verifica as restantes condições: se não houver nenhum botão premido nem contacto, ou se o documento do elemento não for o documento ativo do ponteiro, o método não define a captura nem gera um erro.
A captura não desativa a deslocação nem o zoom por toque; o exemplo usa touch-action: none apenas na área de demonstração. Esta é uma API do browser especificada por Pointer Events, não uma funcionalidade de uma edição específica de ECMAScript. Ter Node 24 não comprova a sua disponibilidade: verifica o método e testa os browsers de destino.
Exemplos
const pad = document.createElement('div');
pad.textContent = 'Press, move outside, release';
pad.style.cssText = 'width:220px;height:100px;background:lightblue;touch-action:none;user-select:none';
const log = document.createElement('pre');
document.body.append(pad, log);
if (typeof pad.setPointerCapture !== 'function') {
log.textContent = 'unsupported';
} else {
let activeId = null;
pad.addEventListener('pointerdown', (event) => {
if (activeId !== null) return;
pad.setPointerCapture(event.pointerId);
activeId = event.pointerId;
log.textContent = `pending: ${pad.hasPointerCapture(activeId)}`;
});
pad.addEventListener('pointermove', (event) => {
if (event.pointerId === activeId) {
log.textContent = 'moving';
}
});
pad.addEventListener('lostpointercapture', (event) => {
if (event.pointerId === activeId) {
activeId = null;
log.textContent = 'released';
}
});
}Resultado
released
O código apresentado e o resultado declarado foram verificados num ambiente isolado pelo método registado na prova de verificação desta versão exata.