npm package: @hadss/react_native_breakpoints
Description: A third-party library that provides responsive breakpoint layout capabilities for React Native apps. Supports multi-device adaptation, custom breakpoints, and is suitable for unified layouts across platforms including OpenHarmony.
Latest version: 1.0.4

# @hadss/react_native_breakpoints

## 介绍

`@hadss/react_native_breakpoints` 是一个为 React Native 应用提供响应式断点布局能力的三方库。它支持多设备、多屏幕尺寸的自适应布局，帮助开发者根据不同设备的屏幕宽度和高度动态调整 UI 组件的显示方式。  
该库内置了常用的横向和纵向断点划分，并支持自定义断点区间，适用于手机、平板等多种终端。  
同时，库还提供了断点管理器（BreakpointManager）、断点 Hook（useBreakpointValue/useHeightBreakpointValue）等 API，方便开发者灵活获取和监听当前断点，实现更智能的响应式布局。

主要特性：
- 支持横向和纵向断点，适配多种屏幕尺寸
- 支持断点自定义，满足不同业务需求
- 提供断点监听、断点值获取等便捷 API
- 兼容 OpenHarmony 及标准 React Native 生态
- 适用于多端统一布局场景

适合需要多设备适配、响应式布局的 React Native 项目，尤其适合面向OpenHarmony生态的多端开发场景。

## 工程目录

```
.
├── harmony
│   ├── breakpoints
│   │   ├── src
│   │   │   └── main
│   │   │       ├── ets
│   │   │       │   ├── BreakpointsModule.ets                    // 断点Turbo Modules原生实现
│   │   │       │   ├── BreakpointsModulePackage.ets
│   │   │       │   └── BreakpointsModuleSpec.ts
├── src
│   ├── config
│   │   └── breakpoints
│   │       ├── breakpoints.ts                                    // 断点区间
│   │       └── types.ts                                          // 断点类型
│   ├── hooks
│   │   ├── BreakpointManager.ts                                  // 断点管理类
│   │   ├── useBreakpointValue.ts                                 // 横向断点hook
│   │   └── useHeightBreakpointValue.ts                           // 纵向断点hook
│   ├── index.ts
│   └── turbo
│       ├── NativeBreakpointsModule.harmony.ts                    // 断点Turbo Modules接口
│       └── NativeBreakpointsModule.ts                            // 提供非OpenHarmony平台空实现

```


## 安装与使用

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

<!-- tabs:start -->

**npm**

```bash
npm install @hadss/react_native_breakpoints
```

**yarn**

```bash
yarn add @hadss/react_native_breakpoints
```

<!-- tabs:end -->

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

**断点BreakpointManager使用示例**
```jsx
import React from 'react';
import { Text, StyleSheet, ScrollView } from 'react-native';
import { useBreakpointValue, useHeightBreakpointValue } from '@hadss/react_native_breakpoints';

export default function BreakpointTest() {
  // 横向断点测试
  const a1 = useBreakpointValue({ base: 1, xs: 3 });
  const a2 = useBreakpointValue({ base: '1', xs: 3 });
  const a3 = useBreakpointValue({ xs: 3, lg: '2' });
  const a4 = useBreakpointValue({ lg: '2', xl: false });
  const a5 = useBreakpointValue({ xs: 'xs', sm: 'sm', md: 'md', lg: 'lg', xl: 'xl' });

  // 纵向断点测试
  const h1 = useHeightBreakpointValue({ base: 100, lg: 120 });
  const h2 = useHeightBreakpointValue({ base: '100', md: '160' });
  const h3 = useHeightBreakpointValue({ sm: 100, md: 'md', lg: false });
  const h4 = useHeightBreakpointValue({ md: 'md', lg: 999 });
  const h5 = useHeightBreakpointValue({ sm: 'sm', md: 'md', lg: 'lg' });

  return (
    <ScrollView style={styles.container}>
      <Text style={styles.header}>useBreakpointValue（横向）测试</Text>
      <Text style={styles.item}>a1: {String(a1)} ({typeof a1})</Text>
      <Text style={styles.item}>a2: {String(a2)} ({typeof a2})</Text>
      <Text style={styles.item}>a3: {String(a3)} ({typeof a3})</Text>
      <Text style={styles.item}>a4: {String(a4)} ({typeof a4})</Text>
      <Text style={styles.item}>a5: {String(a5)} ({typeof a5})</Text>

      <Text style={[styles.header, { marginTop: 24 }]}>useHeightBreakpointValue（纵向）测试</Text>
      <Text style={styles.item}>h1: {String(h1)} ({typeof h1})</Text>
      <Text style={styles.item}>h2: {String(h2)} ({typeof h2})</Text>
      <Text style={styles.item}>h3: {String(h3)} ({typeof h3})</Text>
      <Text style={styles.item}>h4: {String(h4)} ({typeof h4})</Text>
      <Text style={styles.item}>h5: {String(h5)} ({typeof h5})</Text>
    </ScrollView>
  );
}

const styles = StyleSheet.create({
  container: {
    padding: 24,
    backgroundColor: 'white',
    flex: 1,
  },
  header: {
    fontSize: 20,
    fontWeight: 'bold',
    marginBottom: 12,
  },
  item: {
    fontSize: 16,
    marginBottom: 8,
  },
});

```

## Link

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

首先需要使用DevEco Studio打开项目里的OpenHarmony工程，在工程根目录的`oh-package.json5`添加overrides字段：

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

### 引入原生端代码

目前有两种方法：

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

    >**说明：**
    >har包位于三方库安装路径的`harmony`文件夹下。

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

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

    b. 配置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)
    ```

    c. 打开`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)
        };
    }
    ```

    d. 在ArkTs侧引入BreakpointsModulePackage：

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

    ```diff
      ...
    + import { BreakpointsModulePackage } from '@hadss/react_native_breakpoints/ts';
    
    export function createRNPackages(ctx: RNPackageContext): RNPackage[] {
      return [
    +   new BreakpointsModulePackage(ctx),
      ];
    }
    ```

    e. 运行：

    点击右上角的`sync`按钮

    或者在终端执行：

    ```bash
    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操作同步代码。

2. **直接链接源码。**

    如需使用直接链接源码，请参考[直接链接源码说明](https://gitee.com/react-native-oh-library/usage-docs/blob/master/zh-cn/link-source-code.md)。

##  API

>**说明：**
>"Platform"列表示支持的平台，All表示支持所有平台。

### 断点

| Name               | Description                                                  | Type     | Platform |
| ------------------ | ------------------------------------------------------------ | -------- | -------- |
| setBreakpoints     | 设置自定义的横向响应式布局断点值。说明：仅在 JS 侧生效。                               | function | All      |
| setHeightBreakpoints     | 设置自定义的纵向响应式布局断点值。 说明：仅在 JS 侧生效。                                 | function | All      |
| useBreakpointValue | 允许开发者为特定的横向断点定义不同的值，并动态返回与当前屏幕宽度相对应的值。 | hook     | All      |
| useHeightBreakpointValue | 允许开发者为特定的纵向断点定义不同的值，并动态返回与当前屏幕宽度相对应的值。 | hook     | All      |
### BreakpointManager

| Name               | Description                                                  | Type     | Platform |
| ------------------ | ------------------------------------------------------------ | -------- | -------- |
| getInstance        | 获取 BreakpointManager 的单例                             | function | All      |
| getCurrentWidthBreakpoint     | 获取当前的横向断点                               | function | All      |
| getCurrentHeightBreakpoint     | 获取当前的纵向断点                               | function | All      |
| subscribeToBreakpoint | 订阅断点变化 | function     | All      |
| destroy | 注销监听 | function     | All      |


## 约束与限制
本示例仅支持标准系统上运行，支持设备：华为手机。
DevEco Studio版本：5.0.1 Release及以上。
SDK版本：API13及以上。