Getting Started

Instalar

Puede utilizar nuestra configuración asistida por IA para instalar el plugin. Agregue las Capgo habilidades a su herramienta de IA 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 plugin ejecutando los siguientes comandos y siga 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';

Resumen de API

orientation

Obtén 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 detección 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. La detección 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

Iniciar 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 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

Comprobar 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 tanto en iOS (Core Motion) como en 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

Copiar a portapapeles

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

OrientationLockOptions

Copiar a portapapeles

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 el público API cambie en la fuente.

Sigue adelante desde Inicio

Si estás utilizando Inicio para planificar el comportamiento de medios y interfaces 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-videos para la capacidad nativa en Usando @capgo/capacitor-reproductor-de-videos, y @capgo/capacitor-reproductor-de-videos para los detalles de implementación en @capgo/capacitor-reproductor-de-videos.