Document.exitPointerLock() — Methode · JavaScript-Referenz

Signatur

Document.prototype.exitPointerLock()

Beschreibung

Die Methode document.exitPointerLock() beendet die Zeigersperre (Pointer Lock), die vorher über Element.requestPointerLock() für ein Element aktiviert wurde. Danach ist der Mauszeiger wieder sichtbar und kann sich frei über die Seite und den Bildschirm bewegen.

Solange die Zeigersperre aktiv ist, werden alle Mausereignisse an das gesperrte Element geleitet und liefern über movementX/movementY relative Bewegungen. Das braucht man typischerweise für 3D-Spiele, First-Person-Kameras, CAD-Anwendungen oder Drehregler, bei denen der Zeiger nicht am Bildschirmrand hängen bleiben soll. Mit exitPointerLock() gibt man die Sperre selbst wieder frei, zum Beispiel beim Öffnen eines Pausenmenüs.

Die Freigabe läuft asynchron. Ob sie geklappt hat, erfährt man über das Ereignis pointerlockchange am document. Danach ist document.pointerLockElement wieder null. Auch wenn der Nutzer die Sperre mit der Esc-Taste beendet, wird pointerlockchange ausgelöst. Ein Aufruf ohne aktive Sperre bewirkt nichts.

Beispiele

Zeigersperre per Klick setzen und per Taste freigeben

const canvas = document.querySelector('#spiel');

canvas.addEventListener('click', () => {
  canvas.requestPointerLock();
});

document.addEventListener('keydown', (event) => {
  // Taste P öffnet das Pausenmenü und gibt den Zeiger frei
  if (event.key === 'p' && document.pointerLockElement === canvas) {
    document.exitPointerLock();
  }
});

Freigabe über pointerlockchange erkennen

const canvas = document.querySelector('#spiel');

const onMouseMove = (e) => {
  console.log(`Δx=${e.movementX}, Δy=${e.movementY}`);
};

document.addEventListener('pointerlockchange', () => {
  if (document.pointerLockElement === canvas) {
    console.log('Zeigersperre aktiv');
    document.addEventListener('mousemove', onMouseMove);
  } else {
    console.log('Zeigersperre aufgehoben');
    document.removeEventListener('mousemove', onMouseMove);
  }
});

document.addEventListener('pointerlockerror', () => {
  console.error('Zeigersperre konnte nicht gesetzt werden');
});

Zeigersperre aktiv Δx=3, Δy=-1 Zeigersperre aufgehoben

Wiederverwendbare Hilfsfunktion mit Promise

const exitPointerLockAsync = () => new Promise((resolve) => {
  if (!document.pointerLockElement) {
    resolve(false); // keine Sperre aktiv
    return;
  }
  document.addEventListener('pointerlockchange', () => resolve(true), { once: true });
  document.exitPointerLock();
});

const pausieren = async () => {
  const freigegeben = await exitPointerLockAsync();
  console.log(freigegeben ? 'Menü geöffnet, Zeiger frei' : 'Zeiger war nicht gesperrt');
};

pausieren();

Zeiger war nicht gesperrt

// Wichtig · Fallstricke

Asynchron: Direkt nach dem Aufruf kann document.pointerLockElement noch gesetzt sein. Den neuen Zustand liest man erst im Handler von pointerlockchange aus.
Esc-Taste: Browser beenden die Sperre bei Esc von selbst. Die Anwendung sollte deshalb auf pointerlockchange reagieren und sich nicht darauf verlassen, dass nur der eigene Code die Sperre aufhebt.
Erneutes Sperren: Nach einem Verlassen per Esc lassen Chrome und andere Browser ein erneutes requestPointerLock() erst nach etwa einer Sekunde und nur nach einer Nutzeraktion zu. Sonst wird pointerlockerror ausgelöst.
Kompatibilität: Alle aktuellen Desktop-Browser unterstützen die Methode ohne Präfix. Alte Versionen nutzten mozExitPointerLock() bzw. webkitExitPointerLock(). Auf Mobilgeräten wird Pointer Lock kaum unterstützt.
In iframes muss das Attribut sandbox das Recht allow-pointer-lock enthalten, sonst ist Pointer Lock überhaupt nicht verfügbar.

Siehe auch

Element.requestPointerLock() Document.pointerLockElement MouseEvent.movementX Document.exitFullscreen() new VTTRegion()