@react-native-ohos/react-native-safe-area-context

v5.6.4

Published

2 days ago

A flexible way to handle safe area, also works on Android and web.

Downloads

1,180

文档模板：v0.4.2

本项目基于 react-native-safe-area-context 开发。

该第三方库的仓库已迁移至 Gitcode，且支持直接从 npm 下载，新的包名为：@react-native-ohos/react-native-safe-area-context 版本所属关系如下：

| 三方库名称 | 三方库版本（npm地址） | 发布信息 | 支持RN版本 | Autolink | 编译API版本 | 社区基线版本 | 源码地址 | | ------------ | ------------ | ------------------------------ | ------------- | ------------- |------------------------ | ------------- | ------------- | | @react-native-ohos/react-native-safe-area-context | ~ 5.6.3 | Gitcode Releases | 0.82.* | 否 | API12+ | 5.6.2 | br_rnoh0.82 | | @react-native-ohos/react-native-safe-area-context | ~ 5.1.1 | Gitcode Releases | 0.77.* | 否 | API12+ | 5.1.0 | br_rnoh0.77 | | @react-native-ohos/react-native-safe-area-context | ~ 4.7.5 | Gitcode Releases | 0.72.* | 是 | API12+ | 4.7.4 | br_rnoh0.72 | | @react-native-oh-tpl/react-native-safe-area-context | <= 4.7.4-0.2.1@deprecated | Github Releases(deprecated) | 0.72.* | 否 | API12+ | 4.7.4 | sig |

简介

react-native-safe-area-context 是一个灵活处理安全区域（safe area insets）的 React Native 库，可在 JS 中统一获取与应用安全区域 inset 与 frame，同时兼容 Android 与 Web。鸿蒙侧通过 SafeAreaProvider、SafeAreaView 组件以及 useSafeAreaInsets 等 Hooks 暴露安全区域信息，使用方式与原库保持一致，效果对标 iOS / Android。

下载安装

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

npm

npm install @react-native-ohos/react-native-safe-area-context

yarn

yarn add @react-native-ohos/react-native-safe-area-context

Link

| | 是否支持autolink | RN框架版本 | |--------------------------------------|----------------|-----------| | ~ 5.6.3 | No | 0.82 | | ~ 5.1.1 | No | 0.77 | | ~ 4.7.5 | Yes | 0.72 | | <= 4.7.4-0.2.1@deprecated | No | 0.72 |

使用 AutoLink 的工程需要根据 Autolink 框架指导文档配置。

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

首先需要使用 DevEco Studio 打开项目里的 HarmonyOS 工程 harmony。

1. Overrides RN SDK

为了让工程依赖同一个版本的 RN SDK，需要在工程根目录的 oh-package.json5 添加 overrides 字段，指向工程需要使用的 RN SDK 版本。替换的版本既可以是一个具体的版本号，也可以是一个模糊版本，还可以是本地存在的 HAR 包或源码目录。

关于该字段的作用请阅读官方说明

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

2. 引入原生端代码

目前有两种方法：

通过 har 包引入；
直接链接源码。

方法一：通过 har 包引入（推荐）

[!TIP] har 包位于三方库安装路径的 harmony 文件夹下。

打开 entry/oh-package.json5，添加以下依赖

"dependencies": {
    "@react-native-ohos/react-native-safe-area-context": "file:../../node_modules/@react-native-ohos/react-native-safe-area-context/harmony/safe_area.har"
  }

点击右上角的 sync 按钮

或者在命令行终端执行：

cd entry
ohpm install

方法二：直接链接源码

[!TIP] 如需使用直接链接源码，请参考直接链接源码说明

3. 配置 CMakeLists 和引入 SafeAreaViewPackage

[!TIP] 若使用的是 <= 4.7.4-0.2.1 版本，请跳过本章。

打开 entry/src/main/cpp/CMakeLists.txt，添加：

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-safe-area-context/src/main/cpp" ./safe-area)
# 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_safe_area)
# RNOH_END: manual_package_linking_2

打开 entry/src/main/cpp/PackageProvider.cpp，添加：

#include "RNOH/PackageProvider.h"
#include "generated/RNOHGeneratedPackage.h"
#include "SamplePackage.h"
+ #include "SafeAreaViewPackage.h"

using namespace rnoh;

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

4. 在 ArkTs 侧引入 SafeAreaViewPackage

打开 entry/src/main/ets/RNPackagesFactory.ts，添加：

  ...
+ import {SafeAreaViewPackage} from '@react-native-ohos/react-native-safe-area-context/ts';

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

运行

点击右上角的 sync 按钮

或者在命令行终端执行：

cd entry
ohpm install

然后编译、运行即可。

约束与限制

兼容性

本文档内容基于以下版本验证通过：

RNOH: 0.72.96; SDK: HarmonyOS 6.0.0 Release SDK; IDE: DevEco Studio 6.0.0.858; ROM: 6.0.0.112;
RNOH: 0.72.33; SDK: HarmonyOS NEXT B1; IDE: DevEco Studio: 5.0.3.900; ROM: Next.0.0.71;
RNOH: 0.77.18; SDK: HarmonyOS 6.0.0 Release SDK; IDE: DevEco Studio 6.0.0.858; ROM: 6.0.0.112;
RNOH: 0.82.1; SDK: HarmonyOS 6.0.1 Release SDK; IDE: DevEco Studio 6.0.1 Release; ROM:6.0.0.120 SP7;

权限要求

无特殊权限要求。

编译运行API要求（如有）

[!TIP] 当前三方库所有版本均已实现版本隔离，支持在 API12+ 工程编译，及 API12+ ROM运行。

使用示例

下面的代码展示了这个库的基本使用场景：

[!WARNING] 使用时 import 的库名不变。

import React from "react";
import { Text, View } from "react-native";
import {
  SafeAreaProvider,
  SafeAreaView,
  initialWindowMetrics,
} from "react-native-safe-area-context";

const App = () => {
  return (
    <SafeAreaProvider initialMetrics={initialWindowMetrics}>
      <SafeAreaView style={{ flex: 1, backgroundColor: "red" }}>
        <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
          <Text>hello</Text>
        </View>
      </SafeAreaView>
    </SafeAreaProvider>
  );
};

export default App;

使用说明

SafeAreaProvider 应在应用的根组件中添加 SafeAreaProvider；使用 react-native-screens 时，可能还需要在模态框、路由根部等位置添加。请注意，Provider 不应放在使用 Animated 动画的 View 内或 ScrollView 内，否则会导致非常频繁的更新。

import { SafeAreaProvider } from "react-native-safe-area-context";

<SafeAreaProvider>
  <App />
</SafeAreaProvider>

SafeAreaView SafeAreaView 是一个常规 View 组件，将安全区域 inset 应用为 padding 或 margin，通过 edges 控制生效的边、通过 mode 控制作用于 padding 还是 margin。

import { SafeAreaView } from "react-native-safe-area-context";

<SafeAreaView style={{ flex: 1 }} edges={['top', 'bottom']} mode="padding">
  <Content />
</SafeAreaView>

Hooks 通过 useSafeAreaInsets 直接获取 inset 值，用于自定义布局。

import { useSafeAreaInsets } from "react-native-safe-area-context";

const insets = useSafeAreaInsets();
// insets.top / insets.bottom / insets.left / insets.right

接口说明

[!TIP] "Platform"列表示该属性在原三方库上支持的平台。

[!TIP] "HarmonyOS平台支持"列为 yes 表示 HarmonyOS 平台支持该属性；no 则表示不支持；partially 表示部分支持。使用方法跨平台一致，效果对标 iOS 或 Android 的效果。

组件

SafeAreaProvider

| 名称 | 参数类型 | 默认值 | 必填 | 平台 | HarmonyOS平台支持 | 描述 | |----------------|----------|----------|------|------|-------------------|-----------------------------------------------------------------| | Props | object | {flex:1} | 否 | All | Yes | 接受所有 View 属性。 | | initialMetrics | object | - | 否 | All | Yes | 可用于提供 frame 和 insets 的初始值，允许立即渲染（优化首屏）。 |

SafeAreaView

| 名称 | 参数类型 | 默认值 | 必填 | 平台 | HarmonyOS平台支持 | 描述 | |-------|----------|----------|------|------|-------------------|-----------------------------------------------------------------------| | Props | object | {flex:1} | 否 | All | Yes | 接受所有 View 属性。 | | edges | array | all | 否 | All | Yes | 设置要应用安全区域 inset 的边，可选 top / right / bottom / left。 | | mode | string | padding | 否 | All | Yes | 可选 padding（默认）或 margin，决定 inset 作用于 padding 还是 margin。 |

API

| 名称 | 类型 | 参数类型 | 返回值 | 必填 | 平台 | OpenHarmony平台支持 | 描述 | |---------------------------|----------|----------|-------------|------|------|---------------------|-------------------------------------------------------------------------------| | useSafeAreaInsets | function | / | EdgeInsets | 否 | All | Yes | 返回最近 Provider 的安全区域 inset。 | | useSafeAreaFrame | function | / | Rect | 否 | All | Yes | 返回最近 Provider 的 frame，可作为 Dimensions 模块的替代。 | | SafeAreaInsetsContext | object | / | / | 否 | All | Yes | 提供 inset 值的 React Context。 | | withSafeAreaInsets5.1.1+ | function | / | / | 否 | All | Yes | 高阶组件，将安全区域 inset 作为 insets 属性提供给被包裹组件。 | | SafeAreaFrameContext | object | / | / | 否 | All | Yes | 提供 frame 值的 React Context。 | | initialWindowMetrics | object | / | / | 否 | All | Yes | 初始渲染时窗口的 inset 和 frame，可与 SafeAreaProvider 的 initialMetrics 配合使用。 | | SafeAreaListener5.6.3+ | object | / | / | 否 | All | Yes | 监听渲染位置的安全区域变化。 |

遗留问题

无

其他

无

目录结构

/rntpc_react-native-safe-area-context  # 项目根目录
├── harmony              # 鸿蒙适配代码
│    └─ safe_area.har        # har包
│    └─ safe_area            # 鸿蒙适配核心代码
│          └─ index.ets      # 鸿蒙适配代码入口
│          └─ src/main/ets
│              └─ SafeAreaView     # SafeAreaView 鸿蒙组件
│              └─ SafeAreaProvider # SafeAreaProvider 鸿蒙组件
│          └─ src/main/cpp
│              └─ SafeAreaViewPackage.h  # 原生 Package
├── src                  # RN代码
│    └─ index.tsx        # 入口文件
│    └─ SafeAreaView.tsx # SafeAreaView 组件
│    └─ SafeArea.types.ts # 类型定义
│    └─ specs            # Codegen 规范
├── README.md           # 中文安装使用方法    
├── README_EN.md   # 英文安装使用方法

贡献代码

使用过程中发现任何问题都可以提交 Issue，当然，也非常欢迎提交 PR 。

开源协议

本项目基于 The MIT License (MIT) ，请自由地享受和参与开源。