开始入门

安装

您可以使用我们的AI辅助设置来安装插件。将Capgo技能添加到您的AI工具中，使用以下命令：

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.

如果您更喜欢手动设置，请通过运行以下命令安装插件并按照以下平台特定的说明进行操作：

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，则还会使用运动传感器开始跟踪物理设备方向。

注意：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() 或 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

开始屏幕方向跟踪选项

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

设备方向状态的描述

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在上游发生变化时，请重新同步。

继续从 Getting Started

如果您正在使用 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。