鸿蒙应用开发：Refresh + List 下拉刷新组件使用教程

程序员黑黑

34人浏览 · 2026-06-28 09:00:00

程序员黑黑 · 2026-06-28 09:00:00 发布

文章目录

一、引言

在鸿蒙应用开发中，下拉刷新是一个非常常见的交互场景，用于让用户手动触发数据更新。HarmonyOS 提供了 Refresh 组件，可以非常方便地与 List 等滚动容器组件配合，实现优雅的下拉刷新效果。

本文将通过一个简单的实例，带你快速掌握 Refresh 组件的基本用法。

二、效果预览

下拉刷新组件实现的效果如下：当用户向下拖动列表时，顶部会出现一个刷新区域，显示“下拉刷新中。。。”等提示信息，并在数据加载完成后自动收起。

在这里插入图片描述

三、核心组件与属性

3.1 Refresh 组件

Refresh 是一个容器组件，用于包裹可滚动的子组件（如 List、Scroll 等），为其提供下拉刷新的能力。

3.2 关键属性与方法

refreshing：布尔类型，表示组件当前是否处于刷新状态。需要使用 @State 声明一个状态变量，并通过 $$ 双向绑定语法进行绑定。
onRefresh：回调方法，当用户下拉触发刷新时执行。通常在这里发起网络请求或模拟数据加载。
customRefreshContent：自定义刷新区域显示的内容，默认显示“下拉刷新中”，你可以替换为文本、图片或其他自定义组件。

四、完整代码示例

下面是一个完整的示例代码，展示了如何使用 Refresh 组件配合 List 实现下拉刷新。

@Entry
@Component
struct RefreshDemo {
  @State isRefreshing: boolean = false;
  private items: string[] = ['Item 1', 'Item 2', 'Item 3', 'Item 4', 'Item 5'];

  @Builder
  CustomBuilder() {
    Text("下拉刷新中。。。")
      .width("100%")
      .height(50)
      .textAlign(TextAlign.Center)
  }

  build() {
    Column() {
      Refresh({ refreshing: $$this.isRefreshing, promptText: "下拉刷新中。。。", builder: this.CustomBuilder}) {
        List() {
          ForEach(this.items, (item: string) => {
            ListItem() {
              Text(item)
                .width('100%')
                .height(80)
                .textAlign(TextAlign.Center)
                .backgroundColor(Color.White)
                .borderRadius(8)
                .margin({ top: 8 })
            }
          })
        }
        .width('100%')
        .height('100%')
      }
      .onRefreshing(() => {
        // 模拟网络请求
        setTimeout(() => {
          this.isRefreshing = false;
        }, 2000);
      })
    }
    .width('100%')
    .height('100%')
    .backgroundColor('#F5F5F5')
    .padding(16)
  }
}

五、代码详解

5.1 状态变量与双向绑定

@State isRefreshing: boolean = false;

使用 @State 声明一个布尔类型的状态变量 isRefreshing，初始值为 false，表示当前不在刷新状态。
在 Refresh 组件的构造参数中，通过 refreshing: $$this.isRefreshing 进行双向绑定。当用户下拉时，系统会自动将 isRefreshing 改为 true；当数据加载完成后，你需要手动将其改回 false，刷新动画才会收起。

5.2 刷新回调

.onRefreshing(() => {
  setTimeout(() => {
    this.isRefreshing = false;
  }, 2000);
})

.onRefreshing() 是 Refresh 组件的链式回调方法，当用户下拉触发刷新时执行。注意实际代码中它是通过链式调用 .onRefreshing() 设置的，而不是构造参数中的 onRefresh 属性。
在回调中，我们使用 setTimeout 模拟了一个耗时 2 秒的网络请求。
请求完成后，将 isRefreshing 设置为 false，通知组件刷新结束。

5.3 自定义刷新内容

@Builder
CustomBuilder() {
  Text("下拉刷新中。。。")
    .width("100%")
    .height(50)
    .textAlign(TextAlign.Center)
}

通过 @Builder 装饰器定义了一个名为 CustomBuilder 的自定义构建函数，用于定制刷新区域的显示内容。
在 Refresh 构造参数中，通过 builder: this.CustomBuilder 传入该构建函数。
如果只是想显示文本，并不想过多定制刷新区域显示内容，可以使用 promptText 设置提示文本，此时可以去掉 builder: this.CustomBuilder。
你也可以在 CustomBuilder 中放入 Image 组件显示加载动画图标，或者更复杂的布局，实现更丰富的刷新提示效果。