‌React Native必备神器：Orientation，轻松搞定设备方向管理‌

React Native 中，设备方向（横屏/竖屏）切换往往会影响布局与用户体验。借助开源社区的 Orientation（或更常用的 “react-native-orientation-locker”） 库，我们可以轻松检测、锁定、解锁和响应方向变化。本文以“React Native 必备神器：Orientation，轻松搞定设备方向管理”为题，详细介绍安装、API、示例代码与实战场景，并配合图解，帮助你快速上手。

一、为什么需要方向管理

1. 不同页面对横竖屏要求不同

   • 视频播放器、游戏等通常需要 横屏；
   • 新闻详情、文章列表常用 竖屏；
   • 一个应用中多个界面流畅切换时，需要动态锁定或解锁方向。

2. 响应式布局优化

   • 当用户从竖屏切换到横屏时，布局需要重新计算（如两列变三列、图片宽度拉满屏幕等）；
   • 如果不关注方向变化，UI 会出现重叠、撑破屏幕、拉伸失真等问题。

3. 导航栈与方向冲突

   • React Navigation 等导航库本身并不直接管理设备方向，需要手动结合方向锁定逻辑；
   • 如果切换页面时忘记解除锁定，可能导致用户无法切换回默认方向。

思考题：如果你在一个横屏游戏界面深度点击“返回”到一个竖屏列表页，但页面却依然保持横屏，这会严重影响用户体验——这是因为没有正确“解锁”方向。
理想流程：

进入游戏界面 → 锁定为横屏  
用户点击返回 → 自动切换回竖屏  
再次进入其他界面 → 根据需求决定是否横屏或竖屏  

二、库选型与安装

目前社区中常用来管理方向的库有两个：

1. react-native-orientation（早期）
2. react-native-orientation-locker（维护更活跃，支持更多新特性）

本文以 react-native-orientation-locker 为主；若你坚持使用原版 react-native-orientation，API 基本一致，只需替换包名即可。

2.1 安装

1. 使用 Yarn

yarn add react-native-orientation-locker

2. 使用 npm

npm install react-native-orientation-locker --save

3. iOS 原生配置（RN 0.60+ Autolinking 自动链接）

• 进入 iOS 目录：cd ios && pod install && cd ..
• 打开 Xcode → 目标项目 → Info.plist → 添加允许的方向配置（详见下文）。

注意：如果你的项目原本只勾选了 Portrait，但后续想支持 Landscape，就必须在 Info.plist 中将对应方向打开，否则锁定逻辑无法生效。

三、Info.plist 与 AndroidManifest.xml 配置

3.1 iOS (Info.plist)

在 Xcode 中选择项目 Target → “General” → Deployment Info → Device Orientation，勾选需要支持的方向（如下图所示）：

[✔︎] Portrait
[✔︎] Upside Down          ← （通常 iPhone 不需要）
[✔︎] Landscape Left
[✔︎] Landscape Right

图解：Info.plist 中的方向选项

--------------------------------
| Deployment Info             |
| --------------------------- |
| Device Orientation          |
| [✓] Portrait                |
| [ ] Upside Down             |
| [✓] Landscape Left          |
| [✓] Landscape Right         |
--------------------------------

若你只想在某些页面支持横屏，其他页面只竖屏，也需要确保这里至少勾选了所有可能的方向；后续通过代码动态 Lock（锁定）/Unlock（解锁） 达到切换效果。若这里只勾选了 Portrait，则无论如何锁定方向，应用也无法切换到 Landscape。

3.2 Android (AndroidManifest.xml)

默认情况下，Android 已支持横竖屏，只需在特定 Activity 里手动修改 android:screenOrientation。不过使用 react-native-orientation-locker 时，一般不需手动改动 AndroidManifest.xml，库内部会帮助动态切换。
但如果你想全局默认只支持竖屏，在 AndroidManifest.xml 中可以在 <activity> 标签里添加：

<activity
    android:name=".MainActivity"
    android:screenOrientation="portrait"
    ...
>

这样主 Activity 会锁定竖屏；当在代码中调用 Orientation.lockToLandscape() 时，会动态解除并切换到横屏。只要 screenOrientation="fullSensor" 或 unspecified，库才能自由切换；若你将其设为固定值，会导致库无效。因此推荐保留默认 unspecified，或在需要时进行局部控制，再用代码锁定。

四、基础用法与 API 详解

安装完成后，我们在项目中导入 react-native-orientation-locker，并结合 React Native 组件或 Hook 来使用。下面先罗列常用 API，再结合示例代码演示。

4.1 常用 API

import Orientation, {
  PORTRAIT,
  LANDSCAPE,
  LANDSCAPE_LEFT,
  LANDSCAPE_RIGHT,
  DEFAULT,
  useDeviceOrientation,
  useLockOrientation,
} from 'react-native-orientation-locker';

1. 锁定方向

• Orientation.lockToPortrait() → 锁定为竖屏（竖直方向）
• Orientation.lockToLandscape() → 锁定为横屏（自动选择左右，跟随传感器）
• Orientation.lockToLandscapeLeft() → 强制向左横屏
• Orientation.lockToLandscapeRight() → 强制向右横屏
• Orientation.unlockAllOrientations() → 解除锁定，允许随系统方向旋转

2. 获取当前方向

• Orientation.getDeviceOrientation(callback)

  • 回调 callback(orientation)，orientation 为字符串，可能值：

    • 'PORTRAIT'、'LANDSCAPE-LEFT'、'LANDSCAPE-RIGHT'、'PORTRAIT-UPSIDEDOWN'、'UNKNOWN'。

3. 监听方向变化

• Orientation.addDeviceOrientationListener(callback)

  • 当设备方向改变时触发回调，参数同上；

• Orientation.removeDeviceOrientationListener(callback)

  • 移除监听，参数为之前注册的 callback 函数。

4. Hook 封装（函数组件推荐）

• const deviceOrientation = useDeviceOrientation();

  • 返回一个对象 { portrait, landscape, portraitUpsideDown, lock, ... } 等布尔值，表示当前方向。

• const lockOrientation = useLockOrientation();

  • 返回一个函数 lockOrientation(orientationString)，可传入 'PORTRAIT' | 'LANDSCAPE-LEFT' | 'LANDSCAPE-RIGHT' | 'DEFAULT' 等。

4.2 完整示例：监测 + 锁定 + 解锁

下面示例会在页面顶部显示当前方向（文字提示），下方有四个按钮，分别演示锁定竖屏、锁定横屏、解除锁定、获取当前方向。

// OrientationDemo.js
import React, { useEffect, useState } from 'react';
import {
  View,
  Text,
  Button,
  StyleSheet,
  SafeAreaView,
  Platform,
} from 'react-native';
import Orientation, {
  useDeviceOrientation,
} from 'react-native-orientation-locker';

export default function OrientationDemo() {
  // 1. 使用 Hook 获取当前设备方向状态
  const deviceOrientation = useDeviceOrientation();
  // deviceOrientation 对象结构示例：
  // {
  //   orientation: 'PORTRAIT' | 'LANDSCAPE-LEFT' | ...,
  //   portrait: true|false,
  //   landscape: true|false,
  //   portraitUpsideDown: true|false,
  //   lock: true|false, // 是否已被手动锁定
  // }

  // 2. 本地 state 保存文字提示
  const [current, setCurrent] = useState('UNKNOWN');

  useEffect(() => {
    // 当 deviceOrientation.orientation 改变时，更新文字
    setCurrent(deviceOrientation.orientation);
  }, [deviceOrientation.orientation]);

  // 3. 按钮处理函数
  const lockPortrait = () => {
    Orientation.lockToPortrait();
  };
  const lockLandscape = () => {
    Orientation.lockToLandscape();
  };
  const unlock = () => {
    Orientation.unlockAllOrientations();
  };
  const showCurrent = () => {
    Orientation.getDeviceOrientation(ori => {
      alert('当前方向：' + ori);
    });
  };

  return (
    <SafeAreaView style={styles.container}>
      <Text style={styles.title}>React Native 方向管理示例</Text>
      <Text style={styles.info}>
        当前方向：{current} {'\n'}
        锁定状态：{deviceOrientation.lock ? '已锁定' : '未锁定'}
      </Text>

      <View style={styles.buttonRow}>
        <Button title="锁定竖屏" onPress={lockPortrait} />
        <Button title="锁定横屏" onPress={lockLandscape} />
      </View>
      <View style={styles.buttonRow}>
        <Button title="解除锁定" onPress={unlock} />
        <Button title="显示当前方向" onPress={showCurrent} />
      </View>

      <Text style={styles.hint}>
        ※ 在 iOS 模拟器中，⌘+←/→ 可以手动切换方向；Android 模拟器顶部虚拟按键也可切换。
      </Text>
    </SafeAreaView>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    padding: 16,
    backgroundColor: '#FFF',
  },
  title: {
    fontSize: 20,
    fontWeight: 'bold',
    marginBottom: 16,
  },
  info: {
    fontSize: 16,
    marginBottom: 24,
  },
  buttonRow: {
    flexDirection: 'row',
    justifyContent: 'space-around',
    marginBottom: 16,
  },
  hint: {
    marginTop: 32,
    fontSize: 12,
    color: '#666',
  },
});

4.2.1 关键点说明

1. useDeviceOrientation Hook

   • 自动监听方向变化并返回一个对象，包含：

     • orientation（字符串）
     • portrait、landscape、portraitUpsideDown（布尔）
     • lock（是否锁定）
   • 使用 orientation 作为文字提示显示给用户。

2. Orientation.lockToPortrait() / Orientation.lockToLandscape()

   • 即时锁定当前页面为竖屏或横屏；无需重启页面。

3. Orientation.unlockAllOrientations()

   • 解除锁定，允许页面随系统方向变化（如手机旋转或模拟器快捷键切换）。

4. Orientation.getDeviceOrientation(callback)

   • 弹出 Alert 或用于日志，回调返回当前方向字符串。

5. Platform 差异

   • 在 iOS 模拟器，按 ⌘ + ←/→ 可切换横竖屏；
   • 在 Android 模拟器，可点击顶部按钮或执行快捷键 Ctrl + F11/F12。

五、图解：方向监听与切换流程

为了帮助理解，下面用一张简化的流程图说明“方向变化监听与锁定/解锁”机制。

┌────────────────────────────────────────────────────────────────┐
│                        启动 App / 进入页面                     │
└────────────────────────────────────────────────────────────────┘
                     │
                     ▼
┌────────────────────────────────────────────────────────────────┐
│ useDeviceOrientation Hook 启动，自动调用 addListener =>      │
│ 倾听 deviceOrientation.orientation，保留在内存中              │
└────────────────────────────────────────────────────────────────┘
                     │
                     ▼
┌────────────────────────────────────────────────────────────────┐
│ 普通情况下：用户旋转设备 / 模拟器快捷键                         │
│ 触发系统方向变化事件                                             │
│   └─ Native 层捕获新方向                                         │
│   └─ 通过 NativeModule 通知 JS 层                                 │
│   └─ useDeviceOrientation 更新 orientation、portrait 等字段        │
│   └─ React 重新渲染并更新 UI                                      │
└────────────────────────────────────────────────────────────────┘
                     │
      ┌──────────────┴───────────────┐
      │                              │
      ▼                              ▼
┌───────────────┐            ┌───────────────┐
│ 锁定方向      │            │ 未锁定方向    │
│ (lockToXXX)   │            │ (unlockAll)   │
│               │            │               │
│ JS 调用        │            │ JS 调用        │
│ Orientation   │            │ Orientation   │
│ lockToXXXX()  │            │ unlockAll()   │
└───────────────┘            └───────────────┘
      │                              │
      │                              │
      │                              │
      │      ┌────────────────────────────────────────┐
      │       │ 解锁后可随系统方向变化（与上方“普通情况”一致）     │
      │       └────────────────────────────────────────┘
      │
      ▼
┌────────────────────────────────────────────────────────────────┐
│ 锁定后：Native 层立即强制切换到对应方向  (如 Portrait/Landscape) │
│   └─ JS 层收到一次 orientation 更新                             │
│   └─ React 渲染基于锁定方向的布局                                 │
│   └─ 之后系统旋转输入将被忽略  (continue to lock)                │
└────────────────────────────────────────────────────────────────┘

图解说明：

1. 未锁定状态：任何系统方向变化（旋转、快捷键）都会通知 JS，并更新 UI；
2. 锁定状态：一旦调用 lockToPortrait() 或 lockToLandscape()，JS 会调用 Native 将设备方向强制切换到指定方向，并忽略后续系统旋转事件；
3. 解锁后：再一次调用 unlockAllOrientations() 后，恢复对系统旋转的正常监听。

六、实战场景：横屏视频播放 & 列表竖屏切换

下面给出一个典型的实战场景：在一个页面中有竖屏列表，点击某个条目后跳转到横屏视频播放页，播放完成或点击“返回”后，自动切换回竖屏列表。

6.1 目录结构示例

src/
├─ screens/
│   ├─ VideoListScreen.js        ← 竖屏列表页
│   └─ VideoPlayerScreen.js      ← 横屏播放页
└─ App.js                        ← 根导航

6.2 VideoListScreen.js（竖屏模式）

// VideoListScreen.js
import React, { useEffect } from 'react';
import { View, Text, FlatList, TouchableOpacity, StyleSheet } from 'react-native';
import Orientation from 'react-native-orientation-locker';

export default function VideoListScreen({ navigation }) {
  useEffect(() => {
    // 进入列表页，锁定竖屏
    Orientation.lockToPortrait();
    return () => {
      // 可选：离开页面时解除锁定
      // Orientation.unlockAllOrientations();
    };
  }, []);

  const videos = [
    { id: '1', title: 'React Native 入门教程' },
    { id: '2', title: 'Animated 深度解析' },
    { id: '3', title: 'RN 性能优化技巧' },
  ];

  return (
    <View style={styles.container}>
      <Text style={styles.title}>视频列表（竖屏）</Text>
      <FlatList
        data={videos}
        keyExtractor={(item) => item.id}
        renderItem={({ item }) => (
          <TouchableOpacity
            style={styles.item}
            onPress={() => navigation.navigate('VideoPlayer', { videoId: item.id })}
          >
            <Text style={styles.itemText}>{item.title}</Text>
          </TouchableOpacity>
        )}
      />
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1, padding: 16, backgroundColor: '#FAFAFA' },
  title: { fontSize: 20, fontWeight: 'bold', marginBottom: 12 },
  item: {
    paddingVertical: 12,
    borderBottomWidth: 1,
    borderBottomColor: '#DDD',
  },
  itemText: { fontSize: 16 },
});

6.2.1 说明

• 在 useEffect 中调用 Orientation.lockToPortrait()，确保列表页始终保持竖屏；
• 点击列表项导航到播放页时，不需要立即解除锁定；由播放页决定。
• 如果你希望在离开列表页时解除锁定，也可以在 return 回调里调用 Orientation.unlockAllOrientations()，但注意如果同时在播放页也调用，会产生重复调用。

6.3 VideoPlayerScreen.js（横屏模式）

// VideoPlayerScreen.js
import React, { useEffect } from 'react';
import { View, Text, TouchableOpacity, StyleSheet, Platform } from 'react-native';
import Orientation from 'react-native-orientation-locker';

export default function VideoPlayerScreen({ route, navigation }) {
  useEffect(() => {
    // 进入播放页时，锁定横屏
    if (Platform.OS === 'ios') {
      Orientation.lockToLandscapeLeft(); // iOS 建议使用具体方向
    } else {
      Orientation.lockToLandscape(); // Android 可直接锁横屏
    }

    return () => {
      // 离开播放页时，切换回竖屏
      Orientation.lockToPortrait();
    };
  }, []);

  return (
    <View style={styles.container}>
      <Text style={styles.text}>正在播放视频 ID: {route.params.videoId}</Text>
      {/* 这里通常放 Video 组件，全屏播放 */}
      <TouchableOpacity
        style={styles.backBtn}
        onPress={() => navigation.goBack()}
      >
        <Text style={styles.backText}>退出播放</Text>
      </TouchableOpacity>
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    backgroundColor: '#000',
    justifyContent: 'center',
    alignItems: 'center',
  },
  text: { color: '#FFF', fontSize: 18, marginBottom: 20 },
  backBtn: {
    position: 'absolute',
    top: 40,
    left: 20,
    padding: 8,
    backgroundColor: '#FFF',
    borderRadius: 4,
  },
  backText: { color: '#000', fontSize: 14 },
});

6.3.1 说明

1. 横屏锁定

   • 在 iOS 上建议调用 Orientation.lockToLandscapeLeft() 或 Orientation.lockToLandscapeRight()，这样横屏方向更可控；
   • 在 Android 上直接调用 Orientation.lockToLandscape() 即可；

2. 播放完成或点击返回

   • 当用户导航回列表页时（navigation.goBack()），useEffect 的清理函数自动执行 Orientation.lockToPortrait()；
   • 列表页会再次锁定竖屏或遵循全局默认方向。

3. 注意返回动画时机

   • 如果你想在页面真正退出之前（监听 beforeRemove）就先锁回竖屏，可在导航钩子里先调用，避免短暂横屏闪烁。

七、进阶场景与常见问题

7.1 在模态弹窗中也要锁定方向

如果你的播放页是以模态形式出现（如 React Navigation 的 Modal），页面依旧可以像普通页面那样调用 Orientation.lockToLandscape()。只要顶部 Activity/UIViewController 置为支持横屏即可，库会生效。

7.2 与 React Navigation 结合：监听焦点事件

如果你使用 React Navigation，可以在页面获得焦点/失去焦点时再调用锁定/解锁，而不必在 useEffect 里写死。例如：

import { useFocusEffect } from '@react-navigation/native';

useFocusEffect(
  React.useCallback(() => {
    // 页面聚焦时锁定横屏
    Orientation.lockToLandscape();

    return () => {
      // 页面失焦时锁定竖屏
      Orientation.lockToPortrait();
    };
  }, [])
);

此时，当页面被隐藏时，不会立即切换方向，只有在下一个页面获得焦点时才会执行清理函数，减少闪烁。

7.3 监听原生方向改变

你还可以通过 Orientation.addDeviceOrientationListener 监听原生方向变化。例如，在一个仪表盘页面，你想根据横竖屏切换动态调整 UI 布局，可这样写：

useEffect(() => {
  const callback = (orientation) => {
    console.log('设备方向变更为：', orientation);
    // 根据 orientation 判断是否 horizontal/vertical，再 setState 或 set 布局
  };
  Orientation.addDeviceOrientationListener(callback);

  return () => {
    Orientation.removeDeviceOrientationListener(callback);
  };
}, []);

• 当设备从竖屏变横屏时，orientation 会被回调为 'LANDSCAPE-LEFT' 或 'LANDSCAPE-RIGHT'；
• 你可以在回调内处理如 this.setState({ isLandscape: true })，然后在渲染中做条件布局（如 Grid → List 切换）。

7.4 获取默认方向 & 解锁边界

• Orientation.getAutoRotateState(callback)

  • 回调会返回两个布尔：autoRotate、locked，表示系统是否允许自动旋转；
  • 如果 locked===true 且 autoRotate===false，说明用户在系统设置里关闭了自动旋转，任何代码锁定都无法生效。

• 解锁后默认为哪个方向？

  • 调用 unlockAllOrientations() 后，会恢复系统默认方向（即由系统决定传感器方向）。如果你想保证一定是竖屏，可以直接调用 lockToPortrait() 而不是解锁。

八、小结与最佳实践

1. 务必在 Info.plist / AndroidManifest.xml 中允许目标方向，否则后续锁定逻辑会失效。
2. 优先使用 useLockOrientation 或 useDeviceOrientation 等 Hook，使代码更简洁、可读性更高，并自动在组件卸载时移除监听。
3. 页面切换时结合 React Navigation 的 useFocusEffect，在获得焦点时锁定方向，失去焦点时解锁或切换，减少闪烁和“错位”体验。
4. 避免连续反复锁定/解锁，如果同一个页面内多次调用，会导致 UI 重绘开销；建议在一次 useEffect 或 useFocusEffect 中完成。
5. 考虑用户系统设置：如果系统设置了“锁定屏幕方向（autoRotate）”，则代码无法改变，因此可在上层提示用户开启自动旋转。

6. 不同平台差异：

   • iOS 上可精确指定 lockToLandscapeLeft() 或 Right；
   • Android 上只能 lockToLandscape()，不区分左右。

通过本文，相信你已经掌握了如何在 React Native 中使用 Orientation（或 react-native-orientation-locker）轻松搞定设备方向的监听、锁定与解锁，完成跨页面的横/竖屏切换，让应用在视频播放、游戏、仪表盘、图表分析等场景下，实现更加优雅的体验。