JavaScript Screen Orientation API

La Screen Orientation API permite que una página web lea la orientación actual del dispositivo, reaccione cuando cambia y — en dispositivos compatibles — bloquee la pantalla en una orientación específica. Es útil para juegos, reproductores de vídeo, aplicaciones de cámara y cualquier cosa donde el diseño dependa de si el dispositivo se sostiene en modo vertical u horizontal.

Esta página cubre las cuatro cosas que necesitas saber para usarla:

• Leer la orientación actual con screen.orientation (sus propiedades type y angle).
• Reaccionar a la rotación con el evento change.
• Forzar una orientación con lock() y liberarla con unlock().
• Los requisitos y limitaciones: un contexto seguro, pantalla completa para el bloqueo y alternativas de degradación elegante.

La API se expone a través de screen.orientation, un objeto ScreenOrientation disponible en el objeto global screen. Solo funciona en un contexto seguro (HTTPS o localhost).

Alternativa CSS: Si solo necesitas ajustar el diseño al rotar, normalmente no necesitas JavaScript en absoluto — usa las media queries CSS @media (orientation: portrait) y @media (orientation: landscape). Recurre a esta API cuando necesites el valor de orientación en un script, quieras ejecutar código al rotar o necesites bloquear la pantalla.

Leer la Orientación Actual

screen.orientation tiene dos propiedades de solo lectura:

• type — un string que describe la orientación: "portrait-primary", "portrait-secondary", "landscape-primary" o "landscape-secondary".
• angle — la rotación en grados relativa a la orientación natural del dispositivo: 0, 90, 180 o 270.

Verificar la Orientación Actual

Para leer la orientación actual, accede a estas propiedades directamente:

<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>

En un teléfono sostenido en posición vertical, normalmente verías portrait-primary con un ángulo de 0; al girarlo un cuarto de vuelta se convierte en landscape-primary a 90. La mayoría de los monitores de escritorio reportan landscape-primary y nunca cambian.

Reaccionar a los Cambios de Orientación

El objeto screen.orientation dispara un evento change cada vez que la orientación cambia. Escucha este evento para volver a ejecutar la lógica de diseño, repintar un <canvas>, pausar un juego o recalcular tamaños. El evento en sí no lleva datos adicionales — lee el nuevo estado desde screen.orientation dentro del manejador.

<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>

El evento change es el reemplazo moderno del antiguo evento window.onorientationchange y el número window.orientation obsoleto — prefiere screen.orientation en código nuevo.

Bloquear la Orientación de Pantalla

screen.orientation.lock() fuerza la pantalla a una orientación elegida. Es la herramienta adecuada para un juego en pantalla completa que solo funciona en horizontal, o un reproductor de vídeo que no debería girarse mientras reproduce.

Dos requisitos son importantes:

1. El documento debe estar en pantalla completa. El bloqueo solo funciona después de una solicitud exitosa a la Fullscreen API. Llamar a lock() fuera de pantalla completa se rechaza con un NotSupportedError (o similar) en la mayoría de los navegadores.
2. lock() devuelve una Promise. Se resuelve cuando el bloqueo se aplica y se rechaza si la orientación no es compatible, la plataforma lo prohíbe (la mayoría de los escritorios) o el documento no está en pantalla completa. Siempre gestiona el rechazo.

<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>

El string de orientación pasado a lock() puede ser un valor único ("portrait", "landscape", "portrait-primary", …) o, en algunos navegadores, un array de valores aceptables. El bloqueo debe activarse mediante un gesto del usuario, como el clic en el botón anterior.

Dónde funciona: El bloqueo es compatible principalmente en plataformas móviles (especialmente Chrome/Android). La mayoría de los navegadores de escritorio exponen screen.orientation para lectura, pero rechazan lock() — siempre asume que puede fallar y diseña un diseño que funcione en cualquier orientación.

Desbloquear la Orientación de Pantalla

screen.orientation.unlock() libera un bloqueo establecido anteriormente, permitiendo que la pantalla siga al dispositivo de nuevo. Es sincrónico y no devuelve nada. Salir de pantalla completa también borra cualquier bloqueo activo automáticamente.

<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>

Buenas Prácticas

• Trata el bloqueo como un mejor esfuerzo. Falla en la mayoría de los escritorios y puede desactivarse en la configuración del navegador, así que nunca dependas de él para la funcionalidad principal — combínalo con un diseño que funcione en cualquier orientación.
• Siempre captura la Promise. Un lock() rechazado que ignores se convierte en un rechazo no gestionado en la consola.
• Entra primero en pantalla completa. Un bloqueo sin una solicitud de pantalla completa activa será rechazado.
• Prefiere CSS para el diseño. Usa @media (orientation: …) para los estilos y reserva esta API para el comportamiento que genuinamente necesita el valor de orientación en JavaScript.
• Detecta las características. Comprueba if (screen.orientation) e if (screen.orientation.lock) antes de llamar, y recuerda que la API necesita un contexto seguro (HTTPS o localhost).

Temas Relacionados

• JavaScript Fullscreen API — necesario antes de bloquear la orientación.
• JavaScript Window Sizes and Scrolling — lee las dimensiones del viewport que cambian al rotar.

Práctica