ScreenOrientation.unlock() — Methode · JavaScript-Referenz

Signatur

ScreenOrientation.prototype.unlock()

Beschreibung

Die Methode unlock() des Interfaces ScreenOrientation hebt eine Sperre der Bildschirmausrichtung wieder auf, die vorher mit screen.orientation.lock() gesetzt wurde. Danach gilt wieder die Standardausrichtung des Dokuments. Sie ergibt sich aus dem Gerät, den Einstellungen des Betriebssystems (z. B. automatisches Drehen) oder bei installierten Web-Apps aus dem Feld orientation im Web-App-Manifest.

Typische Einsatzfälle sind Videoplayer, Spiele und Bildbetrachter. Diese sperren die Ausrichtung im Vollbildmodus etwa auf "landscape" und müssen sie beim Verlassen des Vollbilds oder beim Schließen der Ansicht wieder freigeben. So kann der Nutzer das Gerät danach wieder frei drehen.

Anders als lock() gibt unlock() kein Promise zurück, sondern arbeitet synchron und liefert undefined. Ist gerade keine Sperre aktiv, hat der Aufruf keine Wirkung. Das eigentliche Drehen des Bildschirms kann trotzdem zeitversetzt passieren. Darüber informiert das Ereignis change auf screen.orientation.

Rückgabewert

Typ

void

Beschreibung

Gibt undefined zurück. Anders als bei lock() gibt es kein Promise.

Beispiele

Querformat im Vollbild sperren und beim Verlassen wieder freigeben

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

const enterFullscreen = async () => {
  await player.requestFullscreen();
  try {
    await screen.orientation.lock('landscape');
    console.log('Ausrichtung gesperrt:', screen.orientation.type);
  } catch (err) {
    console.warn('Sperren nicht möglich:', err.name);
  }
};

document.addEventListener('fullscreenchange', () => {
  if (!document.fullscreenElement) {
    // Vollbild verlassen: Sperre aufheben
    screen.orientation.unlock();
    console.log('Ausrichtung wieder frei');
  }
});

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

Ausrichtung gesperrt: landscape-primary Ausrichtung wieder frei

Sicherer Aufruf mit Feature-Erkennung

const unlockOrientation = () => {
  if (screen.orientation && typeof screen.orientation.unlock === 'function') {
    try {
      screen.orientation.unlock();
      return true;
    } catch (err) {
      // Manche Browser werfen z. B. einen NotSupportedError
      console.warn('unlock() fehlgeschlagen:', err.name);
    }
  }
  return false;
};

console.log(unlockOrientation());

true

Auf die Ausrichtungsänderung nach dem Entsperren reagieren

screen.orientation.addEventListener('change', () => {
  console.log(`Neue Ausrichtung: ${screen.orientation.type} (${screen.orientation.angle}°)`);
}, { once: true });

// Spielansicht schließen: Sperre aufheben
const closeGame = () => {
  screen.orientation.unlock();
  document.exitFullscreen?.();
};

closeGame();

Neue Ausrichtung: portrait-primary (0°)

// Wichtig · Fallstricke

Kein Promise: unlock() gibt undefined zurück. await screen.orientation.unlock() ist zwar kein Fehler, wartet aber auf nichts. Wenn Sie auf die tatsächliche Drehung reagieren wollen, nutzen Sie das Ereignis change.
Nur mit vorheriger Sperre sinnvoll: Ohne aktive Sperre hat der Aufruf keine Wirkung. Die Standardausrichtung legen Gerät, Betriebssystem oder Web-App-Manifest fest, nicht die Seite.
Vollbild-Kopplung: In den meisten Browsern funktioniert lock() nur im Vollbild oder in installierten Web-Apps. Beim Verlassen des Vollbilds heben manche Browser die Sperre selbst auf. Ein ausdrücklicher Aufruf von unlock() ist trotzdem gute Praxis.
Kompatibilität: Auf Desktop-Browsern wirkt das Sperren und Entsperren meist nicht. Ältere Safari-Versionen (vor 16.4) haben screen.orientation gar nicht. In manchen Umgebungen wird ein NotSupportedError geworfen, daher per Feature-Erkennung und try/catch absichern.
Veraltete API: Die ältere Methode screen.unlockOrientation() (mit Präfixen wie moz/ms) ist veraltet und sollte nicht mehr verwendet werden.
In <iframe>-Elementen mit sandbox ist das Sperren nur mit allow-orientation-lock erlaubt.

Siehe auch

ScreenOrientation.lock() Screen.lockOrientation() Notification.close() Keyboard.unlock() Navigation.back()