JavaScript Screen Orientation API

Screen Orientation API позволяет веб-странице считывать текущую ориентацию устройства, реагировать на её изменение и — на поддерживаемых устройствах — фиксировать экран в определённой ориентации. Это полезно для игр, видеоплееров, приложений камеры и всего, где компоновка зависит от того, держится ли устройство в портретном или ландшафтном режиме.

На этой странице рассматриваются четыре вещи, которые нужно знать для работы с ним:

• Чтение текущей ориентации через screen.orientation (свойства type и angle).
• Реакция на поворот с помощью события change.
• Принудительная установка ориентации через lock() и её снятие через unlock().
• Требования и ограничения: безопасный контекст, полноэкранный режим для блокировки и корректная деградация.

API доступен через screen.orientation — объект ScreenOrientation, доступный через глобальный объект screen. Работает только в безопасном контексте (HTTPS или localhost).

Альтернатива на CSS: если вам нужно только скорректировать компоновку при повороте, JavaScript обычно не нужен — используйте медиазапросы CSS @media (orientation: portrait) и @media (orientation: landscape). Прибегайте к этому API, когда нужно получить значение ориентации в скрипте, выполнить код при повороте или заблокировать экран.

Чтение текущей ориентации

screen.orientation имеет два свойства только для чтения:

• type — string, описывающая ориентацию: "portrait-primary", "portrait-secondary", "landscape-primary" или "landscape-secondary".
• angle — угол поворота в градусах относительно естественной ориентации устройства: 0, 90, 180 или 270.

Проверка текущей ориентации

Чтобы прочитать текущую ориентацию, обратитесь к этим свойствам напрямую:

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

На смартфоне, удерживаемом вертикально, вы обычно увидите portrait-primary с углом 0; при повороте на четверть оборота получится landscape-primary при 90. Большинство мониторов отображают landscape-primary и никогда не меняют значение.

Реакция на изменения ориентации

Объект screen.orientation генерирует событие change при каждом изменении ориентации. Подписывайтесь на него, чтобы пересчитывать компоновку, перерисовывать <canvas>, приостанавливать игру или пересчитывать размеры. Само событие не несёт дополнительных данных — читайте новое состояние из screen.orientation внутри обработчика.

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

Событие change — современная замена устаревшему событию window.onorientationchange и устаревшему числу window.orientation; в новом коде предпочтительно использовать screen.orientation.

Блокировка ориентации экрана

screen.orientation.lock() принудительно переключает экран в выбранную ориентацию. Это нужный инструмент для полноэкранной игры, работающей только в ландшафтном режиме, или видеоплеера, который не должен переворачиваться во время воспроизведения.

Два требования важны:

1. Документ должен находиться в полноэкранном режиме. Блокировка работает только после успешного запроса через Fullscreen API. Вызов lock() вне полноэкранного режима отклоняется с ошибкой NotSupportedError (или аналогичной) в большинстве браузеров.
2. lock() возвращает Promise. Он разрешается при применении блокировки и отклоняется, если ориентация не поддерживается, платформа запрещает её (большинство настольных ПК) или документ не находится в полноэкранном режиме. Всегда обрабатывайте отклонение.

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

string ориентации, передаваемая в lock(), может быть единственным значением ("portrait", "landscape", "portrait-primary", …) или, в некоторых браузерах, array допустимых значений. Блокировка должна инициироваться жестом пользователя, например нажатием кнопки, как показано выше.

Где это работает: блокировка в основном поддерживается на мобильных платформах (в первую очередь Chrome/Android). Большинство настольных браузеров предоставляют screen.orientation для чтения, но отклоняют lock() — всегда исходите из того, что блокировка может не сработать, и разрабатывайте компоновку, работающую в любой ориентации.

Разблокировка ориентации экрана

screen.orientation.unlock() снимает установленную ранее блокировку, позволяя экрану снова следовать за устройством. Метод синхронный и ничего не возвращает. Выход из полноэкранного режима также автоматически снимает активную блокировку.

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

Рекомендации

• Считайте блокировку попыткой, а не гарантией. На большинстве настольных устройств она не работает и может быть отключена в настройках браузера, поэтому никогда не полагайтесь на неё как на основную функциональность — сочетайте её с компоновкой, устойчивой к любой ориентации.
• Всегда обрабатывайте отклонение Promise. Необработанный отклонённый lock() превратится в необработанное исключение в консоли.
• Сначала войдите в полноэкранный режим. Блокировка без активного запроса полноэкранного режима будет отклонена.
• Предпочитайте CSS для компоновки. Используйте @media (orientation: …) для стилей, а этот API оставьте для поведения, которому действительно нужно значение ориентации в JavaScript.
• Проверяйте наличие функции. Проверяйте if (screen.orientation) и if (screen.orientation.lock) перед вызовом; помните, что API требует безопасного контекста (HTTPS или localhost).

Связанные темы

• JavaScript Fullscreen API — требуется перед блокировкой ориентации.
• JavaScript Window Sizes and Scrolling — чтение размеров viewport, которые изменяются при повороте.

Практика