Harmony

[Harmony] 鸿蒙开源组件pulltorefresh优化

Posted by xiuyuantech on 2025-09-14

PullToRefresh是一款OpenHarmony环境下可用的下拉刷新、上拉加载组件。
支持设置内置动画的各种属性，支持设置自定义动画，支持lazyForEarch的数据作为数据源。
官方代码仓库：https://gitcode.com/openharmony-sig/ohos_pull_to_refresh

背景摘要

产品需求需要一个长列表，支持下拉刷新和加载更多。经过多方搜索找到两个目前使用最广的开源库，一个是官方提供的案例PullToRefresh, 一个是第三方开源库@abner/refresh。
经过我多次调研Demo发现有不少坑，目前这两个都满足不了我们的需求，重新自定义又太耗时间，所以直接在官方库上作修改优化。至于目前这两个库的优缺点后面会作介绍，优化后支持自动刷新和自动加载更多。
视频动画如下：

功能对比

库名 下拉刷新 加载更多 自定义头尾部 下滑进入二楼/半楼功能 缺省页设置（空布局/错误布局 分组吸顶效果 侧滑效果 字段如bigint/number 状态管理
官方pull_to_refresh 仅支持手动刷新，不支持自动刷新 仅支持手动加载更多，不支持触底时自动加载更多 支持 不支持 不支持 不支持 不支持，需要根据List组件来自己实现 不支持，会缺失精度需要根据json-bigint来实现 V1、V2
@abner/refresh 支持手动刷新/自动刷新 支持手动加载更多，不支持触底时自动加载更多 支持 支持 支持 ListView支持 ListView支持 不支持，会缺失精度需要根据json-bigint来实现 V1、V2(有缺陷)
优化pull_to_refresh 支持手动刷新/自动刷新 支持手动加载更多/触底时自动加载更多 支持 不支持 不支持 不支持 不支持，需要根据List组件来实现 不支持，会缺失精度需要根据json-bigint来实现 V1、V2

如何使用

  • 优化过的pull_to_refresh下载地址：ohos_pull_to_refresh。

  • 将下载好的包解压后重命名为pulltorefresh，然后直接作为moudle引入项目根目录中
    在build-profile.json5中的moudles字段添加{ 'name':'pulltorefresh', 'srcPath':'./pulltorefresh' },然后在oh-package.json5中的dependencies字段添加@ohos/pulltorefresh:'file:./pulltorefresh'。

  • 在使用的地方导入需要的包，如import { PullToRefreshV2 } from '@ohos/pulltorefresh。

  • 设置自动刷新和自动加载更多，PullToRefreshV2({ refreshConfigurator: new PullToRefreshConfigurator().setAutoRefresh(true).setAutoLoadMore() }), 触底自动加载需要在List组件onReachEnd方法中调用this.getUIContext().getHostContext()?.eventHub.emit(''autoLoadMore'),其他使用方法参考官方Demo。

  • 引入json-bigint，解决bigint/number精度缺失问题。

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    //关键代码
    axios.create({
      ...
      transformRespose:[{
        (data:ESObject): ESObject => {
          try{
              return JSONbig.parse(data)
            }catch(err){
             return data
            }
        }
      }],
    })

如果包解压后重命名为xxx，则build-profile.json5中的moudles字段和oh-package.json5中的dependencies字段需要作对应的修改xxx。

官方链接

类型 地址
开源代码仓库 https://gitee.com/openharmony
项目官网 https://www.openharmony.cn
开发者平台 https://developer.harmonyos.com
三方库中心仓 https://ohpm.openharmony.cn

总结建议

  • 简单场景‌：优先选择原生Refresh组件，减少第三方依赖。

  • 复杂需求‌：若需上拉加载或特殊动效，可根据需要评估本站优化过的 ohos_pull_to_refresh 和 @abner/refresh v1版。

FEATURED TAGS
Harmony
FRIENDS