Document.pointerLockElement — Eigenschaft · JavaScript-Referenz

Signatur

Document.pointerLockElement

Beschreibung

Die schreibgeschützte Eigenschaft document.pointerLockElement gehört zur Pointer Lock API. Sie gibt das Element zurück, auf das der Zeiger per element.requestPointerLock() gesperrt wurde. Während der Sperre ist der Mauszeiger unsichtbar, und alle Mausereignisse gehen an dieses Element. Die Bewegung wird dabei über MouseEvent.movementX und movementY gemeldet. Ist keine Sperre aktiv, ist der Wert null.

Typische Einsatzgebiete sind 3D-Spiele mit Ego-Perspektive, Kamerasteuerung in WebGL-Szenen, 3D-Modellbetrachter und Zeichenwerkzeuge, bei denen die Maus sich unbegrenzt bewegen soll, ohne am Bildschirmrand hängen zu bleiben.

Meist fragt man die Eigenschaft im Handler des Ereignisses pointerlockchange ab. So erfährt man, ob die Sperre gerade aktiviert oder aufgehoben wurde, zum Beispiel weil der Nutzer Esc gedrückt hat. Außerdem lässt sich so prüfen, ob die Sperre auf dem erwarteten Element liegt.

Rückgabewert

Typ

Element | null

Beschreibung

Das Element, auf dem der Zeiger aktuell gesperrt ist, oder null, wenn keine Sperre aktiv ist. Innerhalb eines Shadow DOM wird das Element entsprechend angepasst (retargeted); dafür gibt es auch ShadowRoot.pointerLockElement.

Beispiele

Sperrstatus bei pointerlockchange prüfen

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

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

document.addEventListener('pointerlockchange', () => {
  if (document.pointerLockElement === canvas) {
    console.log('Zeiger gesperrt – Steuerung aktiv');
  } else {
    console.log('Zeiger freigegeben – Spiel pausiert');
  }
});

Zeiger gesperrt – Steuerung aktiv (nach Esc:) Zeiger freigegeben – Spiel pausiert

Kamerasteuerung nur bei aktiver Sperre

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

const onMouseMove = (e) => {
  // Nur reagieren, wenn unser Canvas die Sperre hält
  if (document.pointerLockElement !== canvas) return;
  yaw += e.movementX * 0.002;
  pitch = Math.max(-Math.PI / 2, Math.min(Math.PI / 2, pitch - e.movementY * 0.002));
  console.log(`yaw=${yaw.toFixed(3)}, pitch=${pitch.toFixed(3)}`);
};

document.addEventListener('mousemove', onMouseMove);
canvas.addEventListener('click', () => canvas.requestPointerLock());

yaw=0.024, pitch=-0.010

Sperre per Taste umschalten

const viewer = document.querySelector('#viewer');

document.addEventListener('keydown', async (e) => {
  if (e.key !== 'l') return;
  if (document.pointerLockElement) {
    document.exitPointerLock();
  } else {
    try {
      // In neueren Browsern liefert requestPointerLock ein Promise
      await viewer.requestPointerLock({ unadjustedMovement: true });
    } catch (err) {
      console.warn('Pointer Lock abgelehnt:', err.name);
    }
  }
});

document.addEventListener('pointerlockerror', () => {
  console.warn('Sperre konnte nicht aktiviert werden');
});

// Wichtig · Fallstricke

Nutzergeste erforderlich: requestPointerLock() klappt nur nach einer Nutzeraktion wie einem Klick. Direkt nach einem Entsperren per Esc blockieren Browser eine erneute Anfrage für etwa 1 Sekunde. Das löst pointerlockerror aus, und pointerLockElement bleibt null.
Asynchron: Direkt nach dem Aufruf von requestPointerLock() ist pointerLockElement noch null. Werte die Eigenschaft deshalb erst im pointerlockchange-Handler aus oder nachdem das zurückgegebene Promise erfüllt ist.
Iframes: In einem <iframe> mit sandbox-Attribut braucht es allow-pointer-lock, sonst schlägt die Sperre fehl.
Präfixe: Sehr alte Browser kennen nur mozPointerLockElement bzw. webkitPointerLockElement. Heute ist die Eigenschaft ohne Präfix in allen modernen Browsern verfügbar. Auf Mobilgeräten wird die API kaum unterstützt, in Safari auf iOS gar nicht.
Die Eigenschaft ist schreibgeschützt. Eine Zuweisung hat keine Wirkung; zum Beenden nutzt man document.exitPointerLock().

Siehe auch

Element.requestPointerLock() Document.exitPointerLock() MouseEvent.movementX Document.fullscreenElement NodeIterator.pointerBeforeReferenceNode