Document: pointerlockerror — Ereignis · JavaScript-Referenz

Signatur

document.addEventListener("pointerlockerror", handler)

Beschreibung

Das Ereignis pointerlockerror gehört zur Pointer Lock API. Es wird am Document ausgelöst, wenn der Versuch, den Mauszeiger mit Element.requestPointerLock() an ein Element zu binden, fehlschlägt. Typische Ursachen sind ein fehlender Nutzer-Klick (keine transiente Nutzeraktivierung), ein Dokument ohne Fokus, ein Iframe ohne allow-pointer-lock in der Sandbox oder das erneute Sperren kurz nachdem der Nutzer die Sperre mit Esc beendet hat.

Das Ereignis ist ein einfaches Event ohne zusätzliche Eigenschaften. Es blubbert nicht über das Dokument hinaus und lässt sich nicht abbrechen. Registrieren kann man es per document.addEventListener("pointerlockerror", handler) oder über die Eigenschaft document.onpointerlockerror.

Man nutzt das Ereignis vor allem in Spielen, 3D-Viewern und Zeichen-Anwendungen, um den Nutzer zu informieren und eine Rückfallebene anzubieten, etwa einen „Zum Spielen klicken“-Hinweis oder eine Steuerung ohne Zeigersperre. Das Gegenstück bei Erfolg ist pointerlockchange.

In modernen Browsern gibt requestPointerLock() zusätzlich ein Promise zurück, das bei einem Fehler abgelehnt wird. Dieses Promise liefert mit dem DOMException-Objekt genauere Fehlerinformationen als das Ereignis selbst.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname `"pointerlockerror"`.
$handler Pflicht	(event: Event) => void		Callback-Funktion, die ein einfaches `Event`-Objekt erhält. Es hat keine speziellen Zusatzeigenschaften; `event.target` ist das `Document`.
$options	boolean \| AddEventListenerOptions	false	Optionale Listener-Optionen wie `once`, `signal` oder `capture`.

Beispiele

Fehler beim Sperren per addEventListener abfangen

const canvas = document.querySelector('#game');
const hint = document.querySelector('#hint');

document.addEventListener('pointerlockerror', () => {
  console.warn('Zeigersperre fehlgeschlagen');
  hint.textContent = 'Zeigersperre nicht möglich – bitte erneut klicken.';
  hint.hidden = false;
});

// Sperre nur nach Nutzer-Klick anfordern
canvas.addEventListener('click', () => {
  canvas.requestPointerLock();
});

Zeigersperre fehlgeschlagen (falls z. B. zu schnell nach Esc erneut geklickt)

Über die on-Property und Entfernen des Listeners

const onLockError = (event) => {
  console.log(`Ereignis: ${event.type}`);
};

// Variante 1: on-Property
document.onpointerlockerror = onLockError;
// Wieder entfernen
document.onpointerlockerror = null;

// Variante 2: addEventListener / removeEventListener
document.addEventListener('pointerlockerror', onLockError);
document.removeEventListener('pointerlockerror', onLockError);

Moderne Variante: Promise und Ereignis kombinieren

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

document.addEventListener('pointerlockchange', () => {
  const locked = document.pointerLockElement === canvas;
  console.log(locked ? 'Zeiger gesperrt' : 'Zeiger freigegeben');
});

document.addEventListener('pointerlockerror', () => {
  console.log('pointerlockerror ausgelöst');
});

canvas.addEventListener('click', async () => {
  try {
    // unadjustedMovement: Roh-Mausdaten ohne Beschleunigung (Chromium)
    await canvas.requestPointerLock({ unadjustedMovement: true });
  } catch (err) {
    // Detaillierte Ursache, z. B. NotSupportedError oder SecurityError
    console.error(`${err.name}: ${err.message}`);
  }
});

pointerlockerror ausgelöst SecurityError: The user has exited the lock before this request was completed.

// Wichtig · Fallstricke

Nutzeraktivierung nötig: requestPointerLock() ohne vorherigen Klick oder Tastendruck löst in der Regel pointerlockerror aus.
Sperre nach Esc: Beendet der Nutzer die Sperre mit Esc, verweigern Chrome und andere Browser eine erneute Sperre für etwa eine Sekunde. Das führt zu diesem Ereignis.
Iframes: In Iframes mit Sandbox ist das Token allow-pointer-lock erforderlich, sonst schlägt jede Anforderung fehl.
Das Ereignis enthält keine Fehlerursache. Genauere Informationen liefert nur das Promise von requestPointerLock(). Ältere Browser, darunter ältere Safari- und Firefox-Versionen, geben kein Promise zurück (undefined). Deshalb vor await prüfen oder zusätzlich das Ereignis verwenden.
Alte Präfix-Varianten (mozpointerlockerror, webkitpointerlockerror) sind veraltet und nur für sehr alte Browser relevant.
Auf Mobilgeräten und Touch-Geräten wird die Pointer Lock API meist nicht unterstützt.

Siehe auch

Document: pointerlockchange Element.prototype.requestPointerLock() Document.prototype.exitPointerLock() Document.pointerLockElement MouseEvent.movementX AudioWorkletNode: processorerror Element: gotpointercapture