This documentation is available as Markdown for AI agents and LLMs. See the full Markdown index or append .md to any documentation URL.

Expo ScreenOrientation iconExpo ScreenOrientation

用于管理设备屏幕方向的通用库。

Android
iOS
Web
Included in Expo Go
Recommended version:
~58.0.3

屏幕方向是指图形在设备上显示的方向。例如,下图显示的设备在垂直和水平的物理方向上,但屏幕方向为纵向。有关设备物理方向,请参阅 设备运动 的方向部分。

🌐 Screen Orientation is defined as the orientation in which graphics are painted on the device. For example, the figure below has a device in a vertical and horizontal physical orientation, but a portrait screen orientation. For physical device orientation, see the orientation section of Device Motion.

在 Android 和 iOS 平台上,屏幕方向的更改将覆盖任何系统设置或用户偏好。在 Android 上,可以在考虑用户首选方向的情况下更改屏幕方向。在 iOS 上,应用无法访问用户和系统设置,任何屏幕方向的更改都会覆盖现有设置。

🌐 On both Android and iOS platforms, changes to the screen orientation will override any system settings or user preferences. On Android, it is possible to change the screen orientation while taking the user's preferred orientation into account. On iOS, user and system settings are not accessible by the application and any changes to the screen orientation will override existing settings.

iOS 27 及更高版本的方向锁定 
iOS

🌐 Orientation locks on iOS 27 and later 

iOS

从 iOS 27 开始,iPhone 应用可以调整大小,比如在 macOS 上的 iPhone 镜像功能或在 iPad 上运行时。当应用可以调整大小时,系统会把支持的方向当作偏好而不是必须。这有两个结果:

🌐 Starting in iOS 27, iPhone apps can be resized, for example in iPhone Mirroring on macOS or when running on an iPad. While an app is resizable, the system treats a supported orientation as a preference rather than a requirement. This has two consequences:

  • lockAsync 可能没有效果。系统可能会拒绝该请求,而你的应用仍然可以调整大小。
  • getOrientationAsync 可能无法描述你的应用正在绘制的窗口的形状。无论窗口的长宽比如何,iPhone 镜像总是报告纵向方向。

设计你的屏幕时要让它们适应可用空间,而不是依赖固定的方向。在调试版本中,当系统拒绝方向锁定时,这个库会记录一个警告。利用这些警告来找出仍依赖平台不再保证的锁定的屏幕。

🌐 Design your screens to adapt to the space available to them instead of relying on a fixed orientation. In debug builds, this library logs a warning when the system refuses an orientation lock. Use those warnings to find the screens that still depend on a lock the platform no longer guarantees.

安装

🌐 Installation

Terminal
- npx expo install expo-screen-orientation
- yarn expo install expo-screen-orientation
- pnpm expo install expo-screen-orientation
- bun expo install expo-screen-orientation

If you are installing this in an existing React Native app, make sure to install expo in your project.

警告

🌐 Warning

苹果在 iOS 9 中为 iPad 增加了对 分屏视图 模式的支持。这改变了系统处理屏幕方向的方式。简单来说,对于 iOS 来说,你的 iPad 总是处于横屏模式,除非你并排打开两个应用。要使用这个模块锁定屏幕方向,你需要通过在你的 应用配置 中将 ios.requireFullScreen 设置为 true 来禁用对该功能的支持。

🌐 Apple added support for split view mode to iPads in iOS 9. This changed how the screen orientation is handled by the system. To put the matter shortly, for iOS, your iPad is always in landscape mode unless you open two applications side by side. To be able to lock screen orientation using this module you will need to disable support for this feature by setting ios.requireFullScreen to true in your app config.

在 iOS 27 及更高版本中,requireFullScreen 不再让你的应用退出调整大小,因此无法可靠地锁定屏幕方向。请参阅 iOS 27 及更高版本的方向锁定。想了解更多关于 分屏 模式的信息,可以查看 苹果官方文档。

🌐 On iOS 27 and later, requireFullScreen no longer opts your app out of being resized, so it cannot reliably lock the screen orientation. See Orientation locks on iOS 27 and later. For more information about the split view mode, check out the official Apple documentation.

应用配置中的配置

🌐 Configuration in app config

如果你在项目中使用配置插件(连续原生生成 (CNG)),你可以使用其内置的 配置插件 来配置 expo-screen-orientation。该插件允许你配置一些无法在运行时设置的属性,这些属性需要构建新的应用二进制文件才能生效。如果你的应用不使用 CNG,那么你需要手动配置该库。

🌐 You can configure expo-screen-orientation using its built-in config plugin if you use config plugins in your project (Continuous Native Generation (CNG)). The plugin allows you to configure various properties that cannot be set at runtime and require building a new app binary to take effect. If your app does not use CNG, then you'll need to manually configure the library.

Example app.json with config plugin

app.json
{ "expo": { "ios": { "requireFullScreen": true }, "plugins": [ [ "expo-screen-orientation", { "initialOrientation": "DEFAULT" } ] ] } }

Configurable properties

NameDefaultDescription
initialOrientationundefined
Only for: 
iOS

Sets the iOS initial screen orientation. Possible values: DEFAULT, ALL, PORTRAIT, PORTRAIT_UP, PORTRAIT_DOWN, LANDSCAPE, LANDSCAPE_LEFT, LANDSCAPE_RIGHT

Are you using this library in an existing React Native app?
  1. 在 Xcode 中使用 xed ios 打开 ios 目录。如果你没有该目录,请运行 npx expo prebuild -p ios 来生成一个。
  2. 在 Xcode 中勾选 Requires Full Screen 复选框。它应该位于 Project Target > General > Deployment Info 下。

使用 Expo Router 的每屏方向

🌐 Per-screen orientation with Expo Router

如果你使用 Expo Router,你可以在每个屏幕上使用 Stack.Screen 的 orientation 选项来设置方向。这是由 react-native-screens 提供支持的,并且是堆栈导航器中每个屏幕设置方向的推荐方法。

🌐 If you use Expo Router, you can set the orientation per screen using the orientation option on Stack.Screen. This is powered by react-native-screens and is the recommended approach for per-screen orientation in stack navigators.

src/app/_layout.tsx
import { Stack } from 'expo-router'; export default function Layout() { return ( <Stack> <Stack.Screen name="index" options={{ orientation: 'portrait' }} /> <Stack.Screen name="landscape" options={{ orientation: 'landscape' }} /> </Stack> ); }

应用接口

🌐 API

import * as ScreenOrientation from 'expo-screen-orientation';

No API data file found, sorry!