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

屏幕方向是指图形在设备上绘制的方向。例如，下图中的设备处于纵向和横向两种物理方向，但屏幕方向为纵向。有关设备的物理方向，请参阅 Device Motion 的方向部分。

在 Android 和 iOS 平台上，屏幕方向的更改会覆盖任何系统设置或用户偏好。在 Android 上，可以在考虑用户偏好的方向的同时更改屏幕方向。在 iOS 上，应用无法访问用户和系统设置，因此任何屏幕方向更改都会覆盖现有设置。

Web 支持有限。

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

iOS

从 iOS 27 开始，iPhone 应用可以调整大小，例如在 macOS 上使用 iPhone Mirroring 时，或在 iPad 上运行时。当应用可调整大小时，系统会将受支持的方向视为偏好而非要求。这会带来两个后果：

• lockAsync 可能不起作用。系统可以拒绝该请求，而应用仍可调整大小。
• getOrientationAsync 可能无法反映应用所绘制窗口的形状。无论窗口的宽高比如何，iPhone Mirroring 始终报告纵向方向。

请设计能够适应可用空间的屏幕，而不要依赖固定方向。在调试版本中，如果系统拒绝方向锁定，此库会记录警告。利用这些警告找出仍依赖平台不再保证的方向锁定的屏幕。

安装

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

警告

Apple 在 iOS 9 中为 iPad 添加了对 分屏视图 模式的支持。这改变了系统处理屏幕方向的方式。简而言之，对于 iOS，除非你并排打开两个应用，否则 iPad 始终处于横向模式。若要使用此模块锁定屏幕方向，需要通过在应用配置中将 ios.requireFullScreen 设置为 true，禁用对此功能的支持。

在 iOS 27 及更高版本中，requireFullScreen 不再阻止应用调整大小，因此无法可靠地锁定屏幕方向。请参阅 iOS 27 及更高版本中的方向锁定。有关 分屏视图 模式的更多信息，请参阅 Apple 官方文档。

在应用配置中配置

如果项目中使用配置插件（Continuous Native Generation (CNG)），可以使用内置的配置插件配置 expo-screen-orientation。该插件允许你配置各种无法在运行时设置、且需要重新构建应用二进制文件才能生效的属性。如果应用不使用 CNG，则需要手动配置此库。

Example app.json with config plugin

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

Configurable properties

使用 Expo Router 设置每个屏幕的方向

如果使用 Expo Router，可以通过 Stack.Screen 上的 orientation 选项为每个屏幕设置方向。此功能由 react-native-screens 提供支持，也是堆栈导航器中为每个屏幕设置方向的推荐方法。

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';

Methods

async function changeScreenOrientation() {
  await ScreenOrientation.lockAsync(ScreenOrientation.OrientationLock.LANDSCAPE_LEFT);
}

Event subscriptions

Interfaces

Types

Enums