@hadss/react_native_avoid_area
v1.0.0-rc.1
Published
RN framework-oriented multi-device avoid area interface package
Readme
@hadss/react_native_avoid_area
介绍
这是一个旨在解决 React Native多设备获取避让区域问题的三方库，专为不同设备类型（包括折叠屏、平板、手机等）提供了便捷的支持。该库包含的接口，使开发者能够轻松应对各种设备的布局适配需求。
- 在RN框架中获取导航条、状态栏、挖孔、刘海等避让区域。
- 在RN框架中动态获取避让区域的实时数据。
工程目录
.
├─android
│ └─src/main
│ ├─AndroidManifest.xml // 应用清单文件
│ └─java/org/hadss/avoidarea
│ ├─AvoidModule.java // RN方法实现类：提供RN方法安卓层实现
│ ├─AvoidModulePackage.java // RN Turbo库定义类
│ ├─constant
│ │ └─AvoidAreaType.java // 窗口内容需要规避区域的类型常量
│ └─utils
│ └─AvoidAreaUtils.java // 窗口规避区域工具类：提供获取规避区域的方法
├─harmony
│ ├─avoid_area.har // Turbo Modules接口har包
│ └─avoid_area/src/main/ets
│ ├─RTNAvoidAreaRegion.ets // Turbo Modules接口ArkTS实现
│ ├─AvoidModulePackage.ets // AvoidModulesFactory
│ └─AvoidModuleSpec.ts // Turbo Modules接口
├─ios
│ ├─AvoidModule.h // 桥接接口类
│ ├─AvoidModule.mm // 桥接调用类
│ ├─AWSafeAreaMonitor.h // 区域避让接口定义
│ └─AWSafeAreaMonitor.mm // 区域避让接口实现
└─src
├─index.ts // RN模块导出
└─turbo
└─NativeAvoidModule.ts // RN Turbo Modules接口安装与使用
进入到工程目录并输入以下命令：
npm
npm install @hadss/react_native_avoid_areayarn
yarn add @hadss/react_native_avoid_area使用示例
import { View, PixelRatio, Text, StyleSheet } from "@react-native-oh/react-native-harmony";
import { Avoid } from '@hadss/react_native_avoid_area/src/index';
import { useEffect, useState } from "react";
import { AvoidAreaType } from "@hadss/react_native_avoid_area/src/turbo/NativeAvoidModule";
const GamePage = () => {
const [topHeight, setTopHeight] = useState(0);
const [bottomHeight, setBottomHeight] = useState(0);
useEffect(() => {
const getAvoidArea = () => {
let type = AvoidAreaType.TYPE_SYSTEM;
let avoidArea = Avoid.getWindowAvoidArea(type);
let topHeight = avoidArea.topRect.height / PixelRatio.get();
setTopHeight(topHeight);
console.log("TYPE_SYSTEM" + JSON.stringify(topHeight));
type = AvoidAreaType.TYPE_CUTOUT;
avoidArea = Avoid.getWindowAvoidArea(type);
console.log("TYPE_CUTOUT" + JSON.stringify(avoidArea));
type = AvoidAreaType.TYPE_SYSTEM_GESTURE;
avoidArea = Avoid.getWindowAvoidArea(type);
console.log("TYPE_SYSTEM_GESTURE" + JSON.stringify(avoidArea));
type = AvoidAreaType.TYPE_KEYBOARD;
avoidArea = Avoid.getWindowAvoidArea(type);
console.log("TYPE_KEYBOARD" + JSON.stringify(avoidArea));
type = AvoidAreaType.TYPE_NAVIGATION_INDICATOR;
avoidArea = Avoid.getWindowAvoidArea(type);
let bottomHeight = avoidArea.bottomRect.height / PixelRatio.get();
setBottomHeight(bottomHeight);
console.log("TYPE_NAVIGATION_INDICATOR" + JSON.stringify(avoidArea));
};
getAvoidArea();
const area = Avoid.addAvoidAreaListener((e) => {
console.log(JSON.stringify(e));
});
return () => {
Avoid.removeAvoidAreaListener();
};
}, [])
return (
<View>
<View style={{ paddingTop: topHeight, paddingBottom: bottomHeight }}>
<View style={styles.container}>
<Text style={styles.text}>DEMO</Text>
</View>
</View>
</View>
)
}
const styles = StyleSheet.create({
container: {
width: '100%',
height: '100%',
backgroundColor: 'pink' ,
display:'flex',
justifyContent:'center',
alignSelf:'center'
},
text: {
textAlign:'center',
fontSize:20
}
});
export default GamePage;Link
本库依赖以下三方库，请查看对应文档：@react-native-oh-tpl/react-native-orientation
目前OpenHarmony暂不支持AutoLink，所以Link步骤需要手动配置。
首先需要使用DevEco Studio打开项目里的OpenHarmony工程，在工程根目录的oh-package.json5添加overrides字段：
{
"overrides": {
"@rnoh/react-native-openharmony": "./react_native_openharmony"
}
}引入原生端代码
目前有两种方法：
通过har包引入（在IDE完善相关功能后该方法会被遗弃，目前首选此方法）。
说明： har包位于三方库安装路径的
harmony文件夹下。a. 打开
entry/oh-package.json5，添加以下依赖：{ "dependencies":{ "@rnoh/react-native-openharmony": "file:../react_native_openharmony", "@hadss/react_native_avoid_area": "file:../../node_modules/@hadss/react_native_avoid_area/harmony/avoid_area.har" } }b. 配置CMakeLists和引入RNOHGeneratedPackage：
打开
entry/src/main/cpp/CMakeLists.txt，添加：project(rnapp) cmake_minimum_required(VERSION 3.4.1) set(CMAKE_SKIP_BUILD_RPATH TRUE) set(OH_MODULE_DIR "${CMAKE_CURRENT_SOURCE_DIR}/../../../oh_modules") set(RNOH_APP_DIR "${CMAKE_CURRENT_SOURCE_DIR}") set(RNOH_CPP_DIR "${OH_MODULE_DIR}/@rnoh/react-native-openharmony/src/main/cpp") set(RNOH_GENERATED_DIR "${CMAKE_CURRENT_SOURCE_DIR}/generated") 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") add_compile_definitions(WITH_HITRACE_SYSTRACE) set(WITH_HITRACE_SYSTRACE 1) # for other CMakeLists.txt files to use + file(GLOB GENERATED_CPP_FILES "./generated/*.cpp") add_subdirectory("${RNOH_CPP_DIR}" ./rn) add_library(rnoh_app SHARED + ${GENERATED_CPP_FILES} "./PackageProvider.cpp" "${RNOH_CPP_DIR}/RNOHAppNapiBridge.cpp" ) target_link_libraries(rnoh_app PUBLIC rnoh)c. 打开
entry/src/main/cpp/PackageProvider.cpp，添加：#include "RNOH/PackageProvider.h" + #include "generated/RNOHGeneratedPackage.h" using namespace rnoh; std::vector<std::shared_ptr<Package>> PackageProvider::getPackages(Package::Context ctx) { return { + std::make_shared<RNOHGeneratedPackage>(ctx) }; }d. 在ArkTs侧引入AvoidModulePackage：
打开
entry/src/main/ets/RNPackagesFactory.ts，添加：... + import { AvoidModulePackage} from '@hadss/react_native_avoid_area/ts'; export function createRNPackages(ctx: RNPackageContext): RNPackage[] { return [ + new AvoidModulePackage(ctx), ]; }e. 打开entry/src/main/ets/entryability/EntryAbility.ets,添加：
import { RNAbility } from '@rnoh/react-native-openharmony'; + import { window } from '@kit.ArkUI'; + import { WindowManager } from '@kit.SpeechKit'; export default class EntryAbility extends RNAbility { getPagePath() { return 'pages/Index'; } + async onWindowStageCreate(windowStage: window.WindowStage) { + WindowManager.setWindowStage(windowStage); + super.onWindowStageCreate(windowStage); + } }f. 运行：
点击右上角的
sync按钮或者在终端执行：
cd entry ohpm install然后编译、运行即可。
说明 若项目启动时报错：can not find record '&@rnoh/react-native-openharmony/generated/ts&X.X.X'。需在entry\oh_modules@rnoh\react-native-openharmony\ts.ts文件中添加export * from './generated/ts'，并删除.cxx文件夹、build文件夹，然后执行sync操作同步代码。
直接链接源码。
如需使用直接链接源码，请参考直接链接源码说明。
API
说明： "Platform"列表示支持的平台，All表示支持所有平台。
区域避让接口
| Name | Description | Type | Platform | |------------------------------------------------------------------------|----------------|----------|-------------------------------------------------------------------------------------| | getWindowAvoidArea(type: AvoidAreaType): AvoidArea | 获取应用窗口内容规避的区域。 | function | OpenHarmony / Android(仅支持部分窗口类型:TYPE_SYSTEM、TYPE_CUTOUT 、TYPE_NAVIGATION_INDICATOR) | | addAvoidAreaListener(cb: (avoidAreaOptions: AvoidAreaOptions) => void) | 注册系统规避区变化的监听。 | function | OpenHarmony | | removeAvoidAreaListener() | 注销系统规避区变化的监听。 | function | OpenHarmony |
AvoidAreaType 窗口类型枚举。
| 名称 | 值 | 说明 | |:--------------------------|:--|:------------------------------------------| | TYPE_SYSTEM | 0 | 表示系统默认区域。通常表示状态栏区域，悬浮窗状态下的应用主窗中表示三点控制栏区域。 | | TYPE_CUTOUT | 1 | 表示刘海屏区域。 | | TYPE_SYSTEM_GESTURE | 2 | 表示手势区域。当前，各设备均无此类型避让区域。 | | TYPE_KEYBOARD | 3 | 表示软键盘区域。 | | TYPE_NAVIGATION_INDICATOR | 4 | 表示底部导航条区域。 |
AvoidArea 窗口内容规避区域。
如系统栏区域、刘海屏区域、手势区域、软键盘区域等与窗口内容重叠时，需要窗口内容避让的区域。
| 名称 | 类型 | 说明 | |:------------|:---------|:------------------------------| | visible | boolean | 规避区域是否可见。true表示可见；false表示不可见。 | | leftRect | Rect | 屏幕左侧的矩形区。 | | topRect | Rect | 屏幕顶部的矩形区。 | | rightRect | Rect | 屏幕右侧的矩形区。 | | bottomRect | Rect | 屏幕底部的矩形区。 |
Rect 窗口矩形区域。
| 名称 | 类型 | 说明 | |:--------|:--------|:------------------------| | left | number | 矩形区域的左边界，单位为px，该参数为整数。 | | top | number | 矩形区域的上边界，单位为px，该参数应为整数。 | | width | number | 矩形区域的宽度，单位为px，该参数应为整数。 | | height | number | 矩形区域的高度，单位为px，该参数应为整数。 |
AvoidAreaOptions
系统规避区变化后返回当前规避区域以及规避区域类型。
| 名称 | 类型 | 说明 | |:------|:----------------|:-------------------| | type | AvoidAreaType | 系统规避区变化后返回的规避区域类型。 | | area | AvoidArea | 系统规避区变化后返回的规避区域。 |
约束与限制
本示例仅支持标准系统上运行，支持设备：华为手机。 DevEco Studio版本：5.0.0 Release及以上。 SDK版本：API12及以上。