# ReactNativeListRefresh

**Repository Path**: scenario-samples/react-native-list-refresh

## Basic Information

- **Project Name**: ReactNativeListRefresh
- **Description**: 在RN应用开发中，经常需要自定义列表组件的下拉刷新动画，以实现更丰富的交互效果。列表组件通过@react-native-oh-tpl/react-native-smartrefreshlayout 组件（后文简称SmartRefreshControl组件）实现完全的自定义下拉刷新控件，通过@react-native-ohos/lottie-react-native 组件（后文简称Lottie组件）
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-19
- **Last Updated**: 2025-12-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

## 场景介绍

在RN应用开发中，经常需要自定义列表组件的下拉刷新动画，以实现更丰富的交互效果。列表组件通过[@react-native-oh-tpl/react-native-smartrefreshlayout](https://gitee.com/react-native-oh-library/usage-docs/blob/master/zh-cn/react-native-SmartRefreshLayout.md)
组件（后文简称SmartRefreshControl组件）实现完全的自定义下拉刷新控件，通过[@react-native-ohos/lottie-react-native](https://gitee.com/react-native-oh-library/usage-docs/blob/master/zh-cn/lottie-react-native.md)
组件（后文简称Lottie组件）加载lottie动画实现更丰富的交互效果

## 效果预览

<img src="screenshots/ReactNativeListRefresh.webp" width="200">

## 实现思路

1. 示例中的列表组件以FlatList组件为例，ScrollView，SectionList等列表组件也可以直接复用示例代码中refreshControl属性的实现逻辑以实现自定义下拉刷新动画效果。
2. SmartRefreshControl组件的onRefresh方法会在下拉刷新的时触发，同时可通过primaryColor属性设置下拉组件的背景色。
3. 使用Lottie组件加载lottie动画时，AnyHeader组件的height必须设置为0，否则列表组件中listHeader位置出会出现异常占位块，而后将Lottie组件包裹在RN的Animated组件中。
4. 代码中lottie-loading.json为lottie动画文件，使用时自行替换为其他lottie动画文件。


```
<FlatList
  data={listData}
  renderItem={({item}) => (
    <View style={styles.item}>
      <Text style={styles.itemText}>{item.text}</Text>
    </View>
  )}
  bounces={false}
  keyExtractor={item => item.id}
  refreshControl={
    <SmartRefreshControl
      ref={smartRefreshControlRef}
      onRefresh={handleRefresh}
      primaryColor="#f5f5f5"
      headerHeight={REFRESH_HEIGHT}
      HeaderComponent={
        <AnyHeader height={0}>
          <Animated.View style={styles.refreshControl}>
            <LottieView
              source={require('./lottie-loading.json')}
              style={styles.lottie}
              autoPlay
              loop
            />
            <Text style={styles.loadingText}>加载中...</Text>
          </Animated.View>
        </AnyHeader>
      }
    />
  }
/>
```

## 约束与限制

* 本示例支持API Version 20 Release及以上版本。
* 本示例支持HarmonyOS 6.0.0 Release SDK及以上版本。
* 本示例需要使用DevEco Studio 6.0.0 Release及以上版本进行编译运行。

## 权限说明

允许使用Internet网络：[ohos.permission.INTERNET](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/permissions-for-all#ohospermissioninternet)。

## 模块依赖

[@react-native-oh-tpl/react-native-smartrefreshlayout](https://gitee.com/react-native-oh-library/usage-docs/blob/master/zh-cn/react-native-SmartRefreshLayout.md):
^0.6.7-0.2.17。  
[@react-native-ohos/lottie-react-native](https://gitee.com/react-native-oh-library/usage-docs/blob/master/zh-cn/lottie-react-native.md):
^7.2.3-rc.1"。

## 工程目录

```
ReactNativeListRefresh                           // RN工程
├──harmony                                       // harmony工程
│  ├──entry/src/main/cpp                         // native相关配置
│  │  ├──CMakeLists.txt
│  │  └──PackageProvider.cpp
│  └──entry/src/main/ets
│     ├──entryability
│     │  └──EntryAbility.ets
│     ├──entrybackupability
│     │  └──EntryBackupAbility.ets
│     ├──pages
│     │  └──Index.ets                            // harmony侧入口
│     └──RNPackagesFactory.ets
├──App.tsx                                       // 自定义下拉刷新动画示例代码
├──index.js                                      // 入口文件
├──metro.config.js                               // 打包配置
```

## 参考文档

[RNOH使用文档](https://gitcode.com/openharmony-sig/ohos_react_native/blob/master/docs/zh-cn/%E7%8E%AF%E5%A2%83%E6%90%AD%E5%BB%BA.md)  
[@react-native-oh-tpl/react-native-smartrefreshlayout](https://gitee.com/react-native-oh-library/usage-docs/blob/master/zh-cn/react-native-SmartRefreshLayout.md)  
[@react-native-ohos/lottie-react-native](https://gitee.com/react-native-oh-library/usage-docs/blob/master/zh-cn/lottie-react-native.md)