Einstieg

Installieren

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

Importieren

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

API Übersicht

orientation

Ermitteln Sie die aktuelle Bildschirmorientierung.

Gibt die aktuelle Orientierung des Gerätschirms zurück.

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

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

lock

Sperrt die Bildschirmorientierung auf eine bestimmte Art.

Blockiert die Bildschirmorientierung auf die angegebene Ausrichtung. Bei iOS wird, wenn bypassOrientationLock wahr ist, auch die physische Geräteorientierung mit Hilfe der Bewegungssensoren verfolgt.

Hinweis: Die Benutzeroberfläche respektiert den von Benutzern gesetzten Ausrichtungsschutz weiterhin. Die Bewegungsverfolgung ermöglicht es Ihnen, wie das Gerät physisch gehalten wird even wenn die Benutzeroberfläche nicht dreht.

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

Das Bildschirmorientieren freischalten.

Ermöglicht, dass sich das Bildschirmorientieren frei nach Geräteposition bewegt. Stoppt auch jede Bewegungsorientierungsbasierte Orientierungstracking, wenn es aktiviert war.

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

await ScreenOrientation.unlock();

startOrientationTracking

Bewegungsorientierung des Geräts mithilfe von Sensoren verfolgen.

Diese Methode ist nützlich, wenn Sie das physische Geräteorientieren independent von dem Bildschirmorientierungsschutz verfolgen möchten. Sie verwendet Core Motion auf iOS, um Orientierungswerte zu erkennen.

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

Bewegungsorientierung des Geräts mithilfe von Sensoren stoppen.

Beendet die Bewegungsorientierungstracking, wenn es gestartet wurde.

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

await ScreenOrientation.stopOrientationTracking();

isOrientationLocked

Überprüft, ob die Geräteeinstellung für die Orientierungssperre derzeit aktiviert ist.

Diese Methode vergleicht die physische Geräteeinstellung (aus Bewegungssensoren) mit der Benutzeroberflächeneinstellung. Wenn sie sich unterscheiden, ist die Orientierungssperre aktiviert.

Hinweis: Dazu ist die Bewegungsverfolgung aktiviert werden müssen via startOrientationTracking() oder lock() mit bypassOrientationLock: true. Funktioniert auf 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 durch die Methode orientation() zurück.

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

OrientationLockOptions

Einstellungen für die 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

Einstellungen für das 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

Orientierungstyp, der die Orientierungszustand des Geräts beschreibt.

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

OrientationLockType

Der Orientierungssperre-Typ, der zum Sperren der Geräteorientierung verwendet werden kann.

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

Quelle der Wahrheit

Diese Seite wurde aus dem Plugin generiert. src/definitions.tsRe-run die Synchronisierung, wenn die öffentliche API upstream geändert wird.