【鸿蒙优选三方库】@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 数据源。

---

二、核心特点

特性	说明
双版本组件	PullToRefresh（@Component）+ PullToRefreshV2（@ComponentV2）
5 大容器支持	List / Scroll / Tabs / Grid / WaterFlow
自定义动画	替换内置 Refresh / LoadMore 动画，或完全自定义视图
LazyForEach 兼容	完美适配懒加载数据源
Promise 回调	onRefresh / onLoadMore 返回 Promise，结束时机可控
零权限	纯 UI 组件，无需任何权限

---

三、适用场景

• 新闻/资讯/Feed 流：下拉刷新最新内容，上拉加载历史。
• 电商商品列表：下拉刷新推荐，上拉加载更多商品。
• 聊天/消息列表：下拉刷新新消息。
• 订单/物流列表：下拉刷新订单状态。
• 视频/图片瀑布流：WaterFlow + 上拉加载。
• 多 Tab 切换：Tabs + 每个 Tab 独立的下拉刷新与加载。
• 任何需要分页加载的长列表场景。

---

四、快速上手

1. 安装

ohpm install @ohos/pulltorefresh

2. PullToRefresh（@Component 写法）

import { PullToRefresh } from '@ohos/pulltorefresh'

@Entry
@Component
struct RefreshList {
  private scroller: Scroller = new Scroller()
  @State data: string[] = ['Item 1', 'Item 2', 'Item 3']

  build() {
    PullToRefresh({
      // 必传：列表数据
      data: $data,
      // 必传：列表容器
      scroller: this.scroller,
      // 必传：自定义主体布局
      customList: () => {
        this.getListView()
      },
      // 可选：下拉刷新回调
      onRefresh: () => {
        return new Promise<string>((resolve) => {
          setTimeout(() => {
            this.data = ['New 1', 'New 2', 'New 3']
            resolve('刷新成功')
          }, 2000)
        })
      },
      // 可选：上拉加载更多回调
      onLoadMore: () => {
        return new Promise<string>((resolve) => {
          setTimeout(() => {
            this.data.push(`新增条目 ${this.data.length}`)
            resolve('')
          }, 2000)
        })
      }
    })
  }

  @Builder
  getListView() {
    List({ scroller: this.scroller }) {
      ForEach(this.data, (item: string) => {
        ListItem() {
          Text(item).height(60).padding(12)
        }
      }, (item: string) => item)
    }
    .edgeEffect(EdgeEffect.None) // ⚠️ 必需设置
  }
}

3. PullToRefreshV2（@ComponentV2 写法）

import { PullToRefreshV2 } from '@ohos/pulltorefresh'

@Entry
@ComponentV2
struct V2Demo {
  private scroller: Scroller = new Scroller()
  @Local data: string[] = []

  build() {
    PullToRefreshV2({
      data: this.data,
      scroller: this.scroller,
      customList: () => { this.listView() },
      onRefresh: () => { /* ... */ },
      onLoadMore: () => { /* ... */ }
    })
  }

  @Builder
  listView() {
    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 组件，无任何系统权限要求。

---

六、使用限制（必读）

1. ✅ 支持：List / Scroll / Tabs / Grid / WaterFlow
2. ⚠️ 必须设置容器 edgeEffect(EdgeEffect.None)（暂不支持系统弹簧/阴影）
3. ❌ 暂不支持页面触底自动触发上拉
4. ❌ 暂不支持不满一屏时触发上拉
5. ❌ 暂不支持代码方式触发下拉刷新
6. ❌ 暂不提供手势结束回调

---

七、为什么值得选它？

1. 覆盖面广：5 大容器一次搞定，Tabs 多 Tab 列表也能轻松应对。
2. 双版本组件：新老 ArkUI 写法都支持。
3. LazyForEach 友好：长列表性能不受影响。
4. 动画可定制：内置够用，也可以完全自定义。
5. 零依赖零权限：装上即用，无系统负担。

如果你的应用里有任何"滚动 + 分页"的列表场景，@ohos/pulltorefresh 是那个让你 5 分钟搞定刷新的利器。