Étape de Début

Installer

Vous pouvez utiliser notre configuration assistée par l'IA pour installer le plug-in. 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 plug-in 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

Obtenez l'orientation actuelle de l'écran.

Retourne 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

Verrouillez 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 de l'appareil à l'aide de capteurs de mouvement.

Remarque : L'interface utilisateur respectera toujours la mise en veille de l'orientation du utilisateur. Le suivi de mouvement permet de détecter comment l'appareil est physiquement tenu même lorsque 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éverrouillez l'orientation de l'écran.

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

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

await ScreenOrientation.unlock();

startOrientationTracking

Commencez à suivre l'orientation du dispositif à l'aide de capteurs de mouvement.

Cette méthode est utile lorsque vous souhaitez suivre l'orientation physique du dispositif indépendamment du 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êtez de suivre l'orientation du dispositif à l'aide de capteurs de mouvement.

Arrête le suivi de l'orientation basé sur le mouvement si cela avait é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 de 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 activé 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 du dispositif.

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

OrientationLockType

Type de verrouillage d'orientation pouvant être utilisé pour verrouiller l'orientation du dispositif.

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-générez la synchronisation lorsque le public API change en amont.

Continuez de la section « Getting Started »

Si vous utilisez Getting Started pour planifier le comportement des médias et de l'interface natifs, connectez-l’avec Utilisez @capgo/capacitor-orientation-écran pour la capacité native dans Utilisez @capgo/capacitor-orientation-écran, Utilisez @capgo/capacitor-activités-en-vivre pour la capacité native dans Utilisez @capgo/capacitor-activités-en-vivre, @capgo/capacitor-activités en direct pour les détails d'implémentation dans @capgo/capacitor-activités en direct Utilisation de @capgo/capacitor-joueur de vidéo pour la capacité native dans Utilisation de @capgo/capacitor-joueur de vidéo, et @capgo/capacitor-joueur de vidéo pour les détails d'implémentation dans @capgo/capacitor-joueur de vidéo.