Getting Started

이 플러그인의 설치 단계와 전체 마크다운 가이드를 포함한 설정 프롬프트를 복사하세요.

        Set up this Capacitor plugin in the project.

Use the package manager already used by the project.
Install these package(s): `@capgo/capacitor-screen-orientation`
Run the required Capacitor sync/update step after installation.
Read this markdown guide for the full setup steps: https://raw.githubusercontent.com/Cap-go/website/refs/heads/main/apps/docs/src/content/docs/docs/plugins/screen-orientation/getting-started.mdx
Use that guide for platform-specific steps, native file edits, permissions, config changes, imports, and usage setup.
If that guide references other docs pages, read them too.

설치

AI-Assisted Setup을 사용하여 플러그인을 설치할 수 있습니다. AI 도구에 다음 명령어를 사용하여 Capgo 기능을 추가하세요:

npx 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.

만약 Manual Setup을 선호한다면, 플러그인을 설치하기 위해 다음 명령어를 실행하고 아래의 플랫폼별 지침을 따르세요:

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

Import

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

API 개요

`orientation`

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

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

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

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

`lock`

방향 잠금

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

iOS에서 bypassOrientationLock이 true일 경우, 화면 방향을 motion sensors를 사용하여 추적합니다.

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`

__CAPGO_KEEP_0__ 해제

화면이 기기 위치에 따라 자유롭게 회전할 수 있도록 허용합니다. 또한 기기 위치 추적을 위한 운동 기반 방향 추적이 활성화된 경우 중지합니다.

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() 또는 lock() 함수를 사용하여 운동 추적이 활성화되어야 합니다. bypassOrientationLock: true 옵션을 사용합니다. 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`

클립보드에 복사

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`

__CAPGO_KEEP_0__

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`

__CAPGO_KEEP_2__

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`

__CAPGO_KEEP_5__

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

`OrientationLockType`

__CAPGO_KEEP_8__

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

__CAPGO_KEEP_10__

이 페이지는 플러그인의 src/definitions.ts. upstream에서 API이 변경될 때 다시 싱크를 실행하세요.

Getting Started에서 계속

Getting Started을 사용하여 자연스러운 미디어 및 인터페이스 동작을 계획하고 있으면 Using @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-screen-orientation Using @capgo/capacitor-screen-orientation Using @capgo/capacitor-live-activities Using @capgo/capacitor-live-activities for the native capability in Using @capgo/capacitor-live-activities, @capgo/capacitor-live-activities Capgo capgo/capacitor-live-activities 구현 세부 사항 Capgo capgo/capacitor-live-activities 사용 Capgo capgo/capacitor-live-activities의 원천 능력 Capgo capgo/capacitor-live-activities Capgo capgo/capacitor-live-activities 구현 세부 사항