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

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.

Fontes