【鸿蒙优选三方库】@ohos/pulltorefresh:给列表加上刷新,只需一个回调
·
【鸿蒙优选三方库】@ohos/pulltorefresh:给列表加上刷新,只需一个回调> ArkUI 的 List 不带下拉刷新——要自己监听手势、写动画、管状态,还要处理和系统 edgeEffect 弹簧效果的冲突。@ohos/pulltorefresh 一个组件包住列表,onRefresh 返回一个 Promise,剩下的它全包了。> 📦 仓库地址 | ohpm install @ohos/pulltorefresh | v2.1.4-rc.0 | Apache-2.0—## 它解决什么问题信息流、商品列表、聊天记录——只要是有分页的长列表,就离不开"下拉刷新 + 上拉加载"。这套交互在微信、微博、淘宝里都是标配,用户已经形成肌肉记忆。但 ArkUI 原生容器不提供这个能力。自己实现要处理:手势识别与冲突、刷新动画的展开收起、加载状态的边界、和系统弹簧效果的打架。每个列表都要重复一遍。@ohos/pulltorefresh 把它组件化了:包住你的列表,传两个回调,完事。—## 核心能力| 能力 | 说明 ||------|------|| 双版本组件 | PullToRefresh(@Component)+ PullToRefreshV2(@ComponentV2) || 五大容器 | List / Scroll / Tabs / Grid / WaterFlow || Promise 回调 | onRefresh / onLoadMore 返回 Promise,控制动画收起时机 || 自定义动画 | 替换内置 Refresh / LoadMore 视图 || LazyForEach 兼容 | 长列表懒加载性能不打折 || 零权限 | 纯 UI 组件 |—## 30 秒上手bashohpm install @ohos/pulltorefresh``````typescriptimport { PullToRefresh } from '@ohos/pulltorefresh'@Entry@Componentstruct ListPage { private scroller: Scroller = new Scroller() @State data: string[] = ['Item 1', 'Item 2', 'Item 3'] build() { PullToRefresh({ data: $data, // 必传:列表数据 scroller: this.scroller, // 必传:列表容器 customList: () => { this.listView() }, // 必传:主体布局 onRefresh: () => new Promise<string>((resolve) => { fetchData().then((d) => { this.data = d; resolve('刷新成功') }) .catch(() => resolve('')) // ✅ 失败也要 resolve }), onLoadMore: () => new Promise<string>((resolve) => { fetchMore().then((m) => { this.data = this.data.concat(m); resolve('') }) .catch(() => resolve('')) }), }) } @Builder listView() { List({ scroller: this.scroller }) { ForEach(this.data, (item: string) => { ListItem() { Text(item).height(60).padding(12) } }, (item: string) => item) } .edgeEffect(EdgeEffect.None) // ⚠️ 必须设为 None }}三条铁律(记住就不会出问题):1. onRefresh / onLoadMore 必须提供,即使不需要也要给 () => Promise.resolve('')2. 回调必须返回 Promise,不能是 void 函数3. 请求失败也要 resolve,不要 reject 或不管组件靠 Promise 的 resolve 决定何时收起动画——不返回 Promise 或永不 resolve,就会卡在刷新态或提示"刷新失败"。—## 社区已解决的典型问题BindSheet 页面下拉刷新提示"刷新失败"(#182)在半模态弹窗(BindSheet)里使用时,缺失 onRefresh 回调导致下拉后提示刷新失败。已修复。弹窗场景特别容易漏配回调——开发时注意力都在弹窗本身。记住三条铁律就不会踩。代码健壮性优化(#174)处理代码检视发现的边界条件与异常处理问题,完成系统性质量加固。升级到最新版可获得这些改进。版本迭代(#171 → #178 → #183)2.1.3 → 3.0.2 → 3.0.3,迭代活跃。从 2.x 升到 3.x 注意 API 变化并重新测试,生产环境优先用正式版而非 rc。—## 使用限制(必读)这些不是 bug,是设计边界:| 限制 | 说明 | 应对 ||------|------|------|| ✅ 容器范围 | List / Scroll / Tabs / Grid / WaterFlow | 其他容器需自行封装 || ⚠️ edgeEffect | 必须设为 EdgeEffect.None | 忘记设会和弹簧效果冲突 || ❌ 触底自动加载 | 暂不支持 | 需用户主动上拉手势 || ❌ 不满一屏加载 | 暂不支持 | 首屏数据要足够多 || ❌ 代码触发刷新 | 暂不支持 | 进页面时自行调数据加载函数 || ❌ 手势结束回调 | 暂不提供 | 用 Promise resolve 时机替代 |"代码触发刷新"的替代方案:typescript// ❌ 不支持:programmatically 触发刷新动画// controller.triggerRefresh()// ✅ 替代:进页面时静默加载数据aboutToAppear() { this.loadProducts() }—## 适合谁用- 信息流 / 资讯:下拉刷新最新内容,上拉加载历史- 电商商品列表:刷新推荐、加载更多商品- 聊天 / 消息列表:下拉刷新新消息- 订单 / 物流:刷新状态- 瀑布流:WaterFlow + 上拉加载- 多 Tab 场景:每个 Tab 独立刷新167 个 Issue 已关闭。这个库的价值在于把一件每个列表都要做的事标准化了——三条铁律记住,五分钟集成,之后再也不用为刷新交互写一行手势代码。
更多推荐




所有评论(0)