当前位置：首页 > news >正文

arkTs：使用Refresh实现下拉刷新功能（含状态提示与动画控制）

news 2025/8/24 20:49:01

使用Refresh实现下拉刷新功能（含状态提示与动画控制）

1 主要内容说明
- 1.1 关键组件
- 1.2 核心API说明
- 1.3 为什么必须使用 $$this.isRefresh？
- 1.4 Emoji表情字符
2 例子
- 2.1 源码A
- 2.2 源码A运行效果
- - 2.2.1 效果截图
  - 2.2.2 效果视频
3.结语
4.定位日期

1 主要内容说明

在 ArkTS 中使用 Refresh 组件实现下拉刷新功能，并解决一个关键问题：“为何 @State isRefresh = false 无法关闭刷新动画？”。在日常开发中，列表刷新是一种常见且重要的用户交互方式。本文将结合 ArkUI 的 Refresh 组件，通过实际示例，演示如何实现下拉刷新，并探索 refreshing 属性中的 $$ 机制，详解 onRefreshing 与 onStateChange 的配合使用。我们还将自定义刷新头部样式，并动态更新列表数据，最终实现一个完整且可交互的水果列表页面。

1.1 关键组件

Refresh: 下拉刷新组件
List + ForEach: 列表展示
@State: 响应式状态管理
$$this.变量名: 显式通知框架“我需要响应性更新！”

1.2 核心API说明

属性/事件	说明
refreshing	控制是否显示刷新动画，需配合 $$ 使用
onRefreshing	刷新时触发的异步函数
onStateChange	每次状态变化都会触发，适合更新提示信息

1.3 为什么必须使用 $$this.isRefresh？

  // 是否正在刷新，用于控制刷新动画（使用 $$ 绑定到 Refresh）@State isRefresh: boolean = false----------------------------------------------------------------
Refresh({refreshing: $$this.isRefresh,         // 绑定刷新状态builder: this.getRefreshDisplay()     // 自定义刷新状态显示组件}) {}

我们不是已经用了 @State 吗？为什么还要加上 $$？

因为，在 Refresh 的 refreshing 属性中，框架只在组件首次构建时取值。如果之后你修改了 isRefresh = false，但没有用 $$，刷新动画不会重新计算，也不会自动关闭。
$$this.isRefresh 表示“订阅这个变量的变化”，框架会跟踪变化并重新构建 UI。

1.4 Emoji表情字符

代码中的🍎🍌🍇🍍🍉🍒 属于Emoji表情字符。Emoji 是由 Unicode 联盟（Unicode Consortium）统一制定的字符标准，就像汉字、英文字母、标点符号一样，它属于开放标准，不受版权限制。

2 例子

2.1 源码A

/*** Refresh 刷新组件演示示例* - 展示如何使用 Refresh 组件实现下拉刷新* - 使用 $$ 绑定响应式变量，控制刷新动画是否显示*/@Entry
@Component
struct Index {// 列表初始数据@State items: string[] = ['🍎 苹果', '🍌 香蕉', '🍇 葡萄']// 刷新提示文本@State refreshText: string = '默认情况'// 是否正在刷新，用于控制刷新动画（使用 $$ 绑定到 Refresh）@State isRefresh: boolean = false// 当前刷新状态（用于状态判断、显示状态文字）@State refreshStatus: RefreshStatus = RefreshStatus.Inactivebuild() {Column() {// 下拉刷新区域Refresh({refreshing: $$this.isRefresh,         // 绑定刷新状态builder: this.getRefreshDisplay()     // 自定义刷新状态显示组件}) {// 内容区域：一个列表List({ space: 20 }) {ForEach(this.items, (item: string) => {ListItem() {Row() {Text(item).shadow({ radius: 18, color: "#cca", offsetX: 9, offsetY: 9 }).width("100%").height("100%").padding({ left: "5%", right: "5%" }).borderRadius(8)}.width("100%").height("10%").padding({ left: "5%", right: "5%", top: 10, bottom: 10 }).justifyContent(FlexAlign.Center)}})}}.onStateChange((state: RefreshStatus) => {// 当刷新状态发生变化时，更新本地状态this.refreshStatus = state}).onRefreshing(async () => {// 模拟数据刷新：延迟 1.5 秒await new Promise<void>(resolve => setTimeout(resolve, 1500))// 刷新数据：插入新水果项this.items = ['🍍 新鲜菠萝','🍉 西瓜','🍒 樱桃',...this.items]// 手动关闭刷新状态，刷新动画结束this.isRefresh = false}).width("100%").height("100%")}.padding(10)}// 刷新时顶部显示的内容@BuildergetRefreshDisplay() {Row() {LoadingProgress().width(40).aspectRatio(1).color("#fcc") // 粉色加载圈Text(this.getRefreshStatusInfo()) // 动态显示状态信息.fontSize(14).fontColor("#fcc").fontWeight(FontWeight.Bold)}}// 根据当前刷新状态返回提示文字，并赋值给 refreshTextgetRefreshStatusInfo() {switch (this.refreshStatus) {case RefreshStatus.Inactive:return this.refreshText = '默认情况'case RefreshStatus.Drag:return this.refreshText = '继续下拉'case RefreshStatus.OverDrag:return this.refreshText = '松手加载'case RefreshStatus.Refresh:return this.refreshText = '刷新中'case RefreshStatus.Done:return this.refreshText = '刷新完成'default:return "其他状态"}}
}