JavaScript Screen Orientation API

La Screen Orientation API consente a una pagina web di leggere l'orientamento corrente del dispositivo, reagire quando cambia e — sui dispositivi che la supportano — bloccare lo schermo su un orientamento specifico. È utile per giochi, lettori video, app per fotocamera e qualsiasi contesto in cui il layout dipende dal fatto che il dispositivo sia tenuto in verticale o in orizzontale.

Questa pagina tratta le quattro cose che devi sapere per usarla:

• Leggere l'orientamento corrente con screen.orientation (le sue proprietà type e angle).
• Reagire alla rotazione con l'evento change.
• Forzare un orientamento con lock() e rilasciarlo con unlock().
• I requisiti e i limiti: un contesto sicuro, il fullscreen per il blocco e i fallback appropriati.

L'API è esposta tramite screen.orientation, un oggetto ScreenOrientation disponibile sull'oggetto globale screen. Funziona solo in un contesto sicuro (HTTPS o localhost).

Alternativa CSS: Se hai solo bisogno di adattare il layout alla rotazione, di solito non hai bisogno di JavaScript — usa le media query CSS @media (orientation: portrait) e @media (orientation: landscape). Ricorri a questa API quando hai bisogno del valore dell'orientamento in uno script, vuoi eseguire codice alla rotazione, o devi bloccare lo schermo.

Lettura dell'Orientamento Corrente

screen.orientation ha due proprietà di sola lettura:

• type — una string che descrive l'orientamento: "portrait-primary", "portrait-secondary", "landscape-primary", o "landscape-secondary".
• angle — la rotazione in gradi rispetto all'orientamento naturale del dispositivo: 0, 90, 180 o 270.

Verificare l'Orientamento Corrente

Per leggere l'orientamento corrente, accedi direttamente a queste proprietà:

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

Su un telefono tenuto in verticale vedrai tipicamente portrait-primary con un angolo di 0; ruotato di un quarto di giro diventa landscape-primary a 90. La maggior parte dei monitor desktop riporta landscape-primary e non cambia mai.

Reagire ai Cambiamenti di Orientamento

L'oggetto screen.orientation genera un evento change ogni volta che l'orientamento cambia. Ascoltalo per rieseguire la logica di layout, ridisegnare un <canvas>, mettere in pausa un gioco o ricalcolare le dimensioni. L'evento stesso non trasporta dati aggiuntivi — leggi il nuovo stato da screen.orientation all'interno del gestore.

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

L'evento change è il sostituto moderno del vecchio evento window.onorientationchange e del numero window.orientation deprecato — preferisci screen.orientation nel nuovo codice.

Bloccare l'Orientamento dello Schermo

screen.orientation.lock() forza lo schermo in un orientamento scelto. È lo strumento giusto per un gioco a schermo intero che funziona solo in orizzontale, o per un lettore video che non deve ruotare durante la riproduzione.

Due requisiti sono importanti:

1. Il documento deve essere in fullscreen. Il blocco funziona solo dopo una richiesta riuscita della Fullscreen API. Chiamare lock() fuori dal fullscreen genera un errore NotSupportedError (o simile) sulla maggior parte dei browser.
2. lock() restituisce una Promise. Si risolve quando il blocco viene applicato e viene rifiutata se l'orientamento non è supportato, la piattaforma lo vieta (la maggior parte dei desktop), o il documento non è in fullscreen. Gestisci sempre il rifiuto.

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

La string di orientamento passata a lock() può essere un singolo valore ("portrait", "landscape", "portrait-primary", …) o, in alcuni browser, un array di valori accettabili. Il blocco deve essere attivato da un gesto dell'utente, come il clic sul pulsante sopra.

Dove funziona: Il blocco è supportato principalmente sulle piattaforme mobile (in particolare Chrome/Android). La maggior parte dei browser desktop espone screen.orientation per la lettura ma rifiuta lock() — assume sempre che possa fallire e progetta un layout che funzioni in qualsiasi orientamento.

Sbloccare l'Orientamento dello Schermo

screen.orientation.unlock() rilascia un blocco impostato in precedenza, permettendo allo schermo di seguire nuovamente il dispositivo. È sincrono e non restituisce nulla. Uscire dal fullscreen cancella automaticamente anche qualsiasi blocco attivo.

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

Buone Pratiche

• Tratta il blocco come un tentativo non garantito. Fallisce sulla maggior parte dei desktop e può essere disabilitato nelle impostazioni del browser, quindi non dipendere mai da esso per le funzionalità principali — abbinalo a un layout che funzioni in qualsiasi orientamento.
• Gestisci sempre la Promise. Un lock() rifiutato che viene ignorato diventa un rifiuto non gestito nella console.
• Entra prima in fullscreen. Un blocco senza una richiesta di fullscreen attiva verrà rifiutato.
• Preferisci CSS per il layout. Usa @media (orientation: …) per lo stile e riserva questa API per i comportamenti che necessitano realmente del valore dell'orientamento in JavaScript.
• Rileva le funzionalità. Controlla if (screen.orientation) e if (screen.orientation.lock) prima di chiamarle, e ricorda che l'API richiede un contesto sicuro (HTTPS o localhost).

Argomenti Correlati

• JavaScript Fullscreen API — necessaria prima di bloccare l'orientamento.
• JavaScript Window Sizes and Scrolling — leggi le dimensioni del viewport che cambiano alla rotazione.

Esercitazione