目录

WaterFlow

瀑布流容器,由“行”和“列”分割的单元格所组成,通过容器自身的排列规则,将不同大小的“项目”自上而下,如瀑布般紧密布局。支持多列布局、分组混合布局、懒加载、自动计算列数和边缘渐隐等功能,适用于图片画廊、商品展示、内容信息流等需要展示不同尺寸内容的场景。

该组件从API version 9 开始支持。后续版本如有新增内容,则采用上角标单独标记该内容的起始版本。

WaterFlow组件支持展示瀑布流布局,不支持编辑模式和子元素拖动功能。

组件内部已绑定手势实现跟手滚动等功能,需要增加自定义手势操作时请参考手势拦截增强进行处理。

更多WaterFlow开发说明请参考创建瀑布流(WaterFlow),NDK开发请参考使用瀑布流,C API接口请参考ArkUI_NodeAttributeType(滚动容器类组件相关属性)和ArkUI_WaterFlowSectionOption。

子组件

仅支持FlowItem子组件和自定义组件。自定义组件在WaterFlow下使用时,建议使用FlowItem作为自定义组件的顶层组件,不建议给自定义组件设置属性和事件方法。

支持通过渲染控制类型(if/else、ForEach、LazyForEach和Repeat)动态生成子组件,更推荐使用LazyForEach或Repeat以优化性能。

WaterFlow子组件的visibility属性设置为None时不显示,但该子组件周围的columnsGap、rowsGap、margin仍会生效。

在涉及大量子组件的情况下,建议采用懒加载、缓存数据、组件复用、固定宽高以及布局优化等方法,以提升性能和减少内存占用。最佳实践请参考优化瀑布流加载慢丢帧问题。

纵向布局时,WaterFlow会计算每一列中已放置子组件的累计高度,并将新子组件放入累计高度最小的那一列,以保持整体布局紧凑。

当FlowItem的主轴大小在显示后发生变化时,WaterFlow会清理受影响的布局信息,并根据当前layoutMode从变化位置或当前窗口起始位置重新计算相关FlowItem的布局位置。由于瀑布流会将重新参与布局的FlowItem放入当前累计主轴大小最小的列或行,这些FlowItem所在列或行及偏移可能发生变化,表现为位置跳动。为减少位置跳动,建议保持FlowItem主轴大小稳定;图片等异步内容建议预先设置固定宽高或占位大小,使用分组混合布局时也可以通过GetItemMainSizeByIndex回调提供稳定的主轴大小。

使用LazyForEach或Repeat动态生成FlowItem时,如果影响FlowItem主轴大小的数据发生变化,应同时通知框架数据已变化:LazyForEach场景请调用DataChangeListener对应方法(如onDataChange、onDataReloaded或onDatasetChange);Repeat场景应按Repeat的数据更新规则修改状态数组。否则可能复用旧节点或旧缓存,导致显示内容、布局结果与数据不一致。

若多个列的高度相同,优先放入最左边的列。在RTL模式下,优先放入最右边的列。

从API version 21开始,WaterFlow单个子组件的宽高最大为16777216px;API version 20及之前,WaterFlow单个子组件的宽高最大为1000000px。子组件超出该大小可能导致滚动或显示异常。

接口

WaterFlow(options?: WaterFlowOptions)

创建瀑布流容器。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

参数名 类型 必填 说明
options WaterFlowOptions 否 瀑布流组件参数,用于设置滚动控制器、尾部组件、分组和布局模式。

WaterFlowOptions对象说明

瀑布流组件参数对象。

系统能力: SystemCapability.ArkUI.ArkUI.Full

名称 类型 只读 可选 说明
footer CustomBuilder 否 是

设置WaterFlow尾部组件,用于在瀑布流末尾显示自定义内容(如加载提示、底部标识等)。不设置时不显示尾部组件。

说明:

1. 使用方法参见示例1。

2. 同时设置footer和footerContent时,以footerContent设置的组件为准。

3. 使用分组混合布局时不支持单独设置footer,可以使用最后一个分组作为尾部组件。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

footerContent18+ ComponentContent 否 是

设置WaterFlow尾部组件。

该参数的优先级高于参数footer,即同时设置footer和footerContent时,以footerContent设置的组件为准;未设置footerContent时,footer参数仍可设置尾部组件。使用分组混合布局时不支持单独设置尾部组件,可以使用最后一个分组作为尾部组件。

元服务API: 从API version 18开始,该接口支持在元服务中使用。

模型约束: 此接口仅可在Stage模型下使用。

scroller Scroller 否 是

可滚动组件的控制器,与可滚动组件绑定。不设置时不绑定外部控制器,组件自行管理滚动行为。

说明:

1. 不允许和其他滚动类组件,如:ArcList、List、Grid、Scroll和WaterFlow绑定同一个滚动控制对象。

2. 使用SLIDING_WINDOW布局模式时,scroller的currentOffset或offset接口返回的总偏移量在触发跳转或数据更新后不准确,回滑到顶部时会重新校准。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

sections12+ WaterFlowSections 否 是

设置FlowItem分组,实现同一个瀑布流组件内部各分组使用不同列数混合布局。适用于需要在不同区域使用不同列数布局的场景。不设置时使用统一列数布局。

说明:

1. 使用分组混合布局时会忽略columnsTemplate和rowsTemplate属性。

2. 使用分组混合布局时不支持单独设置footer,可以使用最后一个分组作为尾部组件。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

模型约束: 此接口仅可在Stage模型下使用。

layoutMode12+ WaterFlowLayoutMode 否 是

设置WaterFlow的布局模式,根据使用场景选择更切合的模式。ALWAYS_TOP_DOWN适用于固定列数场景;SLIDING_WINDOW适用于动态列数、大数据量、屏幕旋转等场景。

说明:

默认值:ALWAYS_TOP_DOWN。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

模型约束: 此接口仅可在Stage模型下使用。

WaterFlowSections12+

瀑布流分组信息。

使用splice、push、update修改分组信息后需要保证所有分组子组件总数与瀑布流实际子组件总数一致,否则会出现瀑布流因为不能正常布局而无法滑动的问题。

[h2]constructor

constructor()

创建一个瀑布流分组。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

[h2]splice12+

splice(start: number, deleteCount?: number, sections?: Array<SectionOptions>): boolean

移除或者替换已存在的分组和/或添加新分组。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

参数名 类型 必填 说明
start number 是

从0开始计算的索引,会转换为整数,表示要开始改变分组的位置。

说明:

1. 如果索引是负数,则从末尾开始计算,使用start + WaterFlowSections.length()。

2. 如果 start < -WaterFlowSections.length(),则使用0。

3. 如果 start >= WaterFlowSections.length(),则在最后添加新分组。

deleteCount number 否

表示要从start开始删除的分组数量。

说明:

1. 如果省略了deleteCount,或者其值大于或等于由start指定的位置到WaterFlowSections末尾的分组数量,那么从start到WaterFlowSections末尾的所有分组将被删除。

2. 如果deleteCount是0或者负数,则不会删除任何分组。

sections Array<SectionOptions> 否 表示要从start开始加入的分组。如果不指定,splice()将只从瀑布流中删除分组。

返回值:

类型 说明
boolean 分组修改成功返回true;修改失败(要加入的分组中有任意分组的itemsCount不是非负数)返回false。

[h2]push12+

push(section: SectionOptions): boolean

将指定分组添加到瀑布流末尾。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

参数名 类型 必填 说明
section SectionOptions 是 添加到瀑布流末尾的分组,包含该分组的FlowItem数量、列数/行数、间距、外边距和主轴大小回调等配置信息。

返回值:

类型 说明
boolean 分组添加成功返回true,添加失败(新分组的itemsCount不是非负数)返回false。

[h2]update12+

update(sectionIndex: number, section: SectionOptions): boolean

修改指定索引分组的配置信息。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

参数名 类型 必填 说明
sectionIndex number 是

从0开始计算的索引,会转换为整数,表示要修改的分组的位置。

说明:

1. 如果索引是负数,则从末尾开始计算,使用sectionIndex + WaterFlowSections.length()。

2. 如果sectionIndex < -WaterFlowSections.length(),则使用0。

3. 如果sectionIndex >= WaterFlowSections.length(),则在最后添加新分组。

section SectionOptions 是 新的分组信息,用于替换指定索引位置的FlowItem分组配置,包括FlowItem数量、列数/行数、间距、外边距和主轴大小回调等。

返回值:

类型 说明
boolean 分组更新成功返回true,更新失败(新分组的itemsCount不是非负数)返回false。

[h2]values12+

values(): Array<SectionOptions>

获取瀑布流中所有分组配置信息。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

返回值:

类型 说明
Array<SectionOptions> 瀑布流中所有分组配置信息。

[h2]length12+

length(): number

获取瀑布流中分组数量。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

返回值:

类型 说明
number 瀑布流中分组数量。

SectionOptions12+对象说明

FlowItem分组配置信息。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

名称 类型 只读 可选 说明
itemsCount number 否 否 分组中FlowItem数量,必须是非负数。若splice、push、update方法收到的分组中有分组的itemsCount小于0,则该方法不会生效(返回false)。避免使用itemsCount为0的分组,否则可能导致布局计算异常。
crossCount number 否 是 纵向布局时为列数,横向布局时为行数,默认值:1。小于1的按默认值处理。
columnsGap Dimension 否 是 该分组的列间距,不设置该参数时默认使用瀑布流的columnsGap,设置非法值时使用0vp。
rowsGap Dimension 否 是 该分组的行间距,不设置该参数时默认使用瀑布流的rowsGap,设置非法值时使用0vp。
margin Margin | Dimension 否 是

该分组的外边距参数为Length类型时,四个方向外边距同时生效。

默认值:0

单位:vp

margin设置百分比时,上下左右外边距均以瀑布流的width作为基础值。

onGetItemMainSizeByIndex GetItemMainSizeByIndex 否 是

瀑布流组件布局过程中获取指定index的FlowItem的主轴大小,纵向瀑布流时为高度,横向瀑布流时为宽度,单位vp。不设置时,瀑布流按FlowItem的常规测量结果确定主轴大小。

说明:

1. 同时使用onGetItemMainSizeByIndex和FlowItem的宽高属性时,主轴大小以onGetItemMainSizeByIndex返回结果为准,onGetItemMainSizeByIndex会覆盖FlowItem的主轴长度。

2. 使用onGetItemMainSizeByIndex可以提高瀑布流跳转到指定位置或index时的效率,避免混用设置onGetItemMainSizeByIndex和未设置的分组,否则会导致布局异常。

3. onGetItemMainSizeByIndex返回负数时,FlowItem主轴大小为0。

4. 如果FlowItem主轴大小会随数据动态变化,应保证onGetItemMainSizeByIndex返回值与数据源保持一致。使用LazyForEach时,数据变化后应调用onDataChange、onDataReloaded或onDatasetChange等方法通知框架数据已变化;使用Repeat时,应按Repeat的数据更新规则修改状态数组。

GetItemMainSizeByIndex12+

type GetItemMainSizeByIndex = (index: number) => number

根据index获取指定Item的主轴大小。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

参数名 类型 必填 说明
index number 是

FlowItem在WaterFlow中的索引。

取值范围:[0, 子组件总数-1]

返回值:

类型 说明
number 指定index的FlowItem的主轴大小,纵向瀑布流时为高度,横向瀑布流时为宽度,单位vp。

WaterFlowLayoutMode12+枚举说明

瀑布流组件布局模式枚举。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

名称 值 说明
ALWAYS_TOP_DOWN 0 默认的从上到下的布局模式。视窗内的FlowItem依赖视窗上方所有FlowItem的布局信息。因此跳转或切换列数时,需要计算出上方所有的FlowItem的布局信息。
SLIDING_WINDOW 1

移动窗口式的布局模式。只考虑视窗内的布局信息,对视窗上方的FlowItem没有依赖关系,因此向后跳转或切换列数时只需要布局视窗内的FlowItem。建议优先采用该模式,尤其在应用需要支持屏幕旋转或动态切换列数的场景下。

说明:

1. 无动画跳转到较远的位置时,会以目标位置为基准,向前或向后布局FlowItem。这之后如果滑回跳转前的位置,内容的布局效果可能和之前不一致。这个效果会导致跳转后回滑到顶部时,顶部节点可能不对齐。

2. 使用SLIDING_WINDOW布局模式并设置WaterFlowSections分组时,滚动动画结束后,若视窗内包含分组起始位置,且检测到该分组在视窗内的列或行起始位置未对齐,或分组起始FlowItem与分组起始索引不一致,WaterFlow会重新计算布局以校正分组内容位置。

3. 使用SLIDING_WINDOW布局模式调用backToTop回到顶部操作时,若回顶动画结束后仍未到达顶部,WaterFlow会执行一次无动画的顶部校正,使内容重新对齐到起始位置。

4. scroller的currentOffset或offset接口返回的总偏移量在触发跳转或数据更新后不准确,在回滑到顶部时会重新校准,从API version 23开始,新增offset接口。

5. 如果在同一帧内调用跳转(如无动画的scrollToIndex、scrollEdge)和输入偏移量(如滑动手势或滚动动画),两者都会生效。

6. 调用无动画的scrollToIndex进行跳转,如果跳转到较远位置(超过视窗内的FlowItem数量的位置)时,移动窗口模式对总偏移量进行估算。

7. 仅在API version 18及以上版本中支持滚动条scrollBar显示。低于此版本时,设置滚动条将不显示。

对比维度 ALWAYS_TOP_DOWN (默认) SLIDING_WINDOW
适用场景 固定列数 动态列数、大数据量、屏幕旋转
布局策略 从顶部开始完整布局 滑动窗口式布局
性能特点 依赖上方所有 FlowItem 只考虑视窗内布局
跳转效率 需要计算上方所有布局 快速跳转,无需完整计算
列数切换 需要重新计算全部布局 只重新布局视窗内容
屏幕旋转 支持,但性能较差 支持,性能好
滚动条显示 始终支持 API 18+ 支持
布局一致性 始终保持一致 跳转后可能不一致

属性

除支持通用属性和滚动组件通用属性外,还支持以下属性:

WaterFlow组件使用通用属性clip12+和通用属性clip18+时默认值都为true。

WaterFlow组件的内容裁剪模式为ContentClipMode.CONTENT_ONLY,padding区域会被裁剪不显示。

[h2]columnsTemplate

columnsTemplate(value: string)

设置当前瀑布流组件布局列的数量,不设置时默认1列。当layoutDirection设置为横向布局(FlexDirection.Row或FlexDirection.RowReverse)时,columnsTemplate不生效,由rowsTemplate控制布局。使用sections分组混合布局时,此属性会被忽略。

例如,'1fr 1fr 2fr' 是将父组件分3列,将父组件允许的宽分为4等份,第1列占1份,第2列占1份,第3列占2份。

可使用columnsTemplate('repeat(auto-fill,track-size)')根据给定的列宽track-size自动计算列数,其中repeat、auto-fill为关键字,track-size为可设置的宽度,支持的单位包括px、vp、%或有效数字,默认单位为vp,使用方法参见示例2。

非repeat形式的模板串中每项仅支持'数字+fr'、'数字+px'、'数字+%'三种格式,不支持vp(如columnsTemplate('100vp 100vp'))。需要按固定vp尺寸自动计算列数时,应使用repeat(auto-fill, track-size)。

设置为'0fr'时,该列的列宽为0,该列FlowItem不显示。设置为其他非法值时,按固定1列处理。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

参数名 类型 必填 说明
value string 是

当前瀑布流组件布局列的数量。

默认值:'1fr'

[h2]columnsTemplate22+

columnsTemplate(value: string | ItemFillPolicy)

设置当前瀑布流组件布局列的数量,不设置时默认1列。当layoutDirection设置为横向布局(FlexDirection.Row或FlexDirection.RowReverse)时,columnsTemplate不生效,由rowsTemplate控制布局。使用sections分组混合布局时,此属性会被忽略。

当value设置为string类型时,使用方法参考columnsTemplate(value: string)。

当value设置为ItemFillPolicy类型时,将根据WaterFlow组件宽度对应断点类型确定列数。

例如,将ItemFillPolicy的fillType属性设置为PresetFillType.BREAKPOINT_DEFAULT时,在组件宽度属于sm及更小的断点区间时显示2列,属于md断点区间时显示3列,属于lg及更大的断点区间时显示5列,且每列均为1fr。

元服务API: 从API version 22开始,该接口支持在元服务中使用。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

参数名 类型 必填 说明
value string | ItemFillPolicy 是 当前瀑布流组件布局列的数量。当value为ItemFillPolicy类型时,根据WaterFlow组件宽度对应断点类型自动确定列数。

[h2]rowsTemplate

rowsTemplate(value: string)

设置当前瀑布流组件布局行的数量,不设置时默认1行。当layoutDirection设置为纵向布局(FlexDirection.Column或FlexDirection.ColumnReverse)或不设置时,rowsTemplate不生效,由columnsTemplate控制布局。使用sections分组混合布局时,此属性会被忽略。

例如,'1fr 1fr 2fr'是将父组件分3行,将父组件允许的高分为4等份,第1行占1份,第2行占1份,第3行占2份。

可使用rowsTemplate('repeat(auto-fill,track-size)')根据给定的行高track-size自动计算行数,其中repeat、auto-fill为关键字,track-size为可设置的高度,支持的单位包括px、vp、%或有效数字,默认单位为vp。

非repeat形式的模板串中每项仅支持'数字+fr'、'数字+px'、'数字+%'三种格式,不支持vp(如rowsTemplate('100vp 100vp'))。需要按固定vp尺寸自动计算行数时,应使用repeat(auto-fill, track-size)。

设置为'0fr'时,该行的行高为0,该行FlowItem不显示。设置为其他非法值时,按固定1行处理。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

参数名 类型 必填 说明
value string 是

当前瀑布流组件布局行的数量。

默认值:'1fr'

[h2]itemConstraintSize

itemConstraintSize(value: ConstraintSizeOptions)

设置约束尺寸,用于在子组件布局时限制其尺寸范围。使用方法参考示例1。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

参数名 类型 必填 说明
value ConstraintSizeOptions 是

约束尺寸。设置小于0的值,参数不生效。

说明:

1.同时设置itemConstraintSize和FlowItem的constraintSize属性时,minWidth/minHeight会取其中的最大值,maxWidth/maxHeight会取其中的最小值,调整后的值作为FlowItem的constraintSize处理。

2.只设置itemConstraintSize时,相当于对WaterFlow所有子组件设置了相同的constraintSize。

3.itemConstraintSize通过以上两种方式转换成FlowItem的constraintSize后的生效规则与通用属性constraintSize相同。

[h2]columnsGap

columnsGap(value: Length)

设置列与列的间距。使用分组布局时,各分组可通过SectionOptions.columnsGap单独设置列间距覆盖此值。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

参数名 类型 必填 说明
value Length 是

列与列的间距。

默认值:0

单位:vp

取值范围:[0, +∞),小于0时按0处理。

[h2]rowsGap

rowsGap(value: Length)

设置行与行的间距。使用分组布局时,各分组可通过SectionOptions.rowsGap单独设置行间距覆盖此值。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

参数名 类型 必填 说明
value Length 是

行与行的间距。

默认值:0

单位:vp

取值范围:[0, +∞),小于0时按0处理。

[h2]layoutDirection

layoutDirection(value: FlexDirection)

设置布局的主轴方向。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

参数名 类型 必填 说明
value FlexDirection 是

布局的主轴方向。

默认值:FlexDirection.Column

layoutDirection优先级高于rowsTemplate和columnsTemplate。根据layoutDirection设置情况,分为以下三种设置模式:

[h2]enableScrollInteraction10+

enableScrollInteraction(value: boolean)

设置是否支持滚动手势。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

参数名 类型 必填 说明
value boolean 是

是否支持滚动手势。设置为true时可以通过手指或者鼠标滚动,设置为false时无法通过手指或者鼠标滚动,但不影响控制器Scroller的滚动接口。

默认值:true

组件无法通过鼠标按下拖动操作进行滚动。

[h2]nestedScroll10+

nestedScroll(value: NestedScrollOptions)

设置前后两个方向的嵌套滚动模式,实现与父组件的滚动联动。使用方法参考嵌套滚动实现方式二。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

参数名 类型 必填 说明
value NestedScrollOptions 是 嵌套滚动选项,用于设置前后两个方向的嵌套滚动模式,实现与父组件的滚动联动。

[h2]friction10+

friction(value: number | Resource)

设置摩擦系数,手动滑动滚动区域时生效,仅影响惯性滚动过程,对嵌套滚动时惯性向父组件传递的联动效果有间接影响。适用于需要调整瀑布流滑动惯性效果的场景。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

参数名 类型 必填 说明
value number | Resource 是

摩擦系数。

默认值:非可穿戴设备为0.6,可穿戴设备为0.9。

从API version 11开始,非可穿戴设备默认值为0.7。

从API version 12开始,非可穿戴设备默认值为0.75。

取值范围:(0, +∞),设置为小于等于0的值时,按默认值处理。

[h2]cachedCount11+

cachedCount(value: number)

设置预加载的FlowItem数量。

只在LazyForEach和开启了virtualScroll开关的Repeat中生效,超出显示及缓存范围的FlowItem会被释放。

元服务API: 从API version 12开始,该接口支持在元服务中使用。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

参数名 类型 必填 说明
value number 是

预加载的FlowItem的数量。

默认值:根据屏幕内显示的节点个数设置,最大值为16。

取值范围:[0, +∞),设置为小于0的值时,按1处理。

[h2]cachedCount14+

cachedCount(count: number, show: boolean)

设置预加载的FlowItem数量,并配置是否显示预加载节点。

配合clip或clipContent属性可以显示出预加载节点。

只在LazyForEach和开启了virtualScroll开关的Repeat中生效,超出显示及缓存范围的FlowItem会被释放。

元服务API: 从API version 14开始,该接口支持在元服务中使用。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

参数名 类型 必填 说明
count number 是

预加载的FlowItem的数量。

默认值:根据屏幕内显示的节点个数设置,最大值为16。

取值范围:[0, +∞),设置为小于0的值时,按1处理。

show boolean 是

被预加载的FlowItem是否需要显示。设置为true时显示预加载的FlowItem,设置为false时不显示预加载的FlowItem。

默认值:false

[h2]syncLoad20+

syncLoad(enable: boolean)

设置是否同步加载WaterFlow区域内所有子组件。

元服务API: 从API version 20开始,该接口支持在元服务中使用。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

参数名 类型 必填 说明
enable boolean 是

是否同步加载WaterFlow区域内所有子组件。

true表示同步加载,false表示异步加载。

默认值:true。

说明:

设置为false时,在首次显示、不带动画scrollToIndex跳转场景,若当帧布局耗时超过50ms,会将WaterFlow区域内尚未布局的子组件延后到下一帧进行布局。

[h2]supportEmptyBranchInLazyLoading

supportEmptyBranchInLazyLoading(supported: boolean | undefined)

设置当前WaterFlow组件是否支持在LazyForEach或Repeat中使用if/else渲染控制语法生成不包含任何子组件的空分支节点。未设置时不支持空分支节点。此属性初次赋值后不支持更新,所以赋值后无法在支持空分支、不支持空分支行为之间切换。

当通过sections参数设置了WaterFlowSections分组,或通过layoutMode设置SLIDING_WINDOW布局模式时,无论supportEmptyBranchInLazyLoading设为何值或未设置,空分支后的FlowItem都会显示。

起始版本: 26.0.0

模型约束: 此接口仅可在Stage模型下使用。

元服务API: 从API版本26.0.0开始,该接口支持在元服务中使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

参数名 类型 必填 说明
supported boolean | undefined 是

当前WaterFlow组件是否支持在LazyForEach或Repeat中使用if/else渲染控制语法生成一个不含任何子组件的空分支节点。

true表示显示空分支后的FlowItem;false表示不显示空分支后的FlowItem。

值为undefined时,按false处理。

事件

除支持通用事件和滚动组件通用事件外,还支持以下事件:

[h2]onReachStart

onReachStart(event: () => void)

瀑布流内容到达起始位置时触发。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

参数名 类型 必填 说明
event () => void 是 瀑布流内容到达起始位置时触发的回调。

[h2]onReachEnd

onReachEnd(event: () => void)

瀑布流内容到达末尾位置时触发。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

参数名 类型 必填 说明
event () => void 是 瀑布流内容到达末尾位置时触发的回调。

[h2]onScrollFrameBegin10+

onScrollFrameBegin(event: OnScrollFrameBeginCallback)

该接口回调时,事件参数传入即将发生的滑动量。事件处理函数可根据应用场景计算实际需要的滑动量,并返回该值。瀑布流将按照返回的实际滑动量进行滑动。适用于需要自定义滚动行为的场景,例如按比例调整单帧滑动量,或在特定条件下阻止本帧滑动。

满足以下任一条件时触发该事件:

  1. 用户交互(如手指滑动、键鼠操作等)触发滚动。
  2. WaterFlow惯性滚动。
  3. 调用fling接口触发滚动。

不触发该事件的条件:

  1. 调用除fling接口外的其他滚动控制接口。
  2. 越界回弹。
  3. 拖动滚动条。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

参数名 类型 必填 说明
event OnScrollFrameBeginCallback 是 每帧滚动开始回调函数。

[h2]onScrollIndex11+

onScrollIndex(event: (first: number, last: number) => void)

当前瀑布流显示的起始位置/终止位置的子组件发生变化时触发。瀑布流初始化时会触发一次。

瀑布流显示区域上第一个子组件/最后一个组件的索引值有变化就会触发。

从API version 20开始,该接口支持在attributeModifier中调用。

元服务API: 从API version 11开始,该接口支持在元服务中使用。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

参数名 类型 必填 说明
first number 是

当前显示的瀑布流起始位置的索引值。

正常取值范围:[0, 子组件总数-1]。列表为空时存在特殊取值,详见下表。

last number 是

当前显示的瀑布流终止位置的索引值。

正常取值范围:[0, 子组件总数-1]。列表为空时存在特殊取值,详见下表。

通过last参数可以判断是否“继续加载数据”,参考示例3(使用分组)中“即将触底时提前增加数据”的处理逻辑。

当WaterFlow列表为空时,使用不同的WaterFlowOptions参数会导致onScrollIndex事件的返回值有所不同。具体差异请参见下表:

layoutMode sections first last
ALWAYS_TOP_DOWN 无 0 0
ALWAYS_TOP_DOWN 有 0 -1
SLIDING_WINDOW 可选 1000000 -1

UIWaterFlowEvent19+

frameNode中getEvent('WaterFlow')方法的返回值,可用于给WaterFlow节点设置滚动事件。

UIWaterFlowEvent继承于UIScrollableCommonEvent。

[h2]setOnWillScroll19+

setOnWillScroll(callback: OnWillScrollCallback | undefined): void

设置onWillScroll事件的回调。

方法入参为undefined时,会重置事件回调。

元服务API: 从API version 19开始,该接口支持在元服务中使用。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

参数名 类型 必填 说明
callback OnWillScrollCallback | undefined 是 onWillScroll事件的回调函数。

[h2]setOnDidScroll19+

setOnDidScroll(callback: OnScrollCallback | undefined): void

设置onDidScroll事件的回调。

setOnWillScroll用于设置每帧滚动开始前的回调,setOnDidScroll用于设置每帧滚动完成后的回调。两者可同时使用,setOnWillScroll的回调先于setOnDidScroll触发。

方法入参为undefined时,会重置事件回调。

元服务API: 从API version 19开始,该接口支持在元服务中使用。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

参数名 类型 必填 说明
callback OnScrollCallback | undefined 是 onDidScroll事件的回调函数。

[h2]setOnScrollIndex19+

setOnScrollIndex(callback: OnWaterFlowScrollIndexCallback | undefined): void

设置onScrollIndex事件的回调。

方法入参为undefined时,会重置事件回调。

元服务API: 从API version 19开始,该接口支持在元服务中使用。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

参数名 类型 必填 说明
callback OnWaterFlowScrollIndexCallback | undefined 是 onScrollIndex事件的回调函数。

OnWaterFlowScrollIndexCallback19+

type OnWaterFlowScrollIndexCallback = (first: number, last: number) => void

WaterFlow组件可见区域item变化事件的回调类型。

元服务API: 从API version 19开始,该接口支持在元服务中使用。

模型约束: 此接口仅可在Stage模型下使用。

系统能力: SystemCapability.ArkUI.ArkUI.Full

参数:

参数名 类型 必填 说明
first number 是

当前显示的瀑布流起始位置的索引值。

正常取值范围:[0, 子组件总数-1]。列表为空时存在特殊取值,详见onScrollIndex事件说明。

last number 是

当前显示的瀑布流终止位置的索引值。

正常取值范围:[0, 子组件总数-1]。列表为空时存在特殊取值,详见onScrollIndex事件说明。

示例

[h2]示例1(使用基本瀑布流)

该示例展示了WaterFlow组件数据加载处理、属性设置和事件回调等基本使用场景。

WaterFlowDataSource实现了LazyForEach数据源接口IDataSource,用于通过LazyForEach给WaterFlow提供子组件。

当LazyForEach数据中影响FlowItem宽高的字段发生变化时,需要在修改数据后通知DataChangeListener,例如调用onDataChange或onDataReloaded。只修改数据内容但不触发数据变化通知时,LazyForEach可能不会刷新对应FlowItem。

// WaterFlowDataSource.ets

// 实现IDataSource接口的对象,用于瀑布流组件加载数据
export class WaterFlowDataSource implements IDataSource {
  private dataArray: number[] = [];
  private listeners: DataChangeListener[] = [];

  constructor() {
    for (let i = 0; i < 100; i++) {
      this.dataArray.push(i);
    }
  }

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

  // 通知控制器数据重新加载
  notifyDataReload(): void {
    this.listeners.forEach(listener => {
      listener.onDataReloaded();
    });
  }

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

  // 通知控制器数据变化
  notifyDataChange(index: number): void {
    this.listeners.forEach(listener => {
      listener.onDataChange(index);
    });
  }

  // 通知控制器数据删除
  notifyDataDelete(index: number): void {
    this.listeners.forEach(listener => {
      listener.onDataDelete(index);
    });
  }

  // 通知控制器数据位置变化
  notifyDataMove(from: number, to: number): void {
    this.listeners.forEach(listener => {
      listener.onDataMove(from, to);
    });
  }

  // 通知控制器数据批量修改
  notifyDatasetChange(operations: DataOperation[]): void {
    this.listeners.forEach(listener => {
      listener.onDatasetChange(operations);
    });
  }

  // 获取数据总数
  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);
    }
  }

  // 增加数据
  public add1stItem(): void {
    this.dataArray.splice(0, 0, this.dataArray.length);
    this.notifyDataAdd(0);
  }

  // 在数据尾部增加一个元素
  public addLastItem(): void {
    this.dataArray.splice(this.dataArray.length, 0, this.dataArray.length);
    this.notifyDataAdd(this.dataArray.length - 1);
  }

  // 在指定索引位置增加一个元素
  public addItem(index: number): void {
    this.dataArray.splice(index, 0, this.dataArray.length);
    this.notifyDataAdd(index);
  }

  // 删除第一个元素
  public delete1stItem(): void {
    this.dataArray.splice(0, 1);
    this.notifyDataDelete(0);
  }

  // 删除第二个元素
  public delete2ndItem(): void {
    this.dataArray.splice(1, 1);
    this.notifyDataDelete(1);
  }

  // 删除最后一个元素
  public deleteLastItem(): void {
    this.dataArray.splice(-1, 1);
    this.notifyDataDelete(this.dataArray.length);
  }

  // 在指定索引位置删除一个元素
  public deleteItem(index: number): void {
    this.dataArray.splice(index, 1);
    this.notifyDataDelete(index);
  }

  // 重新加载数据
  public reload(): void {
    this.dataArray.splice(1, 1);
    this.dataArray.splice(3, 2);
    this.notifyDataReload();
  }

  // 在数据尾部增加count个元素
  public addNewItems(count: number): void {
    let len = this.dataArray.length;
    for (let i = 0; i < count; i++) {
      this.dataArray.push(this.dataArray[len - 1] + i + 1);
      this.notifyDataAdd(this.dataArray.length - 1);
    }
  }

  // 刷新所有元素
  public refreshItems(): void {
    let newDataArray: number[] = [];
    for (let i = 0; i < 100; i++) {
      newDataArray.push(this.dataArray[0] + i + 1000);
    }
    this.dataArray = newDataArray;
    this.notifyDataReload();
  }
}
// Index.ets
import { WaterFlowDataSource } from './WaterFlowDataSource';

enum FooterState {
  LOADING = 0,
  END = 1
}

@Entry
@Component
struct WaterFlowDemo {
  @State minSize: number = 80;
  @State maxSize: number = 180;
  @State colors: number[] = [0xFFC0CB, 0xDA70D6, 0x6B8E23, 0x6A5ACD, 0x00FFFF, 0x00FF7F];
  @State footerState: FooterState = FooterState.LOADING;
  dataSource: WaterFlowDataSource = new WaterFlowDataSource();
  private itemHeightArray: number[] = [];

  // 计算FlowItem宽/高
  getSize() {
    let ret = Math.floor(Math.random() * this.maxSize);
    return (ret > this.minSize ? ret : this.minSize);
  }

  // 设置FlowItem的宽/高数组
  setItemSizeArray() {
    for (let i = 0; i < 100; i++) {
      this.itemHeightArray.push(this.getSize());
    }
  }

  // 组件生命周期:在组件即将出现时初始化尺寸数组
  aboutToAppear() {
    this.setItemSizeArray();
  }

  @Builder
  itemFoot() {
    // 注意:不要直接用IfElse节点作为footer的根节点
    // 必须在外面使用(Column/Row/Stack等)容器包裹,确保布局正确
    Column() {
      if (this.footerState == FooterState.LOADING) {
        Text(`加载中...`)
          .fontSize(10)
          .backgroundColor(Color.Red)
          .width(50)
          .height(50)
          .align(Alignment.Center)
          .margin({ top: 2 })
      } else if (this.footerState == FooterState.END) {
        Text(`到底啦...`)
          .fontSize(10)
          .backgroundColor(Color.Red)
          .width(50)
          .height(50)
          .align(Alignment.Center)
          .margin({ top: 2 })
      } else {
        Text(`Footer`)
          .fontSize(10)
          .backgroundColor(Color.Red)
          .width(50)
          .height(50)
          .align(Alignment.Center)
          .margin({ top: 2 })
      }
    }
  }

  build() {
    Column({ space: 2 }) {
      WaterFlow({ footer: this.itemFoot() }) {
        LazyForEach(this.dataSource, (item: number) => {
          FlowItem() {
            Column() {
              Text('N' + item).fontSize(12).height('16')
              // 注意:需要确保对应的jpg文件存在才会正常显示
              Image('res/waterFlowTest(' + item % 5 + ').jpg')
                .objectFit(ImageFit.Fill)
                .width('100%')
                .layoutWeight(1)
            }
          }
          .width('100%')
          .height(this.itemHeightArray[item % 100])
          .backgroundColor(this.colors[item % this.colors.length])
        }, (item: number) => item.toString())
      }
      .columnsTemplate('1fr 1fr')    // 设置2列等宽布局
      .columnsGap(10)
      .rowsGap(5)
      .backgroundColor(0xFAEEE0)
      .width('100%')
      .height('100%')
      .itemConstraintSize({minWidth:80,maxWidth:180,minHeight:80,maxHeight:180})
      // 触底加载数据:滚动到底部时触发分页加载
      .onReachEnd(() => {
        console.info('onReachEnd');

        // 模拟分页加载:当数据超过200条时停止加载
        if (this.dataSource.totalCount() > 200) {
          this.footerState = FooterState.END;
          return;
        }
        setTimeout(() => {
          for (let i = 0; i < 100; i++) {
            this.dataSource.addLastItem();
          }
        }, 1000);
      })
      .onReachStart(() => {
        // 滚动到顶部时触发
        console.info('waterFlow reach start');
      })
      .onScrollStart(() => {
        // 开始滚动时触发
        console.info('waterFlow scroll start');
      })
      .onScrollStop(() => {
        // 停止滚动时触发
        console.info('waterFlow scroll stop');
      })
      .onScrollFrameBegin((offset: number, state: ScrollState) => {
        // 滚动帧开始时触发:可以控制滚动行为
        // offset:滚动偏移量,state:滚动状态
        console.info('waterFlow scrollFrameBegin offset: ' + offset + ' state: ' + state.toString());
        return { offsetRemain: offset };  // 返回开发者期望的实际滚动偏移量
      })
    }
  }
}

[h2]示例2(自动计算列数)

该示例通过auto-fill实现了自动计算列数的效果。

WaterFlowDataSource说明及完整代码参考示例1(使用基本瀑布流)。

// Index.ets
import { WaterFlowDataSource } from './WaterFlowDataSource';

@Entry
@Component
struct WaterFlowDemo {
  @State minSize: number = 80;
  @State maxSize: number = 180;
  @State colors: number[] = [0xFFC0CB, 0xDA70D6, 0x6B8E23, 0x6A5ACD, 0x00FFFF, 0x00FF7F];
  dataSource: WaterFlowDataSource = new WaterFlowDataSource();
  private itemWidthArray: number[] = [];
  private itemHeightArray: number[] = [];

  // 计算FlowItem宽/高
  getSize() {
    let ret = Math.floor(Math.random() * this.maxSize);
    return (ret > this.minSize ? ret : this.minSize);
  }

  // 设置FlowItem宽/高数组
  setItemSizeArray() {
    for (let i = 0; i < 100; i++) {
      this.itemWidthArray.push(this.getSize());
      this.itemHeightArray.push(this.getSize());
    }
  }

  // 组件生命周期:在组件即将出现时初始化尺寸数组
  aboutToAppear() {
    this.setItemSizeArray();
  }

  build() {
    Column({ space: 2 }) {
      WaterFlow() {
        LazyForEach(this.dataSource, (item: number) => {
          FlowItem() {
            Column() {
              Text('N' + item).fontSize(12).height('16')
              // 存在对应的jpg文件才会显示图片
              Image('res/waterFlowTest(' + item % 5 + ').jpg')
            }
          }
          .width('100%')
          .height(this.itemHeightArray[item % 100])
          .backgroundColor(this.colors[item % this.colors.length])
        }, (item: number) => item.toString())
      }
      // auto-fill自动计算列数
      // 'repeat(auto-fill,80)' 表示:根据容器宽度自动计算能放下多少个80px宽的列
      // 例如:容器宽度400px,则自动计算为5列(400÷80=5)
      .columnsTemplate('repeat(auto-fill,80)')
      .columnsGap(10)
      .rowsGap(5)
      .padding({left:5})
      .backgroundColor(0xFAEEE0)
      .width('100%')
      .height('100%')
    }
  }
}

[h2]示例3(使用分组)

该示例展示了分组的初始化以及splice、update、values、length等接口的不同效果。

如果配合状态管理V2使用,详情见:WaterFlow与makeObserved。

WaterFlowDataSource说明及完整代码参考示例1(使用基本瀑布流)。

// Index.ets
import { WaterFlowDataSource } from './WaterFlowDataSource';

// 可复用组件:优化性能,减少组件创建销毁开销
@Reusable
@Component
struct ReusableFlowItem {
  @State item: number = 0;

  // 组件复用生命周期:从复用缓存中取出时调用
  // 用于更新组件状态,显示新的内容
  aboutToReuse(params: Record<string, number>) {
    this.item = params.item;
    console.info('Reuse item:' + this.item);
  }

  // 组件生命周期:记录组件创建日志
  aboutToAppear() {
    console.info('new item:' + this.item);
  }

  build() {
    Column() {
      // 注意:需要确保对应的jpg文件存在才会正常显示
      Image('res/waterFlowTest(' + this.item % 5 + ').jpg')
        .overlay('N' + this.item, { align: Alignment.Top })
        .objectFit(ImageFit.Fill)
        .width('100%')
        .layoutWeight(1)
    }
  }
}

@Entry
@Component
struct WaterFlowDemo {
  minSize: number = 80;
  maxSize: number = 180;
  colors: number[] = [0xFFC0CB, 0xDA70D6, 0x6B8E23, 0x6A5ACD, 0x00FFFF, 0x00FF7F];
  scroller: Scroller = new Scroller();
  dataSource: WaterFlowDataSource = new WaterFlowDataSource();
  dataCount: number = this.dataSource.totalCount();
  private itemWidthArray: number[] = [];
  private itemHeightArray: number[] = [];
  // 分组管理:WaterFlow的核心特性,支持不同区域使用不同列数
  @State sections: WaterFlowSections = new WaterFlowSections();
  // 分组边距配置:统一的外边距设置
  sectionMargin: Margin = { top: 10, left: 5, bottom: 10, right: 5 };

  oneColumnSection: SectionOptions = {
    itemsCount: 4,                     // 该分组包含4个FlowItem
    crossCount: 1,                     // 使用1列布局
    columnsGap: 5,
    rowsGap: 10,
    margin: this.sectionMargin,
    // 回调函数:动态设置每个item的高度
    onGetItemMainSizeByIndex: (index: number) => {
      return this.itemHeightArray[index % 100];
    }
  };

  // 第二种分组:双列布局,适合展示列表内容
  twoColumnSection: SectionOptions = {
    itemsCount: 2,                     // 该分组包含2个FlowItem
    crossCount: 2,                     // 使用2列布局
    // 回调函数:固定高度100px
    onGetItemMainSizeByIndex: (index: number) => {
      return 100;
    }
  };

  // 最后一个分组:用于处理剩余数据
  lastSection: SectionOptions = {
    itemsCount: 20,                    // 该分组包含20个FlowItem
    crossCount: 2,                     // 使用2列布局
    // 回调函数:使用随机高度
    onGetItemMainSizeByIndex: (index: number) => {
      return this.itemHeightArray[index % 100];
    }
  };

  // 计算FlowItem高度
  getSize() {
    let ret = Math.floor(Math.random() * this.maxSize);
    return (ret > this.minSize ? ret : this.minSize);
  }

  // 设置FlowItem的高度数组
  setItemSizeArray() {
    for (let i = 0; i < 100; i++) {
      this.itemHeightArray.push(this.getSize());
    }
  }

  // 组件生命周期:初始化数据和瀑布流分组配置
  aboutToAppear() {
    this.setItemSizeArray();

    // 初始化瀑布流分组信息:交替使用单列和双列布局
    let sectionOptions: SectionOptions[] = [];
    let count = 0;                     // 已分配的FlowItem数量计数
    let oneOrTwo = 0;                  // 用于交替选择分组类型

    while (count < this.dataCount) {
      // 剩余数据不足20个时,使用最后一个分组处理
      if (this.dataCount - count < 20) {
        this.lastSection.itemsCount = this.dataCount - count;
        sectionOptions.push(this.lastSection);
        break;
      }

      // 交替使用单列和双列布局
      if (oneOrTwo++ % 2 == 0) {
        sectionOptions.push(this.oneColumnSection);
        count += this.oneColumnSection.itemsCount;
      } else {
        sectionOptions.push(this.twoColumnSection);
        count += this.twoColumnSection.itemsCount;
      }
    }

    // 将配置好的分组添加到WaterFlow中
    this.sections.splice(0, 0, sectionOptions);
  }

  build() {
    Column({ space: 2 }) {
      Row() {
        Button('splice')
          .height('5%')
          .onClick(() => {
            // 重要:必须保证LazyForEach中数据数量和新分组itemsCount累计总数保持一致
            let totalCount: number = this.dataSource.totalCount();
            let newSection: SectionOptions = {
              itemsCount: totalCount,
              crossCount: 2,
              onGetItemMainSizeByIndex: (index: number) => {
                return this.itemHeightArray[index % 100];
              }
            };
            let oldLength: number = this.sections.length();
            this.sections.splice(0, oldLength, [newSection]);  // 替换所有分组
          })
          .margin({ top: 10, left: 20 })

        Button('update')
          .height('5%')
          .onClick(() => {
            // 在第一个分组中增加4个FlowItem
            // 重要:必须保证数据源和分组itemsCount同步更新
            const sections: Array<SectionOptions> = this.sections.values();
            let newSection: SectionOptions = sections[0];

            // 先在数据源中添加4个新数据
            this.dataSource.addItem(this.oneColumnSection.itemsCount);
            this.dataSource.addItem(this.oneColumnSection.itemsCount + 1);
            this.dataSource.addItem(this.oneColumnSection.itemsCount + 2);
            this.dataSource.addItem(this.oneColumnSection.itemsCount + 3);

            // 然后更新分组的itemsCount
            newSection.itemsCount += 4;
            const result: boolean = this.sections.update(0, newSection);
            console.info('update:' + result);
          })
          .margin({ top: 10, left: 20 })
      }.margin({ bottom: 20 })

      Row() {
        Button('delete')
          .height('5%')
          .onClick(() => {
            // 在第一个分组中减少4个FlowItem
            // 重要:必须保证数据源和分组itemsCount同步更新
            const sections: Array<SectionOptions> = this.sections.values();
            let newSection: SectionOptions = sections[0];

            // 检查是否有足够的item可以删除
            if (newSection.itemsCount < 4) {
              return;
            }

            // 先从数据源中删除4条数据
            this.dataSource.deleteItem(this.oneColumnSection.itemsCount - 1);
            this.dataSource.deleteItem(this.oneColumnSection.itemsCount - 2);
            this.dataSource.deleteItem(this.oneColumnSection.itemsCount - 3);
            this.dataSource.deleteItem(this.oneColumnSection.itemsCount - 4);

            // 更新分组的itemsCount
            newSection.itemsCount -= 4;
            this.sections.update(0, newSection);
          })
          .margin({ top: 10, left: 20 })

        Button('values')
          .height('5%')
          .onClick(() => {
            const sections: Array<SectionOptions> = this.sections.values();
            for (const value of sections) {
              console.info(JSON.stringify(value));
            }
            console.info('count:' + this.sections.length());
          })
          .margin({ top: 10, left: 20 })
      }

      WaterFlow({ scroller: this.scroller, sections: this.sections }) {
        LazyForEach(this.dataSource, (item: number) => {
          FlowItem() {
            // 使用可复用组件,提升性能
            ReusableFlowItem({ item: item })
          }
          .width('100%')
          // 注意:同时设置onGetItemMainSizeByIndex和height属性时,
          // 主轴大小以onGetItemMainSizeByIndex返回结果为准
          .height(this.itemHeightArray[item % 100])
          .backgroundColor(this.colors[item % this.colors.length])
        }, (item: number) => item.toString())
      }
      .columnsTemplate('1fr 1fr')
      .columnsGap(10)
      .rowsGap(5)
      .backgroundColor(0xFAEEE0)
      .width('100%')
      .height('100%')
      .layoutWeight(1)
      .onScrollIndex((first: number, last: number) => {
        // 滚动监听:即将触底时提前加载更多数据
        if (last + 20 >= this.dataSource.totalCount()) {
          // 添加100个新数据到数据源
          for (let i = 0; i < 100; i++) {
            this.dataSource.addLastItem();
          }

          // 重要:更新数据源后必须同步更新sections
          // 修改最后一个section的FlowItem数量
          const sections: Array<SectionOptions> = this.sections.values();
          let newSection: SectionOptions = sections[this.sections.length() - 1];
          newSection.itemsCount += 100;
          this.sections.update(-1, newSection);  // -1表示最后一个分组
        }
      })
    }
  }
}

[h2]示例4(双指缩放改变列数)

该示例通过priorityGesture和PinchGesture实现了双指缩放改变列数效果。

WaterFlowDataSource说明及完整代码参考示例1(使用基本瀑布流)。

// Index.ets
import { WaterFlowDataSource } from './WaterFlowDataSource';
import { image } from '@kit.ImageKit';
import { BusinessError } from '@kit.BasicServicesKit';

// 可复用组件:优化性能,减少组件创建销毁开销
@Reusable
@Component
struct ReusableFlowItem {
  @State item: number = 0;

  // 从复用缓存中加入到组件树之前调用,可在此处更新组件的状态变量以展示正确的内容
  aboutToReuse(params: Record<string, number>) {
    this.item = params.item;
  }

  build() {
    Column() {
      Text('N' + this.item).fontSize(12).height('16')
      // 注意:需要确保对应的jpg文件存在才会正常显示
      Image('res/waterFlow(' + this.item % 5 + ').jpg')
        .objectFit(ImageFit.Fill)
        .width('100%')
        .layoutWeight(1)
    }
  }
}

@Entry
@Component
struct WaterFlowDemo {
  minSize: number = 80;
  maxSize: number = 180;
  colors: number[] = [0xFFC0CB, 0xDA70D6, 0x6B8E23, 0x6A5ACD, 0x00FFFF, 0x00FF7F];
  dataSource: WaterFlowDataSource = new WaterFlowDataSource();
  private itemWidthArray: number[] = [];
  private itemHeightArray: number[] = [];
  @State columns: number = 2;
  @State waterFlowScale: number = 1;
  @State imageScale: number = 1;
  @State waterFlowOpacity: number = 1;
  @State waterFlowSnapshot: image.PixelMap | undefined = undefined;
  private columnChanged: boolean = false;
  private oldColumn: number = this.columns;
  private pinchTime: number = 0;

  // 计算FlowItem宽/高
  getSize() {
    let ret = Math.floor(Math.random() * this.maxSize);
    return (ret > this.minSize ? ret : this.minSize);
  }

  // 设置FlowItem的宽/高数组
  setItemSizeArray() {
    for (let i = 0; i < 100; i++) {
      this.itemWidthArray.push(this.getSize());
      this.itemHeightArray.push(this.getSize());
    }
  }

  // 组件生命周期:初始化数据和恢复上次的列数设置
  aboutToAppear() {
    // 读取上次最后切换到的列数
    let lastCount = AppStorage.get<number>('columnsCount');
    if (typeof lastCount != 'undefined') {
      this.columns = lastCount;
    }
    this.setItemSizeArray();
  }

  // 根据缩放阈值改变列数,触发WaterFlow重新布局
  changeColumns(scale: number) {
    if (scale > (this.columns / (this.columns - 0.5)) && this.columns > 1) {
      this.columns--;
      this.columnChanged = true;
    } else if (scale < 1 && this.columns < 4) {
      this.columns++;
      this.columnChanged = true;
    }
  }

  build() {
    Column({ space: 2 }) {
      Row() {
        Text('双指缩放改变列数')
          .height('5%')
          .margin({ top: 10, left: 20 })
      }

      Stack() {
        // 用于展示缩放前的WaterFlow截图
        Image(this.waterFlowSnapshot)
          .width('100%')
          .height('100%')
          .scale({
            x: this.imageScale,
            y: this.imageScale,
            centerX: 0,
            centerY: 0
          })
        
        WaterFlow() {
          LazyForEach(this.dataSource, (item: number) => {
            FlowItem() {
              // 使用可复用组件,提升性能
              ReusableFlowItem({ item: item })
            }
            .width('100%')
            .aspectRatio(this.itemHeightArray[item % 100] / this.itemWidthArray[item%100])
            .backgroundColor(this.colors[item % this.colors.length])
          }, (item: number) => item.toString())
        }
        .id('waterflow') // 设置id用于截图
        .columnsTemplate('1fr '.repeat(this.columns))  // 动态生成列模板,如:'1fr 1fr 1fr'表示3列等宽
        .backgroundColor(0xFAEEE0)
        .width('100%')
        .height('100%')
        .layoutWeight(1)
        .opacity(this.waterFlowOpacity)
        .scale({
          x: this.waterFlowScale,
          y: this.waterFlowScale,
          centerX: 0,
          centerY: 0
        })
        .priorityGesture(
          PinchGesture()
            .onActionStart((event: GestureEvent) => {
              // 双指捏合手势识别成功时截图
              this.pinchTime = event.timestamp;
              this.columnChanged = false;
              this.oldColumn = this.columns;
              this.getUIContext().getComponentSnapshot().get('waterflow', (error: Error, pixmap: image.PixelMap) => {
                if (error) {
                  const err: BusinessError = error as BusinessError;
                  console.error(`Failed to get component snapshot. Code: ${err.code}, message: ${err.message}`);
                  return;
                }
                this.waterFlowSnapshot = pixmap;
              });
            })
            .onActionUpdate((event: GestureEvent) => {
              // 手势更新:处理缩放逻辑和视觉效果
              // 边界限制:防止超出列数范围时继续缩放
              if ((this.oldColumn === 1 && event.scale > 1) || (this.oldColumn === 4 && event.scale < 1)) {
                return;
              }

              // 节流处理:避免过于频繁的更新,提升性能
              if (event.timestamp - this.pinchTime < 10000000) {
                return;
              }
              this.pinchTime = event.timestamp;

              this.waterFlowScale = event.scale;
              this.imageScale = event.scale;
              // 根据缩放比例设置WaterFlow透明度
              this.waterFlowOpacity = (this.waterFlowScale > 1) ? (this.waterFlowScale - 1) : (1 - this.waterFlowScale);
              this.waterFlowOpacity *= 3;
              if (!this.columnChanged) {
                this.changeColumns(event.scale);
              }

              // 列数改变后的缩放比例调整:避免出现空白区域
              if (this.columnChanged) {
                this.waterFlowScale = this.imageScale * this.columns / this.oldColumn;

                // 限制缩放范围,确保视觉效果自然
                if (event.scale < 1) {
                  this.waterFlowScale = this.waterFlowScale > 1 ? this.waterFlowScale : 1;
                } else {
                  this.waterFlowScale = this.waterFlowScale < 1 ? this.waterFlowScale : 1;
                }
              }
            })
            .onActionEnd((event: GestureEvent) => {
              // 手势结束:执行归位动画并保存状态
              // 执行归位动画:平滑过渡到正常状态
              this.getUIContext()?.animateTo({ duration: 300 }, () => {
                this.waterFlowScale = 1;
                this.waterFlowOpacity = 1;
              });

              // 持久化保存当前列数:下次启动时恢复
              AppStorage.setOrCreate<number>('columnsCount', this.columns);
            })
        )
      }
    }
  }
}

[h2]示例5(设置边缘渐隐效果)

该示例通过fadingEdge实现了WaterFlow组件开启边缘渐隐效果,并通过fadingEdgeLength参数设置边缘渐隐长度。

WaterFlowDataSource说明及完整代码参考示例1(使用基本瀑布流)。

// Index.ets
import { LengthMetrics } from '@kit.ArkUI';
import { WaterFlowDataSource } from './WaterFlowDataSource';

@Entry
@Component
struct WaterFlowDemo {
  @State minSize: number = 80;
  @State maxSize: number = 180;
  @State colors: number[] = [0xFFC0CB, 0xDA70D6, 0x6B8E23, 0x6A5ACD, 0x00FFFF, 0x00FF7F];
  dataSource: WaterFlowDataSource = new WaterFlowDataSource();
  scroller: Scroller = new Scroller();
  private itemWidthArray: number[] = [];
  private itemHeightArray: number[] = [];

  // 计算FlowItem宽/高
  getSize() {
    let ret = Math.floor(Math.random() * this.maxSize);
    return (ret > this.minSize ? ret : this.minSize);
  }

  // 设置FlowItem宽/高数组
  setItemSizeArray() {
    for (let i = 0; i < 100; i++) {
      this.itemWidthArray.push(this.getSize());
      this.itemHeightArray.push(this.getSize());
    }
  }

  // 组件生命周期:在组件即将出现时初始化尺寸数组
  aboutToAppear() {
    this.setItemSizeArray();
  }

  build() {
    Column({ space: 2 }) {
      WaterFlow({ scroller: this.scroller }) {
        LazyForEach(this.dataSource, (item: number) => {
          FlowItem() {
            Column() {
              Text('N' + item).fontSize(12).height('16')
            }
          }
          .width('100%')
          .height(this.itemHeightArray[item % 100])
          .backgroundColor(this.colors[item % 5])
        }, (item: number) => item.toString())
      }
      // auto-fill自动计算列数:根据容器宽度自动计算能放下多少个80px宽的列
      .columnsTemplate('repeat(auto-fill,80)')
      .columnsGap(10)
      .rowsGap(5)
      .height('90%')
      .scrollBar(BarState.On)
      // 边缘渐隐效果:在滚动边缘创建渐隐过渡效果
      // true:启用渐隐效果
      // fadingEdgeLength: LengthMetrics.vp(80):渐隐区域长度为80vp
      // 效果:在瀑布流顶部和底部边缘会有80vp的渐隐过渡区域
      .fadingEdge(true, { fadingEdgeLength: LengthMetrics.vp(80) })
    }
  }
}

[h2]示例6(单边边缘效果)

该示例通过edgeEffect接口,实现了WaterFlow组件设置单边边缘效果。

WaterFlowDataSource说明及完整代码参考示例1(使用基本瀑布流)。

// Index.ets
import { WaterFlowDataSource } from './WaterFlowDataSource';

@Entry
@Component
struct WaterFlowDemo {
  @State minSize: number = 80;
  @State maxSize: number = 180;
  @State colors: number[] = [0xFFC0CB, 0xDA70D6, 0x6B8E23, 0x6A5ACD, 0x00FFFF, 0x00FF7F];
  dataSource: WaterFlowDataSource = new WaterFlowDataSource();
  scroller: Scroller = new Scroller();
  private itemWidthArray: number[] = [];
  private itemHeightArray: number[] = [];

  // 计算FlowItem宽/高
  getSize() {
    let ret = Math.floor(Math.random() * this.maxSize);
    return (ret > this.minSize ? ret : this.minSize);
  }

  // 设置FlowItem宽/高数组
  setItemSizeArray() {
    for (let i = 0; i < 100; i++) {
      this.itemWidthArray.push(this.getSize());
      this.itemHeightArray.push(this.getSize());
    }
  }

  // 组件生命周期:在组件即将出现时初始化尺寸数组
  aboutToAppear() {
    this.setItemSizeArray();
  }

  build() {
    Column({ space: 2 }) {
      WaterFlow({ scroller: this.scroller }) {
        LazyForEach(this.dataSource, (item: number) => {
          FlowItem() {
            Column() {
              Text('N' + item).fontSize(12).height('16')
            }
          }
          .width('100%')
          .height(this.itemHeightArray[item % 100])
          .backgroundColor(this.colors[item % 5])
        }, (item: number) => item.toString())
      }
      // auto-fill自动计算列数:根据容器宽度自动计算能放下多少个80px宽的列
      .columnsTemplate('repeat(auto-fill,80)')
      .columnsGap(10)
      .rowsGap(5)
      .height('90%')
      // 单边边缘效果:设置弹簧效果,仅在顶部生效
      // EdgeEffect.Spring:弹簧回弹效果,滑动到边界时会有弹性回弹
      // alwaysEnabled: true:始终启用边缘效果,即使内容不足以滚动
      // effectEdge: EffectEdge.START:仅在起始边缘(顶部)生效
      // 效果:只有向上滑动到顶部时才会有弹簧回弹效果,向下滑动到底部不会有效果
      .edgeEffect(EdgeEffect.Spring, { alwaysEnabled: true, effectEdge: EffectEdge.START })

    }
  }
}

[h2]示例7(WaterFlow组件设置和改变尾部组件)

从API version 18开始,该示例通过WaterFlowOptions对象说明的footerContent接口,实现了WaterFlow组件设置尾部组件。通过ComponentContent的update函数更新尾部组件。

WaterFlowDataSource说明及完整代码参考示例1(使用基本瀑布流)。

// Index.ets
import { ComponentContent, UIContext } from '@kit.ArkUI';
import { WaterFlowDataSource } from './WaterFlowDataSource';

class Params {
  text: string = '';

  constructor(text: string) {
    this.text = text;
  }
}

// Builder函数:构建尾部组件的UI结构
@Builder
function buildText(params: Params) {
  Column() {
    Text(params.text)
      .fontSize(20)
      .fontWeight(FontWeight.Bold)
      .margin(20)
  }
}

@Entry
@Component
struct Index {
  @State message1: string = '已经到底了';
  @State message2: string = '加载更多';
  @State colors: number[] = [0xD5D5D5, 0x7F7F7F, 0xF7F7F7];
  @State minSize: number = 80;
  @State maxSize: number = 180;

  // UI上下文:用于创建ComponentContent
  context: UIContext = this.getUIContext();

  // 动态尾部组件:使用ComponentContent创建可更新的尾部组件
  // ComponentContent<Params>:泛型指定参数类型
  // wrapBuilder<[Params]>(buildText):包装Builder函数
  // new Params(this.message1):初始参数,显示'已经到底了'
  footerContent: ComponentContent<Params> = new ComponentContent<Params>(
    this.context,
    wrapBuilder<[Params]>(buildText),
    new Params(this.message1)
  );

  dataSource: WaterFlowDataSource = new WaterFlowDataSource();
  private itemWidthArray: number[] = [];
  private itemHeightArray: number[] = [];

  // 计算FlowItem宽/高
  getSize() {
    let ret = Math.floor(Math.random() * this.maxSize);
    return (ret > this.minSize ? ret : this.minSize);
  }

  // 设置FlowItem宽/高数组
  setItemSizeArray() {
    for (let i = 0; i < 100; i++) {
      this.itemWidthArray.push(this.getSize());
      this.itemHeightArray.push(this.getSize());
    }
  }

  // 组件生命周期:在组件即将出现时初始化尺寸数组
  aboutToAppear() {
    this.setItemSizeArray();
  }

  build() {
    Row() {
      Column() {
        Button('更新footer').width('90%').margin(20)
          .onClick((event?: ClickEvent) => {
            // 调用ComponentContent的update方法更新尾部组件
            // 传入新的Params对象,文本内容从'已经到底了'变为'加载更多'
            this.footerContent.update(new Params(this.message2));
          })
        WaterFlow({ footerContent: this.footerContent }) {
          LazyForEach(this.dataSource, (item: number) => {
            FlowItem() {
              Column() {
                Text('N' + item).fontSize(12).height('16')
              }
              .width('100%')
              .height(this.itemHeightArray[item % 100])
              .backgroundColor(this.colors[item % 3])
              .justifyContent(FlexAlign.Center)
              .alignItems(HorizontalAlign.Center)
            }
          }, (item: number) => item.toString())
        }
        .columnsTemplate('1fr')
        .height('90%')
      }
      .width('100%')
      .height('100%')
    }
    .height('100%')
  }
}

[h2]示例8(WaterFlow组件实现下拉刷新)

该示例通过Refresh组件和WaterFlow组件,实现了下拉刷新瀑布流组件数据源。

WaterFlowDataSource说明及完整代码参考示例1(使用基本瀑布流)。

// Index.ets
import { WaterFlowDataSource } from './WaterFlowDataSource';

@Entry
@Component
struct WaterFlowDemo {
  @State minSize: number = 80;
  @State maxSize: number = 180;
  @State colors: number[] = [0xFFC0CB, 0xDA70D6, 0x6B8E23, 0x6A5ACD, 0x00FFFF, 0x00FF7F];
  @State isRefreshing: boolean = false;
  dataSource: WaterFlowDataSource = new WaterFlowDataSource();
  scroller: Scroller = new Scroller();
  private itemWidthArray: number[] = [];
  private itemHeightArray: number[] = [];

  // 计算FlowItem宽/高
  getSize() {
    let ret = Math.floor(Math.random() * this.maxSize);
    return (ret > this.minSize ? ret : this.minSize);
  }

  // 设置FlowItem宽/高数组
  setItemSizeArray() {
    for (let i = 0; i < 100; i++) {
      this.itemWidthArray.push(this.getSize());
      this.itemHeightArray.push(this.getSize());
    }
  }

  // 组件生命周期:在组件即将出现时初始化尺寸数组
  aboutToAppear() {
    this.setItemSizeArray();
  }

  build() {
    Column({ space: 2 }) {
      // refreshing: $$this.isRefreshing:双向绑定刷新状态
      Refresh({ refreshing: $$this.isRefreshing }) {
        WaterFlow({ scroller: this.scroller }) {
          LazyForEach(this.dataSource, (item: number) => {
            FlowItem() {
              Column() {
                Text('N' + item).fontSize(12).height('16')
              }
            }
            .width('100%')
            .height(this.itemHeightArray[item % 100])
            .backgroundColor(this.colors[item % this.colors.length])
          }, (item: number) => item.toString())
        }
        // auto-fill自动计算列数:根据容器宽度自动计算能放下多少个80px宽的列
        .columnsTemplate('repeat(auto-fill,80)')
        .columnsGap(10)
        .rowsGap(5)
        .height('90%')
        // 边缘效果:弹簧回弹效果
        .edgeEffect(EdgeEffect.Spring, { alwaysEnabled: true })
        .onReachEnd(() => {
          // 触底加载更多数据:滚动到底部时触发
          setTimeout(() => {
            this.dataSource.addNewItems(100);
          }, 1000);
        })
      }
      .onStateChange((refreshStatus: RefreshStatus) => {
        // 刷新状态变化监听:处理不同的刷新状态
        if (refreshStatus === RefreshStatus.Done) {
          // 刷新完成时:调用数据源的刷新方法,更新所有数据
          this.dataSource.refreshItems();
        }
      })
      .onRefreshing(() => {
        // 正在刷新时的回调:模拟刷新过程
        setTimeout(() => {
          this.isRefreshing = false;
        }, 1000);
      })
    }
  }
}

[h2]示例9(WaterFlow组件基于断点配置列数)

从API version 22开始,该示例展示了WaterFlow组件支持基于断点配置列数效果。

// Index.ets
import { WaterFlowDataSource } from './WaterFlowDataSource';

@Entry
@Component
struct WaterFlowDemo {
  minSize: number = 80;
  maxSize: number = 180;
  colors: number[] = [0xFFC0CB, 0xDA70D6, 0x6B8E23, 0x6A5ACD, 0x00FFFF, 0x00FF7F];
  dataSource: WaterFlowDataSource = new WaterFlowDataSource();
  private itemHeightArray: number[] = [];

  // 计算FlowItem宽/高
  getSize() {
    let ret = Math.floor(Math.random() * this.maxSize);
    return (ret > this.minSize ? ret : this.minSize);
  }

  // 设置FlowItem的高度数组
  setItemSizeArray() {
    for (let i = 0; i < 100; i++) {
      this.itemHeightArray.push(this.getSize());
    }
  }

  // 组件生命周期:在组件即将出现时初始化尺寸数组
  aboutToAppear() {
    this.setItemSizeArray();
  }

  build() {
    Column({ space: 2 }) {
      WaterFlow() {
        LazyForEach(this.dataSource, (item: number) => {
          FlowItem() {
            Column() {
              Text('N' + item).fontSize(12).height('16')
              // 注意:需要确保对应的jpg文件存在才会正常显示
              Image('res/waterFlowTest(' + item % 5 + ').jpg')
                .objectFit(ImageFit.Fill)
                .width('100%')
                .layoutWeight(1)
            }
          }
          .width('100%')
          .height(this.itemHeightArray[item % 100])
          .backgroundColor(this.colors[item % this.colors.length])
        }, (item: number) => item.toString())
      }
      .key('waterFlow')
      // 设置WaterFlow按断点决定列数
      .columnsTemplate({fillType:PresetFillType.BREAKPOINT_SM2MD3LG5})
      .columnsGap(10)
      .rowsGap(5)
      .backgroundColor(0xFAEEE0)
      .margin('20vp')
      .width('100%')
      .height('30%')
    }
  }
}

WaterFlow宽度属于sm及更小的断点区间时显示2列。

WaterFlow宽度属于md断点区间时显示3列。

WaterFlow宽度属于lg及更大的断点区间时显示5列。

[h2]示例10(WaterFlow组件实现获取内容高度)

从API version 22 开始,该示例通过WaterFlow组件,实现了获取内容高度。

WaterFlowDataSource说明及完整代码参考示例1(使用基本瀑布流)。

// Index.ets
import { WaterFlowDataSource } from './WaterFlowDataSource';
import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct WaterFlowContentSizeDemo {
  @State minSize: number = 80;
  @State maxSize: number = 180;
  @State colors: number[] = [0xFFC0CB, 0xDA70D6, 0x6B8E23, 0x6A5ACD, 0x00FFFF, 0x00FF7F];
  @State contentWidth: number = -1;
  @State contentHeight: number = -1;
  scroller: Scroller = new Scroller();
  dataSource: WaterFlowDataSource = new WaterFlowDataSource();
  private itemWidthArray: number[] = [];
  private itemHeightArray: number[] = [];

  // 计算FlowItem宽/高
  getSize() {
    let ret = Math.floor(Math.random() * this.maxSize);
    return (ret > this.minSize ? ret : this.minSize);
  }

  // 设置FlowItem的宽/高数组
  setItemSizeArray() {
    for (let i = 0; i < 100; i++) {
      this.itemWidthArray.push(this.getSize());
      this.itemHeightArray.push(this.getSize());
    }
  }

  // 组件生命周期:在组件即将出现时初始化尺寸数组
  aboutToAppear() {
    this.setItemSizeArray();
  }

  @Builder
  itemFoot() {
    Column() {
      Text(`到底啦...`)
        .fontSize(10)
        .backgroundColor(Color.Red)
        .width(50)
        .height(50)
        .align(Alignment.Center)
        .margin({ top: 2 })
    }
  }

  build() {
    Column({ space: 2 }) {
      // 点击按钮来调用contentSize函数获取内容尺寸
      Button('GetContentSize')
        .onClick(() => {
          // Scroller未绑定组件时会抛异常,需要加上try catch保护
          try {
            // 通过调用contentSize函数获取内容尺寸的宽度值
            this.contentWidth = this.scroller.contentSize().width;
            // 通过调用contentSize函数获取内容尺寸的高度值
            this.contentHeight = this.scroller.contentSize().height;
          } catch (error) {
            let err: BusinessError = error as BusinessError;
            console.error(`Failed to get contentSize of the WaterFlow. Code: ${err.code}, message: ${err.message}`);
          }
        }).margin(5)
      // 将获取到的内容尺寸信息通过文本进行呈现
      Text('Width:' + this.contentWidth)
        .fontColor(Color.Red)
        .height(30)
      Text('Height:' + this.contentHeight)
        .fontColor(Color.Red)
        .height(30)

      WaterFlow({ scroller: this.scroller, footer: this.itemFoot() }) {
        LazyForEach(this.dataSource, (item: number) => {
          FlowItem() {
            Column() {
              Text('N' + item).fontSize(12).height('16')
            }
          }
          .width('100%')
          .height(this.itemHeightArray[item % 100])
          .backgroundColor(this.colors[item % this.colors.length])
        }, (item: number) => item.toString())
      }
      .columnsTemplate('1fr 1fr') // 设置2列等宽布局
      .columnsGap(10)
      .rowsGap(5)
      .backgroundColor(0xFAEEE0)
      .width('100%')
      .height('80%')
    }
  }
}

[h2]示例11(设置滚动事件)

该示例通过FrameNode中的getEvent('WaterFlow')获取UIWaterFlowEvent,并为WaterFlow设置滚动事件回调,用于事件监听方因无法直接修改页面代码而无法使用声明式接口设置回调的场景。

从API version 19开始,新增UIWaterFlowEvent接口。

import { NodeController, FrameNode, typeNode } from '@kit.ArkUI';

class MyNodeController extends NodeController {
  public rootNode: FrameNode | null = null;

  makeNode(uiContext: UIContext): FrameNode | null {
    this.rootNode = new FrameNode(uiContext);
    this.rootNode.commonAttribute.width(100);
    return this.rootNode;
  }

  addCommonEvent(frameNode: FrameNode) {
    // 获取WaterFlow事件
    let waterFlowEvent: UIWaterFlowEvent | undefined = typeNode.getEvent(frameNode, 'WaterFlow');

    // 设置OnWillScroll事件
    waterFlowEvent?.setOnWillScroll((scrollOffset: number, scrollState: ScrollState, scrollSource: ScrollSource) => {
      console.info(`onWillScroll scrollOffset = ${scrollOffset}, scrollState = ${scrollState}, scrollSource = ${scrollSource}`);
    });

    // 设置OnDidScroll事件
    waterFlowEvent?.setOnDidScroll((scrollOffset: number, scrollState: ScrollState) => {
      console.info(`onDidScroll scrollOffset = ${scrollOffset}, scrollState = ${scrollState}`);
    });

    // 设置OnReachStart事件
    waterFlowEvent?.setOnReachStart(() => {
      console.info('onReachStart');
    });

    // 设置OnReachEnd事件
    waterFlowEvent?.setOnReachEnd(() => {
      console.info('onReachEnd');
    });

    // 设置OnScrollStart事件
    waterFlowEvent?.setOnScrollStart(() => {
      console.info('onScrollStart');
    });

    // 设置OnScrollStop事件
    waterFlowEvent?.setOnScrollStop(() => {
      console.info('onScrollStop');
    });

    // 设置OnScrollFrameBegin事件
    waterFlowEvent?.setOnScrollFrameBegin((offset: number, state: ScrollState) => {
      console.info(`onScrollFrameBegin offset = ${offset}, state = ${state}`);
      return undefined;
    });

    // 设置OnScrollIndex事件
    waterFlowEvent?.setOnScrollIndex((first: number, last: number) => {
      console.info(`onScrollIndex start = ${first}, end = ${last}`);
    });
  }
}

@Entry
@Component
struct Index {
  private myNodeController: MyNodeController = new MyNodeController();
  @State numbers: string[] = [];
  @State heights: number[] = [];

  aboutToAppear() {
    for (let i = 0; i < 30; i++) {
      this.numbers.push(`${i + 1}`);
      this.heights.push(70 + Math.floor(Math.random() * 60));
    }
  }

  build() {
    Column() {
      Button('add CommonEvent to WaterFlow')
        .onClick(() => {
          this.myNodeController!.addCommonEvent(this.myNodeController!.rootNode!.getParent()!.getPreviousSibling()!)
        })
      WaterFlow() {
        ForEach(this.numbers, (day: string, index: number) => {
          FlowItem() {
            Text(day)
              .fontSize(16)
              .backgroundColor(0xF9CF93)
              .width('100%')
              .height(this.heights[index])
              .textAlign(TextAlign.Center)
          }
          .width('100%')
        }, (day: string, index: number) => index.toString() + day)
      }
      .columnsTemplate('1fr 1fr')
      .columnsGap(10)
      .rowsGap(10)
      .enableScrollInteraction(true)
      .width('90%')
      .backgroundColor(0xFAEEE0)
      .height(300)
      NodeContainer(this.myNodeController)
    }.width('100%')
  }
}