시작하기

설치

AI-Assisted Setup으로 플러그인을 설치할 수 있습니다. 다음 명령어로 AI 도구에 Capgo 스킬을 추가하세요:

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

그런 다음 아래 프롬프트를 사용하세요:

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

수동 설정을 선호한다면, 다음 명령어를 실행하여 플러그인을 설치하고 아래의 플랫폼별 지침을 따르세요:

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

가져오기

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

빠른 시작

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

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

예시: 잠금

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

예시: 잠금 해제

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

await ScreenOrientation.unlock();

자주 하는 실수

• 리스너: 화면이 언마운트될 때 핸들을 제거합니다.
• 네이티브 동기화: 실행 bunx cap sync 플러그인 업그레이드 후.
• 신뢰할 수 있는 소스: 신뢰 src/definitions.ts GitHub 레포지토리에서.

API 개요

orientation

현재 화면 방향을 가져옵니다.

기기의 현재 화면 방향을 반환합니다.

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

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

lock

화면 방향을 특정 유형으로 고정합니다.

화면을 지정된 방향으로 고정합니다. iOS에서 bypassOrientationLock이 true이면 모션 센서를 사용하여 물리적 기기 방향 추적도 시작됩니다.

참고: UI는 여전히 사용자의 방향 고정 설정을 따릅니다. 모션 추적을 사용하면 UI가 회전하지 않더라도 기기가 물리적으로 어떻게 잡혀 있는지 감지할 수 있습니다.

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

화면 방향 고정을 해제합니다.

기기 위치에 따라 화면이 자유롭게 회전하도록 허용합니다. 활성화되어 있던 모션 기반 방향 추적도 중지합니다.

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

await ScreenOrientation.unlock();

startOrientationTracking

모션 센서로 기기 방향 추적을 시작합니다.

이 메서드는 화면 방향 잠금과 별개로 기기의 물리적 방향을 추적할 때 유용합니다. iOS에서는 Core Motion으로 방향 변화를 감지합니다.

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

모션 센서를 사용한 기기 방향 추적을 중단합니다.

모션 기반 방향 추적이 시작된 경우 중단합니다.

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

await ScreenOrientation.stopOrientationTracking();

isOrientationLocked

현재 기기 방향 잠금이 활성화되어 있는지 확인합니다.

이 메서드는 물리적 기기 방향(모션 센서 기준)과 UI 방향을 비교합니다. 두 방향이 다르면 방향 잠금이 활성화된 상태입니다.

참고: 이 기능을 사용하려면 startOrientationTracking() 또는 bypassOrientationLock: true를 지정한 lock()을 통해 모션 추적이 활성화되어 있어야 합니다. iOS(Core Motion)와 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);
}

타입 레퍼런스

ScreenOrientationResult

orientation() 메서드가 반환하는 결과입니다.

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

OrientationLockOptions

화면 방향을 잠그기 위한 옵션입니다.

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

모션 센서를 사용하여 방향 추적을 시작하기 위한 옵션입니다.

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

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

기기의 방향 상태를 나타내는 Orientation 타입입니다.

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

OrientationLockType

기기 방향을 고정하는 데 사용할 수 있는 Orientation lock 타입입니다.

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

Source of Truth

이 페이지는 플러그인의 src/definitions.tsupstream에서 public API가 변경되면 sync를 다시 실행하세요.

시작하기 다음 단계

사용 중이라면 시작하기 네이티브 미디어 및 인터페이스 동작을 계획하려면, 이를 다음 항목과 연결하세요: @capgo/capacitor-screen-orientation 사용하기 @capgo/capacitor-screen-orientation 사용하기에서 네이티브 기능을 위해, @capgo/capacitor-live-activities 사용 @capgo/capacitor-live-activities 사용에서의 네이티브 기능, @capgo/capacitor-live-activities @capgo/capacitor-live-activities의 구현 세부 사항, @capgo/capacitor-video-player 사용 @capgo/capacitor-video-player 사용에서의 네이티브 기능 및 @capgo/capacitor-video-player @capgo/capacitor-video-player.의 구현 세부 사항