鸿蒙新特性——Refresh 下拉刷新组件详解

一、引言在移动应用中下拉刷新是最核心的交互模式之一。无论是微博首页的最新动态、微信朋友圈的新鲜内容、还是资讯 App 的实时新闻用户都习惯性地下滑列表顶部期待看到最新的数据更新。下拉→加载→新内容出现这个流畅的动作序列已经成为移动端内容消费的肌肉记忆。然而实现下拉刷新并非简单地在列表顶部挂一个加载动画。开发者需要精确处理下拉距离与视觉反馈的对应关系下拉多远才触发刷新回弹动画如何衔接、刷新状态管理空闲→拖动→刷新中→完成→重置、手势冲突列表自身的滚动与下拉手势如何区分、以及多场景适配列表为空时要不要显示刷新网络失败时如何提示。而 HarmonyOS 提供了Refresh组件——一个专用于下拉刷新的容器组件。它包裹在列表内容外层自动处理手势识别、回弹动画和加载状态切换。开发者只需声明refreshing状态通过$$双向绑定并在onRefreshing回调中执行数据加载逻辑即可获得完整的下拉刷新体验。本文通过一个动态资讯Demo 深入讲解 Refresh 组件的核心用法如何创建下拉刷新列表refreshing状态如何通过$$双向绑定onRefreshing回调如何配合数据加载以及如何实现手动刷新、展开详情等完整交互。阅读完本文你将能够使用 Refresh 组件实现下拉刷新功能使用$$双向绑定管理 refreshing 状态在onRefreshing回调中执行异步数据加载将 Refresh 与 List 组件结合构建资讯流实现手动刷新按钮作为下拉刷新的补充交互二、Refresh 组件 API 总览2.1 构造函数Refresh(options:RefreshOptions){// 子内容通常是一个 List、Grid 或 Scroll}interfaceRefreshOptions{refreshing:boolean;// 当前的刷新状态}参数类型说明refreshingbooleantrue 时显示刷新动画loading 旋转图标false 时隐藏。通常使用$$前缀实现双向绑定$$是 ArkUI 提供的双向绑定语法糖格式为$$this.stateVar。它同时完成了两件事将stateVar的值传递给组件以及当组件内部改变该值时自动同步回stateVar。在 Refresh 中用户下拉超过阈值时组件会自动将refreshing设为 true数据加载完成后开发者手动将其设回 false。2.2 链式方法// 刷新状态变化回调用户下拉触发时调用.onRefreshing(callback:()void):RefreshAttribute// 刷新状态变化包含完整的生命周期状态.onStateChange(callback:(state:RefreshStatus)void):RefreshAttribute// 下拉触发阈值距离vp.offset(value:number|string|Resource):RefreshAttribute// 自定义下拉时的显示内容.refreshContent(content:()void):RefreshAttribute方法说明.onRefreshing(Callback)下拉触发的回调。在此回调中执行数据加载网络请求、数据库查询等完成后将 refreshing 设回 false.onStateChange(CallbackRefreshStatus)刷新状态的完整生命周期回调包含 Drag拖动、Refreshing刷新中、Done完成三种状态。用于更细粒度的 UI 反馈如释放立即刷新文案切换.offset(number)下拉触发阈值单位 vp。默认值约为 64vp。设置越大需要下拉越深才触发刷新.refreshContent(CustomBuilder)完全自定义下拉区域的显示内容替代默认的 loading 旋转图标。可嵌入自定义图标、文字提示等2.3 RefreshStatus 枚举enumRefreshStatus{Inactive,// 未激活空闲状态Drag,// 正在拖动下拉中未达阈值OverDrag,// 超过阈值可释放触发刷新Refresh,// 正在刷新加载动画显示中Done// 刷新完成}状态说明UI 反馈示例Inactive空闲列表未下拉无特殊指示Drag正在下拉未超过阈值“下拉刷新” 文字OverDrag超过阈值松手即触发“释放立即刷新” 文字 箭头翻转动画Refresh正在加载数据loading 旋转图标 “加载中…”Done加载完成即将收起loading 消失内容区域回弹Demo 中使用了onRefreshing核心回调管理加载逻辑考虑到 Demo 的简洁性未使用onStateChange。对于需要松手刷新提示文案的产品级应用建议使用onStateChange监听 Drag 和 OverDrag 状态。2.4 Refresh 与手动刷新按钮的配合Refresh 组件的refreshing状态默认为 false。当开发者通过代码设置this.isRefreshing true例如点击手动刷新按钮即使没有下拉手势Refresh 组件也会进入刷新状态显示 loading 动画等待加载完成后设回 false。这意味着一套刷新逻辑doRefresh()方法可以同时服务于两个触发源下拉手势通过onRefreshing回调调用和手动按钮通过onClick直接调用。这是 Demo 中的关键设计——用户既可以通过下拉刷新获取最新资讯也可以点击顶部手动刷新按钮触发加载。三、Demo 设计动态资讯3.1 功能概述Demo 是一个动态资讯应用模拟资讯类 App 的新闻信息流资讯列表15 条预置新闻内容池每次加载随机抽取。每条新闻包含分类标签、来源、发布时间、标题和摘要下拉刷新下拉列表顶部触发刷新loading 1.5 秒后新增 3 条随机新闻插入列表头部手动刷新顶部状态栏手动刷新按钮触发相同加载逻辑上次刷新时间每次刷新后更新时间格式为HH:MM展开/收起详情点击展开全文查看新闻摘要点击收起折叠列表滚动Refresh 包裹的 List 支持完整滚动交互3.2 交互点#交互说明1下拉刷新下滑列表顶部触发 onRefreshing → 加载 3 条新资讯 → 插入列表头部2手动刷新点击手动刷新按钮同样触发加载逻辑更新刷新时间3展开详情点击新闻卡片展开全文→ 显示完整摘要 → 收起折叠4滚动浏览List 中滚动浏览全部资讯分类标签和文章来源辅助筛选四、完整代码实现4.1 数据模型与状态interfaceNewsItem{id:number;title:string;summary:string;source:string;time:string;category:string;catColor:string;}StateisRefreshing:booleanfalse;StatelastRefreshTime:string暂无;StatenewsList:NewsItem[][];StateexpandedId:number-1;privatenewsPool:NewsItem[][];// 15 条预置新闻NewsItem包含新闻的完整信息标题、摘要展开后显示、来源、发布时间、分类带颜色标签。newsPool存储全部 15 条预置新闻作为数据池newsList是当前显示的列表初始 5 条随机新闻。expandedId记录当前展开的新闻 ID-1 表示无展开。4.2 Refresh 包裹 ListRefresh({refreshing:$$this.isRefreshing}){List(){ForEach(this.newsList,(news:NewsItem,idx:number){ListItem(){Column(){Row(){Text(news.category).fontSize(10).fontColor(#FFFFFF).fontWeight(FontWeight.Bold).padding({top:2,bottom:2,left:6,right:6}).borderRadius(4).backgroundColor(news.catColor)Text(news.source).fontSize(11).fontColor(#BBBBCC).margin({left:8})Blank()Text(news.time).fontSize(11).fontColor(#BBBBCC)}.width(100%)Text(news.title).fontSize(16).fontColor(#1a1a2e).fontWeight(FontWeight.Medium).maxLines(2).textOverflow({overflow:TextOverflow.Ellipsis}).width(100%).margin({top:10,bottom:this.expandedIdnews.id?10:6})if(this.expandedIdnews.id){Text(news.summary).fontSize(13).fontColor(#666677).lineHeight(20).width(100%).margin({bottom:10})}Row(){Text(this.expandedIdnews.id?收起:展开全文).fontSize(11).fontColor(#1677FF).fontWeight(FontWeight.Medium).onClick((){this.toggleExpand(news.id);})}}.width(100%).padding({left:Spacing.LG,right:Spacing.LG,top:14,bottom:14})}.border({width:{bottom:0.5},color:#F2F3F5})},(news:NewsItem,idx:number)news.id.toString())}.width(100%).height(100%).scrollBar(BarState.Off)}.onRefreshing((){this.doRefresh();})逐行解析Refresh({ refreshing: $$this.isRefreshing })$$双向绑定isRefreshing状态。用户下拉超过阈值时组件自动将isRefreshing设为 true触发 loading 动画加载完成后开发者将isRefreshing设回 falseList()Refresh 内部包裹一个 List 组件作为可滚动内容。List 每项是ListItem()通过ForEach从newsList数据数组生成.onRefreshing(() { this.doRefresh(); })下拉触发回调调用doRefresh()执行数据加载展开/收起逻辑expandedId记录当前展开项toggleExpand()切换expandedId。展开时显示news.summary约 80~100 字摘要折叠时仅显示标题4.3 数据加载逻辑doRefresh():void{this.isRefreshingtrue;setTimeout((){constfreshNewsthis.randomNews(3);constnewList:NewsItem[][];for(leti0;ifreshNews.length;i){newList.push(freshNews[i]);}for(leti0;ithis.newsList.length;i){newList.push(this.newsList[i]);}this.newsListnewList;constnownewDate();this.lastRefreshTimenow.getHours().toString().concat(:,now.getMinutes().toString().length1?0.concat(now.getMinutes().toString()):now.getMinutes().toString());this.isRefreshingfalse;},1500);}doRefresh()是核心加载方法既由onRefreshing回调触发下拉手势也由手动刷新按钮的onClick触发设置刷新状态this.isRefreshing true激活 loading 动画模拟网络请求setTimeout延迟 1.5 秒模拟网络加载延迟随机抽取新内容randomNews(3)从 15 条预置新闻中随机抽取 3 条不重复的新闻插入列表头部将新 3 条新闻放在newList头部原有内容拼接在后newList.push(this.newsList[i])更新刷新时间获取当前时间的HH:MM格式处理分钟补零如 9:05结束刷新this.isRefreshing false关闭 loading 动画Refresh 组件自动播放回弹动画需要注意数组更新遵循 ArkUI 的不可变数据模式——创建新的数组newList而非修改原数组确保State能检测到变化并触发 UI 更新。4.4 手动刷新按钮Row(){Text(上次刷新.concat(this.lastRefreshTime)).fontSize(11).fontColor(#9999AA)Blank()Text(手动刷新).fontSize(11).fontColor(#1677FF).fontWeight(FontWeight.Medium).padding({top:3,bottom:3,left:10,right:10}).borderRadius(10).backgroundColor(#EEF3FF).onClick((){this.doRefresh();})}.width(100%).height(36).padding({left:Spacing.LG,right:Spacing.LG}).backgroundColor(#F2F3F5)状态栏左侧显示上次刷新HH:MM提供时间参考右侧手动刷新按钮直接调用doRefresh()。这展示了 Refresh 组件的一个重要特性刷新逻辑与触发方式解耦。同一个doRefresh()方法通过下拉手势触发和按钮点击触发都能正确工作——因为$$双向绑定确保了两种触发路径下isRefreshing状态的一致性。4.5 新闻展开/折叠toggleExpand(id:number):void{if(this.expandedIdid){this.expandedId-1;// 收起清除展开状态}else{this.expandedIdid;// 展开记录当前展开项}}toggleExpand()实现手风琴式展开行为——同一时间只有一个新闻项处于展开状态。点击新的展开全文会自动收起之前展开的项。展开时标题下方的 margin 从 6vp 扩大到 10vp为摘要文本留出视觉间距。五、关键技术点详解5.1 $$ 双向绑定的底层机制$$this.isRefreshing是 ArkUI 声明式框架的核心特性之一。它等价于同时做两件事属性传递refreshing: this.isRefreshing—— 将当前isRefreshing的值传给 Refresh 组件事件监听当 Refresh 组件内部改变refreshing时如下拉触发自动调用this.isRefreshing newValue同步回状态变量需要注意的是$$只能用于State、Prop、Link等可观察状态变量不能用于普通private变量。此外在$$模式下开发者不应在onRefreshing回调中再次设置isRefreshing true因为组件已经自动设置了而应该在数据加载完成后设置isRefreshing false。不过 Demo 中doRefresh()同时服务于下拉和手动按钮所以包含了isRefreshing true。对于下拉触发的路径这个赋值是冗余的一次无副作用的相同值写入对于按钮触发的路径则是必要的。5.2 onRefreshing 的触发时机onRefreshing在下拉距离超过 Refresh 组件的触发阈值时自动调用。具体触发流程用户在列表顶部继续向下拖动下拉距离逐渐增加Refresh 组件内部计算偏移量当偏移量超过阈值默认约 64vp组件判定用户意图为刷新组件内部将refreshing设为 true通过$$同步到状态变量调用onRefreshing回调开发者执行数据加载完成后将refreshing设回 false如果在步骤 4 之前用户松手下拉不够深Refresh 组件会自动播放回弹动画回到顶部不会触发刷新。这个下拉距离阈值可以通过.offset(value)自定义单位为 vp。5.3 列表为空时的刷新行为当列表内容为空newsList为空数组时Refresh 组件仍然可以触发刷新。此时的交互略有不同有内容时用户需要将列表滚动到顶部再继续下拉两次手势——先上滑、再下拉或者列表本身就在顶部时直接下拉空列表时Refresh 占据整个容器空间用户在任何位置下拉都能触发刷新这意味着 Refresh 在空列表场景下更加灵敏——非常适合首次加载和数据清空后重新加载的场景。Demo 中初始状态有 5 条新闻不为空但删除所有新闻后列表为空Refresh 依然能正确触发。5.4 手动刷新与下拉刷新的 UX 互补在产品设计中不应仅依赖下拉刷新。以下是常见的补充触发方式触发方式适用场景优点缺点下拉刷新列表在顶部时符合直觉手势自然需要将列表滚到顶部才能触发手动按钮Demo 中使用任意滚动位置无需滚回顶部即时触发占用额外屏幕空间自动轮询实时性要求高的场景聊天、交易零用户操作耗电、耗流量长按菜单刷新工具栏/TabBar 中的刷新选项不需额外空间发现性差Demo 中使用下拉刷新 手动按钮双触发模式快速浏览时随手势下拉刷新自然精确操作时点击按钮快捷。5.5 自定义 refreshContent默认的刷新动画是一个简单的 loading 旋转图标。对于品牌化需求可以使用.refreshContent()自定义下拉区域的显示内容Refresh({refreshing:$$this.isRefreshing}){List(){...}}.refreshContent((){this.customRefreshBuilder()})customRefreshBuilder可以是包含图标、文字、动画的任意组件组合。例如下拉刷新 / 释放立即刷新的状态切换 品牌 Logo 动画。Demo 中使用默认样式以保持简洁但产品级应用建议自定义以增强品牌识别度。5.6 性能考量高频刷新与数据更新策略刷新操作可能被高频触发用户反复下拉需要注意以下性能点防抖Debounce如果onRefreshing中触发的是真实网络请求建议加入防抖逻辑——在刷新动画进行中时忽略新的刷新请求。Demo 中isRefreshing本身起到了一定防护作用在true状态时重复触发doRefresh()不会产生新动画不可变数据更新列表数据更新时必须使用新数组newList [...]而非this.newsList.push(item)否则State无法检测到变化导致 UI 不刷新。Demo 中演示了正确的不可变更新模式列表 key 函数ForEach的第三个参数key 函数帮助框架识别哪些列表项发生了变化、哪些可以复用。Demo 中使用news.id.toString()作为唯一 key确保新增项正确渲染、已有项节点复用控制列表长度实际产品中列表可能包含数百条数据。每次刷新插入新数据后如果列表无限增长应考虑分页加载 旧数据清理策略如保留最近 50 条六、运行效果6.1 初始状态进入动态资讯页面顶部状态栏显示上次刷新暂无和蓝色手动刷新按钮。下方白色说明卡片介绍 Refresh 组件。资讯列表展示 5 条随机新闻每条包含彩色分类标签蓝/绿/橙/紫/红、来源名称如华为官方“开发者社区”、发布时间和标题。底部有 0.5vp 分隔线。6.2 下拉刷新将列表滑到顶部继续向下拖动 → Refresh 组件检测到超过阈值 → loading 旋转图标出现在列表上方 →onRefreshing触发doRefresh()→ 1.5 秒后 3 条新随机新闻插入列表头部 → loading 消失、列表回弹 → 上次刷新时间更新为当前 HH:MM。6.3 手动刷新滚动到列表中间位置 → 点击顶部手动刷新按钮 → loading 动画立即显示无需下拉手势→ 1.5 秒后 3 条新新闻插入 → 刷新时间更新 → loading 消失。手动刷新与下拉刷新使用完全相同的doRefresh()逻辑效果一致。6.4 展开详情点击任意新闻的展开全文→ 该条新闻扩展显示完整摘要约 80~100 字中文描述“展开全文变为收起”。点击收起→ 摘要折叠仅显示标题。点击另一条新闻的展开全文→ 之前展开的自动折叠新点击的展开同一时间仅一项展开。6.5 多次刷新效果连续点击 3 次手动刷新→ 每次插入 3 条列表顶部累积 9 条新新闻。滚动浏览所有内容 → 分类标签颜色帮助快速区分新闻类型。列表流畅滚动无卡顿。七、总结本文通过一个动态资讯实战 Demo深入讲解了 HarmonyOS Refresh 下拉刷新组件的核心用法Refresh 容器包裹 List 内容自动处理下拉手势识别和回弹动画$$双向绑定$$this.isRefreshing实现刷新状态与 Refresh 组件的自动同步组件感知状态变化状态反映组件内部变化onRefreshing回调下拉触发的数据加载入口在此执行异步加载并在完成后将 refreshing 设回 false手动刷新按钮直接调用同一doRefresh()方法展示一套逻辑、多种触发的设计模式不可变数据更新每次刷新创建新数组插入头部确保State检测到变化触发 UI 更新Refresh 将手势识别→阈值判断→加载动画→数据更新→回弹收起这一整套下拉刷新的交互流程封装进一个容器组件开发者只需声明状态绑定和加载回调即可获得完整的下拉刷新体验。希望本文能帮助你在实际项目中高效运用 Refresh 组件。本文基于 HarmonyOS NEXT API 24 编写代码经 DevEco Studio 6.1.1 编译验证通过。