Prise en main

Installer

Vous pouvez utiliser notre configuration assistée par IA pour installer le plugin. Ajoutez les skills Capgo à votre outil d'IA avec la commande suivante :

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

Utilisez ensuite le prompt suivant :

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 une installation manuelle, installez le plugin en exécutant les commandes suivantes et suivez les instructions spécifiques à chaque plateforme ci-dessous :

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

Importer

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

Démarrage rapide

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

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

Exemple : verrouiller

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
});

Exemple : déverrouiller

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

await ScreenOrientation.unlock();

Erreurs courantes

• Écouteurs: supprimez les handles lors du démontage des écrans.
• Sync native : exécuter bunx cap sync après les mises à jour du plugin.
• Source de vérité : fiez-vous src/definitions.ts au repo GitHub.

Aperçu de API

orientation

Récupérer 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

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

Verrouille l'écran sur l'orientation spécifiée. Sur iOS, si bypassOrientationLock vaut true, cela lancera aussi le suivi de l'orientation physique de l'appareil via les capteurs de mouvement.

Note : l'interface respectera toujours le réglage de verrouillage d'orientation de l'utilisateur. Le suivi des mouvements vous permet de détecter comment l'appareil est tenu physiquement même si l'interface ne pivote 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éverrouiller l'orientation de l'écran.

Permet à l'écran de pivoter librement selon la position de l'appareil. Arrête également tout suivi d'orientation basé sur les mouvements s'il était activé.

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

await ScreenOrientation.unlock();

startOrientationTracking

Commencez à suivre l'orientation de l'appareil via les capteurs de mouvement.

Cette méthode est utile pour suivre l'orientation physique de l'appareil 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 le suivi de l'orientation de l'appareil via les capteurs de mouvement.

Arrête le suivi de l'orientation basé sur le mouvement s'il était actif.

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

await ScreenOrientation.stopOrientationTracking();

isOrientationLocked

Vérifiez si le verrouillage de l'orientation de l'appareil est activé.

Cette méthode compare l'orientation physique de l'appareil (via les capteurs) avec l'orientation de l'interface utilisateur. Si elles diffèrent, le verrouillage est activé.

Note : Cela nécessite que le suivi de mouvement soit actif via startOrientationTracking() ou lock() avec bypassOrientationLock: true. Fonctionne sur 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 renvoyé 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 le suivi de l'orientation via les 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 renvoyé 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 décrivant l'état d'orientation de l'appareil.

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

OrientationLockType

Type de verrouillage d'orientation pouvant être utilisé pour verrouiller l'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 de src/definitions.ts. Relancez la synchronisation lorsque l’API public change en amont.

Continuer depuis Getting Started

Si vous utilisez Prise en main pour planifier le comportement des médias et de l'interface natifs, connectez-l’à Utiliser @capgo/capacitor-screen-orientation pour la fonctionnalité native dans « Utiliser @capgo/capacitor-screen-orientation », Utiliser @capgo/capacitor-live-activities pour la capacité native dans Utiliser @capgo/capacitor-live-activities @capgo/capacitor-live-activities pour le détail d'implémentation dans @capgo/capacitor-live-activities Utiliser @capgo/capacitor-video-player pour la capacité native dans Utiliser @capgo/capacitor-video-player, et @capgo/capacitor-video-player pour le détail d'implémentation dans @capgo/capacitor-video-player.