ScreenOrientation.lock() — Methode · JavaScript-Referenz

Signatur

ScreenOrientation.prototype.lock(orientation)

Beschreibung

Mit screen.orientation.lock() legt man die Ausrichtung des Dokuments fest, z. B. auf Querformat. Danach dreht sich die Darstellung nicht mehr mit, wenn das Gerät gedreht wird. Das ist vor allem für Spiele, Videoplayer, Kamera-Apps oder Web-Apps mit festem Layout gedacht.

Die Methode gibt ein Promise zurück. Es wird erfüllt, sobald die Sperre greift, und abgelehnt, wenn der Browser, das Gerät oder der aktuelle Zustand keine Sperre erlaubt. In der Praxis klappt das Sperren meist nur, wenn das Dokument im Vollbildmodus läuft (Element.requestFullscreen()) oder als installierte PWA mit passendem display-Modus gestartet wurde. Auf Desktop-Browsern lehnen die meisten Implementierungen die Anfrage mit NotSupportedError ab.

Wieder aufheben lässt sich die Sperre mit ScreenOrientation.unlock(). Verlässt der Nutzer den Vollbildmodus, heben Browser die Sperre in der Regel automatisch auf. Auf Änderungen der Ausrichtung reagiert man mit dem change-Ereignis von screen.orientation.

Parameter

Name	Typ	Default	Beschreibung
$orientation Pflicht	"any" \| "natural" \| "landscape" \| "portrait" \| "portrait-primary" \| "portrait-secondary" \| "landscape-primary" \| "landscape-secondary"		Die gewünschte Ausrichtung. `"natural"` ist die natürliche Ausrichtung des Geräts, `"any"` erlaubt jede Ausrichtung, `"landscape"`/`"portrait"` erlauben jeweils beide Varianten (primär und sekundär, also auch um 180° gedreht).

Rückgabewert

Typ

Promise<void>

Beschreibung

Ein Promise, das ohne Wert erfüllt wird, sobald die Sperre gilt. Abgelehnt wird es mit einer DOMException: NotSupportedError (Sperre nicht unterstützt), SecurityError (z. B. Dokument nicht aktiv oder in einer Sandbox ohne allow-orientation-lock), AbortError (durch einen weiteren lock()- oder unlock()-Aufruf abgebrochen) oder InvalidStateError (Dokument nicht vollständig aktiv).

Beispiele

Vollbild öffnen und auf Querformat sperren

const playButton = document.querySelector('#play');
const player = document.querySelector('#player');

playButton.addEventListener('click', async () => {
  try {
    // Vollbild ist in den meisten Browsern Voraussetzung
    await player.requestFullscreen();
    await screen.orientation.lock('landscape');
    console.log('Gesperrt auf:', screen.orientation.type);
  } catch (err) {
    console.warn(`Sperren nicht möglich: ${err.name} – ${err.message}`);
  }
});

Gesperrt auf: landscape-primary

Funktionsprüfung mit Fallback

const lockOrientation = async (type) => {
  if (!screen.orientation?.lock) {
    console.info('Screen Orientation Lock wird nicht unterstützt.');
    return false;
  }
  try {
    await screen.orientation.lock(type);
    return true;
  } catch (err) {
    if (err.name === 'NotSupportedError') {
      console.info('Gerät/Kontext erlaubt keine Sperre (z. B. Desktop).');
    }
    return false;
  }
};

const ok = await lockOrientation('portrait-primary');
console.log('Sperre aktiv:', ok);

Gerät/Kontext erlaubt keine Sperre (z. B. Desktop). Sperre aktiv: false

Sperre beim Verlassen des Vollbilds aufheben

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

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

Ausrichtung wieder frei

// Wichtig · Fallstricke

Browser-Kompatibilität: Unterstützt wird die Methode vor allem von Chromium-Browsern auf Android und von Firefox für Android. Desktop-Browser lehnen sie meist mit NotSupportedError ab. Safari auf iOS bietet screen.orientation seit 16.4, lock() ist dort aber nicht nutzbar. In TypeScript fehlt lock() in neueren lib.dom.d.ts-Versionen, deshalb ist eine eigene Typdeklaration nötig.
Vollbild nötig: Ohne Vollbildmodus oder installierte PWA schlägt der Aufruf in der Regel fehl. requestFullscreen() braucht wiederum eine Nutzeraktion (Klick, Tippen).
Immer mit try/catch oder .catch() aufrufen: Ein abgelehntes Promise ohne Fehlerbehandlung erzeugt einen unhandledrejection-Fehler.
In <iframe>-Elementen mit sandbox funktioniert die Sperre nur mit dem Token allow-orientation-lock.
Ein neuer lock()- oder unlock()-Aufruf bricht ein noch offenes Promise mit AbortError ab.
Das veraltete screen.lockOrientation() ist nicht mehr zu verwenden.

Siehe auch

new NotificationEvent() ScreenOrientation.unlock() Screen.lockOrientation() Navigation.back() Notification.close()