Empezar

Instalar

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

Importar

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

API Resumen

orientation

Obtenga la orientación actual de la pantalla.

Devuelve la orientación actual de la pantalla del dispositivo.

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

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

lock

Bloquea la orientación de la pantalla a un tipo específico.

Bloquea la pantalla a la orientación especificada. En iOS, si bypassOrientationLock es verdadero, también iniciará la seguimiento de la orientación física del dispositivo utilizando sensores de movimiento.

Nota: La interfaz de usuario aún respetará la configuración de bloqueo de orientación del usuario. El seguimiento de movimiento permite detectar cómo se sostiene el dispositivo físicamente e incluso cuando la interfaz de usuario no gira.

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

Desbloquea la orientación de la pantalla.

Permite que la pantalla gire libremente según la posición del dispositivo. También detiene cualquier seguimiento de orientación basado en movimiento si estaba habilitado.

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

await ScreenOrientation.unlock();

startOrientationTracking

Inicia el seguimiento de la orientación del dispositivo utilizando sensores de movimiento.

Este método es útil cuando deseas rastrear la orientación física del dispositivo de manera independiente del bloqueo de orientación de la pantalla.

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

Sección titulada “stopOrientationTracking”

Detener el seguimiento de la orientación del dispositivo utilizando sensores de movimiento.

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

await ScreenOrientation.stopOrientationTracking();

isOrientationLocked

Sección titulada “isOrientationLocked”

Verificar si el bloqueo de orientación del dispositivo está actualmente habilitado.

Este método compara la orientación física del dispositivo (de sensores de movimiento) con la orientación de la interfaz de usuario. Si difieren, el bloqueo de orientación está habilitado. Nota: Esto requiere que el seguimiento de movimiento esté activo a través de startOrientationTracking() o lock() con bypassOrientationLock: true. Funciona en ambos iOS (Core Motion) y Android (Acelerómetro).

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

Referencia de tipos

ScreenOrientationResult

Resultado devuelto por el método orientation().

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

OrientationLockOptions

Opciones para bloquear la orientación de pantalla.

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

Opciones para iniciar el seguimiento de orientación usando sensores de movimiento.

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

Resultado devuelto por el método 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

Tipo de orientación que describe el estado de orientación del dispositivo.

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

OrientationLockType

Tipo de bloqueo de orientación que se puede utilizar para bloquear la orientación del dispositivo.

export type OrientationLockType =
  | 'any'
  | 'natural'
  | 'landscape'
  | 'portrait'
  | 'portrait-primary'
  | 'portrait-secondary'
  | 'landscape-primary'
  | 'landscape-secondary';

Fuente de Verdad

Esta página se genera a partir de la página del plugin. src/definitions.ts. Re-ejecutar la sincronización cuando el público API cambia en la fuente.