Démarrage

Installer

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

Importer

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

API Aperçu

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

Fixe l'orientation de l'écran à un type spécifique.

Fixe l'écran à 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 cache d'orientation du utilisateur.

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

Sous-titre « déverrouiller »

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

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

await ScreenOrientation.unlock();

startOrientationTracking

Sous-titre « démarrer le suivi de l'orientation »

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

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 la suivi de l'orientation du dispositif à l'aide des capteurs de mouvement.

Arrête le suivi de l'orientation basé sur le mouvement si cela 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 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 le suivi 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-run la synchronisation lorsque les public API changent en amont.

Continuez de la section « Getting Started »

Si vous utilisez Prise en main pour planifier le comportement de médias et d'interface natifs, et le connecter à En utilisant @capgo/capacitor-orientation-écran pour la capacité native dans En utilisant @capgo/capacitor-orientation-écran, En utilisant @capgo/capacitor-activités-en-vivre pour la capacité native dans En utilisant @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, En utilisant @capgo/capacitor-joueur-de-videos pour la capacité native dans En utilisant @capgo/capacitor-joueur-de-videos, et @capgo/capacitor-joueur-de-videos pour le détail d'implémentation dans @capgo/capacitor-joueur-de-videos.