Panduan Memulai

Instal

Anda bisa menggunakan AI-Assisted Setup kami untuk menginstal plugin ini. Tambahkan skill Capgo ke tool AI Anda dengan command berikut:

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

Lalu gunakan prompt berikut:

Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/capacitor-screen-orientation` plugin in my project.

Jika Anda lebih memilih Manual Setup, instal plugin dengan menjalankan perintah berikut dan ikuti petunjuk khusus platform di bawah ini:

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

Impor

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

Mulai cepat

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

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

Contoh: lock

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

Contoh: unlock

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

await ScreenOrientation.unlock();

Kesalahan umum

• Listener: hapus handle saat screen unmount.
• Sinkronisasi Native: jalankan bunx cap sync setelah upgrade plugin.
• Sumber kebenaran tunggal: percayai src/definitions.ts di repo GitHub.

Ringkasan API

orientation

Dapatkan orientasi layar saat ini.

Mengembalikan orientasi layar perangkat saat ini.

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

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

lock

Kunci orientasi layar ke tipe tertentu.

Mengunci layar ke orientasi yang ditentukan. Di iOS, jika bypassOrientationLock bernilai true, sistem juga akan mulai melacak orientasi fisik perangkat menggunakan sensor gerak.

Catatan: UI tetap akan menghormati pengaturan penguncian orientasi pengguna. Pelacakan gerak memungkinkan Anda mendeteksi bagaimana perangkat dipegang secara fisik, bahkan ketika UI tidak berputar.

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

Buka kunci orientasi layar.

Memungkinkan layar berputar bebas berdasarkan posisi perangkat. Juga menghentikan pelacakan orientasi berbasis gerak jika sebelumnya diaktifkan.

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

await ScreenOrientation.unlock();

startOrientationTracking

Mulai melacak orientasi perangkat menggunakan sensor gerak.

Metode ini berguna saat Anda ingin melacak orientasi fisik perangkat secara independen dari penguncian orientasi layar. Metode ini menggunakan Core Motion di iOS untuk mendeteksi perubahan orientasi.

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

Berhenti melacak orientasi perangkat menggunakan sensor gerak.

Menghentikan pelacakan orientasi berbasis gerakan jika sebelumnya sudah dimulai.

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

await ScreenOrientation.stopOrientationTracking();

isOrientationLocked

Cek apakah kunci orientasi perangkat sedang aktif.

Metode ini membandingkan orientasi fisik perangkat (dari sensor gerak) dengan orientasi UI. Jika berbeda, penguncian orientasi akan diaktifkan.

Catatan: Ini memerlukan pelacakan gerakan yang aktif melalui startOrientationTracking() atau lock() dengan bypassOrientationLock: true. Berfungsi di iOS (Core Motion) dan 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);
}

Referensi Tipe

ScreenOrientationResult

Hasil yang dikembalikan oleh metode orientation().

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

OrientationLockOptions

Opsi untuk mengunci orientasi layar.

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

Opsi untuk memulai pelacakan orientasi menggunakan sensor gerak.

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

Hasil yang dikembalikan oleh metode 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

Jenis orientasi yang menggambarkan status orientasi perangkat.

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

OrientationLockType

Jenis penguncian orientasi yang dapat digunakan untuk mengunci orientasi perangkat.

export type OrientationLockType =
  | 'any'
  | 'natural'
  | 'landscape'
  | 'portrait'
  | 'portrait-primary'
  | 'portrait-secondary'
  | 'landscape-primary'
  | 'landscape-secondary';

Sumber Kebenaran

Halaman ini dibuat dari plugin src/definitions.ts. Jalankan ulang sync saat API publik berubah di upstream.

Lanjutkan dari Getting Started

Jika Anda menggunakan Panduan Memulai untuk merencanakan perilaku media dan antarmuka native, hubungkan dengan Menggunakan @capgo/capacitor-screen-orientation untuk kemampuan native dalam Menggunakan @capgo/capacitor-screen-orientation, Menggunakan @capgo/capacitor-live-activities untuk kemampuan native di Menggunakan @capgo/capacitor-live-activities, @capgo/capacitor-live-activities untuk detail implementasi di @capgo/capacitor-live-activities, Menggunakan @capgo/capacitor-video-player untuk kemampuan native di Menggunakan @capgo/capacitor-video-player, dan @capgo/capacitor-video-player untuk detail implementasi di @capgo/capacitor-video-player.