Expo ScreenOrientation

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

Android

iOS

Web

Included in Expo Go

GitHub

npm

更新日志

Bundled version:

~8.1.7

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

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

Web 仅有有限支持。

安装

Terminal

- npx expo install expo-screen-orientation

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

警告

Apple 在 iOS 9 中为 iPad 添加了对 split view 模式的支持。这改变了系统处理屏幕方向的方式。简而言之，在 iOS 中，除非你并排打开两个应用，否则你的 iPad 始终处于横屏模式。要使用此模块锁定屏幕方向，你需要禁用对此功能的支持。有关 split view 模式的更多信息，请查看 Apple 官方文档。

应用配置中的配置

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

Example app.json with config plugin

app.json

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

Configurable properties

Name	Default	Description
`initialOrientation`	`undefined`	Only for: iOS 设置 iOS 初始屏幕方向。可选值：`DEFAULT`、`ALL`、`PORTRAIT`、`PORTRAIT_UP`、`PORTRAIT_DOWN`、`LANDSCAPE`、`LANDSCAPE_LEFT`、`LANDSCAPE_RIGHT`

Are you using this library in an existing React Native app?

在 Xcode 中使用 xed ios 打开 ios 目录。如果没有该目录，请运行 npx expo prebuild -p ios 来生成。
在 Xcode 中勾选 Requires Full Screen 复选框。它位于 Project Target > General > Deployment Info 下。

API

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

Methods

`ScreenOrientation.getOrientationAsync()`

Android

iOS

Web

Gets the current screen orientation.

Returns:

Promise<Orientation>

Returns a promise that fulfils with an Orientation value that reflects the current screen orientation.

`ScreenOrientation.getOrientationLockAsync()`

Android

iOS

Web

Gets the current screen orientation lock type.

Returns:

Promise<OrientationLock>

Returns a promise which fulfils with an OrientationLock value.

`ScreenOrientation.getPlatformOrientationLockAsync()`

Android

iOS

Web

Gets the platform specific screen orientation lock type.

Returns:

Promise<PlatformOrientationInfo>

Returns a promise which fulfils with a PlatformOrientationInfo value.

`ScreenOrientation.lockAsync(orientationLock)`

Android

iOS

Web

Parameter	Type	Description
orientationLock	`OrientationLock`	The orientation lock to apply. See the `OrientationLock` enum for possible values.

Lock the screen orientation to a particular OrientationLock.

Returns:

Promise<void>

Returns a promise with void value, which fulfils when the orientation is set.

Example

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

`ScreenOrientation.lockPlatformAsync(options)`

Android

iOS

Web

Parameter	Type	Description
options	`PlatformOrientationInfo`	The platform specific lock to apply. See the `PlatformOrientationInfo` object type for the different platform formats.

Returns:

Promise<void>

Returns a promise with void value, resolving when the orientation is set and rejecting if an invalid option or value is passed.

`ScreenOrientation.supportsOrientationLockAsync(orientationLock)`

Android

iOS

Web

Parameter	Type
orientationLock	`OrientationLock`

Returns whether the OrientationLock policy is supported on the device.

Returns:

Promise<boolean>

Returns a promise that resolves to a boolean value that reflects whether or not the orientationLock is supported.

`ScreenOrientation.unlockAsync()`

Android

iOS

Web

Sets the screen orientation back to the OrientationLock.DEFAULT policy.

Returns:

Promise<void>

Returns a promise with void value, which fulfils when the orientation is set.

Event Subscriptions

`ScreenOrientation.addOrientationChangeListener(listener)`

Android

iOS

Web

Parameter	Type	Description
listener	`OrientationChangeListener`	Each orientation update will pass an object with the new `OrientationChangeEvent` to the listener.

Invokes the listener function when the screen orientation changes from portrait to landscape or from landscape to portrait. For example, it won't be invoked when screen orientation change from portrait up to portrait down, but it will be called when there was a change from portrait up to landscape left.

Returns:

EventSubscription

`ScreenOrientation.removeOrientationChangeListener(subscription)`

Android

iOS

Web

Parameter	Type	Description
subscription	`EventSubscription`	A subscription object that manages the updates passed to a listener function on an orientation change.

Unsubscribes the listener associated with the Subscription object from all orientation change updates.

Returns:

void

`ScreenOrientation.removeOrientationChangeListeners()`

Android

iOS

Web

Removes all listeners subscribed to orientation change updates.

Returns:

void

Interfaces

`Subscription`

Android

iOS

Web

A subscription object that allows to conveniently remove an event listener from the emitter.

Subscription Methods

`remove()`

Android

iOS

Web

Removes an event listener for which the subscription has been created. After calling this function, the listener will no longer receive any events from the emitter.

Returns:

void

Types

`OrientationChangeEvent`

Android

iOS

Web

Property	Type	Description
orientationInfo	`ScreenOrientationInfo`	The current `ScreenOrientationInfo` of the device.
orientationLock	`OrientationLock`	The current `OrientationLock` of the device.

`OrientationChangeListener(event)`

Android

iOS

Web

Parameter	Type
event	`OrientationChangeEvent`

Returns:

void

`PlatformOrientationInfo`

Android

iOS

Web

Property	Type	Description
screenOrientationArrayIOS(optional)	`Orientation[]`	Only for: iOS An array of orientations to allow on the iOS platform.
screenOrientationConstantAndroid(optional)	`number`	Only for: Android A constant to set using the Android native API. For example, in order to set the lock policy to unspecified, `-1` should be passed in.
screenOrientationLockWeb(optional)	`WebOrientationLock`	Only for: Web A web orientation lock to apply in the browser.

`ScreenOrientationInfo`

Android

iOS

Web

Property	Type	Description
horizontalSizeClass(optional)	`SizeClassIOS`	Only for: iOS The horizontal size class of the device.
orientation	`Orientation`	The current orientation of the device.
verticalSizeClass(optional)	`SizeClassIOS`	Only for: iOS The vertical size class of the device.

Enums

`Orientation`

Android

iOS

Web

`UNKNOWN`

Orientation.UNKNOWN ＝ 0

An unknown screen orientation. For example, the device is flat, perhaps on a table.

`PORTRAIT_UP`

Orientation.PORTRAIT_UP ＝ 1

Right-side up portrait interface orientation.

`PORTRAIT_DOWN`

Orientation.PORTRAIT_DOWN ＝ 2

Upside down portrait interface orientation.

`LANDSCAPE_LEFT`

Orientation.LANDSCAPE_LEFT ＝ 3

Left landscape interface orientation.

`LANDSCAPE_RIGHT`

Orientation.LANDSCAPE_RIGHT ＝ 4

Right landscape interface orientation.

`OrientationLock`

Android

iOS

Web

An enum whose values can be passed to the lockAsync method.

Note: OrientationLock.ALL and OrientationLock.PORTRAIT are invalid on devices which don't support OrientationLock.PORTRAIT_DOWN.

`DEFAULT`

OrientationLock.DEFAULT ＝ 0

The default orientation. On iOS, this will allow all orientations except Orientation.PORTRAIT_DOWN. On Android, this lets the system decide the best orientation.

`ALL`

OrientationLock.ALL ＝ 1

All four possible orientations

`PORTRAIT`

OrientationLock.PORTRAIT ＝ 2

Any portrait orientation.

`PORTRAIT_UP`

OrientationLock.PORTRAIT_UP ＝ 3

Right-side up portrait only.

`PORTRAIT_DOWN`

OrientationLock.PORTRAIT_DOWN ＝ 4

Upside down portrait only.

`LANDSCAPE`

OrientationLock.LANDSCAPE ＝ 5

Any landscape orientation.

`LANDSCAPE_LEFT`

OrientationLock.LANDSCAPE_LEFT ＝ 6

Left landscape only.

`LANDSCAPE_RIGHT`

OrientationLock.LANDSCAPE_RIGHT ＝ 7

Right landscape only.

`OTHER`

OrientationLock.OTHER ＝ 8

A platform specific orientation. This is not a valid policy that can be applied in lockAsync.

`UNKNOWN`

OrientationLock.UNKNOWN ＝ 9

An unknown screen orientation lock. This is not a valid policy that can be applied in lockAsync.

`SizeClassIOS`

Android

iOS

Web

Each iOS device has a default set of size classes that you can use as a guide when designing your interface.

`UNKNOWN`

SizeClassIOS.UNKNOWN ＝ 0

`COMPACT`

SizeClassIOS.COMPACT ＝ 1

`REGULAR`

SizeClassIOS.REGULAR ＝ 2

`WebOrientation`

Android

iOS

Web

`LANDSCAPE_PRIMARY`

WebOrientation.LANDSCAPE_PRIMARY ＝ "landscape-primary"

`LANDSCAPE_SECONDARY`

WebOrientation.LANDSCAPE_SECONDARY ＝ "landscape-secondary"

`PORTRAIT_PRIMARY`

WebOrientation.PORTRAIT_PRIMARY ＝ "portrait-primary"

`PORTRAIT_SECONDARY`

WebOrientation.PORTRAIT_SECONDARY ＝ "portrait-secondary"

`WebOrientationLock`

Android

iOS

Web

An enum representing the lock policies that can be applied on the web platform, modelled after the W3C specification. These values can be applied through the lockPlatformAsync method.

`ANY`

WebOrientationLock.ANY ＝ "any"

`LANDSCAPE`

WebOrientationLock.LANDSCAPE ＝ "landscape"

`LANDSCAPE_PRIMARY`

WebOrientationLock.LANDSCAPE_PRIMARY ＝ "landscape-primary"

`LANDSCAPE_SECONDARY`

WebOrientationLock.LANDSCAPE_SECONDARY ＝ "landscape-secondary"

`NATURAL`

WebOrientationLock.NATURAL ＝ "natural"

`PORTRAIT`

WebOrientationLock.PORTRAIT ＝ "portrait"

`PORTRAIT_PRIMARY`

WebOrientationLock.PORTRAIT_PRIMARY ＝ "portrait-primary"

`PORTRAIT_SECONDARY`

WebOrientationLock.PORTRAIT_SECONDARY ＝ "portrait-secondary"

`UNKNOWN`

WebOrientationLock.UNKNOWN ＝ "unknown"