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 支持有限。

安装

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 始终处于横屏模式。要能够使用此模块锁定屏幕方向，你需要禁用对该功能的支持。有关 分屏视图 模式的更多信息，请查看Apple 官方文档。

app 配置中的配置

如果你在项目中使用配置插件（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