Getting Started

Install

Anda dapat menggunakan Setup Bantuan AI kami untuk menginstal plugin. Tambahkan Capgo kemampuan ke alat AI Anda menggunakan perintah berikut:

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

Kemudian 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 suka Setup Manual, instal plugin dengan menjalankan perintah-perintah berikut dan ikuti instruksi spesifik platform di bawah:

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

Import

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

API Ringkasan

orientation

Peroleh 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

Blokir orientasi layar ke jenis tertentu.

Mengunci layar ke orientasi yang ditentukan. Di iOS, jika bypassOrientationLock adalah true, maka akan juga memulai mengikuti orientasi fisik perangkat menggunakan sensor gerakan.

Perlu diingat: UI akan tetap menghormati pengaturan lock orientasi pengguna. Pengikutan gerakan memungkinkan Anda mendeteksi bagaimana perangkat dipegang 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

Membuka orientasi layar.

Memungkinkan layar untuk berputar bebas berdasarkan posisi perangkat. Juga menghentikan pengikatan orientasi berdasarkan gerakan jika sudah diaktifkan.

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

await ScreenOrientation.unlock();

startOrientationTracking

Mulai mengikuti orientasi perangkat menggunakan sensor gerakan.

Methode ini berguna ketika Anda ingin mengikuti orientasi fisik perangkat secara independen dari pengikatan orientasi layar. Menggunakan Core Motion pada 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

Menghentikan pengikatan orientasi perangkat menggunakan sensor gerakan.

Menghentikan pengikatan orientasi berdasarkan gerakan jika sudah diaktifkan.

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

await ScreenOrientation.stopOrientationTracking();

isOrientationLocked

Periksa jika pengikatan orientasi perangkat sudah diaktifkan.

Metode ini membandingkan orientasi perangkat fisik (dari sensor gerakan) dengan orientasi antarmuka. Jika mereka berbeda, penguncian orientasi diaktifkan.

Perlu diingat: Ini memerlukan tracking gerakan aktif melalui startOrientationTracking() atau lock() dengan bypassOrientationLock: true. Bekerja pada baik 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 pengaturan orientasi menggunakan sensor gerakan.

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

Tipe orientasi yang menjelaskan keadaan orientasi perangkat.

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

OrientationLockType

Tipe pemutus orientasi yang dapat digunakan untuk memutuskan orientasi perangkat.

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

Sumber Kebenaran

Halaman ini dibuat dari plugin’s src/definitions.tsRe-run sinkronisasi ketika API publik berubah di atas

Teruskan dari Getting Started

Jika Anda menggunakan Getting Started untuk merencanakan perilaku media asli dan antarmuka, hubungkannya dengan Menggunakan @capgo/capacitor-orientasi-layar untuk kemampuan asli di Menggunakan @capgo/capacitor-orientasi-layar, Menggunakan @capgo/capacitor-aktivitas-hidup untuk kemampuan asli di Menggunakan @capgo/capacitor-aktivitas-hidup, @capgo/capacitor-aktivitas-nyata-hidup untuk detail implementasi di @capgo/capacitor-aktivitas-nyata-hidup Menggunakan @capgo/capacitor-pemain-video-asli untuk kemampuan asli di Menggunakan @capgo/capacitor-pemain-video-asli, dan @capgo/capacitor-pemain-video-asli untuk detail implementasi di @capgo/capacitor-pemain-video-asli.