【鸿蒙优选三方库】@ohos/pulltorefresh：一行给鸿蒙列表加上下拉刷新与上拉加载

【鸿蒙优选三方库】ohos/pulltorefresh一行给鸿蒙列表加上下拉刷新与上拉加载给 List / Scroll / Tabs / Grid / WaterFlow 一行加上下拉刷新 上拉加载ohos/pulltorefresh基于 OpenHarmony ArkUI 打造开箱即用、支持自定义动画、完美适配LazyForEach数据源——做列表类应用的必备利器。包名ohos/pulltorefresh当前版本v2.1.4-rc.0协议Apache License 2.0安装ohpm install ohos/pulltorefresh仓库https://gitcode.com/CPF-ApplicationTPC/ohos_pull_to_refresh一、它解决了什么问题鸿蒙应用做列表离不开两个高频交互下拉刷新上拉加载更多。但 ArkUI 原生的List/Scroll组件本身不带这套交互能力开发者要么自己监听手势 写动画重复造轮子找三方方案却发现兼容性差不支持LazyForEach、不支持某些容器组件上拉/下拉体验不一致、与系统风格割裂。ohos/pulltorefresh提供即插即用的 PullToRefresh / PullToRefreshV2 组件5 大系统容器全覆盖List / Scroll / Tabs / Grid / WaterFlow自定义动画支持替换内置动画、接自定义 Refresh 视图完美适配LazyForEach数据源。二、核心特点特性说明双版本组件PullToRefreshComponentPullToRefreshV2ComponentV25 大容器支持List / Scroll / Tabs / Grid / WaterFlow自定义动画替换内置 Refresh / LoadMore 动画或完全自定义视图LazyForEach 兼容完美适配懒加载数据源Promise 回调onRefresh/onLoadMore返回 Promise结束时机可控零权限纯 UI 组件无需任何权限三、适用场景新闻/资讯/Feed 流下拉刷新最新内容上拉加载历史。电商商品列表下拉刷新推荐上拉加载更多商品。聊天/消息列表下拉刷新新消息。订单/物流列表下拉刷新订单状态。视频/图片瀑布流WaterFlow 上拉加载。多 Tab 切换Tabs 每个 Tab 独立的下拉刷新与加载。任何需要分页加载的长列表场景。四、快速上手1. 安装ohpminstallohos/pulltorefresh2. PullToRefreshComponent 写法import{PullToRefresh}fromohos/pulltorefreshEntryComponentstruct RefreshList{privatescroller:ScrollernewScroller()Statedata:string[][Item 1,Item 2,Item 3]build(){PullToRefresh({// 必传列表数据data:$data,// 必传列表容器scroller:this.scroller,// 必传自定义主体布局customList:(){this.getListView()},// 可选下拉刷新回调onRefresh:(){returnnewPromisestring((resolve){setTimeout((){this.data[New 1,New 2,New 3]resolve(刷新成功)},2000)})},// 可选上拉加载更多回调onLoadMore:(){returnnewPromisestring((resolve){setTimeout((){this.data.push(新增条目${this.data.length})resolve()},2000)})}})}BuildergetListView(){List({scroller:this.scroller}){ForEach(this.data,(item:string){ListItem(){Text(item).height(60).padding(12)}},(item:string)item)}.edgeEffect(EdgeEffect.None)// ⚠️ 必需设置}}3. PullToRefreshV2ComponentV2 写法import{PullToRefreshV2}fromohos/pulltorefreshEntryComponentV2struct V2Demo{privatescroller:ScrollernewScroller()Localdata:string[][]build(){PullToRefreshV2({data:this.data,scroller:this.scroller,customList:(){this.listView()},onRefresh:(){/* ... */},onLoadMore:(){/* ... */}})}BuilderlistView(){List({scroller:this.scroller}){ForEach(this.data,(item:string){ListItem(){Text(item).height(60)}},(item:string)item)}.edgeEffect(EdgeEffect.None)}}4. 自定义动画PullToRefresh({// ...customLoad:null,// 用 null 使用内置或传自定义组件customRefresh:null,// 同上})// 完全自定义传入自定义 Builder 替换内置动画PullToRefresh({customRefresh:(){this.myCustomRefreshView()},customLoad:(){this.myCustomLoadView()}})五、亮点能力速览双版本组件兼容Component旧写法与ComponentV2新写法按项目风格选用。5 大容器支持List / Scroll / Tabs / Grid / WaterFlow 全覆盖。LazyForEach 友好完美适配懒加载数据源长列表性能不打折。Promise 回调onRefresh/onLoadMore返回 Promise组件内部根据 Promise resolve 状态收/放动画。可定制动画内置精美动画也允许完全自定义。零权限纯 UI 组件无任何系统权限要求。六、使用限制必读✅ 支持List / Scroll / Tabs / Grid / WaterFlow⚠️必须设置容器edgeEffect(EdgeEffect.None)暂不支持系统弹簧/阴影❌ 暂不支持页面触底自动触发上拉❌ 暂不支持不满一屏时触发上拉❌ 暂不支持代码方式触发下拉刷新❌ 暂不提供手势结束回调七、为什么值得选它覆盖面广5 大容器一次搞定Tabs 多 Tab 列表也能轻松应对。双版本组件新老 ArkUI 写法都支持。LazyForEach 友好长列表性能不受影响。动画可定制内置够用也可以完全自定义。零依赖零权限装上即用无系统负担。如果你的应用里有任何滚动 分页的列表场景ohos/pulltorefresh是那个让你 5 分钟搞定刷新的利器。