Memulai

1. Instal paket

   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. Sinkronisasi dengan proyek asli

   npm

   npx cap sync

   pnpm

   pnpm cap sync

   yarn

   yarn cap sync

   bun

   bunx cap sync

3. iOS Konfigurasi (opsional) Untuk mendeteksi orientasi perangkat fisik menggunakan sensor gerak di iOS, tambahkan ke Info.plist Anda:

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

Penggunaan Dasar

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

Deteksi Orientasi Fisik

Plugin ini memiliki fitur unik: plugin ini dapat mendeteksi orientasi fisik sebenarnya perangkat menggunakan sensor gerak, bahkan ketika pengguna telah mengaktifkan kunci orientasi pada perangkatnya.

Catatan

UI akan tetap mengikuti pengaturan kunci orientasi pengguna. Pelacakan gerakan memungkinkan Anda mengetahui cara perangkat dipegang secara fisik, namun UI tidak akan berputar jika kunci orientasi diaktifkan.

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 Referensi

orientasi()

Dapatkan orientasi layar saat ini.

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

Nilai Tipe Orientasi:

• 'potret-utama' - Potret, tombol beranda di bagian bawah
• 'potret-sekunder' - Potret, terbalik
• 'landscape-primary' - Landscape, tombol beranda di sebelah kanan
• 'lanskap-sekunder' - Lanskap, tombol beranda di sebelah kiri

kunci (opsi)

Kunci layar ke orientasi tertentu.

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

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

Nilai OrientationLockType:

• 'apa saja' - Orientasi apa pun
• 'alami' - Orientasi alami perangkat
• 'lanskap' - Mode lanskap apa pun
• 'potret' - Mode potret apa pun
• 'potret-primer' / 'potret-sekunder'
• 'lanskap-primer' / 'lanskap-sekunder'

buka kunci()

Buka kunci orientasi layar.

await ScreenOrientation.unlock();

startOrientationTracking(pilihan?)

Mulai lacak orientasi perangkat fisik menggunakan sensor gerak.

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

hentikanPelacakanOrientasi()

Hentikan pelacakan orientasi berbasis gerakan.

await ScreenOrientation.stopOrientationTracking();

isOrientationLocked()

Periksa apakah kunci orientasi perangkat diaktifkan.

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

Tips

Metode ini memerlukan pelacakan gerak yang aktif agar dapat berfungsi dengan baik.

addListener(nama kejadian, panggilan balik)

Dengarkan perubahan orientasi.

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

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

hapusSemua Pendengar()

Hapus semua pendengar acara.

await ScreenOrientation.removeAllListeners();

Contoh Lengkap

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

Catatan Platform

iOS

• Menggunakan kerangka Core Motion untuk deteksi orientasi fisik
• Membutuhkan NSMotionUsageDescription di Info.plist untuk sensor gerak
• Dukungan penuh untuk semua jenis orientasi

Android

• Menggunakan sensor accelerometer untuk deteksi orientasi fisik
• Tidak diperlukan izin tambahan
• Dukungan penuh untuk semua jenis orientasi

Web

• Menggunakan Orientasi Layar API
• Deteksi sensor gerak terbatas
• Beberapa browser mungkin tidak mendukung semua jenis kunci