Vai al contenuto
Capgo

Getting Started

Questo contenuto non è ancora disponibile nella tua lingua.

  1. Install the package

    Terminal window
    npm i @capgo/capacitor-screen-orientation

  2. Sync with native projects

    Terminal window
    npx cap sync

  3. iOS Configuration (optional) To detect physical device orientation using motion sensors on iOS, add to your Info.plist:

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

Basic Usage

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

Physical Orientation Detection

This plugin has a unique feature: it can detect the true physical orientation of the device using motion sensors, even when the user has enabled orientation lock on their device.

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 Reference

orientation()

Get the current screen orientation.

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

OrientationType values:

  • 'portrait-primary' - Portrait, home button at bottom
  • 'portrait-secondary' - Portrait, upside down
  • 'landscape-primary' - Landscape, home button on right
  • 'landscape-secondary' - Landscape, home button on left

lock(options)

Lock the screen to a specific orientation.

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


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

OrientationLockType values:

  • 'any' - Any orientation
  • 'natural' - Device’s natural orientation
  • 'landscape' - Any landscape mode
  • 'portrait' - Any portrait mode
  • 'portrait-primary' / 'portrait-secondary'
  • 'landscape-primary' / 'landscape-secondary'

unlock()

Unlock the screen orientation.

await ScreenOrientation.unlock();

startOrientationTracking(options?)

Start tracking physical device orientation using motion sensors.

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

stopOrientationTracking()

Stop motion-based orientation tracking.

await ScreenOrientation.stopOrientationTracking();

isOrientationLocked()

Check if device orientation lock is enabled.

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

addListener(eventName, callback)

Listen for orientation changes.

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


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

removeAllListeners()

Remove all event listeners.

await ScreenOrientation.removeAllListeners();

Complete Example

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

Platform Notes

iOS

  • Uses Core Motion framework for physical orientation detection
  • Requires NSMotionUsageDescription in Info.plist for motion sensors
  • Full support for all orientation types

Android

  • Uses accelerometer sensor for physical orientation detection
  • No additional permissions required
  • Full support for all orientation types

Web

  • Uses Screen Orientation API
  • Motion sensor detection is limited
  • Some browsers may not support all lock types