用于管理设备屏幕方向的通用库。
屏幕方向定义为在设备上绘制图形的方向。例如,下图有一个设备处于垂直和水平物理方向,但屏幕方向为纵向。有关物理设备方向,请参阅 设备运动 的方向部分。
¥Screen Orientation is defined as the orientation in which graphics are painted on the device. For example, the figure below has a device in a vertical and horizontal physical orientation, but a portrait screen orientation. For physical device orientation, see the orientation section of Device Motion.
在 Android 和 iOS 平台上,屏幕方向的更改将覆盖任何系统设置或用户首选项。在 Android 上,可以在考虑用户首选方向的同时更改屏幕方向。在 iOS 上,应用无法访问用户和系统设置,并且对屏幕方向的任何更改都将覆盖现有设置。
¥On both Android and iOS platforms, changes to the screen orientation will override any system settings or user preferences. On Android, it is possible to change the screen orientation while taking the user's preferred orientation into account. On iOS, user and system settings are not accessible by the application and any changes to the screen orientation will override existing settings.
Web 有 有限的支持。
¥Web has limited support.
¥Installation
-
npx expo install expo-screen-orientation
If you are installing this in an existing React Native app (bare workflow), start by installing expo
in your project. Then, follow the additional instructions as mentioned by library's README under "Installation in bare React Native projects" section.
¥Warning
Apple 在 iOS 9 中为 iPad 添加了对分割视图模式的支持。这改变了系统处理屏幕方向的方式。简而言之,对于 iOS,你的 iPad 始终处于横向模式,除非你并排打开两个应用。为了能够使用此模块锁定屏幕方向,你需要禁用对此功能的支持。有关分割视图模式的更多信息,请查看 苹果官方文档。
¥Apple added support for split view mode to iPads in iOS 9. This changed how the screen orientation is handled by the system. To put the matter shortly, for iOS, your iPad is always in landscape mode unless you open two applications side by side. To be able to lock screen orientation using this module you will need to disable support for this feature. For more information about the split view mode, check out the official Apple documentation.
¥Configuration in app.json/app.config.js
如果你在项目中使用配置插件(EAS 构建 或 npx expo run:[android|ios]
),则可以使用其内置的 配置插件 配置 expo-screen-orientation
。该插件允许你配置无法在运行时设置的各种属性,并且需要构建新的应用二进制文件才能生效。
¥You can configure expo-screen-orientation
using its built-in config plugin if you use config plugins in your project (EAS Build or npx expo run:[android|ios]
). The plugin allows you to configure various properties that cannot be set at runtime and require building a new app binary to take effect.
使用 xed ios
打开 Xcode 中的 ios 目录。如果你没有目录,请运行 npx expo prebuild -p ios
来生成一个。
¥Open the ios directory in Xcode with xed ios
. If you don't have the directory, run npx expo prebuild -p ios
to generate one.
在 Xcode 中勾选 Requires Full Screen
复选框。它应该位于项目目标 > 常规 > 部署信息下。
¥Tick the Requires Full Screen
checkbox in Xcode. It should be located under Project Target > General > Deployment Info.
{
"expo": {
"ios": {
"requireFullScreen": true
},
"plugins": [
[
"expo-screen-orientation",
{
"initialOrientation": "DEFAULT"
}
]
]
}
}
Name | Default | Description |
---|---|---|
initialOrientation | undefined | Only for: iOS Sets the iOS initial screen orientation. Possible values: |
import * as ScreenOrientation from 'expo-screen-orientation';
ScreenOrientation.getOrientationAsync()
Gets the current screen orientation.
Returns a promise that fulfils with an Orientation
value that reflects the current screen orientation.
ScreenOrientation.getOrientationLockAsync()
Gets the current screen orientation lock type.
Returns a promise which fulfils with an OrientationLock
value.
ScreenOrientation.getPlatformOrientationLockAsync()
Gets the platform specific screen orientation lock type.
Returns a promise which fulfils with a PlatformOrientationInfo
value.
ScreenOrientation.lockAsync(orientationLock)
Name | Type | Description |
---|---|---|
orientationLock | OrientationLock | The orientation lock to apply. See the |
Lock the screen orientation to a particular OrientationLock
.
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)
Name | Type | Description |
---|---|---|
options | PlatformOrientationInfo | The platform specific lock to apply. See the |
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)
Name | Type |
---|---|
orientationLock | OrientationLock |
Returns whether the OrientationLock
policy is supported on
the device.
Promise<boolean>
Returns a promise that resolves to a boolean
value that reflects whether or not the
orientationLock is supported.
ScreenOrientation.unlockAsync()
Sets the screen orientation back to the OrientationLock.DEFAULT
policy.
Promise<void>
Returns a promise with void
value, which fulfils when the orientation is set.
ScreenOrientation.addOrientationChangeListener(listener)
Name | Type | Description |
---|---|---|
listener | OrientationChangeListener | Each orientation update will pass an object with the new |
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
.
ScreenOrientation.removeOrientationChangeListener(subscription)
Name | Type | Description |
---|---|---|
subscription | Subscription | 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.
void
ScreenOrientation.removeOrientationChangeListeners()
Removes all listeners subscribed to orientation change updates.
void
OrientationChangeEvent
Name | Type | Description |
---|---|---|
orientationInfo | ScreenOrientationInfo | The current |
orientationLock | OrientationLock | The current |
OrientationChangeListener()
Name | Type |
---|---|
event | OrientationChangeEvent |
PlatformOrientationInfo
Name | 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,
|
screenOrientationLockWeb (optional) | WebOrientationLock | Only for: Web A web orientation lock to apply in the browser. |
ScreenOrientationInfo
Name | 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. |
Subscription
Name | Type | Description |
---|---|---|
remove | () => void | A method to unsubscribe the listener. |
Orientation
Orientation Values
UNKNOWN
Orientation.UNKNOWN = 0
An unknown screen orientation. For example, the device is flat, perhaps on a table.
OrientationLock
An enum whose values can be passed to the lockAsync
method.
Note:
OrientationLock.ALL
andOrientationLock.PORTRAIT
are invalid on devices which don't supportOrientationLock.PORTRAIT_DOWN
.
OrientationLock Values
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.
SizeClassIOS
Each iOS device has a default set of size classes that you can use as a guide when designing your interface.
SizeClassIOS Values
UNKNOWN
SizeClassIOS.UNKNOWN = 0
COMPACT
SizeClassIOS.COMPACT = 1
REGULAR
SizeClassIOS.REGULAR = 2
WebOrientation
WebOrientation Values
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
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.
WebOrientationLock Values
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"