# rn_multidevice_layout_scenepkg

**Repository Path**: ohadss/rn_multidevice_layout_scenepkg

## Basic Information

- **Project Name**: rn_multidevice_layout_scenepkg
- **Description**: RN framework-oriented multi-device layout scenario package.
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 2
- **Created**: 2024-11-05
- **Last Updated**: 2025-01-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<p align="center">
  <h1 align="center"> <code>rn_multidevice_layout_scenepkg</code> </h1>
</p>

## 介绍

这是一个旨在解决 React Native 多设备适配问题的三方库，专为不同设备类型（包括折叠屏、平板、手机等）提供了便捷的支持。该库包含的接口和开箱即用的组件，使开发者能够轻松应对各种设备的布局适配需求。

## 工程目录

```
.
├─harmony
│  │  fold.har              // 折叠屏turbo接口har包
│  │
│  └─fold
│      └─src
│          └─main
│              └─ets
│                  │  FoldModule.ets     // tur接口ArkTS实现
│                  │  FoldModulePackage.ets   // FoldModulesFactory
│                  │  FoldModuleSpec.ts  // turbo接口
│                  │
│                  └─core
│                          FoldConfig.ts   
│
└─src
    │  index.ts    // RN模块导出
    │
    ├─component
    │      FoldSplitContainer.tsx    // 折叠屏高阶组件
    │
    ├─config
    │      breakpoints.ts   // 断点配置类
    │
    ├─hooks
    │      useBreakpointValue.ts   //断点hook
    │
    └─turbo
            NativeFoldModule.ts   // RN turbo接口
```




## 安装与使用

请拉取[rn_multidevice_layout_scenepkg](https://gitee.com/ohadss/rn_multidevice_layout_scenepkg)代码仓并执行npm pack获取 tgz 包。

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

> [!TIP] # 处替换为 tgz 包的路径

<!-- tabs:start -->

#### **npm**

```bash
npm install rn_multidevice_layout_scenepkg@file:#
```

#### **yarn**

```bash
yarn add rn_multidevice_layout_scenepkg@file:#
```

<!-- tabs:end -->

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


```jsx
const TestSample = () => {
  const [foldCreaseRegion, setFoldCreaseRegion] = useState<number[]>([]);
  const [foldStatus, setFoldStatus] = useState('');
  const [breakpoints, setBreakpointsState] = useState({});
  const [isDeviceFoldable, setIsDeviceFoldable] = useState(false);

  useEffect(() => {
    const checkFoldable = () => {
      // 判断当前设备是否可折叠
      const foldable = Fold.isFoldable();
      setIsDeviceFoldable(foldable);
      if (foldable) {
        // 获取折痕区域
        setFoldCreaseRegion(Fold.getFoldCreaseRegion());
        
        // 获取当前折叠屏状态
        setFoldStatus(Fold.getFoldStatus());
      }
    };

    checkFoldable();

    // 监听折叠屏状态变化
    Fold.addFoldListener((foldStatus) => {
      console.log('折叠屏状态发生变化', foldStatus);
    });

    return () => {
      // 销毁监听折叠屏状态变化
      Fold.removeFoldListener();
    };
  }, []);

  const handleGetBreakpoints = () => {
    setBreakpointsState(getBreakpoints());
  };

  const handleSetBreakpoints = () => {
    // 设置断点区间
    setBreakpoints({
      base: 320,
      md: 768,
      lg: 1024,
    });
  };

  const handleGetFoldStatus = () => {
    if (isDeviceFoldable) {
      // 获取当前折叠屏状态
      setFoldStatus(Fold.getFoldStatus());
    }
  };

  const color = useBreakpointValue({
    // 根据不同断点设置不同的颜色
    base: 'red',
    xs: 'blue',
    sm: 'green',
    md: 'yellow',
    lg: 'purple',
    xl: 'orange',
  });
    
  // FoldSplitContainer 主要区域
  const primaryRender = () => (
    <View style={{ flex: 1 }}>
      <Text style={{ color }}>Responsive Color Text</Text>
      <Text>Is Device Foldable: {isDeviceFoldable ? 'Yes' : 'No'}</Text>

      {isDeviceFoldable && (
        <>
          <Text>Fold Crease Region: {JSON.stringify(foldCreaseRegion)}</Text>
          <Button title="Get Fold Status" onPress={handleGetFoldStatus} />
          {foldStatus && <Text>Fold Status: {foldStatus}</Text>}
        </>
      )}

      <Button title="Get Breakpoints" onPress={handleGetBreakpoints} />
      {Object.keys(breakpoints).length > 0 && (
        <Text>Breakpoints: {JSON.stringify(breakpoints)}</Text>
      )}

      <Button title="Set Custom Breakpoints" onPress={handleSetBreakpoints} />
    </View>
  );

  // FoldSplitContainer 次要区域
  const secondRender = () => (
    <View style={{ flex: 1, backgroundColor: 'blue' }}>
      <Text style={{ fontSize: 20 }}>secondRender</Text>
    </View>
  );

  // FoldSplitContainer 扩展区域
  const extraRender = () => (
    <View style={{ flex: 1, backgroundColor: 'red' }}>
      <Text style={{ fontSize: 20 }}>extraRender</Text>
    </View>
  );

  // 折叠屏展开态配置
  const expandedLayoutOptions: ExpandedRegionLayoutOptions = {
    isExtraRegionPerpendicular: false,
    extraRegionPosition: ExtraRegionPosition.BOTTOM,
  };

  // 折叠屏悬停态配置
  const hoverModeRegionLayoutOptions: HoverModeRegionLayoutOptions = {
    showExtraRegion: true,
  };

  return (
    <View style={styles.container}>
      // 折叠屏高阶组件
      <FoldSplitContainer
        primary={primaryRender()}
        secondary={secondRender()}
        extra={extraRender()}
        expandedLayoutOptions={expandedLayoutOptions}
        hoverModeLayoutOptions={hoverModeRegionLayoutOptions}
      />
    </View>
  );
};

const styles = StyleSheet.create({
  container: {
    flex: 1,
  },
});

export default TestSample;
```

## Link

本库依赖以下三方库，请查看对应文档：

- [@react-native-oh-tpl/react-native-orientation](https://gitee.com/react-native-oh-library/usage-docs/blob/master/zh-cn/react-native-orientation.md#3%E5%9C%A8-arkts-%E4%BE%A7%E5%BC%95%E5%85%A5-rnorientationpackage)

目前 OpenHarmony 暂不支持 AutoLink，所以 Link 步骤需要手动配置。

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

### 1.在工程根目录的 `oh-package.json5` 添加 overrides 字段

```json
{
  ...
  "overrides": {
    "@rnoh/react-native-openharmony" : "./react_native_openharmony"
  }
}
```

### 2.引入原生端代码

目前有两种方法：

1. 通过 har 包引入（在 IDE 完善相关功能后该方法会被遗弃，目前首选此方法）；
2. 直接链接源码。

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

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

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

```json
"dependencies": {
    "@rnoh/react-native-openharmony": "file:../react_native_openharmony",
    "fold": "file:../../node_modules/rn_multidevice_layout_scenepkg/harmony/fold.har",
  }
```

点击右上角的 `sync` 按钮

或者在终端执行：

```bash
cd entry
ohpm install
```

### 3.配置 CMakeLists 和引入 RNOHGeneratedPackage

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

```diff
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)
```

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

```diff
#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)
    };
}
```

### 4.在 ArkTs 侧引入 FoldModulePackage

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

```diff
  ...
+ import { FoldModulePackage } from 'fold/ts';

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

### 5.运行

点击右上角的 `sync` 按钮

或者在终端执行：

```bash
cd entry
ohpm install
```

然后编译、运行即可。

##  API

> [!tip] "Platform"列表示支持的平台，All表示支持所有平台。

### 断点

| Name               | Description                                                  | Type     | Platform |
| ------------------ | ------------------------------------------------------------ | -------- | -------- |
| getBreakpoints     | 获取当前用于响应式布局的断点值。                             | function | All      |
| setBreakpoints     | 设置自定义的响应式布局断点值。                               | function | All      |
| useBreakpointValue | 允许开发者为特定断点定义不同的值，并动态返回与当前屏幕宽度相对应的值。 | hook     | All      |

### 折叠屏适配

**折叠屏接口**

| Name                | Description                                                  | Type     | Platform  |
| ------------------- | ------------------------------------------------------------ | -------- | --------- |
| getFoldCreaseRegion | 获取可折叠设备屏幕的折痕区域。                               | function | OpenHarmony |
| getFoldStatus       | 获取当前可折叠设备的状态（例如：展开、半折叠或折叠）。       | function | OpenHarmony |
| isFoldable          | 判断设备是否可折叠。如果为 `true`，设备是可折叠的；否则是不可折叠设备。 | function | OpenHarmony |
| addFoldListener     | 监听折叠设备的折叠状态变化。                                 | function | OpenHarmony |
| removeFoldListener  | 移除已添加的折叠状态变化监听。                               | function | OpenHarmony |

**FoldSplitContainer组件**

| Name                   | Description                                    | Type                         | Platform  |
| :--------------------- | :--------------------------------------------- | :--------------------------- | :-------- |
| primary                | 主要区域回调函数。                             | function                     | OpenHarmony |
| secondary              | 次要区域回调函数。                             | function                     | OpenHarmony |
| extra                  | 扩展区域回调函数，不传入的情况，没有对应区域。 | function                     | OpenHarmony |
| expandedLayoutOptions  | 展开态布局信息。                               | ExpandedRegionLayoutOptions  | OpenHarmony |
| hoverModeLayoutOptions | 悬停态布局信息。                               | HoverModeRegionLayoutOptions | OpenHarmony |
| foldedLayoutOptions    | 折叠态布局信息。                               | FoldedRegionLayoutOptions    | OpenHarmony |
| onHoverStatusChange    | 折叠屏进入或退出悬停模式时触发的回调函数。     | onHoverStatusChangeHandler   | OpenHarmony |

**ExpandedRegionLayoutOptions**

| Name                       | Description                                                  | Type                | Platform  |
| :------------------------- | :----------------------------------------------------------- | :------------------ | --------- |
| isExtraRegionPerpendicular | 扩展区域是否从上到下贯穿整个组件，当且仅当extra有效时此字段才生效。默认值：true。 | boolean             | OpenHarmony |
| verticalSplitRatio         | 主要区域与次要区域之间的高度比例。默认值：PresetSplitRatio.LAYOUT_1V1。 | number              | OpenHarmony |
| horizontalSplitRatio       | 主要区域与扩展区域之间的宽度比例，当且仅当extra有效时此字段才生效。默认值：PresetSplitRatio.LAYOUT_3V2。 | number              | OpenHarmony |
| extraRegionPosition        | 扩展区域的位置信息，当且仅当isExtraRegionPerpendicular = false有效时此字段才生效。默认值：ExtraRegionPosition.top。 | ExtraRegionPosition | OpenHarmony |

**HoverModeRegionLayoutOptions**

| Name                 | Description                                                  | Type                | Platform  |
| :------------------- | :----------------------------------------------------------- | :------------------ | :-------- |
| showExtraRegion      | 可折叠屏幕在半折叠状态下是否显示扩展区域。默认值：false。    | boolean             | OpenHarmony |
| horizontalSplitRatio | 主要区域与扩展区域之间的宽度比例，当且仅当extra有效时此字段才生效。默认值：PresetSplitRatio.LAYOUT_3V2。 | number              | OpenHarmony |
| extraRegionPosition  | 扩展区域的位置信息，当且仅当showExtraRegion时此字段才生效。默认值：ExtraRegionPosition.top。 | ExtraRegionPosition | OpenHarmony |

**FoldedRegionLayoutOptions**

| Name               | Description                                                  | Type   | Platform  |
| :----------------- | :----------------------------------------------------------- | :----- | :-------- |
| verticalSplitRatio | 主要区域与次要区域之间的高度比例。默认值：PresetSplitRatio.LAYOUT_1V1。 | number | OpenHarmony |

**onHoverStatusChangeHandler**

| Name     | Description                                | Type                              | Platform  |
| :------- | :----------------------------------------- | :-------------------------------- | :-------- |
| callback | 折叠屏进入或退出悬停模式时触发的回调函数。 | (status: HoverModeStatus) => void | OpenHarmony |

**HoverModeStatus**

| Name        | Description             | Type       | Platform  |
| :---------- | :---------------------- | :--------- | :-------- |
| foldStatus  | 设备的折叠状态。        | FoldStatus | OpenHarmony |
| isHoverMode | app当前是否处于悬停态。 | boolean    | OpenHarmony |

**ExtraRegionPosition**

| Name   | Description              | Value |
| :----- | :----------------------- | :---- |
| top    | 扩展区域在组件上半区域。 | 1     |
| bottom | 扩展区域在组件下半区域。 | 2     |

**PresetSplitRatio**

| Name       | Description | Value |
| :--------- | :---------- | :---- |
| LAYOUT_1V1 | 1:1比例。   | 1/1   |
| LAYOUT_3V2 | 3:2比例。   | 3/2   |
| LAYOUT_2V3 | 2:3比例。   | 2/3   |