Démarrage

Installez

Vous pouvez utiliser notre configuration assistée par l'IA pour installer le plugin. Ajoutez les Capgo compétences à votre outil IA à l'aide de la commande suivante :

npx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

Ensuite, utilisez la prompt suivante :

Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/capacitor-screen-orientation` plugin in my project.

Si vous préférez la configuration manuelle, installez le plugin en exécutant les commandes suivantes et suivez les instructions spécifiques à la plateforme ci-dessous :

bun add @capgo/capacitor-screen-orientation
bunx cap sync

Importer

import { ScreenOrientation } from '@capgo/capacitor-screen-orientation';

API Vue d'ensemble

orientation

Obtenir l'orientation actuelle de l'écran.

Renvoie l'orientation actuelle de l'écran de l'appareil.

import { ScreenOrientation } from '@capgo/capacitor-screen-orientation';

const result = await ScreenOrientation.orientation();
console.log('Current orientation:', result.type);

lock

Verrouille l'orientation de l'écran sur un type spécifique.

Verrouille l'écran sur l'orientation spécifiée. Sur iOS, si bypassOrientationLock est vrai, il commencera également à suivre l'orientation physique du dispositif à l'aide de capteurs de mouvement.

Remarque : L'interface utilisateur respectera toujours la mise en verrouillage d'orientation du utilisateur. Le suivi de mouvement permet de détecter comment le dispositif est physiquement tenu even si l'interface utilisateur ne tourne pas.

import { ScreenOrientation } from '@capgo/capacitor-screen-orientation';

// Standard lock
await ScreenOrientation.lock({ orientation: 'landscape' });

// Lock with motion tracking on iOS
await ScreenOrientation.lock({
  orientation: 'portrait',
  bypassOrientationLock: true
});

unlock

Déverrouille l'orientation de l'écran.

Permet à l'écran de tourner librement en fonction de la position du dispositif. Arrête également tout suivi d'orientation basé sur le mouvement si cela était activé.

import { ScreenOrientation } from '@capgo/capacitor-screen-orientation';

await ScreenOrientation.unlock();

startOrientationTracking

Démarrer le suivi de l'orientation du dispositif à l'aide de capteurs de mouvement.

Cette méthode est utile lorsque vous souhaitez suivre l'orientation physique du dispositif de manière independante de la verrouillage de l'orientation de l'écran. Elle utilise Core Motion sur iOS pour détecter les changements d'orientation.

import { ScreenOrientation } from '@capgo/capacitor-screen-orientation';

await ScreenOrientation.startOrientationTracking({
  bypassOrientationLock: true
});

// Listen for changes
ScreenOrientation.addListener('screenOrientationChange', (result) => {
  console.log('Orientation changed:', result.type);
});

stopOrientationTracking

Arrêter la suivi de l'orientation du dispositif à l'aide des capteurs de mouvement.

Arrête le suivi de l'orientation basé sur les mouvements si celui-ci a été démarré.

import { ScreenOrientation } from '@capgo/capacitor-screen-orientation';

await ScreenOrientation.stopOrientationTracking();

isOrientationLocked

Vérifiez si le verrouillage de l'orientation du dispositif est actuellement activé.

Cette méthode compare l'orientation physique du dispositif (à partir des capteurs de mouvement) avec l'orientation de l'interface utilisateur. Si elles diffèrent, le verrouillage de l'orientation est activé.

Remarque : Cela nécessite que le suivi de mouvement soit actif via startOrientationTracking() ou lock() avec bypassOrientationLock : true. Fonctionne sur les deux iOS (Core Motion) et Android (Accéléromètre).

import { ScreenOrientation } from '@capgo/capacitor-screen-orientation';

// Start motion tracking first
await ScreenOrientation.startOrientationTracking({
  bypassOrientationLock: true
});

// Check lock status
const status = await ScreenOrientation.isOrientationLocked();
if (status.locked) {
  console.log('Orientation lock is ON');
  console.log('Physical:', status.physicalOrientation);
  console.log('UI:', status.uiOrientation);
}

Référence de type

ScreenOrientationResult

Résultat retourné par la méthode orientation().

export interface ScreenOrientationResult {
  /**
   * The current orientation type.
   *
   * @since 1.0.0
   */
  type: OrientationType;
}

OrientationLockOptions

Options pour verrouiller l'orientation de l'écran.

export interface OrientationLockOptions {
  /**
   * The orientation type to lock to.
   *
   * @since 1.0.0
   */
  orientation: OrientationLockType;

  /**
   * Whether to track physical device orientation using motion sensors.
   * When true, uses device motion sensors to detect the true physical
   * orientation of the device, even when the device orientation lock is enabled.
   *
   * **Important:** This does NOT bypass the UI orientation lock.
   * The screen will still respect the user's orientation lock setting.
   * This option only affects orientation detection/tracking - you'll receive
   * orientation change events based on how the device is physically held,
   * but the UI will not rotate if orientation lock is enabled.
   *
   * Supported on iOS (Core Motion) and Android (Accelerometer).
   *
   * @default false
   * @since 1.0.0
   */
  bypassOrientationLock?: boolean;
}

StartOrientationTrackingOptions

Options pour démarrer la traçabilité de l'orientation à l'aide de capteurs de mouvement.

export interface StartOrientationTrackingOptions {
  /**
   * Whether to track physical device orientation using motion sensors.
   * When true, uses device motion sensors to detect the true physical
   * orientation of the device, even when the device orientation lock is enabled.
   *
   * **Important:** This does NOT bypass the UI orientation lock.
   * This only enables detection of the physical orientation.
   *
   * Supported on iOS (Core Motion) and Android (Accelerometer).
   *
   * @default false
   * @since 1.0.0
   */
  bypassOrientationLock?: boolean;
}

OrientationLockStatusResult

Résultat retourné par la méthode isOrientationLocked().

export interface OrientationLockStatusResult {
  /**
   * Whether the device orientation lock is currently enabled.
   *
   * This is determined by comparing the physical device orientation
   * (from motion sensors) with the UI orientation. If they differ,
   * orientation lock is enabled.
   *
   * Available on iOS (Core Motion) and Android (Accelerometer) when motion tracking is active.
   *
   * @since 1.0.0
   */
  locked: boolean;

  /**
   * The physical orientation of the device from motion sensors.
   * Available when motion tracking is active (iOS and Android).
   *
   * @since 1.0.0
   */
  physicalOrientation?: OrientationType;

  /**
   * The current UI orientation reported by the system.
   *
   * @since 1.0.0
   */
  uiOrientation: OrientationType;
}

OrientationType

Type d'orientation qui décrit l'état d'orientation de l'appareil.

export type OrientationType = 'portrait-primary' | 'portrait-secondary' | 'landscape-primary' | 'landscape-secondary';

OrientationLockType

Type de verrouillage d'orientation qui peut être utilisé pour verrouiller l'état d'orientation de l'appareil.

export type OrientationLockType =
  | 'any'
  | 'natural'
  | 'landscape'
  | 'portrait'
  | 'portrait-primary'
  | 'portrait-secondary'
  | 'landscape-primary'
  | 'landscape-secondary';

Source De Vérité

Cette page est générée à partir du plugin’s. src/definitions.tsRe-run the sync when the public API changes upstream.

Continuez de l'étape de démarrage

Si vous utilisez Getting Started pour planifier le comportement de médias et d'interface natifs, connectez-le à Utiliser @capgo/capacitor-orientation-écran pour la capacité native dans Utiliser @capgo/capacitor-orientation-écran, Utiliser @capgo/capacitor-activités-en-vivre pour la capacité native dans Utiliser @capgo/capacitor-activités-en-vivre, @capgo/capacitor-activités-en-vivre pour le détail d'implémentation dans @capgo/capacitor-activités-en-vivre, Utiliser @capgo/capacitor-joueur-de-videos pour la capacité native dans Utiliser @capgo/capacitor-joueur-de-videos, et @capgo/capacitor-player vidéo pour les détails d'implémentation dans @capgo/capacitor-player vidéo.