JavaScript Screen Orientation API

La Screen Orientation API permet à une page web de lire l'orientation actuelle de l'appareil, de réagir lorsqu'elle change et — sur les appareils compatibles — de verrouiller l'écran sur une orientation spécifique. Elle est utile pour les jeux, les lecteurs vidéo, les applications de caméra et tout ce dont la mise en page dépend du fait que l'appareil soit tenu en mode portrait ou paysage.

Cette page couvre les quatre points essentiels à connaître pour l'utiliser :

• Lire l'orientation actuelle avec screen.orientation (son type et son angle).
• Réagir à la rotation avec l'événement change.
• Forcer une orientation avec lock() et la relâcher avec unlock().
• Les exigences et les limites : un contexte sécurisé, le plein écran pour le verrouillage, et des solutions de repli adaptées.

L'API est exposée via screen.orientation, un objet ScreenOrientation disponible sur l'objet global screen. Elle ne fonctionne que dans un contexte sécurisé (HTTPS ou localhost).

Alternative CSS : Si vous n'avez besoin que d'ajuster la mise en page lors d'une rotation, vous n'avez généralement pas besoin de JavaScript du tout — utilisez les media queries CSS @media (orientation: portrait) et @media (orientation: landscape). Recourez à cette API lorsque vous avez besoin de la valeur d'orientation dans un script, souhaitez exécuter du code lors d'une rotation, ou devez verrouiller l'écran.

Lire l'orientation actuelle

screen.orientation possède deux propriétés en lecture seule :

• type — une string décrivant l'orientation : "portrait-primary", "portrait-secondary", "landscape-primary" ou "landscape-secondary".
• angle — la rotation en degrés par rapport à l'orientation naturelle de l'appareil : 0, 90, 180 ou 270.

Vérifier l'orientation actuelle

Pour lire l'orientation actuelle, accédez directement à ces propriétés :

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

Sur un téléphone tenu droit, vous verrez généralement portrait-primary avec un angle de 0 ; tourné d'un quart de tour, il devient landscape-primary à 90. La plupart des moniteurs de bureau indiquent landscape-primary et ne changent jamais.

Réagir aux changements d'orientation

L'objet screen.orientation déclenche un événement change chaque fois que l'orientation change. Écoutez-le pour relancer la logique de mise en page, repeindre un <canvas>, mettre un jeu en pause ou recalculer des tailles. L'événement lui-même ne transporte aucune donnée supplémentaire — lisez le nouvel état depuis screen.orientation dans le gestionnaire.

<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'événement change est le remplacement moderne de l'ancien événement window.onorientationchange et du nombre déprécié window.orientation — préférez screen.orientation dans le nouveau code.

Verrouiller l'orientation de l'écran

screen.orientation.lock() force l'écran dans une orientation choisie. C'est l'outil approprié pour un jeu en plein écran qui ne fonctionne qu'en mode paysage, ou un lecteur vidéo qui ne doit pas basculer pendant la lecture.

Deux exigences sont importantes :

1. Le document doit être en plein écran. Le verrouillage ne fonctionne qu'après une requête réussie via la Fullscreen API. L'appel de lock() hors du plein écran est rejeté avec une NotSupportedError (ou similaire) sur la plupart des navigateurs.
2. lock() retourne une Promise. Elle se résout lorsque le verrou est appliqué et est rejetée si l'orientation n'est pas prise en charge, si la plateforme l'interdit (la plupart des ordinateurs de bureau), ou si le document n'est pas en plein écran. Gérez toujours le rejet.

<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 d'orientation transmise à lock() peut être une valeur unique ("portrait", "landscape", "portrait-primary", …) ou, dans certains navigateurs, un array de valeurs acceptables. Le verrouillage doit être déclenché par un geste de l'utilisateur, comme le clic sur le bouton ci-dessus.

Compatibilité : Le verrouillage est principalement pris en charge sur les plateformes mobiles (notamment Chrome/Android). La plupart des navigateurs de bureau exposent screen.orientation pour la lecture, mais rejettent lock() — supposez toujours qu'il peut échouer et concevez une mise en page qui fonctionne dans n'importe quelle orientation.

Déverrouiller l'orientation de l'écran

screen.orientation.unlock() libère un verrou que vous avez défini précédemment, permettant à l'écran de suivre à nouveau l'appareil. Cette méthode est synchrone et ne retourne rien. Quitter le plein écran efface également tout verrou actif automatiquement.

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

Bonnes pratiques

• Traitez le verrouillage comme une tentative au mieux. Il échoue sur la plupart des ordinateurs de bureau et peut être désactivé dans les paramètres du navigateur, donc ne comptez jamais dessus pour des fonctionnalités essentielles — associez-le à une mise en page qui fonctionne dans toute orientation.
• Gérez toujours la Promise. Un lock() rejeté que vous ignorez devient un rejet non géré dans la console.
• Entrez d'abord en plein écran. Un verrou sans requête de plein écran active sera rejeté.
• Préférez CSS pour la mise en page. Utilisez @media (orientation: …) pour le style et réservez cette API aux comportements qui nécessitent véritablement la valeur d'orientation en JavaScript.
• Détectez les fonctionnalités. Vérifiez if (screen.orientation) et if (screen.orientation.lock) avant d'appeler, et n'oubliez pas que l'API nécessite un contexte sécurisé (HTTPS ou localhost).

Sujets connexes

• JavaScript Fullscreen API — requis avant de verrouiller l'orientation.
• JavaScript Window Sizes and Scrolling — lisez les dimensions du viewport qui changent lors d'une rotation.

Pratique