文档模板：v0.4.2

react-native-orientation-locker

本项目基于 react-native-orientation-locker 开发。

该第三方库的仓库已迁移至 Gitcode，并支持直接从 npm 下载，新包名为：@react-native-ohos/react-native-orientation-locker。版本归属关系如下：

简介

react-native-orientation-locker 是一款 React Native 库，可监听设备方向变化、获取当前屏幕方向，并将屏幕锁定至首选方向。

下载安装

进入工程目录，并输入以下命令：

npm

npm install @react-native-ohos/react-native-orientation-locker

yarn

yarn add @react-native-ohos/react-native-orientation-locker

链接

使用 AutoLink 的工程需按照该文档进行配置，AutoLink 框架指导文档：https://gitcode.com/CPF-RN/ohos_react_native/blob/master/docs/zh-cn/Autolinking.md

如果您使用的版本支持 AutoLink，并且工程已接入 AutoLink，可跳过 ManualLink 配置。

{
  "overrides": {
    "@rnoh/react-native-openharmony": "^0.84.30" // ohpm 在线版本
    // "@rnoh/react-native-openharmony" : "./react_native_openharmony.har" // 指向本地 har 包的路径
    // "@rnoh/react-native-openharmony" : "./react_native_openharmony" // 指向源码路径
  }
}

"dependencies": {
  "@react-native-ohos/react-native-orientation-locker":"file:../../node_modules/@react-native-ohos/react-native-orientation-locker/harmony/orientation_locker.har"
}

cd entry
ohpm install

project(rnapp)
cmake_minimum_required(VERSION 3.4.1)
set(CMAKE_SKIP_BUILD_RPATH TRUE)
set(RNOH_APP_DIR "${CMAKE_CURRENT_SOURCE_DIR}")
set(NODE_MODULES "${CMAKE_CURRENT_SOURCE_DIR}/../../../../../node_modules")
+ set(OH_MODULES "${CMAKE_CURRENT_SOURCE_DIR}/../../../oh_modules")
set(RNOH_CPP_DIR "${CMAKE_CURRENT_SOURCE_DIR}/../../../../../../react-native-harmony/harmony/cpp")
set(LOG_VERBOSITY_LEVEL 1)
set(CMAKE_ASM_FLAGS "-Wno-error=unused-command-line-argument -Qunused-arguments")
set(CMAKE_CXX_FLAGS "-fstack-protector-strong -Wl,-z,relro,-z,now,-z,noexecstack -s -fPIE -pie")
set(WITH_HITRACE_SYSTRACE 1) # for other CMakeLists.txt files to use
add_compile_definitions(WITH_HITRACE_SYSTRACE)

add_subdirectory("${RNOH_CPP_DIR}" ./rn)

# RNOH_BEGIN: manual_package_linking_1
add_subdirectory("../../../../sample_package/src/main/cpp" ./sample-package)
+ add_subdirectory("${OH_MODULES}/@react-native-ohos/react-native-orientation-locker/src/main/cpp" ./orientation_locker)
# RNOH_END: manual_package_linking_1

file(GLOB GENERATED_CPP_FILES "./generated/*.cpp")

add_library(rnoh_app SHARED
    ${GENERATED_CPP_FILES}
    "./PackageProvider.cpp"
    "${RNOH_CPP_DIR}/RNOHAppNapiBridge.cpp"
)
target_link_libraries(rnoh_app PUBLIC rnoh)

# RNOH_BEGIN: manual_package_linking_2
target_link_libraries(rnoh_app PUBLIC rnoh_sample_package)
+ target_link_libraries(rnoh_app PUBLIC rnoh_orientation_locker)
# RNOH_END: manual_package_linking_2

#include "RNOH/PackageProvider.h"
#include "SamplePackage.h"
+ #include "OrientationLockerPackage.h"

using namespace rnoh;

std::vector<std::shared_ptr<Package>> PackageProvider::getPackages(Package::Context ctx) {
    return {
      std::make_shared<SamplePackage>(ctx),
+     std::make_shared<OrientationLockerPackage>(ctx),
    };
}

  ...
+ import { RNOrientationLockerPackage } from '@react-native-ohos/react-native-orientation-locker/ts';

export function createRNPackages(ctx: RNPackageContext): RNPackage[] {
  return [
+    new RNOrientationLockerPackage(ctx)
  ];
}

运行

点击右上角的 sync 按钮

或者在命令行终端中执行：

cd entry
ohpm install

然后进行编译并运行即可。

约束与限制

兼容性

本文档内容已在以下版本中验证通过：

1. RNOH: 0.82.1；SDK: HarmonyOS 6.0.1 Release SDK；IDE: DevEco Studio 6.0.1 Release；ROM: 6.0.0.328 SP52；
2. RNOH: 0.84.30；SDK: HarmonyOS 6.0.1 Release SDK；IDE: DevEco Studio 6.0.1 Release；ROM: 6.0.0.328 SP52；

权限要求

由于该库需要获取加速度传感器数据，使用时需配置相应权限，请在 entry/src/main 目录下的 module.json5 文件中添加如下权限：

...
"requestPermissions": [
...
+      {
+        "name": "ohos.permission.ACCELEROMETER"
+       }
    ]

使用示例

以下代码展示了该库的基本使用场景：

import React, { useState } from "react";
import { View, Text, TouchableOpacity } from "react-native";
import Orientation from "react-native-orientation-locker";

const App = () => {
  const [orientation, setOrientation] = useState("");

  const getOrientation = () => {
    Orientation.getOrientation((ori) => setOrientation(ori));
  };

  return (
    <View style={{ flex: 1 }}>
      <Text>当前方向: {orientation}</Text>
      <TouchableOpacity onPress={() => Orientation.lockToPortrait()}>
        <Text>锁定竖屏</Text>
      </TouchableOpacity>
      <TouchableOpacity onPress={() => Orientation.lockToLandscape()}>
        <Text>锁定横屏</Text>
      </TouchableOpacity>
      <TouchableOpacity onPress={() => Orientation.unlockAllOrientations()}>
        <Text>解锁旋转</Text>
      </TouchableOpacity>
      <TouchableOpacity onPress={getOrientation}>
        <Text>获取当前方向</Text>
      </TouchableOpacity>
    </View>
  );
};

export default App;

使用说明

基本用法

import Orientation from 'react-native-orientation-locker';

// 锁定为竖屏
Orientation.lockToPortrait();

// 锁定为横屏
Orientation.lockToLandscape();

// 解锁，允许自由旋转
Orientation.unlockAllOrientations();

// 获取当前 UI 方向（回调）
Orientation.getOrientation((orientation) => {
  console.log('当前方向:', orientation);
});

// 判断当前是否已锁定
const locked = Orientation.isLocked();

Hooks 用法

import React from 'react';
import {
  useOrientationChange,
  useDeviceOrientationChange,
  useLockListener,
} from 'react-native-orientation-locker';

const App = () => {
  useOrientationChange((orientation) => {
    console.log('UI 方向变化:', orientation);
  });
  useDeviceOrientationChange((deviceOrientation) => {
    console.log('设备物理方向变化:', deviceOrientation);
  });
  useLockListener((orientation) => {
    console.log('锁定状态变化:', orientation);
  });
  return <Text>方向监听示例</Text>;
};

事件监听

import React from 'react';
import Orientation from 'react-native-orientation-locker';

const App = () => {
  React.useEffect(() => {
    const listener = (orientation) => {
      console.log('UI 方向变化:', orientation);
    };
    Orientation.addOrientationListener(listener);
    return () => {
      Orientation.removeOrientationListener(listener);
    };
  }, []);

  return <Text>方向监听示例</Text>;
};

接口说明

API

事件

Hooks

组件

OrientationLocker

声明式方向锁定组件，通过 props 控制屏幕方向锁定。

遗留问题

其他

无

目录结构

/rntpc_react-native-orientation-locker  # 项目根目录
├── harmony                     # 鸿蒙适配代码
│    ├── orientation_locker.har # har 包
│    └── orientation_locker     # 鸿蒙适配核心代码
│          ├── Index.ets        # 鸿蒙适配代码入口
│          └── src/main
│              ├── cpp          # C++ 原生模块
│              │    └── OrientationLockerPackage.h
│              └── ets          # ArkTS 代码
│                   ├── RNOrientationLockerPackage.ets    # 包注册
│                   ├── RNOrientationLockerTurboModule.ts # 原生模块实现
│                   └── generated                          # 生成的 TurboModule 代码
├── src                         # RN 代码
│    ├── orientation.js         # 方向监听/锁定核心逻辑
│    ├── orientation.harmony.js # 鸿蒙平台实现
│    ├── orientation.android.js # Android 平台实现
│    ├── orientation.ios.js     # iOS 平台实现
│    ├── OrientationLocker.js   # 声明式方向锁定组件
│    └── hooks                  # Hooks 实现
│         ├── index.js
│         ├── useOrientationChange.js
│         ├── useDeviceOrientationChange.js
│         └── useLockListener.js
├── index.js                    # 入口文件
├── index.d.ts                  # 类型定义
├── README_en.md                # 英文文档
└── README.md                   # 中文文档

贡献代码

在使用过程中发现任何问题，都可以提交 Issue，同时也欢迎提交 PR 。

开源协议

本项目基于 The MIT License (MIT) ，欢迎自由使用与参与开源。