Erste Schritte

Installieren

Du kannst unser KI-gestütztes Setup nutzen, um das Plugin zu installieren. Füge die Capgo Skills mit dem folgenden Befehl deinem KI-Tool hinzu:

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

Nutze dann diesen Prompt:

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

Wenn du ein manuelles Setup bevorzugst, installiere das Plugin mit den folgenden Befehlen und befolge die plattformspezifischen Anweisungen unten:

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

Importieren

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

Quickstart

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

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

Beispiel: lock

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

Beispiel: unlock

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

await ScreenOrientation.unlock();

Häufige Stolperfallen

• Listener: Handles beim Unmounten von Screens entfernen.
• Nativer Sync: ausführen bunx cap sync nach Plugin-Upgrades.
• Single Source of Truth: Vertrauen src/definitions.ts im GitHub Repo.

API Übersicht

orientation

Die aktuelle Bildschirmausrichtung abrufen.

Gibt die aktuelle Ausrichtung des Bildschirms zurück.

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

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

lock

Die Bildschirmausrichtung auf einen bestimmten Typ fixieren.

Sperrt den Bildschirm auf die angegebene Ausrichtung. Auf iOS startet bei bypassOrientationLock = true zusätzlich das Tracking der physischen Geräteausrichtung über Bewegungssensoren.

Hinweis: Die UI respektiert weiterhin die Ausrichtungssperre des Nutzers. Motion Tracking erlaubt es zu erkennen, wie das Gerät physisch gehalten wird, auch wenn sich die UI 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

Die Bildschirmausrichtung entsperren.

Ermöglicht dem Bildschirm, sich frei nach der Geräteposition zu drehen. Stoppt außerdem bewegungsbasiertes Motion Tracking, falls es aktiviert war.

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

await ScreenOrientation.unlock();

startOrientationTracking

Tracking der Geräteausrichtung mit Bewegungssensoren starten.

Diese Methode ist nützlich, um die physische Ausrichtung des Geräts unabhängig von der Bildschirm-Orientierungssperre zu tracken. Auf iOS wird Core Motion verwendet, um Orientierungsänderungen 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

Tracking der Geräteausrichtung mit Bewegungssensoren stoppen.

Stoppt das bewegungsbasierte Orientation Tracking, falls es gestartet wurde.

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

await ScreenOrientation.stopOrientationTracking();

isOrientationLocked

Prüfen, ob die Ausrichtungssperre aktuell aktiviert ist.

Diese Methode vergleicht die physische Geräteausrichtung (via Bewegungssensoren) mit der UI-Ausrichtung. Wenn diese abweichen, ist die Orientierungssperre aktiviert.

Hinweis: Dies erfordert, dass das Motion Tracking über\nstartOrientationTracking() oder lock() mit bypassOrientationLock: true aktiviert ist.\nFunktioniert sowohl auf iOS (Core Motion) als auch auf 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);
}

Typreferenz

ScreenOrientationResult

Das von der orientation() Methode zurückgegebene Ergebnis.

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

OrientationLockOptions

Optionen zum Sperren 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 des Orientation-Trackings via 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

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 den Zustand des Geräts beschreibt.

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

OrientationLockType

Art der Orientierungssperre, mit der die Geräteausrichtung fixiert werden kann.

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

Source of Truth

Diese Seite wird aus dem Plugin generiert src/definitions.ts. Führe den Sync erneut aus, wenn sich das öffentliche API upstream ändert.

Weiter geht's nach Getting Started

Wenn du es nutzt Erste Schritte , um natives Media- und Interface-Verhalten zu planen, verbinde es mit @capgo/capacitor-screen-orientation verwenden für die native Funktion bei der Nutzung von @capgo/capacitor-screen-orientation, @capgo/capacitor-live-activities verwenden für die native Funktion in „@capgo/capacitor-live-activities verwenden“, @capgo/capacitor-live-activities für die Implementierungsdetails in @capgo/capacitor-live-activities, Verwendung von @capgo/capacitor-video-player für die native Funktion in „@capgo/capacitor-video-player verwenden“, und @capgo/capacitor-video-player für das Implementierungsdetail in @capgo/capacitor-video-player.