はじめる

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 リファレンス

向き()

現在の画面の向きを取得します。

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

OrientationType 値:

• 'portrait-primary' - 縦向き、下部にホームボタン
• 'portrait-Secondary' - 縦向き、上下逆さま
• 'landscape-primary' - 横向き、右側のホームボタン
• 'landscape-Secondary' - 横向き、左側のホームボタン

ロック(オプション)

画面を特定の向きにロックします。

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

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

OrientationLockType 値:

• 'any' - 任意の方向
• 'natural' - デバイスの自然な向き
• 'landscape' - 任意の風景モード
• 'portrait' - 任意のポートレート モード
• 'ポートレート-プライマリ' / 'ポートレート-セカンダリ'
• 'ランドスケープ-プライマリ' / ‘ランドスケープ-セカンダリ’`

ロック解除()

画面の向きのロックを解除します。

await ScreenOrientation.unlock();

startOrientationTracking(オプション?)

モーション センサーを使用して物理デバイスの向きの追跡を開始します。

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

stopOrientationTracking()

モーションベースの方向追跡を停止します。

await ScreenOrientation.stopOrientationTracking();

isOrientationLocked()

デバイスの向きのロックが有効になっているかどうかを確認します。

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

ヒント

この方法が正しく動作するには、モーション トラッキングがアクティブになっている必要があります。

addListener(イベント名, コールバック)

方向の変化を聞きます。

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

• 物理的な向きの検出に加速度センサーを使用
• 追加の権限は必要ありません
• すべての向きのタイプを完全にサポート

ウェブ

• 画面の向き API を使用します
• モーションセンサーの検出は制限されています
• 一部のブラウザはすべてのロック タイプをサポートしていない場合があります