Mulai Menggunakan

Install

Anda dapat menggunakan Setup Bantuan AI kami untuk menginstal plugin ini. Tambahkan Capgo kemampuan ke alat AI Anda menggunakan perintah 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 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

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

• Pengguna: hapuskan tangani ketika layar tidak terpasang.
• Sinkron nativeJalankan bunx cap sync setelah pengembangan plugin.
• Sumber Kebenaran: percayalah src/definitions.ts di repositori GitHub.

Ringkasan API

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

Kunci orientasi layar ke jenis tertentu.

Menjaga layar terkunci pada orientasi yang ditentukan. Di iOS, jika bypassOrientationLock adalah benar, maka akan memulai pula mengikuti orientasi fisik perangkat menggunakan sensor gerakan.

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

Allows the screen to rotate freely based on device position. Also stops any motion-based orientation tracking if it was enabled.

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

await ScreenOrientation.unlock();

startOrientationTracking

Mulai mengikuti orientasi perangkat menggunakan sensor gerakan.

This method is useful when you want to track the device’s physical orientation independently from the screen orientation lock. It uses Core Motion on iOS to detect orientation changes.

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

Hentikan penginderaan orientasi perangkat menggunakan sensor gerakan.

Hentikan penginderaan orientasi perangkat berdasarkan sensor gerakan jika sudah dimulai.

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

await ScreenOrientation.stopOrientationTracking();

isOrientationLocked

Periksa apakah penguncian orientasi perangkat sedang diaktifkan.

Menggunakan metode ini, perangkat lunak membandingkan orientasi perangkat fisik (dari sensor gerakan) dengan orientasi antarmuka pengguna. Jika mereka berbeda, penguncian orientasi diaktifkan.

Catatan: Fitur ini memerlukan pengaktifan tracking gerakan 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

Bab berjudul “Pilihan Orientasi Layar Terkunci”

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

Bab berjudul “Pilihan Mulai Mengikuti Orientasi”

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

Bab berjudul “Hasil Status Orientasi Terkunci”

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 menjelaskan keadaan orientasi perangkat.

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

OrientationLockType

Jenis pengunci 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 dihasilkan dari plugin’s src/definitions.ts. Ulangi sinkronisasi ketika API publik berubah secara upstream.

Teruskan dari Mulai Membuat

Jika Anda menggunakan Mulai Dari Sini untuk merencanakan perilaku media dan antarmuka native, hubungkannya dengan Menggunakan @capgo/capacitor-orientasi-layar untuk kemampuan native di Menggunakan @capgo/capacitor-orientasi-layar, Menggunakan @capgo/capacitor-aktivitas-hidup untuk kemampuan native di Menggunakan @capgo/capacitor-aktivitas-hidup, @capgo/capacitor-aktivitas-hidup untuk detail implementasi di @capgo/capacitor-aktivitas-hidup, Menggunakan @capgo/capacitor-pemain-video untuk kemampuan native di Menggunakan @capgo/capacitor-pemain-video, dan @capgo/capacitor-pemain-video untuk detail implementasi di @capgo/capacitor-pemain-video.