Erste Schritte mit Screen Orientation

1. Paket installieren

   npm

   npm i @capgo/capacitor-screen-orientation

   pnpm

   pnpm add @capgo/capacitor-screen-orientation

   yarn

   yarn add @capgo/capacitor-screen-orientation

   bun

   bun add @capgo/capacitor-screen-orientation

2. Mit nativen Projekten synchronisieren

   npm

   npx cap sync

   pnpm

   pnpm cap sync

   yarn

   yarn cap sync

   bun

   bunx cap sync

3. iOS-Konfiguration (optional) Um physikalische Geräteorientierung mit Bewegungssensoren auf iOS zu erkennen, fügen Sie zu Ihrer Info.plist hinzu:

   <key>NSMotionUsageDescription</key>
   <string>Diese App verwendet Bewegungssensoren zur Erkennung der Geräteorientierung.</string>

Grundlegende Verwendung

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

// Aktuelle Orientierung abrufen
const current = await ScreenOrientation.orientation();
console.log('Aktuelle Orientierung:', current.type);

// Im Landscape-Modus sperren
await ScreenOrientation.lock({ orientation: 'landscape' });

// Orientierung entsperren
await ScreenOrientation.unlock();

// Auf Orientierungsänderungen abhören
const listener = await ScreenOrientation.addListener(
  'screenOrientationChange',
  (result) => {
    console.log('Orientierung geändert:', result.type);
  }
);

Erkennung der physikalischen Orientierung

Dieses Plugin hat eine einzigartige Funktion: Es kann die wahre physikalische Orientierung des Geräts unter Verwendung von Bewegungssensoren erkennen, auch wenn der Benutzer die Orientierungssperre auf seinem Gerät aktiviert hat.

Hinweis

Die Benutzeroberfläche respektiert weiterhin die Orientierungssperreinstellung des Benutzers. Motion-Tracking ermöglicht es Ihnen, zu wissen, wie das Gerät physikalisch gehalten wird, aber die Benutzeroberfläche dreht sich nicht, wenn die Orientierungssperre aktiviert ist.

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

// Motion-basiertes Tracking starten
await ScreenOrientation.startOrientationTracking({
  bypassOrientationLock: true
});

// Jetzt zeigen Orientierungsänderungsereignisse die physikalische Orientierung
const listener = await ScreenOrientation.addListener(
  'screenOrientationChange',
  (result) => {
    console.log('Physikalische Orientierung:', result.type);
  }
);

// Überprüfen Sie, ob Orientierungssperre aktiviert ist
const lockStatus = await ScreenOrientation.isOrientationLocked();
if (lockStatus.locked) {
  console.log('Benutzer hat Orientierungssperre aktiviert');
  console.log('Physisch:', lockStatus.physicalOrientation);
  console.log('UI:', lockStatus.uiOrientation);
}

// Tracking beenden, wenn fertig
await ScreenOrientation.stopOrientationTracking();

API-Referenz

orientation()

Rufen Sie die aktuelle Bildschirmausrichtung ab.

const result = await ScreenOrientation.orientation();
// Rückgabe: { type: OrientationType }

OrientationType-Werte:

• 'portrait-primary' - Hochformat, Startknopf unten
• 'portrait-secondary' - Hochformat, umgekehrt
• 'landscape-primary' - Querformat, Startknopf rechts
• 'landscape-secondary' - Querformat, Startknopf links

lock(options)

Sperren Sie den Bildschirm auf eine bestimmte Ausrichtung.

interface OrientationLockOptions {
  orientation: OrientationLockType;
  bypassOrientationLock?: boolean; // Motion Tracking aktivieren
}

await ScreenOrientation.lock({ orientation: 'landscape' });

OrientationLockType-Werte:

• 'any' - Beliebige Orientierung
• 'natural' - Natürliche Ausrichtung des Geräts
• 'landscape' - Beliebiger Landscape-Modus
• 'portrait' - Beliebiger Portrait-Modus
• 'portrait-primary' / 'portrait-secondary'
• 'landscape-primary' / 'landscape-secondary'

unlock()

Entsperren Sie die Bildschirmausrichtung.

await ScreenOrientation.unlock();

startOrientationTracking(options?)

Beginnen Sie mit der Verfolgung der physikalischen Geräteausrichtung mit Bewegungssensoren.

await ScreenOrientation.startOrientationTracking({
  bypassOrientationLock: true
});

stopOrientationTracking()

Stoppen Sie die Motion-basierte Orientierungsverfolgung.

await ScreenOrientation.stopOrientationTracking();

isOrientationLocked()

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

const result = await ScreenOrientation.isOrientationLocked();
// Rückgabe: {
//   locked: boolean,
//   physicalOrientation?: OrientationType,
//   uiOrientation?: OrientationType
// }

Tipp

Diese Methode erfordert, dass Motion Tracking aktiv ist, um ordnungsgemäß zu funktionieren.

addListener(eventName, callback)

Abhören auf Orientierungsänderungen.

const listener = await ScreenOrientation.addListener(
  'screenOrientationChange',
  (result) => {
    console.log('Neue Orientierung:', result.type);
  }
);

// Entfernen Sie, wenn fertig
await listener.remove();

removeAllListeners()

Entfernen Sie alle Event-Listener.

await ScreenOrientation.removeAllListeners();

Vollständiges Beispiel

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

class OrientationManager {
  private listener: any = null;

  async init() {
    // Motion Tracking für Erkennung der physikalischen Ausrichtung starten
    await ScreenOrientation.startOrientationTracking({
      bypassOrientationLock: true
    });

    // Auf Änderungen abhören
    this.listener = await ScreenOrientation.addListener(
      'screenOrientationChange',
      this.onOrientationChange.bind(this)
    );

    // Anfängliche Orientierung abrufen
    const { type } = await ScreenOrientation.orientation();
    console.log('Anfängliche Orientierung:', type);
  }

  onOrientationChange(result: { type: string }) {
    console.log('Orientierung geändert zu:', result.type);

    // Benutzeroberfläche basierend auf Orientierung anpassen
    if (result.type.includes('landscape')) {
      this.showLandscapeUI();
    } else {
      this.showPortraitUI();
    }
  }

  showLandscapeUI() {
    // Landscape-spezifische UI-Anpassungen
  }

  showPortraitUI() {
    // Portrait-spezifische UI-Anpassungen
  }

  async lockLandscape() {
    await ScreenOrientation.lock({ orientation: 'landscape' });
  }

  async lockPortrait() {
    await ScreenOrientation.lock({ orientation: 'portrait' });
  }

  async freeRotation() {
    await ScreenOrientation.unlock();
  }

  async checkIfUserHasOrientationLock() {
    const { locked, physicalOrientation, uiOrientation } =
      await ScreenOrientation.isOrientationLocked();

    if (locked) {
      console.log(`Gerät wird in ${physicalOrientation} gehalten, aber UI zeigt ${uiOrientation}`);
      return true;
    }
    return false;
  }

  async destroy() {
    await ScreenOrientation.stopOrientationTracking();
    if (this.listener) {
      await this.listener.remove();
    }
  }
}

Plattformnotizen

iOS

• Verwendet Core Motion Framework für Erkennung der physikalischen Ausrichtung
• Erfordert NSMotionUsageDescription in Info.plist für Bewegungssensoren
• Vollständige Unterstützung für alle Ausrichtungstypen

Android

• Verwendet Beschleunigungssensor für Erkennung der physikalischen Ausrichtung
• Keine zusätzlichen Berechtigungen erforderlich
• Vollständige Unterstützung für alle Ausrichtungstypen

Web

• Verwendet Screen Orientation API
• Bewegungssensor-Erkennung ist begrenzt
• Einige Browser unterstützen möglicherweise nicht alle Lock-Typen