Inicio

Instalar

Puede utilizar nuestra configuración asistida por inteligencia artificial para instalar el complemento. Agregue las Capgo habilidades a su herramienta de inteligencia artificial utilizando el siguiente comando:

npx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

Luego utilice la siguiente solicitud:

Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/capacitor-screen-orientation` plugin in my project.

Si prefiere la configuración manual, instale el complemento ejecutando los siguientes comandos y siguiendo las instrucciones específicas de la plataforma a continuación:

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

Bloquear 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 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.

Esta función es útil cuando deseas rastrear 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 la 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.

Este método 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, se habilita el bloqueo de orientación.

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 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.tsRe-ejecutar la sincronización cuando los cambios públicos API cambian en la fuente

Sigue adelante desde Getting Started

Si estás utilizando Getting Started para planificar el comportamiento de medios y interfaz nativos, conecta 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 los detalles de implementación en @capgo/capacitor-actividades en vivo Usando @capgo/capacitor-reproductor de video para la capacidad nativa en Usando @capgo/capacitor-reproductor de video, y @capgo/capacitor-reproductor de video para los detalles de implementación en @capgo/capacitor-reproductor de video.