시작하기

1. 패키지 설치

   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. 네이티브 프로젝트와 동기화

   npm

   npx cap sync

   pnpm

   pnpm cap sync

   yarn

   yarn cap sync

   bun

   bunx cap sync

3. iOS 구성 (선택사항) iOS에서 모션 센서를 사용하여 실제 기기 방향을 감지하려면 Info.plist에 추가하세요:

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

기본 사용법

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

실제 방향 감지

이 플러그인에는 고유한 기능이 있습니다: 사용자가 기기에서 방향 잠금을 활성화한 경우에도 모션 센서를 사용하여 기기의 실제 물리적 방향을 감지할 수 있습니다.

참고

UI는 여전히 사용자의 방향 잠금 설정을 따릅니다. 모션 추적을 통해 기기가 물리적으로 어떻게 잡혀 있는지 알 수 있지만, 방향 잠금이 활성화된 경우 UI는 회전하지 않습니다.

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 참조

orientation()

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

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

OrientationType 값:

• 'portrait-primary' - 세로, 홈 버튼이 하단에 위치
• 'portrait-secondary' - 세로, 거꾸로
• 'landscape-primary' - 가로, 홈 버튼이 오른쪽에 위치
• 'landscape-secondary' - 가로, 홈 버튼이 왼쪽에 위치

lock(options)

화면을 특정 방향으로 잠급니다.

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

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

OrientationLockType 값:

• 'any' - 모든 방향
• 'natural' - 기기의 자연스러운 방향
• 'landscape' - 모든 가로 모드
• 'portrait' - 모든 세로 모드
• 'portrait-primary' / 'portrait-secondary'
• 'landscape-primary' / 'landscape-secondary'

unlock()

화면 방향 잠금을 해제합니다.

await ScreenOrientation.unlock();

startOrientationTracking(options?)

모션 센서를 사용하여 실제 기기 방향 추적을 시작합니다.

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

stopOrientationTracking()

모션 기반 방향 추적을 중지합니다.

await ScreenOrientation.stopOrientationTracking();

isOrientationLocked()

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

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

팁

이 메서드가 제대로 작동하려면 모션 추적이 활성화되어 있어야 합니다.

addListener(eventName, callback)

방향 변경을 수신합니다.

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

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

removeAllListeners()

모든 이벤트 리스너를 제거합니다.

await ScreenOrientation.removeAllListeners();

완전한 예제

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

플랫폼 참고사항

iOS

• 실제 방향 감지를 위해 Core Motion 프레임워크 사용
• 모션 센서를 위해 Info.plist에 NSMotionUsageDescription 필요
• 모든 방향 유형에 대한 완전한 지원

Android

• 실제 방향 감지를 위해 가속도계 센서 사용
• 추가 권한 불필요
• 모든 방향 유형에 대한 완전한 지원

Web

• Screen Orientation API 사용
• 모션 센서 감지는 제한적
• 일부 브라우저는 모든 잠금 유형을 지원하지 않을 수 있음