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 folgenden Befehl ausführen:

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

Kopieren Sie dann die folgende Anleitung:

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 untenstehenden Plattform-spezifischen Anweisungen befolgen:

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

Importieren

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

API Übersicht

orientation

Erhalte die aktuelle Bildschirmorientierung.

Rückgabewert: Die aktuelle Orientierung des Gerätebildschirms.

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

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

lock

Blockiere die Bildschirmorientierung auf eine bestimmte Art.

Blockiert den Bildschirm auf der angegebenen Orientierung. Bei iOS wird die Orientierung auch mit Hilfe der Bewegungssensoren nachverfolgt, wenn bypassOrientationLock wahr ist.

Hinweis: Die Benutzeroberfläche respektiert den Orientierungssperreinstellung des Benutzers weiterhin. Die Bewegungsnachverfolgung 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

Freigeb die Bildschirmorientierung.

Erstellt es ermöglicht, dass der Bildschirm frei rotiert, basierend auf der Geräteposition. Es stoppt auch jede Bewegungsorientierungsnachverfolgung, wenn sie aktiviert war.

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

await ScreenOrientation.unlock();

startOrientationTracking

Geräteorientierung mithilfe von Bewegungssensoren verfolgen.

This method is useful when you want to track the device’s physical orientation independently from the screen orientation lock. It uses Core Motion on iOS to detect orientation changes.

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

Abschnitt mit dem Titel „stopOrientationTracking“

Beendet die Bewegungsorientierte Orientierungserkennung, wenn sie gestartet wurde.

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

await ScreenOrientation.stopOrientationTracking();

isOrientationLocked

Abschnitt mit dem Titel „isOrientationLocked“

Diese Methode vergleicht die physische Geräteorientierung (aus Bewegungssensoren) mit der Benutzeroberflächenoientierung. Wenn sie sich unterscheiden, wird die Orientierungssperre aktiviert.

Hinweis: Dies erfordert die Aktivierung der Bewegungsverfolgung über 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

Ergebnis, das durch die Methode orientation() zurückgegeben wird.

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

OrientationLockOptions

Optionen zum Blockieren 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 Orientierungsverfolgung 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

Ergbnis 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 Orientierungszustand des Geräts beschreibt

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

OrientationLockType

Orientierungssperre, die 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 aus dem Plugin generiert. src/definitions.tsRe-run die Synchronisierung, wenn die öffentliche API upstream geändert wird.

Weitergehen von Getting Started

Wenn Sie Capgo verwenden Getting Started um native Medien und Schnittstellenverhalten zu planen, verbinden Sie es mit Verwendung von @capgo/capacitor-Bildschirmorientierung für die native Fähigkeit in Using @capgo/capacitor-screen-orientation, Verwendung von @capgo/capacitor-live-aktivitäten für die native Fähigkeit in Using @capgo/capacitor-live-activities, Using @capgo/capacitor-live-activities Für die Implementierungsdetails in @capgo/capacitor-live-aktivitäten, Mit @capgo/capacitor-video-player Für die native Fähigkeit in Mit @capgo/capacitor-video-player und @capgo/capacitor-Video-Player Für die Implementierungsdetails in @capgo/capacitor-video-player.