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

CKTIS / JavaScript

PointerEvent: identificador e ponteiro principal

`pointerId` associa os eventos do mesmo ponteiro ativo; `isPrimary` indica se esse ponteiro é o principal para o seu tipo de entrada.

Versão: Current web platform; runtime support varies

Sintaxe

// Pointer Events Web API; no ECMAScript 2024 requirement
event.pointerId  // number, read-only
event.isPrimary  // boolean, read-only

pointerId é um identificador numérico só de leitura. Permite associar os eventos do mesmo ponteiro ativo e distingui-lo dos outros ponteiros ativos, como um segundo ponto de contacto. Não é um identificador permanente do dispositivo: não deduzas o tipo de dispositivo a partir do número nem assumas que este se mantém entre interações ou nunca é reutilizado. Nos eventos gerados pelo navegador, -1 indica que não interveio um dispositivo apontador, por exemplo num click acionado pelo teclado.

isPrimary é uma propriedade booleana só de leitura. true indica o ponteiro principal para esse pointerType, não o botão principal. O ponteiro do rato é principal; para o toque e a caneta, é principal o primeiro ponteiro desse tipo que fica ativo quando não há outro do mesmo tipo ativo. O rato e um contacto tátil podem, portanto, ter isPrimary === true ao mesmo tempo. Quando o contacto tátil principal termina, outro contacto que continue ativo não se torna automaticamente principal.

Para acompanhar vários gestos, guarda o estado numa Map com pointerId como chave em pointerdown, consulta-o em pointermove e remove-o em pointerup ou pointercancel. Se precisares de um só ponteiro para todos os tipos de entrada, guarda o identificador escolhido: filtrar apenas por isPrimary não basta. Estas propriedades pertencem a uma API da Web, não ao ECMAScript; verifica o suporte no ambiente de execução pretendido.

Exemplos

<!doctype html>
<meta charset="utf-8">
<title>PointerEvent example</title>
<pre id="output"></pre>
<script>
  const events = [
    new PointerEvent("pointerdown", { pointerType: "touch", pointerId: 7, isPrimary: true }),
    new PointerEvent("pointerdown", { pointerType: "touch", pointerId: 8, isPrimary: false }),
    new PointerEvent("pointermove", { pointerType: "touch", pointerId: 7, isPrimary: true }),
    new PointerEvent("pointermove", { pointerType: "mouse", pointerId: 12, isPrimary: true }),
  ];

  const lines = [];
  for (const event of events) {
    lines.push(`${event.type} ${event.pointerType} ${event.pointerId} ${event.isPrimary}`);
  }
  document.getElementById("output").textContent = lines.join("\n");
</script>

Resultado

pointerdown touch 7 true
pointerdown touch 8 false
pointermove touch 7 true
pointermove mouse 12 true

Guarda o exemplo como ficheiro HTML e abre-o num navegador que suporte `PointerEvent`. O resultado aparece na página. O identificador `7` associa dois eventos de toque, `8` identifica outro contacto, e tanto o rato como o primeiro contacto têm o valor `true`. O código lê valores definidos explicitamente em eventos sintéticos. Não despacha os eventos nem testa como o navegador atribui os valores em resposta a entradas reais.

Lições relacionadas

  • JavaScript · Lição 35 · Intermédio · Versão: 3

Fontes