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

This is documentation for the next SDK version. For up-to-date documentation, see the latest version (SDK 57).

屏幕方向是指图形在设备上绘制时所采用的方向。例如，下图中的设备在物理上处于竖直和水平方向，但屏幕方向是纵向。有关物理设备方向，请参阅 Device Motion 的 orientation 部分。

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

Web 仅有有限支持。

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

iOS

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

• lockAsync 可能不会生效。系统可以拒绝该请求，而你的应用会保持可调整大小的状态。
• getOrientationAsync 可能无法描述应用所绘制窗口的形状。无论窗口的宽高比如何，iPhone 镜像始终会报告纵向方向。

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

安装

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 内置的 config plugin 进行配置。该插件允许你配置运行时无法设置、并且需要重新构建新的应用二进制文件才会生效的各种属性。如果你的应用不使用 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