Einstieg

Installieren

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

Importieren

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

API Übersicht

orientation

Ermittelt die aktuelle Orientierung des Bildschirms des Geräts.

Gibt die aktuelle Orientierung des Bildschirms des Geräts zurück.

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

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

lock

Die Bildschirmorientierung auf eine bestimmte Art sperren.

Sperren Sie die Bildschirmorientierung auf die angegebene Art. Bei iOS wird die Sperre auch dann aktiviert, wenn bypassOrientationLock auf true gesetzt ist, und es wird die physische Geräteorientierung mithilfe von Bewegungssensoren verfolgt.

Hinweis: Die Benutzeroberfläche respektiert den Sperreinstellung des Benutzers weiterhin. Die Bewegungserkennung ermöglicht es Ihnen, zu erkennen, wie das Gerät physisch gehalten wird, auch wenn die Benutzeroberfläche nicht rotiert.

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

Die Bildschirmorientierung entsperren.

Die Bildschirmorientierung wird frei basierend auf der Geräteposition gedreht. Es wird auch jede Bewegungsbasierte Orientierungserkennung, wenn sie aktiviert war, beendet.

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

await ScreenOrientation.unlock();

startOrientationTracking

Die Geräteorientierung mithilfe von Bewegungssensoren verfolgen.

Dieser Methoden ist nützlich, wenn Sie die Geräteorientierung unabhängig von der Bildschirmorientierung sperren möchten.

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

Verwenden Sie die Bewegungssensoren, um die Geräteorientierung zu stoppen.

Beendet die Bewegungsbasierte Orientierungserkennung, wenn sie gestartet wurde.

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

await ScreenOrientation.stopOrientationTracking();

isOrientationLocked

Überprüfen Sie, ob die Geräteorientierungssperre derzeit aktiviert ist.

Diese Methode vergleicht die physische Geräteorientierung (aus Bewegungssensoren) mit der UI-Orientierung. Wenn sie sich unterscheiden, ist die Orientierungssperre aktiviert.

Hinweis: Dies erfordert die Aktivierung der Bewegungserkennung via startOrientationTracking() oder lock() mit bypassOrientationLock: true. Funktioniert auf beiden iOS (Core Motion) und Android (Accelerometer).

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

Typenreferenz

ScreenOrientationResult

Ergibt das Ergebnis der Methode orientation().

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

OrientationLockOptions

Optionen zur Sperre der Bildschirmorientierung.

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

Optionen zum Starten der Orientierungstracking mit Bewegungssensoren.

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

Ergibt das Ergebnis der Methode 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

Geräteorientierungstyp, der den Orientierungsstatus des Geräts beschreibt.

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

OrientationLockType

Geräteorientierungstyp, der verwendet werden kann, um die Geräteorientierung zu sperren.

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

Quelle der Wahrheit

Diese Seite wird von dem Plugin generiert. src/definitions.tsRe-run the sync, wenn die öffentliche API upstream geändert wird.

Weitermachen von Getting Started

Wenn Sie " Getting Started um native Medien und Schnittstellen zu planen, verbinden Sie es mit Verwenden Sie @capgo/capacitor-Bildschirmorientierung für die native Fähigkeit in Verwenden Sie @capgo/capacitor-Bildschirmorientierung, Verwenden Sie @capgo/capacitor-Live-Aktivitäten für die native Fähigkeit in Verwenden Sie @capgo/capacitor-Live-Aktivitäten, @capgo/capacitor-Live-Aktivitäten für die Implementierungsdetails in @capgo/capacitor-Live-Aktivitäten, Verwenden Sie @capgo/capacitor-Video-Player für die native Fähigkeit in Verwenden Sie @capgo/capacitor-Video-Player, und @capgo/capacitor-Video-Player für die Implementierungsdetails in @capgo/capacitor-Video-Player.