Getting Started

Installieren

Sie können unser AI-gestütztes Setup verwenden, um das Plugin zu installieren. Fügen Sie die Capgo-Fähigkeiten zu Ihrem AI-Tool hinzu, indem Sie die folgende Befehl ausführen:

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

Dann verwenden Sie die folgende Anweisung:

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

Wenn Sie die manuelle Einrichtung bevorzugen, installieren Sie das Plugin, indem Sie die folgenden Befehle ausführen und die darunterstehenden plattform-spezifischen Anweisungen befolgen:

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 der Geräteschirmseite zurück.

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

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

lock

Sperre die Bildschirmorientierung auf eine bestimmte Art.

Sperrt die Bildschirmorientierung auf die angegebene Orientierung. Bei iOS wird, wenn bypassOrientationLock wahr ist, auch 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, ebenbei, 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

Freigibt die Bildschirmorientierung.

Ermöglicht es dem Bildschirm, frei zu rotieren, basierend auf der Geräteposition. Stopp auch jede Bewegungsorientierungserkennung, wenn sie aktiviert war.

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

await ScreenOrientation.unlock();

startOrientationTracking

Geräteneinstellung mit Hilfe von Bewegungssensoren verfolgen.

Dieser Methoden ist nützlich, wenn Sie die physische Geräteeinstellung 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

Geräteneinstellung mit Hilfe von Bewegungssensoren verfolgen.

Die Bewegungsbasierte Orientierung verfolgung stoppt, wenn sie gestartet wurde.

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

await ScreenOrientation.stopOrientationTracking();

isOrientationLocked

Überprüfen, ob die Geräteeinstellung gesperrt ist.

Dieser Methoden vergleicht die physische Geräteeinstellung (aus Bewegungssensoren) mit der UI-Orientierung. Wenn sie sich unterscheiden, ist die Einstellung gesperrt.

Hinweis: Dies erfordert die Aktivierung der Bewegungserfassung 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);
}

Typenverweis

ScreenOrientationResult

Ergibt durch die 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 des Orientierungstrackings 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

Der Orientierungstyp, der den Orientierungszustand des Geräts beschreibt.

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

OrientationLockType

Der Orientierungsverschlussart, der zum Blockieren 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 wird aus dem Plugin generiert. src/definitions.ts. Wenn sich die öffentliche API im Quellcode ändert, führen Sie die Synchronisierung erneut durch.

Weitermachen von Getting Started

Wenn Sie Getting Started verwenden Getting Started um native Medien und Schnittstellenverhalten zu planen, verbinden Sie es mit Using @capgo/capacitor-screen-orientation für die native Fähigkeit in Using @capgo/capacitor-screen-orientation Using @capgo/capacitor-live-activities für die native Fähigkeit in Using @capgo/capacitor-live-activities @capgo/capacitor-live-activities für die Implementierungsdetail in @capgo/capacitor-live-activities Using @capgo/capacitor-video-player für die native Fähigkeit in @capgo/capacitor-video-player und @capgo/capacitor-video-player für die Implementierungsdetail in @capgo/capacitor-video-player.