Getting Started

Install

Vous pouvez utiliser notre configuration assistée par l'IA pour installer le plugin. Ajoutez les Capgo compétences à votre outil IA en utilisant 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

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

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

Fixe l'orientation de l'écran sur la position spécifiée. Sur iOS, si bypassOrientationLock est vrai, il suivra également l'orientation physique du dispositif à l'aide de capteurs de mouvement.

Note: The UI will still respect the user’s orientation lock setting. Motion tracking allows you to detect how the device is physically held even when the UI doesn’t rotate.

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 la rotation de l'écran 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

Suivez 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 celui-ci a été démarré.

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

await ScreenOrientation.stopOrientationTracking();

isOrientationLocked

Check if device orientation lock is currently enabled.

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éférence de type : Options de verrouillage de l'orientation

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

OrientationLockOptions

Paramètres pour bloquer 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

Paramètres pour démarrer la 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.ts. Re-run the sync when the public API changes upstream.

Continuez de Getting Started

Si vous utilisez Getting Started pour planifier le comportement natif des médias et de l'interface, connectez-l’avec planer des médias et du comportement d'interface natifs, connectez-l’avec Utilisation de @capgo/capacitor-orientation d'écran pour la capacité native dans l'utilisation de @capgo/capacitor-orientation-écran. Utilisation de @capgo/capacitor-activités en direct pour la capacité native dans l'utilisation de @capgo/capacitor-activités en direct. @capgo/capacitor-activités-en-vivre pour les détails d'implémentation dans @capgo/capacitor-activités en direct En utilisant @capgo/capacitor-joueur de vidéo pour la capacité native dans En utilisant @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.