PointerEvent.isPrimary — Eigenschaft · JavaScript-Referenz

Signatur

PointerEvent.isPrimary

Beschreibung

Die schreibgeschützte Eigenschaft isPrimary des PointerEvent-Interfaces ist true, wenn das Ereignis vom primären Zeiger stammt. Bei Multi-Pointer-Szenarien, etwa mehreren Fingern auf einem Touchscreen, gibt es pro Zeigertyp (pointerType) genau einen primären Zeiger.

Die Regeln sind je nach Gerät unterschiedlich:

Maus: Der Mauszeiger ist immer primär.
Touch: Primär ist der Finger, der den Bildschirm zuerst berührt hat, während kein anderer Finger aufgelegt war. Weitere Finger sind nicht primär. Hebt man den ersten Finger an, wird kein anderer Finger nachträglich primär.
Stift: Primär ist der erste Stiftkontakt, wenn kein anderer Stift aktiv ist.

Die Eigenschaft ist nützlich, wenn eine Anwendung nur Ein-Zeiger-Interaktionen verarbeiten soll, z. B. beim Ziehen eines Elements, bei einfachen Wischgesten oder zum Nachbilden von Mausverhalten. Nur für primäre Zeiger erzeugt der Browser auch kompatible Mausereignisse (mousedown, mousemove usw.).

Rückgabewert

Typ

boolean

Beschreibung

true, wenn der Zeiger, der das Ereignis ausgelöst hat, der primäre Zeiger seines Typs ist, sonst false.

Beispiele

Primären Zeiger protokollieren

const flaeche = document.querySelector('#zeichenflaeche');

flaeche.addEventListener('pointerdown', (event) => {
  console.log(`ID ${event.pointerId}, Typ ${event.pointerType}, primär: ${event.isPrimary}`);
});

ID 1, Typ touch, primär: true ID 2, Typ touch, primär: false

Drag & Drop nur mit dem ersten Finger

const karte = document.querySelector('.karte');
let start = null;

karte.addEventListener('pointerdown', (event) => {
  if (!event.isPrimary) return; // weitere Finger ignorieren
  karte.setPointerCapture(event.pointerId);
  start = { x: event.clientX, y: event.clientY };
});

karte.addEventListener('pointermove', (event) => {
  if (!event.isPrimary || !start) return;
  const dx = event.clientX - start.x;
  const dy = event.clientY - start.y;
  karte.style.transform = `translate(${dx}px, ${dy}px)`;
});

karte.addEventListener('pointerup', (event) => {
  if (event.isPrimary) start = null;
});

Multi-Touch-Geste erkennen

const aktiveZeiger = new Map();
const ziel = document.querySelector('#bild');

ziel.addEventListener('pointerdown', (event) => {
  aktiveZeiger.set(event.pointerId, event);
  if (!event.isPrimary && aktiveZeiger.size === 2) {
    console.log('Zweiter Finger erkannt – Pinch-Zoom starten');
  }
});

const entfernen = (event) => aktiveZeiger.delete(event.pointerId);
ziel.addEventListener('pointerup', entfernen);
ziel.addEventListener('pointercancel', entfernen);

Zweiter Finger erkannt – Pinch-Zoom starten

Synthetisches PointerEvent erzeugen

const ev = new PointerEvent('pointerdown', {
  pointerId: 5,
  pointerType: 'pen',
  isPrimary: true
});
console.log(ev.isPrimary);
console.log(new PointerEvent('pointerdown').isPrimary);

true false

// Wichtig · Fallstricke

Schreibgeschützt: Eine Zuweisung an event.isPrimary wird ignoriert (im Strict Mode gibt es einen TypeError). Bei synthetischen Ereignissen setzt man den Wert über das Initialisierungsobjekt im Konstruktor; Standard ist false.
Primär ist pro Zeigertyp: Maus und Touch können gleichzeitig jeweils einen primären Zeiger haben. Wer Eingaben strikt auf einen Zeiger beschränken will, sollte zusätzlich die pointerId speichern und vergleichen.
Kein Nachrücken: Hebt man den ersten Finger an, während andere noch aufliegen, werden die verbleibenden Finger nicht primär. Erst nach dem Loslassen aller Finger kann ein neuer primärer Touch-Zeiger entstehen.
Nur primäre Zeiger lösen kompatible Mausereignisse aus. Wer auf mousedown hört, bekommt Eingaben weiterer Finger nicht mit.
Browser-Kompatibilität: Pointer Events werden von allen aktuellen Browsern unterstützt, Safari seit Version 13. Für sehr alte Umgebungen 'PointerEvent' in window prüfen.

Siehe auch

PaymentRequest.shippingType PointerEvent.pressure PointerEvent.tiltY PointerEvent.height PointerEvent.pointerId