JavaScript Screen Orientation API

Die Screen Orientation API ermöglicht es einer Webseite, die aktuelle Ausrichtung des Geräts zu lesen, auf Änderungen zu reagieren und — auf unterstützten Geräten — den Bildschirm auf eine bestimmte Ausrichtung zu sperren. Sie ist nützlich für Spiele, Videoplayer, Kamera-Apps und alles, bei dem das Layout davon abhängt, ob das Gerät im Hoch- oder Querformat gehalten wird.

Diese Seite behandelt die vier Dinge, die Sie wissen müssen, um sie zu nutzen:

• Die aktuelle Ausrichtung mit screen.orientation lesen (deren type und angle).
• Auf Rotation mit dem change-Event reagieren.
• Eine Ausrichtung mit lock() erzwingen und mit unlock() freigeben.
• Die Voraussetzungen und Einschränkungen: ein sicherer Kontext, Fullscreen zum Sperren und sinnvolle Fallbacks.

Die API wird über screen.orientation bereitgestellt, ein ScreenOrientation-Objekt, das am globalen screen-Objekt verfügbar ist. Es funktioniert nur in einem sicheren Kontext (HTTPS oder localhost).

CSS-Alternative: Wenn Sie nur das Layout bei Rotation anpassen möchten, benötigen Sie in der Regel überhaupt kein JavaScript — verwenden Sie CSS-Media-Queries @media (orientation: portrait) und @media (orientation: landscape). Greifen Sie auf diese API zurück, wenn Sie den Ausrichtungswert im Script benötigen, Code bei Rotation ausführen möchten oder den Bildschirm sperren müssen.

Die aktuelle Ausrichtung lesen

screen.orientation besitzt zwei schreibgeschützte Eigenschaften:

• type — ein string, der die Ausrichtung beschreibt: "portrait-primary", "portrait-secondary", "landscape-primary" oder "landscape-secondary".
• angle — die Drehung in Grad relativ zur natürlichen Ausrichtung des Geräts: 0, 90, 180 oder 270.

Aktuelle Ausrichtung prüfen

Um die aktuelle Ausrichtung zu lesen, greifen Sie direkt auf diese Eigenschaften zu:

<script>
    // Read the current screen orientation
    function displayOrientation() {
        if (screen.orientation) {
            alert('Type: ' + screen.orientation.type +
                  '\nAngle: ' + screen.orientation.angle + '°');
        } else {
            alert('Screen Orientation API is not supported.');
        }
    }
    document.getElementById('check-btn').addEventListener('click', displayOrientation);
</script>

<div>
    <button id="check-btn">Check Orientation</button>
</div>

Bei einem aufrecht gehaltenen Mobiltelefon sehen Sie typischerweise portrait-primary mit einem Winkel von 0; um eine Vierteldrehung gedreht wird es zu landscape-primary bei 90. Die meisten Desktop-Monitore melden landscape-primary und ändern sich nie.

Auf Ausrichtungsänderungen reagieren

Das screen.orientation-Objekt löst ein change-Event aus, wann immer die Ausrichtung wechselt. Lauschen Sie darauf, um Layout-Logik erneut auszuführen, ein <canvas> neu zu zeichnen, ein Spiel zu pausieren oder Größen neu zu berechnen. Das Event selbst enthält keine zusätzlichen Daten — lesen Sie den neuen Zustand aus screen.orientation im Handler.

<script>
    var output = document.getElementById('orientation-status');

    function showOrientation() {
        output.textContent =
            screen.orientation.type + ' (' + screen.orientation.angle + '°)';
    }

    // Update on load and whenever the device rotates
    showOrientation();
    screen.orientation.addEventListener('change', showOrientation);
</script>

<div>
    <p>Current orientation: <strong id="orientation-status">…</strong></p>
</div>

Das change-Event ist der moderne Ersatz für das alte window.onorientationchange-Event und die veraltete window.orientation-Zahl — bevorzugen Sie screen.orientation in neuem Code.

Die Bildschirmausrichtung sperren

screen.orientation.lock() zwingt den Bildschirm in eine gewählte Ausrichtung. Es ist das richtige Werkzeug für ein Vollbild-Spiel, das nur im Querformat funktioniert, oder einen Videoplayer, der beim Abspielen nicht kippen soll.

Zwei Voraussetzungen sind wichtig:

1. Das Dokument muss sich im Vollbild-Modus befinden. Das Sperren funktioniert nur nach einer erfolgreichen Fullscreen API-Anfrage. Das Aufrufen von lock() außerhalb des Vollbilds wird in den meisten Browsern mit einem NotSupportedError (oder ähnlichem) abgelehnt.
2. lock() gibt ein Promise zurück. Es wird aufgelöst, wenn die Sperre angewendet wird, und abgelehnt, wenn die Ausrichtung nicht unterstützt wird, die Plattform es verbietet (die meisten Desktops) oder das Dokument nicht im Vollbild ist. Behandeln Sie die Ablehnung immer.

<script>
    var app = document.getElementById('app');

    async function lockLandscape() {
        try {
            // 1. Enter fullscreen first — locking requires it.
            await app.requestFullscreen();
            // 2. Then lock to landscape.
            await screen.orientation.lock('landscape-primary');
            console.log('Orientation locked to landscape.');
        } catch (error) {
            console.error('Lock failed:', error.message);
        }
    }

    document.getElementById('lock-btn').addEventListener('click', lockLandscape);
</script>

<div id="app">
    <button id="lock-btn">Go Fullscreen &amp; Lock to Landscape</button>
</div>

Der an lock() übergebene Ausrichtungs-string kann ein einzelner Wert sein ("portrait", "landscape", "portrait-primary", …) oder in einigen Browsern ein array akzeptabler Werte. Das Sperren muss durch eine Benutzergeste ausgelöst werden, wie etwa den oben gezeigten Button-Klick.

Wo es funktioniert: Das Sperren wird hauptsächlich auf mobilen Plattformen unterstützt (insbesondere Chrome/Android). Die meisten Desktop-Browser stellen screen.orientation zum Lesen bereit, lehnen lock() jedoch ab — gehen Sie immer davon aus, dass es fehlschlagen kann, und gestalten Sie ein Layout, das in jeder Ausrichtung funktioniert.

Die Bildschirmausrichtung entsperren

screen.orientation.unlock() hebt eine zuvor gesetzte Sperre auf und lässt den Bildschirm dem Gerät wieder folgen. Es ist synchron und gibt nichts zurück. Das Verlassen des Vollbilds löscht eine aktive Sperre ebenfalls automatisch.

<script>
    function unlockOrientation() {
        if (screen.orientation && screen.orientation.unlock) {
            screen.orientation.unlock();
            console.log('Orientation unlocked.');
        }
    }
    document.getElementById('unlock-btn').addEventListener('click', unlockOrientation);
</script>

<div>
    <button id="unlock-btn">Unlock Orientation</button>
</div>

Best Practices

• Behandeln Sie das Sperren als Best-Effort. Es schlägt auf den meisten Desktops fehl und kann in den Browser-Einstellungen deaktiviert werden — verlassen Sie sich daher nie darauf für die Kernfunktionalität. Kombinieren Sie es mit einem Layout, das jede Ausrichtung übersteht.
• Fangen Sie das Promise immer ab. Ein abgelehntes lock(), das Sie ignorieren, wird zu einer unbehandelten Ablehnung in der Konsole.
• Wechseln Sie zuerst in den Vollbild-Modus. Eine Sperre ohne eine aktive Vollbild-Anfrage wird abgelehnt.
• Bevorzugen Sie CSS für das Layout. Verwenden Sie @media (orientation: …) für das Styling und behalten Sie diese API für Verhalten vor, das den Ausrichtungswert tatsächlich in JavaScript benötigt.
• Feature-Detection durchführen. Prüfen Sie if (screen.orientation) und if (screen.orientation.lock) vor dem Aufruf, und denken Sie daran, dass die API einen sicheren Kontext (HTTPS oder localhost) benötigt.

Verwandte Themen

• JavaScript Fullscreen API — erforderlich, bevor die Ausrichtung gesperrt werden kann.
• JavaScript Window Sizes and Scrolling — Viewport-Dimensionen lesen, die sich bei Rotation ändern.

Übungen