はじめに

インストール

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

インポート

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を使用して物理的なデバイスの回転を追跡します。

注意: 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

画面回転を解除します。

デバイスの位置に応じて画面が自由に回転できるようにします。 また、motion-based orientation trackingが有効になっていた場合も停止します。

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の回転を比較します。 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

画面の向きを取得する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

クリップボードにコピー

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

デバイスの向きの状態を表す向きの種類

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

OrientationLockType

デバイスの向きを固定するために使用できる向きのロックの種類

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

ソース オブ トゥルース

このページはプラグインの src/definitions.ts API がアップストリームで変更された場合に、再度 Sync を実行してください。

Getting Started から続けてください

__CAPGO_KEEP_0__で「__CAPGO_KEEP_1__」を使用している場合 Getting Started ネイティブメディアとインターフェイスの動作を計画するには、__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-screen-orientationと接続してください 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-live-activitiesを使用してください capgo/capacitor-video-playerのネイティブ機能を使用するには、Using @capgo/capacitor-video-playerを使用してください capgo/capacitor-video-player capgo/capacitor-video-player capgo/capacitor-video-player @capgo/capacitor-video-player @capgo/capacitor-video-player