Screen.lockOrientation() — Methode · JavaScript-Referenz

Signatur

Screen.prototype.lockOrientation(orientation)

Beschreibung

screen.lockOrientation() war ein früher Entwurf der Screen Orientation API. Damit ließ sich die Ausrichtung des Bildschirms festlegen, zum Beispiel bei Spielen, Videoplayern oder Kamera-Anwendungen, die nur im Querformat sinnvoll funktionieren. Der Aufruf gibt synchron einen Wahrheitswert zurück, der anzeigt, ob die Sperre angenommen wurde.

Die Methode wurde nie unpräfixiert ausgeliefert. Es gab sie nur als mozLockOrientation() (Firefox OS, älteres Firefox für Android) und als msLockOrientation() (Internet Explorer 11 unter Windows 8 und neuer, Edge Legacy). Aus der Spezifikation wurde sie entfernt, und moderne Browser unterstützen sie nicht mehr.

In neuem Code solltest du stattdessen screen.orientation.lock() aus dem ScreenOrientation-Interface verwenden. Diese Methode gibt ein Promise zurück und setzt in der Regel den Vollbildmodus voraus. lockOrientation() ist nur noch wichtig, wenn du Altgeräte unterstützen musst oder Bestandscode pflegst. Dann nutzt du sie ausschließlich als Rückfallebene mit Funktionserkennung.

Parameter

Name	Typ	Default	Beschreibung
$orientation Pflicht	string \| string[]		Die gewünschte Ausrichtung als String oder als Array mehrerer erlaubter Ausrichtungen. Gültige Werte: `"portrait-primary"`, `"portrait-secondary"`, `"landscape-primary"`, `"landscape-secondary"`, `"portrait"` (beide Hochformate), `"landscape"` (beide Querformate) sowie `"default"` (Standardausrichtung des Geräts). Die Array-Form wird nicht in jeder Implementierung unterstützt.

Rückgabewert

Typ

boolean

Beschreibung

true, wenn die Sperre gesetzt werden durfte, sonst false. Auch bei true ist nicht sicher, dass sich der Bildschirm tatsächlich dreht.

Beispiele

Querformat sperren mit Präfix-Erkennung

// Präfixversion ermitteln (unpräfixiert wurde die Methode nie ausgeliefert)
const legacyLock =
  screen.lockOrientation ||
  screen.mozLockOrientation ||
  screen.msLockOrientation;

if (legacyLock) {
  // Mit call aufrufen, damit this auf screen zeigt
  const ok = legacyLock.call(screen, 'landscape');
  console.log(ok ? 'Querformat gesperrt' : 'Sperre abgelehnt');
} else {
  console.log('lockOrientation() wird nicht unterstützt');
}

lockOrientation() wird nicht unterstützt // in allen aktuellen Browsern

Moderne API bevorzugen, Altmethode als Rückfallebene

const lockLandscape = async () => {
  // 1. Moderner Weg: ScreenOrientation API (braucht meist den Vollbildmodus)
  if (screen.orientation?.lock) {
    try {
      await document.documentElement.requestFullscreen();
      await screen.orientation.lock('landscape');
      return 'modern';
    } catch (err) {
      console.warn('orientation.lock fehlgeschlagen:', err.name);
    }
  }
  // 2. Rückfall auf die veraltete Präfix-Methode
  const legacy = screen.lockOrientation || screen.mozLockOrientation || screen.msLockOrientation;
  if (legacy && legacy.call(screen, 'landscape')) return 'legacy';
  return 'nicht möglich';
};

// Muss durch eine Nutzeraktion ausgelöst werden
document.querySelector('#play').addEventListener('click', async () => {
  console.log('Sperre über:', await lockLandscape());
});

Sperre über: modern

Mehrere Ausrichtungen erlauben und Sperre wieder aufheben

const legacyLock = screen.mozLockOrientation || screen.msLockOrientation;
const legacyUnlock = screen.mozUnlockOrientation || screen.msUnlockOrientation;

if (legacyLock) {
  // Beide Hochformate zulassen
  legacyLock.call(screen, ['portrait-primary', 'portrait-secondary']);

  // Nach 10 Sekunden wieder freie Drehung erlauben
  setTimeout(() => {
    legacyUnlock?.call(screen);
    console.log('Ausrichtung wieder frei');
  }, 10_000);
}

Ausrichtung wieder frei

// Wichtig · Fallstricke

Veraltet und nicht standardisiert: Die Methode steht nicht mehr in der Spezifikation und fehlt in allen aktuellen Browsern (Chrome, Safari, Firefox, Edge Chromium). Sie existierte nur als mozLockOrientation und msLockOrientation.
Ersatz: screen.orientation.lock(type), das ein Promise zurückgibt. In Chromium unter Android funktioniert es; Desktop-Browser und Safari lehnen es meist mit NotSupportedError ab. Die Sperre hebst du mit screen.orientation.unlock() auf.
Kontext: Browser erlauben eine Sperre meist nur im Vollbildmodus, in installierten Web-Apps oder nach einer Nutzeraktion. Die Rückgabe true heißt nicht, dass sich der Bildschirm wirklich dreht.
this-Bindung: Wenn du die Methode in einer Variablen speicherst, musst du sie mit .call(screen, …) aufrufen. Sonst wird ein TypeError ausgelöst.
Für eine reine Darstellungsanpassung reichen oft CSS-Media-Queries (@media (orientation: landscape)) oder das Manifest-Feld "orientation" bei PWAs.

Siehe auch

Screen.orientation Screen Screen.unlockOrientation() ScreenOrientation.lock() PannerNode.setOrientation()