Screen.orientation — Eigenschaft · JavaScript-Referenz

Signatur

Screen.orientation

Beschreibung

screen.orientation gibt ein ScreenOrientation-Objekt zurück. Es beschreibt, wie der Bildschirm gerade ausgerichtet ist. Über type bekommst du die Ausrichtung als Zeichenkette ("portrait-primary", "portrait-secondary", "landscape-primary" oder "landscape-secondary"). angle liefert den Drehwinkel in Grad (0, 90, 180 oder 270).

Die Eigenschaft ist nützlich, wenn sich das Layout oder die Logik je nach Ausrichtung ändern soll, etwa bei Spielen, Videoplayern, Kamera-Anwendungen oder Kartenansichten. Das Objekt erbt von EventTarget. Bei jeder Drehung löst es das Ereignis change aus. Dafür kannst du addEventListener("change", …) oder die Eigenschaft onchange verwenden.

Mit screen.orientation.lock() kannst du eine Ausrichtung erzwingen, mit unlock() hebst du die Sperre wieder auf. Das Sperren klappt in der Regel nur im Vollbildmodus und auf Mobilgeräten.

Wenn es nur um die Darstellung geht, reichen oft CSS-Medienabfragen wie @media (orientation: landscape). Die JavaScript-API brauchst du vor allem, wenn du den genauen Winkel wissen musst oder die Ausrichtung sperren willst.

Rückgabewert

Typ

ScreenOrientation

Beschreibung

Ein Objekt mit den Eigenschaften type (string) und angle (number), den Methoden lock() und unlock() sowie dem Ereignis change.

Beispiele

Aktuelle Ausrichtung auslesen

const { type, angle } = screen.orientation;
console.log(`Ausrichtung: ${type}, Winkel: ${angle}°`);

Ausrichtung: landscape-primary, Winkel: 0°

Auf Drehungen reagieren (addEventListener und onchange)

const handleChange = () => {
  const isLandscape = screen.orientation.type.startsWith('landscape');
  document.body.classList.toggle('querformat', isLandscape);
  console.log('Neue Ausrichtung:', screen.orientation.type);
};

screen.orientation.addEventListener('change', handleChange);

// Später wieder entfernen:
// screen.orientation.removeEventListener('change', handleChange);

// Alternative über die on-Property:
// screen.orientation.onchange = handleChange;

Neue Ausrichtung: portrait-primary

Querformat für ein Spiel im Vollbild sperren

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

document.querySelector('#start').addEventListener('click', startGame);

// Beim Verlassen des Spiels:
// screen.orientation.unlock();

Ausrichtung gesperrt: landscape-primary

Funktionsprüfung mit Rückfall auf matchMedia

const getOrientation = () => {
  if (screen.orientation) return screen.orientation.type;
  return matchMedia('(orientation: portrait)').matches
    ? 'portrait-primary'
    : 'landscape-primary';
};

console.log(getOrientation());

portrait-primary

// Wichtig · Fallstricke

Browser-Unterstützung: Safari unterstützt screen.orientation erst ab Version 16.4. Ältere iOS-Geräte kennen nur das veraltete window.orientation mit dem Ereignis orientationchange. Prüfe daher vorher mit if (screen.orientation), ob die Eigenschaft vorhanden ist.
lock() ist stark eingeschränkt: Die Methode funktioniert meist nur im Vollbildmodus und auf Mobilgeräten. Auf dem Desktop und in Safari wird das Promise häufig mit NotSupportedError abgelehnt. Fange den Fehler deshalb immer mit try/catch ab.
Nicht mit Geräteausrichtung verwechseln: screen.orientation beschreibt, wie der Bildschirm ausgerichtet ist. Ist die automatische Drehung am Gerät abgeschaltet, ändert sich der Wert nicht, obwohl das Gerät physisch gedreht wird. Die physische Lage des Geräts liefert DeviceOrientationEvent.
Was „primary“ bedeutet, hängt vom Gerät ab: Auf Tablets entspricht angle === 0 oft dem Querformat, auf Smartphones dem Hochformat. Leite die Ausrichtung deshalb aus type ab, nicht aus angle.
Die Eigenschaft selbst ist schreibgeschützt. Eine Zuweisung an screen.orientation hat keine Wirkung.

Siehe auch

Screen Screen.mozEnabled Screen.height Screen.isExtended Screen.width