JavaScript Screen Orientation API

A Screen Orientation API permite que uma página web leia a orientação atual do dispositivo, reaja quando ela muda e — em dispositivos compatíveis — bloqueie a tela em uma orientação específica. É útil para jogos, players de vídeo, aplicativos de câmera e tudo em que o layout depende de o dispositivo estar na vertical ou na horizontal.

Esta página aborda as quatro coisas que você precisa saber para usá-la:

• Ler a orientação atual com screen.orientation (seu type e angle).
• Reagir à rotação com o evento change.
• Forçar uma orientação com lock() e liberá-la com unlock().
• Os requisitos e limites: um contexto seguro, fullscreen para bloquear e fallbacks adequados.

A API é exposta por meio de screen.orientation, um objeto ScreenOrientation disponível no objeto global screen. Funciona apenas em um contexto seguro (HTTPS ou localhost).

Alternativa com CSS: Se você só precisa ajustar o layout na rotação, geralmente não precisa de JavaScript — use as media queries CSS @media (orientation: portrait) e @media (orientation: landscape). Recorra a esta API quando precisar do valor da orientação em script, quiser executar código na rotação ou precisar bloquear a tela.

Lendo a Orientação Atual

screen.orientation tem duas propriedades somente leitura:

• type — uma string que descreve a orientação: "portrait-primary", "portrait-secondary", "landscape-primary" ou "landscape-secondary".
• angle — a rotação em graus relativa à orientação natural do dispositivo: 0, 90, 180 ou 270.

Verificando a Orientação Atual

Para ler a orientação atual, acesse essas propriedades diretamente:

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

Em um telefone segurado na vertical, você normalmente veria portrait-primary com um ângulo de 0; virado um quarto de volta, torna-se landscape-primary em 90. A maioria dos monitores de desktop reporta landscape-primary e nunca muda.

Reagindo a Mudanças de Orientação

O objeto screen.orientation dispara um evento change sempre que a orientação muda. Ouça-o para re-executar a lógica de layout, redesenhar um <canvas>, pausar um jogo ou recalcular tamanhos. O evento em si não carrega dados extras — leia o novo estado de screen.orientation dentro do 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>

O evento change é o substituto moderno do antigo evento window.onorientationchange e do número obsoleto window.orientation — prefira screen.orientation em código novo.

Bloqueando a Orientação da Tela

screen.orientation.lock() força a tela em uma orientação escolhida. É a ferramenta certa para um jogo em fullscreen que só funciona na horizontal, ou um player de vídeo que não deve girar durante a reprodução.

Dois requisitos são importantes:

1. O documento deve estar em fullscreen. O bloqueio só funciona após uma solicitação bem-sucedida da Fullscreen API. Chamar lock() fora do fullscreen rejeita com NotSupportedError (ou similar) na maioria dos navegadores.
2. lock() retorna uma Promise. Ela é resolvida quando o bloqueio é aplicado e rejeitada se a orientação não for suportada, a plataforma proibir (maioria dos desktops) ou o documento não estiver em fullscreen. Sempre trate a rejeição.

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

A string de orientação passada para lock() pode ser um único valor ("portrait", "landscape", "portrait-primary", …) ou, em alguns navegadores, um array de valores aceitáveis. O bloqueio deve ser acionado por um gesto do usuário, como o clique no botão acima.

Onde funciona: O bloqueio é suportado principalmente em plataformas móveis (notavelmente Chrome/Android). A maioria dos navegadores de desktop expõe screen.orientation para leitura, mas rejeita lock() — sempre assuma que pode falhar e projete um layout que funcione em qualquer orientação.

Desbloqueando a Orientação da Tela

screen.orientation.unlock() libera um bloqueio definido anteriormente, permitindo que a tela siga o dispositivo novamente. É síncrono e não retorna nada. Sair do fullscreen também limpa automaticamente qualquer bloqueio ativo.

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

Boas Práticas

• Trate o bloqueio como melhor esforço. Ele falha na maioria dos desktops e pode ser desabilitado nas configurações do navegador, então nunca dependa dele para funcionalidade central — combine-o com um layout que suporte qualquer orientação.
• Sempre capture a Promise. Um lock() rejeitado que você ignora torna-se uma rejeição não tratada no console.
• Entre em fullscreen primeiro. Um bloqueio sem uma solicitação ativa de fullscreen será rejeitado.
• Prefira CSS para layout. Use @media (orientation: …) para estilização e reserve esta API para comportamentos que genuinamente precisam do valor de orientação em JavaScript.
• Detecte a funcionalidade. Verifique if (screen.orientation) e if (screen.orientation.lock) antes de chamar, e lembre-se de que a API precisa de um contexto seguro (HTTPS ou localhost).

Tópicos Relacionados

• JavaScript Fullscreen API — necessária antes de bloquear a orientação.
• JavaScript Window Sizes and Scrolling — leia as dimensões do viewport que mudam na rotação.

Prática