Screen.unlockOrientation() — Methode · JavaScript-Referenz

Signatur

Screen.prototype.unlockOrientation()

Beschreibung

screen.unlockOrientation() ist das Gegenstück zu screen.lockOrientation(). Hat eine Seite die Bildschirmausrichtung festgelegt, zum Beispiel für ein Spiel oder einen Videoplayer im Querformat, gibt diese Methode die Sperre wieder frei. Danach richtet sich der Bildschirm wieder nach der Lage des Geräts und den Systemeinstellungen.

Die Methode stammt aus einem frühen Entwurf der Screen Orientation API und wurde nie ohne Präfix breit unterstützt. In der Praxis gab es nur screen.mozUnlockOrientation() (Firefox, vor allem Firefox OS und Firefox für Android) und screen.msUnlockOrientation() (Internet Explorer 11 und Edge Legacy auf Touch-Geräten).

Für neuen Code solltest du stattdessen screen.orientation.unlock() aus dem Interface ScreenOrientation verwenden. Die alte Methode ist nur noch nützlich, wenn du ältere Browser als Ausweichlösung unterstützen musst.

Rückgabewert

Typ

boolean

Beschreibung

true, wenn die Sperre aufgehoben wurde, sonst false. Die moderne Methode screen.orientation.unlock() gibt dagegen undefined zurück.

Beispiele

Sperre mit Prüfung auf verfügbare Varianten aufheben

// Nimmt die moderne API, sonst die veralteten Varianten mit Präfix
const unlockScreenOrientation = () => {
  if (screen.orientation?.unlock) {
    screen.orientation.unlock();
    return true;
  }
  const legacyUnlock =
    screen.unlockOrientation ||
    screen.mozUnlockOrientation ||
    screen.msUnlockOrientation;

  if (typeof legacyUnlock === 'function') {
    // Muss mit screen als this aufgerufen werden
    return legacyUnlock.call(screen);
  }
  console.warn('Das Entsperren der Ausrichtung wird nicht unterstützt.');
  return false;
};

console.log(unlockScreenOrientation());

true

Videoplayer: Querformat im Vollbild sperren, beim Verlassen freigeben

const player = document.querySelector('#video-player');

const lockLandscape = async () => {
  await player.requestFullscreen();
  try {
    await screen.orientation.lock('landscape');
  } catch {
    // Ausweichlösung für ältere Browser
    const legacyLock = screen.lockOrientation || screen.mozLockOrientation || screen.msLockOrientation;
    legacyLock?.call(screen, 'landscape');
  }
};

document.addEventListener('fullscreenchange', () => {
  if (!document.fullscreenElement) {
    // Vollbild verlassen: Sperre aufheben
    if (screen.orientation?.unlock) {
      screen.orientation.unlock();
    } else {
      const legacyUnlock = screen.unlockOrientation || screen.mozUnlockOrientation || screen.msUnlockOrientation;
      legacyUnlock?.call(screen);
    }
    console.log('Ausrichtung freigegeben');
  }
});

document.querySelector('#fullscreen-btn').addEventListener('click', lockLandscape);

Ausrichtung freigegeben

Unterstützung prüfen

const support = {
  modern: typeof screen.orientation?.unlock === 'function',
  legacy: typeof screen.unlockOrientation === 'function',
  moz: typeof screen.mozUnlockOrientation === 'function',
  ms: typeof screen.msUnlockOrientation === 'function'
};
console.table(support);

{ modern: true, legacy: false, moz: false, ms: false } (in aktuellen Browsern)

// Wichtig · Fallstricke

Veraltet: Die Methode gehört zu keinem aktuellen Standard. In modernen Browsern gibt es sie nicht mehr, auch nicht mit Präfix. Verwende screen.orientation.unlock().
Nur mit Präfix: Früher gab es sie praktisch nur als mozUnlockOrientation oder msUnlockOrientation. Prüfe daher immer, ob die Methode vorhanden ist, bevor du sie aufrufst.
this-Bindung: Speicherst du die Methode in einer Variablen, musst du sie mit .call(screen) aufrufen. Sonst gibt es einen TypeError („Illegal invocation“).
Nur sinnvoll nach einer Sperre: Wurde vorher keine Sperre gesetzt, bewirkt der Aufruf nichts. Auf Desktop-Browsern ist die Ausrichtung meist gar nicht sperrbar.
Moderne API: screen.orientation.lock() funktioniert in der Regel nur im Vollbildmodus. Beim Verlassen des Vollbilds wird die Sperre in vielen Browsern automatisch aufgehoben. Safari auf iOS unterstützt das Sperren überhaupt nicht.

Siehe auch

Screen.lockOrientation() ScreenOrientation.unlock() ScreenOrientation.lock() Screen.orientation Screen new RelativeOrientationSensor()