スタートガイド

インストール

AIアシストによるセットアップでプラグインをインストールできます。以下のコマンドを使用して、お使いの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 type。

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

OrientationLockType

デバイスの向きを固定するために使用できる Orientation lock type。

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

Source of Truth

このページはプラグインの src/definitions.tsから生成されています。upstream で公開 API が変更されたら、再度 sync を実行してください。

Getting Startedの続きを進める

使用している場合 スタートガイド ネイティブメディアとインターフェースの挙動を計画するには、次と連携させてください @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. の実装の詳細については