Element.requestPointerLock() — Methode · JavaScript-Referenz

Signatur

Element.prototype.requestPointerLock(options)

Beschreibung

requestPointerLock() gehört zur Pointer Lock API. Nach erfolgreicher Anforderung wird der Mauszeiger ausgeblendet und an das Element gebunden. Er kann dann den Bildschirmrand oder das Fenster nicht mehr „verlassen“. Mausereignisse gehen ab diesem Moment nur noch an das gesperrte Element. Die Bewegung liest du über MouseEvent.movementX und MouseEvent.movementY aus. Die absoluten Koordinaten wie clientX bleiben dagegen unverändert.

Typische Einsatzfälle sind 3D-Spiele mit Ego-Perspektive, Kamerasteuerung in WebGL-Anwendungen, 3D-Modellierungswerkzeuge und alle Bedienelemente, bei denen die Maus ohne Grenzen bewegt werden soll, etwa ein Drehregler.

Die Anforderung läuft asynchron. Ob sie geklappt hat, meldet der Browser über die Ereignisse pointerlockchange und pointerlockerror am document. Moderne Browser geben zusätzlich ein Promise zurück. Welches Element gerade gesperrt ist, steht in document.pointerLockElement. Beenden lässt sich die Sperre mit document.exitPointerLock(). Die Nutzerin oder der Nutzer kann sie jederzeit mit der Esc-Taste aufheben.

Die Anforderung muss aus einer Nutzerinteraktion heraus erfolgen, zum Beispiel in einem click-Handler. Andernfalls lehnt der Browser sie ab.

Parameter

Name	Typ	Default	Beschreibung
$options	object	{}	Optionales Einstellungsobjekt. Unterstützt wird `unadjustedMovement` (`boolean`, Standard `false`): Bei `true` schaltet der Browser die Mausbeschleunigung des Betriebssystems ab und liefert Rohdaten der Bewegung. Das ist ideal für Spiele.

Rückgabewert

Typ

Promise<undefined> | undefined

Beschreibung

In modernen Implementierungen (z. B. Chromium) ein Promise. Es wird erfüllt, sobald die Sperre aktiv ist, und bei einem Fehler abgelehnt, etwa mit NotSupportedError oder SecurityError. Ältere Implementierungen geben undefined zurück und melden das Ergebnis nur über Ereignisse.

Beispiele

Pointer Lock per Klick auf ein Canvas aktivieren

const canvas = document.querySelector('#game');
let yaw = 0;
let pitch = 0;

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

const onMouseMove = (event) => {
  // Nur relative Bewegung auswerten
  yaw += event.movementX * 0.002;
  pitch -= event.movementY * 0.002;
  pitch = Math.max(-Math.PI / 2, Math.min(Math.PI / 2, pitch));
};

document.addEventListener('pointerlockchange', () => {
  if (document.pointerLockElement === canvas) {
    console.log('Zeiger gesperrt');
    document.addEventListener('mousemove', onMouseMove);
  } else {
    console.log('Zeiger freigegeben');
    document.removeEventListener('mousemove', onMouseMove);
  }
});

document.addEventListener('pointerlockerror', () => {
  console.error('Pointer Lock fehlgeschlagen');
});

Zeiger gesperrt Zeiger freigegeben // nach Druck auf Esc

Rohe Mausdaten mit Rückfall auf die Standardsperre

const lockPointer = async (element) => {
  try {
    // Ohne Mausbeschleunigung des Betriebssystems
    await element.requestPointerLock({ unadjustedMovement: true });
    console.log('Sperre mit Rohdaten aktiv');
  } catch (error) {
    if (error.name === 'NotSupportedError') {
      // Plattform unterstützt keine Rohdaten: normale Sperre anfordern
      await element.requestPointerLock();
      console.log('Standardsperre aktiv');
    } else {
      console.error('Sperre abgelehnt:', error.name);
    }
  }
};

document.querySelector('#game')
  .addEventListener('click', (e) => lockPointer(e.currentTarget));

Sperre mit Rohdaten aktiv

Sperre umschalten und per Programm beenden

const viewer = document.querySelector('#viewer');
const button = document.querySelector('#toggle-lock');

button.addEventListener('click', () => {
  if (document.pointerLockElement) {
    document.exitPointerLock();
  } else {
    viewer.requestPointerLock();
  }
});

document.addEventListener('pointerlockchange', () => {
  const locked = document.pointerLockElement === viewer;
  button.textContent = locked ? 'Maus freigeben' : 'Maus sperren';
  console.log('Gesperrt:', locked);
});

Gesperrt: true

// Wichtig · Fallstricke

Nutzeraktion erforderlich: Ohne vorherige Nutzerinteraktion, etwa einen Klick, schlägt die Anforderung fehl. Das wird mit pointerlockerror bzw. einem abgelehnten Promise gemeldet.
Erneute Sperre nach Esc: Chromium verweigert eine neue Sperre für etwa eine Sekunde, nachdem der Nutzer sie mit Esc beendet hat. Die Anwendung muss diesen Fehler abfangen.
Rückgabewert uneinheitlich: Nicht alle Browser geben ein Promise zurück. Wer robusten Code will, wertet zusätzlich die Ereignisse pointerlockchange/pointerlockerror aus. Vor dem Aufruf von .then() sollte man prüfen, ob überhaupt ein Promise zurückkommt.
unadjustedMovement: Die Option wird nicht auf allen Plattformen unterstützt und ist in Firefox und Safari teils noch nicht verfügbar. Nicht unterstützte Fälle führen zu NotSupportedError, also einen Rückfall vorsehen.
iframes: In <iframe sandbox> ist Pointer Lock nur mit dem Token allow-pointer-lock erlaubt.
Das Element muss im Dokument eingehängt sein, und das Dokument muss den Fokus haben. Verliert das Fenster den Fokus, wird die Sperre automatisch aufgehoben.
Ältere Präfix-Varianten wie mozRequestPointerLock und webkitRequestPointerLock sind veraltet und werden nicht mehr benötigt.
Barrierefreiheit: Weise deutlich darauf hin, wie sich die Sperre beenden lässt (Esc), denn der Zeiger ist unsichtbar.

Siehe auch

Document.exitPointerLock() Document.pointerLockElement MouseEvent.movementX MouseEvent.movementY Element.requestFullscreen()