#跟着若城学鸿蒙# UI组件篇-Refresh及其属性

Huang兄

498人浏览 · 2025-05-18 00:57:28

Huang兄 · 2025-05-18 00:57:28 发布

前言

在现代移动应用开发中，用户体验至关重要。下拉刷新作为一种常见的交互方式，能够让用户通过简单的下拉动作刷新页面内容，提升应用的响应性和互动性。ArkUI 作为华为推出的新一代 UI 开发框架，提供了强大的 Refresh 组件，用于实现下拉刷新功能。本文将详细介绍 ArkUI 中的 Refresh 组件，包括其基本用法、高级配置、事件处理、性能优化以及在实际项目中的应用示例。

Refresh 组件的基本用法

组件定义

Refresh 组件是一个可支持下拉刷新操作的容器组件，通常包裹在需要刷新的内容外部。其基本用法如下：

import { Component, Entry, State } from '@kit.ArkUI';

@Entry
@Component
struct RefreshExample {
  @State isRefreshing: boolean = false;

  build() {
    Column() {
      Refresh({ refreshing: this.isRefreshing }) {
        List() {
          ForEach(this.data, (item) => {
            ListItem() {
              Text(item)
            }
          })
        }
      }
    }
  }
}

在上述示例中，Refresh 组件包裹了一个 List 组件，当用户下拉时，isRefreshing 状态变量会被设置为 true，从而触发刷新动画。

属性配置

Refresh 组件支持多种属性配置，以满足不同的需求：

refreshing: 布尔值，表示当前是否处于刷新状态。
offset: 数值或字符串，表示下拉起点距离组件顶部的距离，默认值为 16vp。
friction: 数值或字符串，表示下拉摩擦系数，取值范围为 0 到 100，默认值为 62。
builder: 自定义刷新区域显示内容。
promptText: 设置刷新区域底部显示的自定义文本。
refreshingContent: 自定义刷新区域显示内容。

自定义刷新区域内容

通过 builder 或 refreshingContent 属性，可以自定义刷新区域的显示内容。例如，可以显示一个加载动画或自定义的提示信息：

@Builder
function CustomRefreshContent() {
  Stack() {
    Row() {
      LoadingProgress().height(32)
      Text('Refreshing...').fontSize(16).margin({ left: 20 })
    }.alignItems(VerticalAlign.Center)
  }.align(Alignment.Center).clip(true).constraintSize({ minHeight: 32 }).width('100%')
}

@Entry
@Component
struct RefreshExample {
  @State isRefreshing: boolean = false;

  build() {
    Column() {
      Refresh({ refreshing: this.isRefreshing, builder: CustomRefreshContent }) {
        List() {
          ForEach(this.data, (item) => {
            ListItem() {
              Text(item)
            }
          })
        }
      }
    }
  }
}

自定义刷新动画

可以通过自定义组件和动画效果，实现更具个性化的刷新动画。例如，可以使用 ArkUI 提供的动画 API 来创建复杂的动画效果：

@Builder
function AnimatedRefreshContent() {
  Animation.animate(this.animationState, {
    from: { opacity: 0, scale: 0.5 },
    to: { opacity: 1, scale: 1 },
    duration: 500,
    easing: AnimationCurve.EaseInOut
  }).onFinish(() => {
    this.animationState = { opacity: 1, scale: 1 };
  });
  Stack() {
    Row() {
      LoadingProgress().height(32)
      Text('Refreshing...').fontSize(16).margin({ left: 20 })
    }.alignItems(VerticalAlign.Center).opacity(this.animationState.opacity).scale(this.animationState.scale)
  }.align(Alignment.Center).clip(true).constraintSize({ minHeight: 32 }).width('100%')
}

@Entry
@Component
struct RefreshExample {
  @State isRefreshing: boolean = false;
  @State animationState: { opacity: number, scale: number } = { opacity: 0, scale: 0.5 };

  build() {
    Column() {
      Refresh({ refreshing: this.isRefreshing, builder: AnimatedRefreshContent }) {
        List() {
          ForEach(this.data, (item) => {
            ListItem() {
              Text(item)
            }
          })
        }
      }
    }
  }
}

性能优化

在使用 Refresh 组件时，需要注意性能优化，以确保刷新过程的流畅性和响应性。以下是一些性能优化的建议：

减少不必要的渲染

避免在刷新过程中频繁更新状态变量，以减少不必要的渲染。可以使用 @Watch 装饰器来监听状态变量的变化，仅在必要时更新 UI。

@Watch('isRefreshing') onRefreshingChanged(newValue: boolean) { if (newValue) { // 执行刷新逻辑 } }

实际应用示例

示例 1：下拉刷新新闻列表

以下示例展示了如何使用 Refresh 组件实现下拉刷新新闻列表的功能：

import { Component, Entry, State } from '@kit.ArkUI';

@Entry
@Component
struct NewsList {
  @State isRefreshing: boolean = false;
  @State news: string[] = [];

  build() {
    Column() {
      Refresh({ refreshing: this.isRefreshing, }) {
        List() {
          ForEach(this.news, (item) => {
            ListItem() {
              Text(item)
            }
          })
        }
      }.onRefreshing: () => {
        this.fetchNews();
      }
    }
  }

  fetchNews() {
    // 模拟网络请求
    setTimeout(() => {
      this.news = ['新闻1', '新闻2', '新闻3'];
      this.isRefreshing = false;
    }, 2000);
  }
}
}

示例 2：下拉刷新图片列表

以下示例展示了如何使用 Refresh 组件实现下拉刷新图片列表的功能：

import { Component, Entry, State } from '@kit.ArkUI';

@Entry
@Component
struct ImageList {
  @State isRefreshing: boolean = false;
  @State images: string[] = [];

  build() {
    Column() {
      Refresh({
        refreshing: this.isRefreshing,
      }) {
        Grid() {
          ForEach(this.images, (item) => {
            GridItem() {
              Image(item).width(100).height(100)
            }
          })
        }
      }.onRefreshing(() => {
        this.fetchImages()
        console.log('onRefreshing test');
      })
    }
  }

  fetchImages() {
    // 模拟网络请求
    setTimeout(() => {
      this.images = ['image1.jpg', 'image2.jpg', 'image3.jpg'];
      this.isRefreshing = false;
    }, 2000);
  }
}
}