Expo ScreenOrientation

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

Android

iOS

Web

Included in Expo Go

GitHub

npm

更新日志

Bundled version:

~55.0.0

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

在 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 官方文档。

应用配置中的配置

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

Deprecated: this function will be removed in a future version. Use subscription.remove() instead.

`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

Deprecated: this function will be removed in future versions. Keep track of your own subscriptions.

`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"