HarmonyOS WaterFlow瀑布流组件完全指南

已于 2025-05-17 02:30:29 修改
阅读量482 收藏 8
点赞数 20
文章标签： harmonyos 华为
于 2025-05-17 02:29:34 首次发布
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
本文链接：https://blog.csdn.net/qq_46215761/article/details/148020273
版权

目录

一、WaterFlow简介

二、基础用法

2.1 创建简单的双列瀑布流

2.2 自动计算列数

三、数据源管理

3.1 创建数据源类

3.2 使用LazyForEach加载数据

四、高级功能

4.1 底部加载更多

4.2 分组布局

4.3 性能优化

4.4 滑动窗口模式

4.5 边缘渐隐效果

五、交互与控制

5.1 设置滚动控制器

5.2 监听滚动事件

六、实战案例：图片瀑布流

七、注意事项

八、最佳实践

一、WaterFlow简介

WaterFlow是HarmonyOS中的瀑布流容器组件，由"行"和"列"分割的单元格所组成，通过容器自身的排列规则，将不同大小的"项目"自上而下，如瀑布般紧密布局。这种布局方式特别适合展示图片画廊、商品列表等内容不规则的场景。

二、基础用法

2.1 创建简单的双列瀑布流

最基本的瀑布流创建方式如下：

WaterFlow() {
  ForEach(this.dataArray, (item) => {
    FlowItem() {
      Column() {
        Image(item.imageUrl)
          .width('100%')
          .borderRadius(8)
        Text(item.title)
          .fontSize(14)
      }
    }
    .width('100%')
    .height(item.height)
  })
}
.columnsTemplate('1fr 1fr') // 创建两列布局
.columnsGap(10) // 设置列间距
.rowsGap(10) // 设置行间距

2.2 自动计算列数

可以使用repeat(auto-fill, size)实现根据容器宽度自动计算列数：

WaterFlow() {
  // 瀑布流内容
}
.columnsTemplate('repeat(auto-fill, 120)') // 每列120vp宽度，自动计算列数

三、数据源管理

3.1 创建数据源类

推荐使用实现IDataSource接口的数据源类与LazyForEach结合使用：

export class WaterFlowDataSource implements IDataSource {
  private dataArray: any[] = [];
  private listeners: DataChangeListener[] = [];

  constructor() {
    // 初始化数据
    for (let i = 0; i < 100; i++) {
      this.dataArray.push({
        id: i,
        title: `标题${i}`,
        height: 100 + Math.floor(Math.random() * 100)
      });
    }
  }

  // 获取索引对应的数据
  public getData(index: number): any {
    return this.dataArray[index];
  }

  // 获取数据总数
  public totalCount(): number {
    return this.dataArray.length;
  }

  // 注册数据变化监听器
  registerDataChangeListener(listener: DataChangeListener): void {
    if (this.listeners.indexOf(listener) < 0) {
      this.listeners.push(listener);
    }
  }

  // 取消注册数据变化监听器
  unregisterDataChangeListener(listener: DataChangeListener): void {
    const pos = this.listeners.indexOf(listener);
    if (pos >= 0) {
      this.listeners.splice(pos, 1);
    }
  }

  // 通知数据添加
  notifyDataAdd(index: number): void {
    this.listeners.forEach(listener => {
      listener.onDataAdd(index);
    })
  }

  // 添加数据方法
  public addLastItem(): void {
    const index = this.dataArray.length;
    this.dataArray.push({
      id: index,
      title: `标题${index}`,
      height: 100 + Math.floor(Math.random() * 100)
    });
    this.notifyDataAdd(index);
  }
}

3.2 使用LazyForEach加载数据

@Component
struct WaterFlowExample {
  dataSource: WaterFlowDataSource = new WaterFlowDataSource();
  
  build() {
    WaterFlow() {
      LazyForEach(this.dataSource, (item) => {
        FlowItem() {
          // 内容组件
        }
        .width('100%')
        .height(item.height)
      }, item => item.id.toString())
    }
  }
}

四、高级功能

4.1 底部加载更多

使用footer参数和onReachEnd事件实现触底加载：

@Component
struct WaterFlowExample {
  @State isLoading: boolean = false;
  @State isEnd: boolean = false;
  
  @Builder
  footerBuilder() {
    Column() {
      if (this.isLoading) {
        Row({ space: 5 }) {
          LoadingProgress().width(20).height(20)
          Text('加载中...').fontSize(14)
        }
        .height(40)
      } else if (this.isEnd) {
        Text('已经到底了').fontSize(14)
        .height(40)
      }
    }
    .width('100%')
    .justifyContent(FlexAlign.Center)
  }
  
  build() {
    WaterFlow({ footer: this.footerBuilder() }) {
      // 瀑布流内容
    }
    .onReachEnd(() => {
      if (this.isEnd) return;
      this.isLoading = true;
      
      // 模拟网络请求
      setTimeout(() => {
        // 添加更多数据
        for (let i = 0; i < 10; i++) {
          this.dataSource.addLastItem();
        }
        
        // 判断是否加载完毕
        if (this.dataSource.totalCount() > 200) {
          this.isEnd = true;
        }
        
        this.isLoading = false;
      }, 1000);
    })
  }
}

4.2 分组布局

使用sections参数实现不同列数的混合布局：

@Component
struct WaterFlowSectionsExample {
  @State sections: WaterFlowSections = new WaterFlowSections();
  
  aboutToAppear() {
    // 初始化分组
    this.sections.splice(0, 0, [
      {
        itemsCount: 3,  // 第一组包含3个项目
        crossCount: 1,  // 单列布局
        margin: { top: 10, bottom: 10 },
        columnsGap: 0,
        rowsGap: 8
      },
      {
        itemsCount: 6,  // 第二组包含6个项目
        crossCount: 2,  // 双列布局
        margin: { top: 0, bottom: 10 },
        columnsGap: 8,
        rowsGap: 8
      },
      {
        itemsCount: 12, // 第三组包含12个项目
        crossCount: 3,  // 三列布局
        margin: { top: 0, bottom: 10 }
      }
    ]);
  }
  
  build() {
    WaterFlow({ sections: this.sections }) {
      LazyForEach(this.dataSource, (item, index) => {
        FlowItem() {
          // 内容组件，可根据索引判断显示不同样式
        }
      })
    }
  }
}

4.3 性能优化

使用onGetItemMainSizeByIndex提前计算项目尺寸提高性能：

{
  itemsCount: 20,
  crossCount: 2,
  onGetItemMainSizeByIndex: (index: number) => {
    // 提前计算高度，避免布局计算开销
    return this.itemHeightArray[index % this.itemHeightArray.length];
  }
}

4.4 滑动窗口模式

使用layoutMode选择更高效的布局模式：

  • ALWAYS_TOP_DOWN：默认模式，滚动位置依赖所有上方项目的布局
  • SLIDING_WINDOW：移动窗口式布局，仅考虑视窗内的布局，对大数据集性能更好
WaterFlow()
  .layoutMode(WaterFlowLayoutMode.SLIDING_WINDOW)

4.5 边缘渐隐效果

设置边缘渐隐效果增强视觉体验：

WaterFlow()
  .fadingEdge(true, {fadingEdgeLength: LengthMetrics.vp(80)})

五、交互与控制

5.1 设置滚动控制器

使用Scroller控制瀑布流滚动：

@Component
struct WaterFlowExample {
  scroller: Scroller = new Scroller();
  
  build() {
    Column() {
      // 添加控制按钮
      Row({ space: 10 }) {
        Button('滚动到顶部')
          .onClick(() => {
            this.scroller.scrollToIndex(0);
          })
          
        Button('滚动到中间')
          .onClick(() => {
            this.scroller.scrollToIndex(50);
          })
      }
      
      WaterFlow({ scroller: this.scroller }) {
        // 瀑布流内容
      }
    }
  }
}

5.2 监听滚动事件

WaterFlow()
  .onScrollIndex((first: number, last: number) => {
    console.log(`当前显示范围: ${first} - ${last}`);
  })
  .onScrollStart(() => {
    console.log('开始滚动');
  })
  .onScrollStop(() => {
    console.log('停止滚动');
  })

六、实战案例：图片瀑布流

下面是一个完整的图片瀑布流示例：

@Entry
@Component
struct ImageWaterFlow {
  scroller: Scroller = new Scroller();
  dataSource: WaterFlowDataSource = new WaterFlowDataSource();
  @State isLoading: boolean = false;
  @State isEnd: boolean = false;
  
  aboutToAppear() {
    // 初始化数据
    this.loadImages();
  }
  
  loadImages() {
    this.isLoading = true;
    
    // 模拟网络请求
    setTimeout(() => {
      for (let i = 0; i < 20; i++) {
        this.dataSource.addImageItem();
      }
      this.isLoading = false;
    }, 1000);
  }
  
  @Builder
  footerBuilder() {
    Column() {
      if (this.isLoading) {
        Row({ space: 10 }) {
          LoadingProgress().width(24).height(24)
          Text('正在加载更多图片...').fontSize(14)
        }
        .height(50)
      } else if (this.isEnd) {
        Text('已经没有更多图片了').fontSize(14)
        .height(50)
      }
    }
    .width('100%')
    .justifyContent(FlexAlign.Center)
  }
  
  build() {
    Column() {
      Row() {
        Text('图片瀑布流').fontSize(20).fontWeight(FontWeight.Bold)
      }
      .width('100%')
      .justifyContent(FlexAlign.Center)
      .height(56)
      
      WaterFlow({ footer: this.footerBuilder(), scroller: this.scroller }) {
        LazyForEach(this.dataSource, (item: ImageItem) => {
          FlowItem() {
            Column() {
              Stack() {
                Image(item.imageUrl)
                  .width('100%')
                  .objectFit(ImageFit.Cover)
                  .borderRadius({ topLeft: 8, topRight: 8 })
                  
                if (item.isNew) {
                  Text('New')
                    .fontSize(12)
                    .backgroundColor('#FF3B30')
                    .fontColor(Color.White)
                    .borderRadius(4)
                    .padding(4)
                    .position({ x: 8, y: 8 })
                }
              }
              
              Column({ space: 4 }) {
                Text(item.title)
                  .fontSize(14)
                  .fontWeight(FontWeight.Medium)
                  .maxLines(2)
                  
                Row() {
                  Row({ space: 4 }) {
                    Image('/assets/user_avatar.png')
                      .width(16)
                      .height(16)
                      .borderRadius(8)
                    Text(item.author)
                      .fontSize(12)
                      .fontColor('#666')
                  }
                  
                  Row({ space: 4 }) {
                    Image('/assets/like_icon.png')
                      .width(14)
                      .height(14)
                    Text(item.likes.toString())
                      .fontSize(12)
                      .fontColor('#666')
                  }
                }
                .width('100%')
                .justifyContent(FlexAlign.SpaceBetween)
              }
              .padding(8)
            }
            .borderRadius(8)
            .backgroundColor(Color.White)
            .width('100%')
          }
          .width('100%')
          .height(item.height)
        })
      }
      .columnsTemplate('1fr 1fr')
      .columnsGap(12)
      .rowsGap(12)
      .padding(16)
      .layoutWeight(1)
      .backgroundColor('#F5F5F5')
      .onReachEnd(() => {
        if (this.isLoading || this.isEnd) return;
        
        if (this.dataSource.totalCount() > 100) {
          this.isEnd = true;
        } else {
          this.loadImages();
        }
      })
    }
    .width('100%')
    .height('100%')
  }
}

// 数据源实现省略

笔记列表呈现瀑布流实际效果图：

七、注意事项

  1. WaterFlow组件仅支持FlowItem子组件
  2. 使用分组布局时会忽略columnsTemplate和rowsTemplate属性
  3. 如果同时设置itemConstraintSize和FlowItem的constraintSize，则取两者之间的适当值
  4. 滑动窗口模式不支持使用滚动条，但性能更好
  5. 使用onGetItemMainSizeByIndex会覆盖FlowItem设置的主轴长度
  6. 分组布局中务必保证所有分组子节点总数与实际子节点数一致

八、最佳实践

  1. 对于大数据集，优先使用滑动窗口布局模式
  2. 提前计算并缓存元素尺寸，使用onGetItemMainSizeByIndex提高性能
  3. 实现组件复用机制，减少内存占用
  4. 图片加载使用懒加载方式，避免一次性加载过多图片
  5. 当数据量大时使用分页加载机制，避免一次性加载全部数据

通过本教程，您已经掌握了HarmonyOS中WaterFlow瀑布流组件的各种用法和技巧。这个组件为开发复杂的内容展示界面提供了强大而灵活的布局方案，希望能帮助您更好地开发HarmonyOS应用！

鸿蒙HarmonyOS开发：WaterFlow高性能开发指南
keleeQAQ的博客
08-13 1019
瀑布流常用于展示图片信息，如多用于购物、资讯类应用。
HarmonyOS：使用常用组件构建页面
ChinaDragon10的博客
11-17 1195
HarmonyOS：使用常用组件构建页面
鸿蒙HarmonyOS NEXT开发：常见性能优化场景-（瀑布流性能优化）
diongdingQAQ的博客
09-13 1069
瀑布流是应用开发中相当常见的开发场景。
【鸿蒙实战开发】基于WaterFlow的页面滑动加载
HarmonyOSMN的博客
07-08 888
可通过Item和分组分组信息中itemsCount设置指定Item的布局，例如Item=5，第一个分组中itemsCount: 4，Item=5为第二个分组的第二个Item(此处Item从0开始)。在瀑布流分组中为要吸顶的部分预留出位置，监听瀑布流滚动事件，吸顶部分基于瀑布流滚动后的偏移量设置位置，让吸顶部分跟随瀑布流一起滚动，吸顶部分到顶后固定不动。场景一：瀑布流页面多列混排的布局场景，例如：10个item在2列内布局，中间5个item在1列内撑满宽度布局，后10个item在3列内布局。
纯血鸿蒙APP实战开发——主页瀑布流实现
m0_71524094的博客
04-27 939
本示例介绍使用ArkUIWaterFlow组件和实现瀑布流场景。该场景多用于购物、资讯类应用。如果你觉得这篇内容对你还蛮有帮助，我想邀请你帮我三个小忙：关注小编，同时可以期待后续文章ing🚀，不定期分享原创知识。
鸿蒙(HarmonyOS)学习路线总结
安辉
09-05 3140
以上的内容都简单过了一遍，去开发者学堂把相关基础视频看一遍，就能做项目了，边做边学如果您想第一时间看我的后期文章，扫码关注公众号安辉编程笔记 - 开发技术分享扫描二维码加关注。
鸿蒙next开发：WaterFlow高性能开发指南
shudaoshanQAQ的博客
05-21 1743
瀑布流常用于展示图片信息，如多用于购物、资讯类应用。
鸿蒙HarmonyOS 5.0开发实战：主页瀑布流实现案例
m0_73088370的博客
03-03 415
本示例介绍使用ArkUIWaterFlow组件和LazyForEach实现瀑布流场景。
鸿蒙HarmonyOS NEXT开发：ArkUI高性能开发-（全局自定义组件复用实现）
diongdingQAQ的博客
09-12 1184
默认的组件复用行为，是将子组件放在父组件的缓存池里..........
HarmonyOS（设备场景适配）——折叠屏应用指南(二)
shangkangba的博客
11-08 1317
折叠屏悬停描述折叠屏中的折痕避让和悬停适配，并介绍了折叠屏悬停的一些典型场景。1.悬停适配与折痕避让折叠屏产品具有独特的悬停态，即用户可以将产品半折后立在桌面上，实
鸿蒙NEXT开发动画案例10
鸿蒙布道师
05-16 991
本文介绍了如何在鸿蒙系统中创建一个名为SpinTen的动画组件。首先，在Page文件夹下新建Spin.ets文件，定义了一个包含旋转动画的组件，通过Grid布局和Canvas绘制实现动画效果。接着，修改Index.ets文件，引入并调用SpinTen组件，设置其大小和颜色。最后，运行项目并登录华为账号进行签名，即可看到动画效果。该动画通过Keyframe动画实现，具有平滑的缩放和位移效果，适用于加载或等待场景。
鸿蒙Next API17学习新特性之组件可见区域变化事件新增支持设置事件的回调参数，限制它的执行间隔
风中追风
05-14 628
鸿蒙开发文档更新的非常快，对应我们开发者的学习能力也要求非常高，今天这篇文章给大家分享一下鸿蒙API17中更新的新特性学习。鸿蒙 Next 的组件可见区域变化事件在最新的 API Version 17 中得到了增强，新增了支持设置事件的回调参数的功能，并能够限制回调的执行间隔。这一改进使得开发者可以更精细地控制组件可见区域变化事件的触发频率，从而优化应用性能和用户体验。本文将深入探讨这一新特性的使用方法和应用场景。
【HarmonyOs鸿蒙】七种传参方式
m0_64455070的博客
05-13 536
在HarmonyOS应用开发中，参数传递是组件间通信和数据共享的重要机制。以下是鸿蒙（ArkUI）开发中常见的7种传参方式及其具体实现
鸿蒙5.0项目开发——鸿蒙天气项目的实现（主页2）
高心星的专栏
05-16 98
这是一个基于 HarmonyOS 开发的天气应用，提供实时天气查询、天气预报和城市搜索等功能。
HarmonyOS 开发之 —— 合理使用动画与转场
最新发布
this_is_bug的博客
05-16 85
本文介绍了在HarmonyOS开发中如何合理使用动画与转场效果，以提升用户体验。首先，文章详细讲解了属性动画（Property Animation），包括其核心组件如Animator、ValueAnimator、ObjectAnimator，以及插值器和估值器的作用。通过代码示例展示了如何实现视图位置移动、组合动画（缩放与透明度变化）以及自定义属性动画。接着，文章探讨了转场动画（Transition Animation），分为简单转场和带共享元素的转场，并提供了页面滑动切换和图片点击放大进入新页面的具体实现
OpenHarmony 开源鸿蒙南向开发——linux下使用make交叉编译第三方库——wget
我是晚秋，我在这里，谢谢你的看见。
05-14 418
本文介绍了在Linux环境下为OpenHarmony（开源鸿蒙）南向开发配置交叉编译环境的过程，重点是如何编译第三方库Wget及其依赖库（如Gnutls、gmp、nettle、libunistring）。首先，下载并解压Wget源码，然后设置环境变量，包括OpenHarmony SDK路径和交叉编译工具链（如clang、llvm等）。接着，配置编译选项，如目标架构（armv7a）和依赖库路径，并通过./configure和make命令完成编译和安装。整个过程旨在为OpenHarmony开发提供必要的工具链和
鸿蒙接入flutter环境变量配置windows-命令行或者手动配置-到项目的创建-运行demo项目
weixin_42301175的博客
05-13 690
鸿蒙接入flutter环境变量配置windows-命令行或者手动配置-到项目的创建-运行demo项目
HarmonyOS概述
学无止境
05-14 1063
HarmonyOS（鸿蒙操作系统）是由华为公司研发的分布式操作系统，专为万物互联时代设计。它支持多种终端设备，如手机、平板、智能穿戴设备等，提供全场景业务功能，包括移动办公、运动健康等。HarmonyOS的核心理念是“一次开发，多端部署”，通过分布式技术实现设备间的协同工作，逻辑上融合为一个超级终端。系统采用分层架构，包括内核层、系统服务层、框架层和应用层，支持多种开发语言，如C/C++、Java、ArkTS等。HarmonyOS的目标是覆盖“1+8+N”全场景终端设备，提供统一生态和原生智能体验。自201
鸿蒙OS&UniApp 实现的地图定位与导航功能#三方框架 #Uniapp
小淼淼的博客
05-15 832
最近在做一个外勤签到应用，需要实现地图定位、标记和导航功能。由于产品需要覆盖安卓、iOS、鸿蒙等多个平台，我们选择了UniApp作为开发框架。其中对鸿蒙系统的适配是一个新挑战，经过一番摸索，总结出了一套可行的实现方案，今天就把这个过程分享给大家。通过本文，我们详细介绍了如何在UniApp框架下实现地图定位与导航功能，并针对鸿蒙系统进行了适配。基础地图组件：使用UniApp的map组件实现地图展示与交互定位功能：获取用户当前位置并显示在地图上标记功能：在地图上添加与管理标记点导航功能。
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值