Inicio rápido

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 comenzará a rastrear 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 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

Desbloquear la orientación de 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

Comienza a seguir la orientación del dispositivo utilizando sensores de movimiento.

Este método es útil cuando deseas seguir la orientación física del dispositivo de manera independiente del bloqueo de orientación de pantalla. Utiliza Core Motion en iOS para detectar cambios de orientación.

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

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

Detiene el seguimiento de orientación basado en movimiento si estaba iniciado.

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

await ScreenOrientation.stopOrientationTracking();

isOrientationLocked

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

Esta función compara la orientación física del dispositivo (a partir 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 tanto en iOS (Core Motion) como en Android (Acceleró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 la 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 la orientación utilizando 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 del plugin’s src/definitions.ts. Vuelva a ejecutar la sincronización cuando los cambios públicos API cambien en la fuente.

Siga adelante desde Getting Started

Si está utilizando Getting Started para planificar el comportamiento de medios y interfaces nativos, conecte con Usando @capgo/capacitor-orientación de pantalla para la capacidad nativa en Usando @capgo/capacitor-orientación de pantalla, Usando @capgo/capacitor-actividades en vivo para la capacidad nativa en Usando @capgo/capacitor-actividades-en-vivo, @capgo/capacitor-actividades-en-vivo para el detalle de implementación en @capgo/capacitor-actividades-en-vivo, Usando @capgo/capacitor-reproductor-de-videos para la capacidad nativa en Usando @capgo/capacitor-reproductor-de-videos, y @capgo/capacitor-reproductor-de-videos para el detalle de implementación en @capgo/capacitor-reproductor-de-videos.