HarmonyOS7 WaterFlow 实现双列瀑布流发现页

文章目录

• • • 前言
    • 代码讲解
    • • 页面入口怎么安排
      • 数据模型先稳住
      • 状态变量控制页面反馈
      • 布局代码不要从样式开始读
      • Builder 和方法承担复用
      • 使用方式
    • 完整代码
    • 关键代码解析
    • • `interface` 不是摆设
      • `@State` 是交互的开关
      • 列表和卡片要靠数据驱动
      • 事件回调要短一点
      • 样式参数别急着抽常量
    • 总结

前言

瀑布流适合内容高度不一致的场景，强行用等高 Grid 反而会显得呆。

我建议把这篇当成一个可以直接改造的 ArkUI 页面模板来看。先跑起来，确认页面展示和交互都正常；再把里面的模拟数据替换成接口数据；最后再调整颜色、间距和业务字段。这样改起来比较稳，不容易一边改样式一边把状态逻辑弄乱。

这篇文章会按「页面意图、数据结构、状态流转、布局组织、交互细节」这条线来读代码。你不用从第一行样式硬看到最后，先抓住主线，后面的细节会轻松很多。

代码讲解

页面入口怎么安排

代码里的入口组件是WaterFlowDiscoveryPage。如果你把它当成单独页面预览，保留@Entry就可以；如果要塞进现有工程的路由体系，通常会去掉@Entry，再由外层页面或路由模块统一管理。

这个习惯很重要。一个项目里入口页面太多，预览时容易混，后期拆组件也会麻烦。我的做法是：案例阶段保留入口，接业务时只保留真正需要被路由访问的页面。

数据模型先稳住

本案例涉及的数据模型主要有：WaterFlowCard。

这些interface的作用不是为了“看起来规范”，而是给 UI 层划边界。比如列表项需要标题、描述、颜色、选中态，就应该在模型里说清楚。后续从接口拿数据时，可以在请求层做字段映射，别让后端字段名直接污染页面代码。

如果你准备接真实业务，建议把模拟数组替换成接口返回后的 ViewModel。页面只关心自己要渲染什么，不关心接口原始字段长什么样。

状态变量控制页面反馈

本案例里的关键状态包括：likedIds、selectedTag。

@State的职责是让 UI 对用户操作有反馈。比如选中某个卡片、切换分类、展开内容、修改输入值、控制加载中状态，这些都应该由状态驱动。状态一变，相关 UI 自动刷新，这也是 ArkUI 声明式开发最核心的体验。

这里有个容易踩的坑：不要把所有数据都塞进@State。静态配置用普通数组就够了，只有用户会改、接口会更新、页面需要重新渲染的数据，才适合放进状态里。

布局代码不要从样式开始读

这个页面里比较关键的组件有：

• Row：横向排列、左右分栏、按钮组或卡片行都依赖它来控制水平方向的节奏。
• Column：纵向组织标题、内容、操作区，适合搭页面主骨架。
• Stack：负责图层叠放，常见于角标、遮罩、封面文字压图。
• WaterFlow：适合高度不一致的内容流，比如发现页、图片流、灵感卡片。
• Scroll：用于长内容容器，锚点跳转和返回顶部都离不开滚动控制。

读布局时，我更建议先找大容器，再看内部如何拆块。比如一个页面通常会先用Column纵向放标题区、内容区、操作区；内容区里再用Row、Grid、List或其他容器细分。这样看代码，层级会比逐行看.padding()、.fontSize()清楚得多。

如果页面显示错位，优先检查容器关系，而不是马上改像素。很多问题不是某个.margin()不对，而是外层容器的宽高、滚动方向、权重分配或对齐方式没想清楚。

Builder 和方法承担复用

这篇没有额外拆出 Builder，页面结构主要集中在build()中。

辅助方法主要有：getFilteredCards、toggleLike、isLiked、getLikesCount。

@Builder更适合复用 UI 片段，比如卡片、列表行、头部区域、按钮组。普通方法更适合放计算逻辑，比如筛选列表、统计数量、切换状态、生成颜色。两者分清楚后，页面会干净很多。

我不建议把所有东西都塞进build()。刚开始代码少还行，需求一多，build()会变成几百行，后面改一个按钮都要找半天。

使用方式

把下面的完整代码放到 ArkTS 页面文件里即可运行。文章中的组件名已经是语义化命名，不包含编号式案例名称，接路由时直接使用WaterFlowDiscoveryPage就行。

如果你要改成业务页面，优先改三处：数据模型、状态变量、事件方法。样式可以后调，先保证数据流和交互是通的。

完整代码

// WaterFlowDiscoveryPage: 瀑布流布局 - WaterFlow 组件 // 知识点: WaterFlow、FlowItem、columnsTemplate、动态高度、图片流 interface WaterFlowCard { cardId: number cardTitle: string cardEmoji: string cardBg: string cardHeight: number cardTags: string[] cardLikes: number authorName: string authorEmoji: string } @Entry @Component struct WaterFlowDiscoveryPage { @State likedIds: number[] = [] @State selectedTag: string = '全部' private allTags: string[] = ['全部', '风景', '美食', '旅行', '科技', '设计'] private cardList: WaterFlowCard[] = [ { cardId: 1, cardTitle: '夕阳下的海边漫步', cardEmoji: '🌅', cardBg: '#FFE0B2', cardHeight: 180, cardTags: ['风景', '旅行'], cardLikes: 256, authorName: '晴天', authorEmoji: '😊' }, { cardId: 2, cardTitle: '城市夜景', cardEmoji: '🌃', cardBg: '#1A237E', cardHeight: 130, cardTags: ['风景'], cardLikes: 189, authorName: '夜猫', authorEmoji: '🦉' }, { cardId: 3, cardTitle: '日式拉面的正确打开方式', cardEmoji: '🍜', cardBg: '#FFCCBC', cardHeight: 200, cardTags: ['美食'], cardLikes: 342, authorName: '吃货', authorEmoji: '😋' }, { cardId: 4, cardTitle: 'HarmonyOS UI 设计规范', cardEmoji: '📱', cardBg: '#E3F2FD', cardHeight: 150, cardTags: ['科技', '设计'], cardLikes: 128, authorName: '设计师', authorEmoji: '🎨' }, { cardId: 5, cardTitle: '京都古城之旅', cardEmoji: '⛩️', cardBg: '#FCE4EC', cardHeight: 170, cardTags: ['旅行'], cardLikes: 415, authorName: '旅行家', authorEmoji: '✈️' }, { cardId: 6, cardTitle: '手冲咖啡入门', cardEmoji: '☕', cardBg: '#EFEBE9', cardHeight: 140, cardTags: ['美食'], cardLikes: 97, authorName: '咖啡师', authorEmoji: '👨‍🍳' }, { cardId: 7, cardTitle: '极简主义工作台', cardEmoji: '💻', cardBg: '#F5F5F5', cardHeight: 160, cardTags: ['设计'], cardLikes: 203, authorName: '极客', authorEmoji: '🤓' }, { cardId: 8, cardTitle: '云雾中的山峰', cardEmoji: '⛰️', cardBg: '#E8EAF6', cardHeight: 190, cardTags: ['风景', '旅行'], cardLikes: 328, authorName: '登山客', authorEmoji: '🧗' }, { cardId: 9, cardTitle: 'AI 绘画创作实践', cardEmoji: '🤖', cardBg: '#E0F7FA', cardHeight: 130, cardTags: ['科技', '设计'], cardLikes: 176, authorName: 'AI艺术家', authorEmoji: '🎭' }, { cardId: 10, cardTitle: '烘焙日记：红丝绒蛋糕', cardEmoji: '🎂', cardBg: '#FCE4EC', cardHeight: 155, cardTags: ['美食'], cardLikes: 261, authorName: '烘焙师', authorEmoji: '👩‍🍳' }, { cardId: 11, cardTitle: '东南亚海岛度假', cardEmoji: '🏝️', cardBg: '#E0F2F1', cardHeight: 185, cardTags: ['旅行', '风景'], cardLikes: 389, authorName: '背包客', authorEmoji: '🎒' }, { cardId: 12, cardTitle: '代码的美学', cardEmoji: '👾', cardBg: '#1B1B2F', cardHeight: 145, cardTags: ['科技'], cardLikes: 142, authorName: '程序员', authorEmoji: '👨‍💻' }, ] getFilteredCards(): WaterFlowCard[] { if (this.selectedTag === '全部') return this.cardList return this.cardList.filter(c => c.cardTags.includes(this.selectedTag)) } toggleLike(cardId: number) { const idx = this.likedIds.indexOf(cardId) if (idx >= 0) { this.likedIds = this.likedIds.filter(id => id !== cardId) } else { this.likedIds = this.likedIds.concat([cardId]) } } isLiked(cardId: number): boolean { return this.likedIds.includes(cardId) } getLikesCount(card: WaterFlowCard): number { return this.isLiked(card.cardId) ? card.cardLikes + 1 : card.cardLikes } build() { Column({ space: 0 }) { // 顶部标题 Row({ space: 0 }) { Text('🌊 发现') .fontSize(20) .fontWeight(FontWeight.Bold) .fontColor('#1A1A1A') .layoutWeight(1) Text('🔍') .fontSize(20) } .width('100%') .height(56) .padding({ left: 16, right: 16 }) .backgroundColor('#FFFFFF') // 标签筛选 Scroll() { Row({ space: 8 }) { ForEach(this.allTags, (tag: string) => { Text(tag) .fontSize(13) .fontColor(this.selectedTag === tag ? '#FFFFFF' : '#555555') .padding({ left: 14, right: 14, top: 7, bottom: 7 }) .backgroundColor(this.selectedTag === tag ? '#007DFF' : '#F0F0F0') .borderRadius(20) .onClick(() => { this.selectedTag = tag }) }, (tag: string) => tag) } .padding({ left: 16, right: 16 }) } .scrollable(ScrollDirection.Horizontal) .scrollBar(BarState.Off) .width('100%') .padding({ top: 8, bottom: 8 }) .backgroundColor('#FFFFFF') .border({ width: { bottom: 1 }, color: '#F0F0F0' }) // 瀑布流 WaterFlow() { ForEach(this.getFilteredCards(), (card: WaterFlowCard) => { FlowItem() { Column({ space: 0 }) { // 图片区（用渐变色+emoji模拟） Stack({ alignContent: Alignment.BottomEnd }) { Column() .width('100%') .height(card.cardHeight) .backgroundColor(card.cardBg) .borderRadius({ topLeft: 12, topRight: 12 }) Text(card.cardEmoji) .fontSize(card.cardHeight > 160 ? 60 : 44) .opacity(0.6) .position({ x: card.cardHeight > 160 ? 12 : 8, y: card.cardHeight > 160 ? 16 : 8 }) // 标签 Row({ space: 4 }) { ForEach(card.cardTags.slice(0, 1), (tag: string) => { Text(tag) .fontSize(10) .fontColor('#FFFFFF') .padding({ left: 6, right: 6, top: 2, bottom: 2 }) .backgroundColor('rgba(0,0,0,0.35)') .borderRadius(4) }, (tag: string) => tag) } .padding({ right: 8, bottom: 8 }) } .width('100%') // 信息区 Column({ space: 6 }) { Text(card.cardTitle) .fontSize(13) .fontColor('#1A1A1A') .fontWeight(FontWeight.Medium) .maxLines(2) .textOverflow({ overflow: TextOverflow.Ellipsis }) .lineHeight(18) .width('100%') Row({ space: 0 }) { Text(card.authorEmoji) .fontSize(14) .margin({ right: 4 }) Text(card.authorName) .fontSize(11) .fontColor('#888888') .layoutWeight(1) Text(this.isLiked(card.cardId) ? '❤️' : '🤍') .fontSize(14) .onClick(() => { this.toggleLike(card.cardId) }) Text(` ${this.getLikesCount(card)}`) .fontSize(11) .fontColor(this.isLiked(card.cardId) ? '#EF4444' : '#BBBBBB') } .width('100%') .alignItems(VerticalAlign.Center) } .padding({ left: 10, right: 10, top: 8, bottom: 10 }) .alignItems(HorizontalAlign.Start) } .backgroundColor('#FFFFFF') .borderRadius(12) .shadow({ radius: 4, color: '#10000000', offsetY: 2 }) .clip(true) } }, (card: WaterFlowCard) => card.cardId.toString()) } .columnsTemplate('1fr 1fr') .columnsGap(10) .rowsGap(10) .padding({ left: 12, right: 12, top: 12, bottom: 24 }) .scrollBar(BarState.Off) .edgeEffect(EdgeEffect.Spring) .layoutWeight(1) } .width('100%') .height('100%') .backgroundColor('#F5F6FA') } }

关键代码解析

interface不是摆设

很多新手写 ArkUI 页面时，会直接在ForEach里使用一堆临时对象。页面小的时候没问题，但字段一多，就很难知道每个字段到底用于哪里。本案例把数据结构提前声明出来，读代码时能很快判断每个 UI 区块依赖哪些字段。

后续如果接接口，也建议保留这层结构。接口可以变，页面模型尽量稳定。这样页面不会因为后端多返回一个字段、少返回一个字段就跟着大改。

@State是交互的开关

本案例的交互反馈都围绕状态展开。点击、切换、输入、刷新这类行为，本质上都是修改某个状态值，然后让 UI 重新计算显示结果。

写这类代码时有一个简单判断：如果某个值变化后，页面应该立刻变，那它大概率应该是状态；如果它只是配置项、静态文案、固定颜色，就不要放进状态。

列表和卡片要靠数据驱动

只要页面里出现重复结构，就应该优先想到数据数组加ForEach。这样新增一项、删除一项、调整顺序都只动数据，不用复制粘贴一段 UI。

这个案例的完整代码里已经把主要内容抽成数组或方法。你可以试着多加一条数据，看页面是否能自然渲染出来。如果能，说明结构是健康的；如果加一条就要改很多 UI，说明组件拆分还不够。

事件回调要短一点

.onClick()、onChange()这类回调里可以直接改状态，但不建议堆太多逻辑。简单切换可以写在回调里，复杂逻辑最好拆成方法。

这样做有两个好处：一是读页面结构时不会被业务逻辑打断；二是后面要加埋点、请求接口、异常处理时，有明确的位置可以改。

样式参数别急着抽常量

这个案例里有不少颜色、间距、圆角、字号。学习阶段直接写在组件链上，反而更容易看出效果。等你确定页面风格稳定后，再把主题色、通用间距、卡片圆角提到统一常量里。

过早抽象会让示例代码变绕。先让页面清楚，再谈工程化，这是我比较推荐的顺序。

总结

这个案例真正值得学的，不只是某个 ArkUI 组件怎么写，而是一个页面如何从数据走到状态，再走到布局和交互。

你可以按这个顺序改造：先替换数据模型，再确认状态更新是否正确，接着调整布局容器，最后打磨样式细节。只要这条主线不乱，页面规模变大也不会失控。

如果后续继续扩展，我会优先把可复用的卡片、列表行、筛选栏或控制区拆成独立组件。这样主页面只保留数据和流程，代码会更接近真实项目里的写法。