Iniziare

1. Installa il pacchetto

   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. Sincronizzazione con progetti nativi

   npm

   npx cap sync

   pnpm

   pnpm cap sync

   yarn

   yarn cap sync

   bun

   bunx cap sync

3. iOS Configurazione (opzionale) Per rilevare l’orientamento del dispositivo fisico utilizzando i sensori di movimento su iOS, aggiungi al tuo Info.plist:

   <key>NSMotionUsageDescription</key>
   <string>This app uses motion sensors to detect device orientation.</string>

Utilizzo di base

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

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

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

// Unlock orientation
await ScreenOrientation.unlock();

// Listen for orientation changes
const listener = await ScreenOrientation.addListener(
  'screenOrientationChange',
  (result) => {
    console.log('Orientation changed:', result.type);
  }
);

Rilevamento dell’orientamento fisico

Questo plugin ha una caratteristica unica: può rilevare il vero orientamento fisico del dispositivo utilizzando sensori di movimento, anche quando l’utente ha abilitato il blocco dell’orientamento sul proprio dispositivo.

Nota

L’interfaccia utente rispetterà comunque l’impostazione di blocco dell’orientamento dell’utente. Il rilevamento del movimento ti consente di sapere come viene tenuto fisicamente il dispositivo, ma l’interfaccia utente non ruoterà se il blocco dell’orientamento è abilitato.

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

// Start motion-based tracking
await ScreenOrientation.startOrientationTracking({
  bypassOrientationLock: true
});

// Now orientation change events will reflect physical orientation
const listener = await ScreenOrientation.addListener(
  'screenOrientationChange',
  (result) => {
    console.log('Physical orientation:', result.type);
  }
);

// Check if orientation lock is enabled
const lockStatus = await ScreenOrientation.isOrientationLocked();
if (lockStatus.locked) {
  console.log('User has orientation lock enabled');
  console.log('Physical:', lockStatus.physicalOrientation);
  console.log('UI:', lockStatus.uiOrientation);
}

// Stop tracking when done
await ScreenOrientation.stopOrientationTracking();

API Riferimento

orientamento()

Ottieni l’orientamento corrente dello schermo.

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

Valori OrientationType:

• 'ritratto-primario' - Ritratto, pulsante home in basso
• 'ritratto-secondario' - Ritratto, capovolto
• 'landscape-primary' - Paesaggio, pulsante home a destra
• 'landscape-secondary' - Paesaggio, pulsante home a sinistra

serratura(opzioni)

Blocca lo schermo su un orientamento specifico.

interface OrientationLockOptions {
  orientation: OrientationLockType;
  bypassOrientationLock?: boolean; // Enable motion tracking
}

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

Valori OrientationLockType:

• 'any' - Qualsiasi orientamento
• 'natural' - Orientamento naturale del dispositivo
• 'landscape' - Qualsiasi modalità orizzontale
• 'ritratto' - Qualsiasi modalità ritratto
• “ritratto-primario” / “ritratto-secondario”.
• 'paesaggio-primario' / 'paesaggio-secondario'

sblocca()

Sblocca l’orientamento dello schermo.

await ScreenOrientation.unlock();

startOrientationTracking(opzioni?)

Inizia a monitorare l’orientamento del dispositivo fisico utilizzando i sensori di movimento.

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

stopOrientamentoTracciamento()

Arresta il tracciamento dell’orientamento basato sul movimento.

await ScreenOrientation.stopOrientationTracking();

isOrientationLocked()

Controlla se il blocco dell’orientamento del dispositivo è abilitato.

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

Suggerimento

Questo metodo richiede che il rilevamento del movimento sia attivo per funzionare correttamente.

addListener(nomeevento, callback)

Ascolta i cambiamenti di orientamento.

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

// Remove when done
await listener.remove();

rimuoviTuttiGliAscoltatori()

Rimuovi tutti i listener di eventi.

await ScreenOrientation.removeAllListeners();

Esempio completo

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

class OrientationManager {
  private listener: any = null;

  async init() {
    // Start motion tracking for physical orientation detection
    await ScreenOrientation.startOrientationTracking({
      bypassOrientationLock: true
    });

    // Listen for changes
    this.listener = await ScreenOrientation.addListener(
      'screenOrientationChange',
      this.onOrientationChange.bind(this)
    );

    // Get initial orientation
    const { type } = await ScreenOrientation.orientation();
    console.log('Initial orientation:', type);
  }

  onOrientationChange(result: { type: string }) {
    console.log('Orientation changed to:', result.type);

    // Adjust UI based on orientation
    if (result.type.includes('landscape')) {
      this.showLandscapeUI();
    } else {
      this.showPortraitUI();
    }
  }

  showLandscapeUI() {
    // Landscape-specific UI adjustments
  }

  showPortraitUI() {
    // Portrait-specific UI adjustments
  }

  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(`Device is held in ${physicalOrientation} but UI shows ${uiOrientation}`);
      return true;
    }
    return false;
  }

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

Note sulla piattaforma

iOS

• Utilizza il framework Core Motion per il rilevamento dell’orientamento fisico
• Richiede NSMotionUsageDescription in Info.plist per i sensori di movimento
• Pieno supporto per tutti i tipi di orientamento

Android

• Utilizza il sensore dell’accelerometro per il rilevamento dell’orientamento fisico
• Non sono necessarie autorizzazioni aggiuntive
• Pieno supporto per tutti i tipi di orientamento

Rete

• Utilizza l’orientamento dello schermo API
• Il rilevamento del sensore di movimento è limitato
• Alcuni browser potrebbero non supportare tutti i tipi di blocco