Démarrage

Installer

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

Importer

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

API Aperçu

orientation

Obtenez 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

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 verrouillage d'orientation du utilisateur. Le suivi de mouvement permet de détecter comment l'appareil 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éverrouillez l'orientation de l'écran.

Permet à l'écran de tourner librement en fonction de la position de l'appareil. 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êtez la traçabilité de l'orientation basée sur le mouvement si elle a été démarrée.

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.

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

Section intitulée “Source de Vérité”

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

Continuez de l'étape de démarrage

Si vous utilisez Démarrage pour planifier le comportement de médias et d'interface natifs, connectez-le avec 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 les détails d'implémentation dans @capgo/capacitor-activités en direct, En utilisant @capgo/capacitor-lecteur de vidéos pour la capacité native dans En utilisant @capgo/capacitor-lecteur de vidéos, et @capgo/capacitor-lecteur de vidéos pour les détails d'implémentation dans @capgo/capacitor-lecteur de vidéos.