ScreenOrientation — Schnittstelle · JavaScript-Referenz

Signatur

interface ScreenOrientation extends EventTarget

Beschreibung

Das Interface ScreenOrientation gehört zur Screen Orientation API und beschreibt die aktuelle Ausrichtung des Bildschirms bzw. Dokuments. Eine eigene Instanz erzeugt man nicht, man greift immer über screen.orientation darauf zu. Da das Interface von EventTarget erbt, kann man auf Änderungen der Ausrichtung mit dem Ereignis change reagieren.

Wichtige Bestandteile:

type (nur lesbar): "portrait-primary", "portrait-secondary", "landscape-primary" oder "landscape-secondary".
angle (nur lesbar): Drehwinkel in Grad (0, 90, 180, 270).
lock(orientation): sperrt die Ausrichtung und gibt ein Promise<void> zurück.
unlock(): hebt eine Sperre wieder auf.
onchange / Ereignis change: wird bei einer Änderung der Ausrichtung ausgelöst.

Gebraucht wird das Interface vor allem für Spiele, Videoplayer, Kamera-Apps und responsive Layouts, die mehr als CSS-Media-Queries (@media (orientation: landscape)) brauchen, also zum Beispiel Logik in JavaScript, die an die Drehung des Geräts gekoppelt ist. Für reine Layout-Anpassungen reichen die Media-Queries meistens aus.

Parameter

Name	Typ	Default	Beschreibung
$orientation Pflicht	"any"\|"natural"\|"landscape"\|"portrait"\|"portrait-primary"\|"portrait-secondary"\|"landscape-primary"\|"landscape-secondary"		Parameter von `lock()`: gewünschte Ausrichtung, auf die gesperrt werden soll.

Beispiele

Aktuelle Ausrichtung auslesen

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

const istQuerformat = type.startsWith('landscape');
console.log('Querformat?', istQuerformat);

Ausrichtung: landscape-primary, Winkel: 0° Querformat? true

Auf Änderungen reagieren (addEventListener und onchange)

const handleChange = () => {
  const { type, angle } = screen.orientation;
  document.body.dataset.orientation = type;
  console.log(`Neu: ${type} (${angle}°)`);
};

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

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

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

Neu: portrait-primary (0°)

Spiel im Vollbild auf Querformat sperren

const startButton = document.querySelector('#start');

startButton.addEventListener('click', async () => {
  try {
    // lock() funktioniert meist nur im Vollbildmodus
    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, err.message);
  }
});

document.addEventListener('fullscreenchange', () => {
  if (!document.fullscreenElement) {
    screen.orientation.unlock();
  }
});

Ausrichtung gesperrt: landscape-primary

Feature-Erkennung mit Fallback

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

console.log(getOrientation());

portrait-primary

// Wichtig · Fallstricke

Kompatibilität: type, angle und das Ereignis change gibt es in allen modernen Browsern, in Safari erst ab 16.4. Ältere iOS-Versionen kennen nur das veraltete window.orientation und das Ereignis orientationchange.
lock() ist stark eingeschränkt: Auf Desktop-Browsern und in Safari wird das Promise meist mit NotSupportedError abgelehnt. Auf Android klappt das Sperren in der Regel nur im Vollbildmodus oder in installierten PWAs. Deshalb lock() immer mit try/catch aufrufen.
Wer lock() nicht aus einer Nutzeraktion heraus oder außerhalb des Vollbilds aufruft, bekommt oft einen SecurityError oder NotSupportedError. In sandboxed iframes ist dafür allow-orientation-lock nötig.
"primary" und "secondary" hängen von der natürlichen Ausrichtung des Geräts ab. Bei Tablets ist angle === 0 deshalb manchmal Querformat. Verlass dich also nicht darauf, dass ein Winkel immer dieselbe Ausrichtung bedeutet.
Für reine Layout-Anpassungen ist die CSS-Media-Query orientation sparsamer und robuster.

Siehe auch

Screen Presentation ScreenDetails ScreenDetailed CSSAnimation