@capacitor/screen-orientation

屏幕方向 API 提供与屏幕方向相关的信息与功能。

安装

npm install @capacitor/screen-orientation
npx cap sync

iOS

锁定屏幕方向仅对 Capacitor View Controller 有效，而对其他呈现的视图控制器（例如由 Browser 插件呈现的控制器）无效。 若需同时锁定已呈现的视图控制器，可将以下代码添加到应用的 AppDelegate.swift 文件中：

func application(_ application: UIApplication, supportedInterfaceOrientationsFor window: UIWindow?) -> UIInterfaceOrientationMask {
  return UIInterfaceOrientationMask(rawValue: (self.window!.rootViewController as! CAPBridgeViewController).supportedInterfaceOrientations.rawValue)
}

iPad 方向锁定

默认情况下，iPad 支持多任务处理且其方向无法被锁定。如需在 iPad 上锁定方向，请将 Requires Full Screen 选项设置为 YES，即在 Info.plist 中添加以下内容：

  <key>UIRequiresFullScreen</key>
  <true/>

API

• orientation()
• lock(...)
• unlock()
• addListener('screenOrientationChange', ...)
• removeAllListeners()
• 接口
• 类型别名

orientation()

orientation() => Promise<ScreenOrientationResult>

返回当前屏幕方向。

返回值：

Promise<ScreenOrientationResult>

自版本： 4.0.0

---

lock(...)

lock(options: OrientationLockOptions) => Promise<void>

锁定屏幕方向。

从 Android targetSdk 36 开始，此方法对 Android 16 及更高版本的大屏幕设备（例如平板电脑）无效。 您可以通过在 AndroidManifest.xml 的 <application> 或 <activity> 中添加 <property android:name="android.window.PROPERTY_COMPAT_ALLOW_RESTRICTED_RESIZABILITY" android:value="true" /> 来选择退出此行为。 但请注意，此退出选项是临时的，并且在 Android 17 中将不再有效。Android 不鼓励为大屏幕设备设置特定方向。 常规的 Android 手机不受此更改影响。 更多信息请查阅 Android 文档：https://developer.android.com/about/versions/16/behavior-changes-16#adaptive-layouts

参数	类型
options	OrientationLockOptions

自版本： 4.0.0

---

unlock()

unlock() => Promise<void>

解锁屏幕方向。

自版本： 4.0.0

---

addListener('screenOrientationChange', ...)

addListener(eventName: 'screenOrientationChange', listenerFunc: (orientation: ScreenOrientationResult) => void) => Promise<PluginListenerHandle>

监听屏幕方向变化。

参数	类型
eventName	'screenOrientationChange'
listenerFunc	(orientation: ScreenOrientationResult) => void

返回值：

Promise<PluginListenerHandle>

自版本： 4.0.0

---

removeAllListeners()

removeAllListeners() => Promise<void>

移除所有监听器。

自版本： 4.0.0

---

Interfaces

ScreenOrientationResult

属性	类型
type	OrientationType

OrientationLockOptions

属性	类型	描述
orientation	OrientationLockType	注意：TypeScript v5.2+ 用户应从 @capacitor/screen-orientation 导入 OrientationLockType。

PluginListenerHandle

属性	类型
remove	() => Promise<void>

Type Aliases

OrientationLockType

  'any' | 'natural' | 'landscape' | 'portrait' | 'portrait-primary' | 'portrait-secondary' | 'landscape-primary' |
  'landscape-secondary'