From b19dbae68d0e1510f0024a568e8427761c4d0a8d Mon Sep 17 00:00:00 2001 From: tangdongming Date: Thu, 5 Feb 2026 10:18:37 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=96=B0=E5=A2=9Ereact-native-smart-re?= =?UTF-8?q?fresh=E7=9A=84=E4=B8=AD=E8=8B=B1=E6=96=87=E6=8C=87=E5=AF=BC?= =?UTF-8?q?=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- en/react-native-smart-refresh.md | 253 ++++++++++++++++++++++++++ zh-cn/react-native-smart-refresh.md | 269 ++++++++++++++++++++++++++++ 2 files changed, 522 insertions(+) create mode 100644 en/react-native-smart-refresh.md create mode 100644 zh-cn/react-native-smart-refresh.md diff --git a/en/react-native-smart-refresh.md b/en/react-native-smart-refresh.md new file mode 100644 index 00000000..6ea5393e --- /dev/null +++ b/en/react-native-smart-refresh.md @@ -0,0 +1,253 @@ +\> Template Version: v0.3.0 + +

+

@react-native-ohos/react-native-smart-refresh

+

+ +

+ + Supported platforms + + + License + +

+ +> [!TIP] [Github 地址](https://github.com/gaokaikai/react-native-smart-refresh/tree/master) + +## 1. Installation and Usage + +Please refer to the Releases page of the third-party library for matching version information: [@react-native-ohos/react-native-smart-refresh Releases](). + +| Third-party Library Version | Release Information | Supported RN Version | +| --------------------------- | ---------------------------------------------------------- | -------------------- | +| 1.0.0 | [@react-native-ohos/react-native-smart-refresh Releases]() | 0.72、0.77 | + +For older versions not published to npm, please refer to the [Installation Guide](/zh-cn/tgz-usage.md) to install the tgz package. + +Navigate to your project directory and run the following commands: +> [!TIP] Supplemental Note. RN framework version 0.72 uses 0.27.xx versions of this library, and RN framework version 0.77 uses 0.28.xx versions. + + +#### **npm** + +```bash +npm install @react-native-ohos/react-native-smart-refresh@xxx +``` + +#### **yarn** + +```bash +yarn install @react-native-ohos/react-native-smart-refresh@xxx +``` + + + +The following code demonstrates the basic usage of this library: + +```js +import React, { useState, useRef, useEffect } from 'react'; +import { SafeAreaView, ScrollView, Text, View, StyleSheet } from 'react-native'; +import { RNRefreshNormalView, RNRefreshAnimateView } from "@react-native-ohos/react-native-smart-refresh"; + +const RNSmartRefresh = () => { + const [isRefresh, setRefresh] = useState(false); + let timerRef = useRef(null); + + // Simulate data refresh + const handleRefresh = () => { + if (timerRef.current) { + clearTimeout(timerRef.current); + } + setRefresh(true); + timerRef.current = setTimeout(() => { + setRefresh(false); // Fixed typo: "fasle" → "false" + clearTimeout(timerRef.current); + }, 3000); + }; + + // Clear timer when component unmounts + useEffect(() => { + return () => { + if (timerRef.current) { + clearTimeout(timerRef.current); + } + }; + }, []); + + return ( + + + + + + + ); +}; + +export default RNSmartRefresh; +``` + +## 2. Link + +| | Supports autolink | RN Framework Version | +| ---- | ----------------- | -------------------- | +| ~1.0.0 | No | 0.72/0.77 | + +Projects using AutoLink need to be configured according to this document: Autolink Framework Guide: [https://gitcode.com/openharmony-sig/ohos_react_native/blob/master/docs/zh-cn/Autolinking.md](https://gitee.com/link?target=https%3A%2F%2Fgitcode.com%2Fopenharmony-sig%2Fohos_react_native%2Fblob%2Fmaster%2Fdocs%2Fzh-cn%2FAutolinking.md) + +If your version supports Autolink and the project has integrated Autolink, you can skip the ManualLink configuration. + +
+ ManualLink: This section provides guidance for manually configuring native dependencies + +First, open the HarmonyOS project `harmony` in your project using DevEco Studio. + +### 2.1 Overrides RN SDK + +To ensure the project depends on the same version of the RN SDK, add an `overrides` field to `harmony/oh-package.json5` in the project root directory, pointing to the RN SDK version required by the project. The version to replace can be a specific version number, a fuzzy version, or a local HAR package or source code directory. + +For the function of this field, please refer to the [official documentation](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-V5/ide-oh-package-json5-V5#zh-cn_topic_0000001792256137_overrides) (Note: Link to Chinese official doc as no English version is available). + +```json +{ + "overrides": { + "@rnoh/react-native-openharmony": "^0.72.58" + } +} +``` + +### 2.2 Import Native Code + +There are currently two methods: +- Import via HAR package; +- Link source code directly. + +Method 1: Import via HAR package (Recommended) + +> [!TIP] The HAR package is located in the `harmony` folder of the third-party library's installation path. + +Open `entry/oh-package.json5` and add the following dependency: + +```json +"dependencies": { + "@react-native-ohos/react-native-smart-refresh": "file:../../node_modules/@react-native-ohos/react-native-smart-refresh/harmony/smart_refresh.har" + } +``` + +Click the `Sync` button in the upper right corner, or run the following command in the terminal: + +```bash +cd entry +ohpm install +``` + +Method 2: Link source code directly + +> [!TIP] If you need to link source code directly, please refer to [Link Source Code Guide](/zh-cn/link-source-code.md). + +### 2.3 Configure CMakeLists and Import NestedScrollViewPackage + +Open `entry/src/main/cpp/CMakeLists.txt` and add: + +```diff ++ set(OH_MODULES "${CMAKE_CURRENT_SOURCE_DIR}/../../../oh_modules") + +# RNOH_BEGIN: manual_package_linking_1 ++ add_subdirectory("${OH_MODULES}/@react-native-ohos/react-native-smart-refresh/src/main/cpp" ./smart_refresh) +# RNOH_END: manual_package_linking_1 + +# RNOH_BEGIN: manual_package_linking_2 ++ target_link_libraries(rnoh_app PUBLIC rnoh_smart_refresh) +# RNOH_END: manual_package_linking_2 +``` + +Open `entry/src/main/cpp/PackageProvider.cpp` and add: + +```diff +#include "RNOH/PackageProvider.h" +#include "generated/RNOHGeneratedPackage.h" ++ #include "RNSmartRefreshPackage.h" + +using namespace rnoh; + +std::vector> PackageProvider::getPackages(Package::Context ctx) { + return { + std::make_shared(ctx), ++ std::make_shared(ctx), + }; +} +``` + +### 2.4 Run + +Click the `Sync` button in the upper right corner, or run the following command in the terminal: + +```bash +cd entry +ohpm install +``` + +Then compile and run the project. + +
+ +## 3. Constraints and Limitations + +### 3.1 Compatibility + +Please refer to the Releases page of the third-party library for matching version information: [@react-native-ohos/react-native-smart-refresh Releases](). + +## 4. Properties + +> [!TIP] The "Platform" column indicates the platforms supported by these properties in the original third-party library. + +> [!TIP] If the value in the "HarmonyOS Support" column is "yes", it means the property is supported on the HarmonyOS platform; "no" means not supported; "partially" means part of the property's functions are supported. The usage of the property is the same across platforms, and the effect is consistent with the iOS or Android platform. + +### RNRefreshNormalView Properties +| Name | Description | Type | Required | Platform | HarmonyOS Support | +| ------------------ | ------------------------------- | --------------------- | -------- | -------- | ----------------- | +| refreshing | Controls the display/hiding of the refresh indicator | boolean (default false) | YES | All | yes | +| imageStyle | Image style | ImageStyle | NO | All | Partially | +| arrowIcon | Image source | string | NO | All | no | +| containerStyle | Container style | ViewStyle | NO | All | Partially | +| titleStyle | Title text style | TextStyle | NO | All | Partially | +| timeStyle | Time text style | TextStyle | NO | All | Partially | +| leftContainerStyle | Left container style | ViewStyle | NO | All | Partially | +| rightContainerStyle| Right container style | ViewStyle | NO | All | Partially | + +### RNRefreshAnimateView Properties +| Name | Description | Type | Required | Platform | HarmonyOS Support | +| :-------------------- | :------------------------------ | :-------------------- | :------- | :------- | :---------------- | +| refreshing | Controls the display/hiding of the refresh indicator | boolean (default false) | YES | All | yes | +| resizeMode | Animation resize mode | string | NO | All | yes | +| loop | Animation loop | boolean (default true) | NO | All | yes | +| autoPlay | Animation auto-play | boolean (default true) | NO | All | yes | +| speed | Animation speed | number | NO | All | yes | +| source | Animation source (passed in JSON format) | string | NO | All | yes | +| hardwareAccelerated | Whether to use caching | boolean (default true) | NO | All | yes | +| cacheStrategy | Caching strategy | string | NO | All | no | +| progress | Animation progress | number | NO | All | no | +| containerStyle | Animation background style | ViewStyle | NO | All | Partially | +| lottieStyle | Animation style | ViewStyle | NO | All | Partially | + +## 5. Methods +### RNRefreshNormalView Methods +| Name | Description | Type | Platform | HarmonyOS Support | +| ---------- | --------------------- | -------- | -------- | ----------------- | +| onRefresh | Refresh callback | function | All | yes | + +### RNRefreshAnimateView Methods +| Name | Description | Type | Platform | HarmonyOS Support | +| ---------- | --------------------- | -------- | -------- | ----------------- | +| onRefresh | Refresh callback | function | All | yes | + +## 6. Known Issues +None + +## 7. Open Source License + +This project is licensed under [The MIT License (MIT)](), feel free to use and contribute to open source. diff --git a/zh-cn/react-native-smart-refresh.md b/zh-cn/react-native-smart-refresh.md new file mode 100644 index 00000000..02ed4452 --- /dev/null +++ b/zh-cn/react-native-smart-refresh.md @@ -0,0 +1,269 @@ +> 模板版本：v0.3.0 + +

+

@react-native-ohos/react-native-smart-refresh

+

+ +

+ + Supported platforms + + + License + +

+ +> [!TIP] [Github 地址](https://github.com/gaokaikai/react-native-smart-refresh/tree/master) + +## 1. 安装与使用 + +请到三方库的 Releases 发布地址查看配套的版本信息：[@react-native-ohos/react-native-smart-refresh Releases]() 。 + +| 三方库版本 | 发布信息 | 支持RN版本 | +| ---------- | ------------------------------------------------------------ | ---------- | +| 1.0.0 | [@react-native-ohos/react-native-smart-refresh Releases]() | 0.72、0.77 | + + +对于未发布到npm的旧版本，请参考[安装指南](/zh-cn/tgz-usage.md)安装tgz包。 + + +进入到工程目录并输入以下命令： +> [!TIP] 补充说明。0.72的RN框架版本使用0.27.xx版本，0.77的RN框架版本使用0.28.xx版本 + + +#### **npm** + +```bash +npm install @react-native-ohos/react-native-smart-refresh@xxx +``` + +#### **yarn** + +```bash +yarn install @react-native-ohos/react-native-smart-refresh@xxx +``` + + + +下面的代码展示了这个库的基本使用场景： + +```js +import React, { useState, useRef, useEffect } from 'react'; +import { SafeAreaView, ScrollView, Text, View, StyleSheet } from 'react-native'; +import { RNRefreshNormalView, RNRefreshAnimateView } from "@react-native-ohos/react-native-smart-refresh"; + + +const RNSmartRefresh = () => { + + const [isRefresh, setRefresh] = useState(false) + + let timerRef = useRef(null); + + // 模拟数据刷新 + const handleRefresh = () => { + if (timerRef.current) { + clearTimeout(timerRef.current); + } + setRefresh(true); + timerRef.current = setTimeout(() => { + setRefresh(fasle); + // + + clearTimeout(timerRef.current); + }, 3000); + }; + + //退出组件清除定时器 + useEffect(() => { + return () => { + if (timerRef.current) { + clearTimeout(timerRef.current); + } + }; + }, []); + + return ( + + + + + + + ) +} + +export default RNSmartRefresh; + +``` + +## 2. Link + +| | 是否支持autolink | RN框架版本 | +| ---- | ---------------- | ---------- | +| ~1.0.0 | No | 0.72/0.77 | + +使用AutoLink的工程需要根据该文档配置，Autolink框架指导文档：[https://gitcode.com/openharmony-sig/ohos_react_native/blob/master/docs/zh-cn/Autolinking.md](https://gitee.com/link?target=https%3A%2F%2Fgitcode.com%2Fopenharmony-sig%2Fohos_react_native%2Fblob%2Fmaster%2Fdocs%2Fzh-cn%2FAutolinking.md) + +如您使用的版本支持 Autolink，并且工程已接入 Autolink，可跳过ManualLink配置。 + +
+ ManualLink: 此步骤为手动配置原生依赖项的指导 +首先需要使用 DevEco Studio 打开项目里的 HarmonyOS 工程 `harmony`。 + +### 2.1 Overrides RN SDK + +为了让工程依赖同一个版本的 RN SDK，需要在工程根目录的 `harmony/oh-package.json5` 添加 overrides 字段，指向工程需要使用的 RN SDK 版本。替换的版本既可以是一个具体的版本号，也可以是一个模糊版本，还可以是本地存在的 HAR 包或源码目录。 + +关于该字段的作用请阅读[官方说明](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-V5/ide-oh-package-json5-V5#zh-cn_topic_0000001792256137_overrides) + +```json +{ + "overrides": { + "@rnoh/react-native-openharmony": "^0.72.101" + } +} +``` + +### 2.2 引入原生端代码 + +目前有两种方法： + +- 通过 har 包引入； +- 直接链接源码。 + +方法一：通过 har 包引入（推荐） + +> [!TIP] har 包位于三方库安装路径的 `harmony` 文件夹下。 + +打开 `entry/oh-package.json5`，添加以下依赖 + +```json +"dependencies": { + "@react-native-ohos/react-native-smart-refresh": "file:../../node_modules/@react-native-ohos/react-native-smart-refresh/harmony/smart_refresh.har" + } +``` + +点击右上角的 `sync` 按钮 + +或者在终端执行： + +```bash +cd entry +ohpm install +``` + +方法二：直接链接源码 + +> [!TIP] 如需使用直接链接源码，请参考[直接链接源码说明]() + +### 2.3 配置 CMakeLists 和引入 NestedScrollViewPackage + +打开 `entry/src/main/cpp/CMakeLists.txt`，添加： + +```diff ++ set(OH_MODULES "${CMAKE_CURRENT_SOURCE_DIR}/../../../oh_modules") + +# RNOH_BEGIN: manual_package_linking_1 ++ add_subdirectory("${OH_MODULES}/@react-native-ohos/react-native-smart-refresh/src/main/cpp" ./smart_refresh) +# RNOH_END: manual_package_linking_1 + +# RNOH_BEGIN: manual_package_linking_2 ++ target_link_libraries(rnoh_app PUBLIC rnoh_smart_refresh) +# RNOH_END: manual_package_linking_2 +``` + +打开 `entry/src/main/cpp/PackageProvider.cpp`，添加： + +```diff +#include "RNOH/PackageProvider.h" +#include "generated/RNOHGeneratedPackage.h" ++ #include "RNSmartRefreshPackage.h" + +using namespace rnoh; + +std::vector> PackageProvider::getPackages(Package::Context ctx) { + return { + std::make_shared(ctx), ++ std::make_shared(ctx), + }; +} +``` + +### 2.4 运行 + +点击右上角的 `sync` 按钮 + +或者在终端执行： + +```bash +cd entry +ohpm install +``` + +然后编译、运行即可。 + +
+ +## 3. 约束与限制 + +### 3.1 兼容性 + +请到三方库相应的 Releases 发布地址查看 Release 配套的版本信息：[@react-native-ohos/react-native-smart-refresh Releases]() + +## 4. 属性 + +> [!TIP] "Platform" 列表示这些属性在原始第三方库中支持的平台。 + +> [!TIP] "如果“HarmonyOS 支持”列的值为“yes”，则表示 HarmonyOS 平台支持该属性；“no”则表示不支持；“partially”表示部分支持该属性的功能。该属性在不同平台上的使用方法相同，效果与 iOS 或 Android 平台一致。 +### RNRefreshNormalView属性 +| Name | Description | Type | Required | Platform | HarmonyOS Support | +| ----------- |---------------------|---------|----------| -------- | ----------------- | +| refreshing| 控制刷新指示器的显示与隐藏 | boolean（default false） | YES | All | yes | +| imageStyle | 图片样式 | ImageStyle | NO | All | partially | +| arrowIcon | 图片源 | string | NO | All | no | +| containerStyle | 内容样式 | ViewStyle | NO | All | partially | +| titleStyle | 标题文本样式 | TextStyle | NO | All | partially | +| timeStyle | 时间样式 | TextStyle | NO | All | partially | +| leftContainerStyle | 左侧内容样式 | ViewStyle | NO | All | partially | +| rightContainerStyle | 右侧内容样式 | ViewStyle | NO | All | partially | + +### RNRefreshAnimateView属性 +| Name | Description | Type | Required | Platform | HarmonyOS Support | +| :---------- |:--------------------|:--------|:---------| :------- | :---------------- | +| refreshing| 控制刷新指示器的显示与隐藏 | boolean（default false） | YES | All | yes | +| resizeMode | 动画填充方式 | string | NO | All | yes | +| loop | 动画循环 | boolean（default true） | NO | All | yes | +| autoPlay | 动画播放 | boolean（default true） | NO | All | yes | +| speed | 动画速度 | number | NO | All | yes | +| source | 动画源，以JSON格式传入 | string | NO | All | yes | +| hardwareAccelerated | 是否使用缓存 | boolean（default true） | NO | All | yes | +| cacheStrategy | 缓存方式 | string | NO | All | no | +| progress | 动画进度 | number | NO | All | no | +| containerStyle | 动画背景样式 | ViewStyle | NO | All | partially | +| lottieStyle | 动画样式 | ViewStyle | NO | All | partially | + + + + +## 5.方法 +### RNRefreshNormalView方法 +| Name | Description | Type | Platform | HarmonyOS Support | +| ----------- |---------------------|---------| -------- | ----------------- | +| onRefresh | 刷新回调 | function | All | yes | + + +### RNRefreshAnimateView方法 +| Name | Description | Type | Platform | HarmonyOS Support | +| ----------- |---------------------|---------| -------- | ----------------- | +| onRefresh | 刷新回调 | function | All | yes | + +## 6. 遗留问题 +无 + +## 7. 开源协议 + +本项目基于 [The MIT License (MIT)]()，请自由地享受和参与开源。 + -- Gitee