鸿蒙新特性：Refresh 下拉刷新——构建新闻资讯流与状态管理

下拉刷新是移动应用中最基础也最高频的交互之一。从微博到微信从新闻客户端到电商应用下拉刷新几乎无处不在——它让用户以最自然的手势获取最新内容而无需寻找任何按钮。HarmonyOS NEXT ArkUI 提供了 Refresh 组件将下拉刷新的手势识别、动画反馈和状态管理封装为一个开箱即用的容器。但一个完整的新闻资讯流远不止下拉刷新分类筛选让用户聚焦感兴趣的内容、收藏标记帮助用户沉淀优质文章、已读/未读状态让用户追踪浏览进度。本文将深入讲解 Refresh 组件与 List 的协作模式并构建一个完整的新闻资讯应用——支持下拉刷新、分类筛选、收藏标记和已读管理。关键词HarmonyOS、ArkUI、Refresh、下拉刷新、新闻资讯、分类筛选、收藏一、Refresh 组件 API1.1 基本用法Refresh 是一个容器组件它的子组件必须是可滚动的如 List、Scroll、Grid 等。当用户下拉超过阈值时触发刷新回调Staterefreshing:booleanfalse;Refresh({refreshing:$$this.refreshing}){List(){ForEach(this.data,(item:NewsItem){ListItem(){/* 列表项 */}})}}.onRefreshing((){this.refreshingtrue;// 执行刷新逻辑...setTimeout((){this.refreshingfalse;},1500);})核心属性refreshing通过$$双向绑定一个State boolean控制刷新指示器的显示与隐藏onRefreshing下拉触发刷新时的回调函数1.2 双向绑定的含义$$是 ArkUI 的双向绑定语法。与单向绑定State父传子不同$$允许子组件Refresh在特定时机修改父组件的状态变量。具体到 Refresh用户下拉时Refresh 内部开始动画下拉距离超过阈值并松手后Refresh 调用onRefreshing回调开发者在回调中设置this.refreshing true显示加载指示器数据加载完成后开发者设置this.refreshing false隐藏指示器这种设计意味着开发者完全掌控刷新的生命周期——Refresh 组件只负责手势检测和动画数据加载的时机和逻辑由开发者决定。1.3 一个容易被忽略的细节Refresh 组件的刷新回调名称是onRefreshing而非onRefresh。这是 ArkUI 的命名惯例——onRefreshing描述的是正在刷新这个动作而不仅仅是触发刷新这个瞬间事件。如果你从其他框架如 Flutter 的onRefresh迁移过来这个差异需要特别注意。二、新闻资讯流的整体设计2.1 页面架构本文 Demo 构建一个新闻资讯应用模拟主流新闻客户端的信息流体验RefreshPage ├── 标题栏 — 新闻资讯 未读数徽标 ├── 分类标签栏 — 横向滚动的分类选项卡带未读计数 ├── 工具栏 — 结果计数 收藏筛选 全部已读 ├── 下拉刷新区域Refresh 组件 │ └── List │ ├── 空状态提示无结果时 │ └── 新闻卡片列表 │ ├── 分类标签 来源 NEW 标记 时间 收藏星标 │ ├── 标题已读/未读 粗细不同 │ └── 摘要最多 2 行 └── 底部空白2.2 数据结构classNewsItem{id:number;title:string;// 标题summary:string;// 摘要source:string;// 来源time:string;// 发布时间相对时间category:string;// 分类科技 / 财经 / 体育 / 娱乐bookmarked:boolean;// 是否收藏read:boolean;// 是否已读}这里将NewsItem定义为class而非interface原因在于 ArkTS 不支持对象展开运算符...item。当需要在数组中修改某个对象的某个字段时如将bookmarked置为true不能使用{ ...item, bookmarked: true }而必须显示创建一个新对象。为NewsItem添加工厂方法可以大幅简化这一操作classNewsItem{// ... 属性声明 ...constructor(id:number,title:string,summary:string,source:string,time:string,category:string,bookmarked:boolean,read:boolean){// ... 属性赋值 ...}withBookmark(v:boolean):NewsItem{returnnewNewsItem(this.id,this.title,this.summary,this.source,this.time,this.category,v,this.read);}withRead(v:boolean):NewsItem{returnnewNewsItem(this.id,this.title,this.summary,this.source,this.time,this.category,this.bookmarked,v);}}withBookmark和withRead方法返回一个除指定字段外完全相同的新对象配合Array.map()使用// 收藏/取消收藏用 withBookmark 替代展开运算符this.allNewsthis.allNews.slice().map((item:NewsItem){if(item.idid)returnitem.withBookmark(!item.bookmarked);returnitem;});这个模式是 ArkTS 中处理不可变更新的标准做法——通过slice()创建数组新引用通过map() 工厂方法创建新的对象引用触发 ArkUI 的状态感知和 UI 重绘。2.3 12 篇预设新闻Demo 提供了 12 篇新闻覆盖四大分类新闻标题分类来源HarmonyOS NEXT 正式发布全场景体验再升级科技华为官方全球股市震荡科技板块领跌避险资产受追捧财经财经日报世界杯预选赛国足 2:1 击败对手出线形势明朗体育体育周刊热门剧集《星途》大结局收视率破纪录娱乐娱乐头条AI 芯片需求爆发国产 GPU 厂商加速追赶科技科技前沿央行释放流动性信号市场预期降准临近财经财经日报NBA 季后赛湖人队逆转晋级詹姆斯砍下 40 分体育体育周刊新综艺《声生不息》首播获好评豆瓣评分 8.5娱乐娱乐头条量子计算突破中国团队实现 512 量子比特纠缠科技科技前沿新能源汽车销量再创新高渗透率突破 45%财经财经日报城市马拉松热潮上半年全国举办超 200 场赛事体育体育周刊经典电影《花样年华》4K 修复版即将重映娱乐娱乐头条三、下拉刷新实现3.1 Refresh 嵌套 ListRefresh({refreshing:$$this.refreshing}){List(){ForEach(this.getFilteredNews(),(item:NewsItem,idx:number){ListItem(){// 新闻卡片}},(item:NewsItem)item.id.toString())}.width(100%).layoutWeight(1).scrollBar(BarState.Off).edgeEffect(EdgeEffect.Spring)}.onRefreshing((){this.doRefresh();})layoutWeight(1)让 List 占据剩余空间edgeEffect(EdgeEffect.Spring)提供回弹效果——当滚动到顶部继续下拉时列表会产生弹性形变这是触发 Refresh 的前奏。3.2 刷新逻辑doRefresh():void{this.refreshingtrue;setTimeout((){this.refreshingfalse;promptAction.showToast({message:已刷新暂无新内容,duration:1500});},1200);}Demo 中用 1.2 秒的延迟模拟网络请求。在真实应用中这里应当调用后端 API 获取最新数据并在成功回调中设置this.refreshing false。Demo 总是返回暂无新内容——因为数据是硬编码的但 Toast 提示让用户明确知道刷新操作已生效。3.3 Refresh 与 List 的协作机制这里有一个重要的架构细节getFilteredNews()方法每次调用时都会从this.allNews重新计算过滤结果。为什么不在State results中维护一个独立的过滤数组答案在于 ArkUI 的State响应机制。如果维护两个独立的State数组allNews和results每次修改收藏或已读状态时需要同时更新两个数组——这不仅增加代码复杂度还容易出错。使用单一数据源 计算属性模式allNews是唯一的真实数据getFilteredNews()是它的过滤视图。当用户切换分类或点击仅看收藏时ArkUI 检测到selectedCategory或showBookmarked的变化自动重新渲染列表——无需手动维护中间状态。四、分类筛选4.1 横向标签栏分类标签以横向滚动的标签栏展示Scroll(){Row(){ForEach(this.getCategories(),(cat:string,idx:number){Row(){Text(cat)if(this.getUnreadCount(cat)0){Text(this.getUnreadCount(cat).toString()).backgroundColor(...)}}.backgroundColor(catthis.selectedCategory?#1677FF:#FFFFFF).onClick((){this.selectedCategorycat;})})}}.scrollBar(BarState.Off)选中分类使用蓝色填充 白色文字未选中使用白色填充 灰色文字——视觉对比强烈用户一眼即可识别当前位置。每个标签旁边显示该分类的未读数量小徽标让用户无需进入分类就能感知这个分类里还有多少没看的。这个徽标在选中和未选中状态下使用不同的颜色白色半透明 vs 浅灰保持视觉层次的一致性。4.2 过滤器组合分类筛选和收藏筛选可以叠加使用getFilteredNews():NewsItem[]{letnewsthis.allNews.slice();if(this.selectedCategory!推荐){newsnews.filter((item:NewsItem)item.categorythis.selectedCategory);}if(this.showBookmarked){newsnews.filter((item:NewsItem)item.bookmarked);}returnnews;}两个过滤器是与关系——先按分类缩小范围再按收藏状态进一步过滤。用户可以在科技分类下仅看收藏文章这在真实使用场景中非常有用“我在科技分类下收藏了哪些文章”。五、收藏与已读管理5.1 收藏切换每条新闻卡片右上角有一个星标图标点击切换收藏状态Text(item.bookmarked?★:☆).fontSize(18).fontColor(item.bookmarked?#FAAD14:#CCCCDD).onClick((){this.toggleBookmark(item.id);})已收藏显示金色实心星标★未收藏显示灰色空心星标☆。收藏操作是即时生效的——点击卡片上的星标时stopPropagation不会阻止事件冒泡。因此需要注意点击星标会同时触发toggleBookmark星标的 onClick和markRead卡片的 onClick。这实际上是合理的行为——用户收藏一篇文章时通常也已经阅读了它至少浏览了标题。5.2 已读标记点击新闻卡片将文章标记为已读.onClick((){this.markRead(item.id);})已读状态通过标题的字重体现未读文章标题使用FontWeight.Bold加粗已读文章使用FontWeight.Normal常规。同时每张卡片上方会显示一个红色的NEW标记表明未读状态。5.3 全部已读工具栏右侧提供全部已读按钮仅在有未读文章时显示if(this.getUnreadCount()0){Text(全部已读).onClick((){this.markAllRead();})}markAllRead将数组中所有对象的read字段置为true然后显示 Toast 确认markAllRead():void{this.allNewsthis.allNews.slice().map((item:NewsItem){returnitem.withRead(true);});promptAction.showToast({message:已全部标为已读,duration:1500});}5.4 未读计数标题栏右侧显示全局未读总数分类标签上显示各分类未读数。两个计数都通过getUnreadCount()方法实时计算getUnreadCount(category?:string):number{letnewsthis.allNews.slice();if(category){newsnews.filter((item:NewsItem)item.categorycategory);}returnnews.filter((item:NewsItem)!item.read).length;}不传参数时统计全部分类传分类名时只统计该分类。随着用户浏览和标记已读这些数字实时变化——这是State响应式更新的直观体现。六、页面状态管理6.1 四种视图状态页面存在四种可能的视图状态正常列表有新闻数据正常展示空分类某个分类下没有匹配的新闻空收藏开启了仅看收藏但无收藏文章刷新中下拉刷新加载指示器显示中每种状态都有对应的 UI 反馈if(this.getFilteredNews().length0){ListItem(){Column(){Text(this.showBookmarked?暂无收藏文章:暂无新闻)Text(this.showBookmarked?点击星标图标收藏文章:试试切换其他分类)}}}空状态不是空白页面——它明确告知用户当前状态并给出下一步建议。6.2 收藏筛选切换工具栏的收藏按钮是一个切换开关Row(){Text(this.showBookmarked?全部:收藏).fontColor(this.showBookmarked?#1677FF:#888899)}.backgroundColor(this.showBookmarked?#F0F5FF:#F8F9FA).onClick((){this.showBookmarked!this.showBookmarked;})激活时按钮文字变为全部点击返回全量视图未激活时显示收藏点击进入仅看收藏。按钮的蓝色高亮状态明确告知用户当前处于筛选模式中。6.3 工具栏工具栏位于分类标签下方提供三个信息/操作结果计数左“共 X 条新闻”收藏切换右切换收藏筛选全部已读右一键标记全部为已读工具栏的布局使用了Blank()将左侧计数和右侧按钮组隔开信息层级清晰。七、视觉效果与交互细节7.1 新闻卡片设计每条新闻卡片包含三个层次元信息行顶部分类标签蓝底 来源名称灰字 NEW 标记红字 时间灰字 收藏星标右对齐标题行中部15px 加粗/常规最多 2 行摘要行下部13px 灰色最多 2 行三行内容形成清晰的信息层级先看分类和来源判断可信度再看标题了解核心内容最后看摘要获取细节。卡片之间用Divider分隔避免拥挤感。7.2 首尾卡片的圆角处理多篇新闻以卡片组的形式展示——第一项有顶部圆角最后一项有底部圆角借用BorderRadius.LG中间的卡片为直角。当只有一条结果时四个角都是圆角.borderRadius(idx0this.getFilteredNews().length1?BorderRadius.LG:(idx0?{topLeft:12,topRight:12,bottomLeft:0,bottomRight:0}:{}))7.3 分类标签的未读徽标分类标签中的未读计数使用了视觉分层backgroundColor(catthis.selectedCategory?#FFFFFF30:#F2F3F5)选中时使用白色半透明#FFFFFF30与蓝色选中背景形成层次对比未选中时使用淡灰#F2F3F5与白色背景保持微妙差异。这个细节让 5 个分类标签的视觉处理各异但统一。八、交互流程演示8.1 浏览推荐页进入页面时默认选中推荐分类展示全部 12 篇新闻。标题栏显示未读数12每个分类标签旁有小徽标显示各类别未读数。所有标题加粗显示未读状态卡片上有红色 NEW 标记。8.2 下拉刷新在列表顶部继续下拉。当超过阈值时刷新指示器出现。1.2 秒后 Toast 提示已刷新暂无新内容。8.3 分类切换点击科技分类标签。列表从 12 篇变为 3 篇仅科技类新闻。工具栏显示共 3 条新闻。点击财经标签列表切换到 3 篇财经新闻。8.4 阅读与收藏点击一篇科技新闻。该新闻的标题从加粗变为常规已读NEW 标记消失。标题栏未读数从 12 变为 11科技分类标签的未读徽标同步更新。点击该新闻的星标☆变为金色★表示已收藏。再点击收藏筛选按钮列表仅显示这一篇文章。8.5 全部已读返回推荐分类。点击全部已读按钮所有文章的标题变为常规字重NEW 标记全部消失标题栏未读数归零。Toast 提示已全部标为已读。九、总结本文通过新闻资讯流这个实战案例全面讲解了 ArkUI Refresh 组件的使用方法。核心知识点包括Refresh 组件$$双向绑定 onRefreshing回调 refreshing状态管理List Refresh 协作List 作为 Refresh 子组件提供滚动容器和下拉检测分类筛选横向滚动标签栏 未读计数徽标 多过滤器组合收藏/已读管理class 工厂方法替代对象展开 slice().map()触发响应式更新四种视图状态正常 / 空分类 / 空收藏 / 刷新中每种有对应的 UI 反馈单一数据源模式allNews为唯一真实数据getFilteredNews()为计算视图下拉刷新是移动应用中最值得打磨的交互之一。一个好的下拉刷新不仅仅是能拉下来转圈——它需要在最恰当的时机给用户最舒适的反馈同时与列表筛选、状态管理等周边功能无缝协作。ArkUI 的 Refresh 组件处理了手势识别和动画帧的底层细节让开发者可以专注于刷新逻辑、数据结构和 UI 反馈的设计。