From 31385db520b47f4bdf3bbe280178dbc759025129 Mon Sep 17 00:00:00 2001
From: jiangdayuan <jiangdayuan@huawei.com>
Date: Thu, 18 May 2023 11:32:38 +0800
Subject: [PATCH] add waterflow doc to 3.2release

Signed-off-by: jiangdayuan <jiangdayuan@huawei.com>
Change-Id: I2c1ec8686f257f1893e7d965443ef20af3a58cbd
---
 .../reference/arkui-ts/Readme-EN.md           |   1 +
 .../arkui-ts/ts-components-summary.md         |   6 +
 .../arkui-ts/ts-container-flowitem.md         |  31 ++
 .../reference/arkui-ts/ts-container-scroll.md |   2 +-
 .../arkui-ts/ts-container-waterflow.md        | 291 +++++++++++++++++
 en/application-dev/website.md                 |   1 +
 .../reference/arkui-ts/Readme-CN.md           |   1 +
 .../arkui-ts/ts-components-summary.md         |   6 +
 .../arkui-ts/ts-container-flowitem.md         |  31 ++
 .../reference/arkui-ts/ts-container-scroll.md |   2 +-
 .../arkui-ts/ts-container-waterflow.md        | 296 ++++++++++++++++++
 zh-cn/application-dev/website.md              |   1 +
 12 files changed, 667 insertions(+), 2 deletions(-)
 create mode 100644 en/application-dev/reference/arkui-ts/ts-container-flowitem.md
 create mode 100644 en/application-dev/reference/arkui-ts/ts-container-waterflow.md
 create mode 100644 zh-cn/application-dev/reference/arkui-ts/ts-container-flowitem.md
 create mode 100644 zh-cn/application-dev/reference/arkui-ts/ts-container-waterflow.md

diff --git a/en/application-dev/reference/arkui-ts/Readme-EN.md b/en/application-dev/reference/arkui-ts/Readme-EN.md
index 9d70349a99..e94a5832f7 100644
--- a/en/application-dev/reference/arkui-ts/Readme-EN.md
+++ b/en/application-dev/reference/arkui-ts/Readme-EN.md
@@ -124,6 +124,7 @@
   - [Swiper](ts-container-swiper.md)
   - [Tabs](ts-container-tabs.md)
   - [TabContent](ts-container-tabcontent.md)
+  - [WaterFlow](ts-container-waterflow.md)
 - Media Components
   - [Video](ts-media-components-video.md)
 - Drawing Components
diff --git a/en/application-dev/reference/arkui-ts/ts-components-summary.md b/en/application-dev/reference/arkui-ts/ts-components-summary.md
index 5bc9050761..19bc1f97ee 100644
--- a/en/application-dev/reference/arkui-ts/ts-components-summary.md
+++ b/en/application-dev/reference/arkui-ts/ts-components-summary.md
@@ -69,6 +69,12 @@
 - [Swiper](ts-container-swiper.md)
 
     A container that is able to display child components in looping mode.
+- [WaterFlow](ts-container-waterflow.md)
+
+    A container that consists of cells formed by rows and columns and arranges items of different sizes from top to bottom according to the preset rules.
+- [FlowItem](ts-container-flowitem.md)
+
+    A child component of the **\<WaterFlow>** container that is used to display specific items in the container layout.
 
 
 ## Navigation
diff --git a/en/application-dev/reference/arkui-ts/ts-container-flowitem.md b/en/application-dev/reference/arkui-ts/ts-container-flowitem.md
new file mode 100644
index 0000000000..71a0bf73f8
--- /dev/null
+++ b/en/application-dev/reference/arkui-ts/ts-container-flowitem.md
@@ -0,0 +1,31 @@
+# FlowItem
+
+
+**\<FlowItem>** is a child component of the [\<WaterFlow>](ts-container-waterflow.md) container and is used to display specific items in the container layout.
+
+
+> **NOTE**
+>
+> This component is supported since API version 9. Updates will be marked with a superscript to indicate their earliest API version.
+
+
+## Child Components
+
+
+This component supports only one child component.
+
+
+## APIs
+
+FlowItem()
+
+Ceates a child component in the **\<WaterFlow>** layout.
+
+
+## Attributes
+
+None
+
+## Example
+
+See [WaterFlow](ts-container-waterflow.md#example).
diff --git a/en/application-dev/reference/arkui-ts/ts-container-scroll.md b/en/application-dev/reference/arkui-ts/ts-container-scroll.md
index 677f97e8f3..d54ecbf1d4 100644
--- a/en/application-dev/reference/arkui-ts/ts-container-scroll.md
+++ b/en/application-dev/reference/arkui-ts/ts-container-scroll.md
@@ -61,7 +61,7 @@ In addition to the [universal attributes](ts-universal-attributes-size.md), the
 
 ## Scroller
 
-Implements a controller for a scrollable container component. You can bind this component to a container component and use it to control the scrolling of that component. One controller can control only one container component. The supported container components are **\<List>**, **\<Scroll>**, **\<ScrollBar>**, and **\<Grid>**.
+Implements a controller for a scrollable container component. You can bind this component to a container component and use it to control the scrolling of that component. One controller can control only one container component. The supported container components are **\<List>**, **\<Scroll>**, **\<ScrollBar>**, **\<Grid>**, and **\<WaterFlow>**.
 
 
 ### Objects to Import
diff --git a/en/application-dev/reference/arkui-ts/ts-container-waterflow.md b/en/application-dev/reference/arkui-ts/ts-container-waterflow.md
new file mode 100644
index 0000000000..76507f08df
--- /dev/null
+++ b/en/application-dev/reference/arkui-ts/ts-container-waterflow.md
@@ -0,0 +1,291 @@
+# WaterFlow
+
+
+The **\<WaterFlow>** component is a container that consists of cells formed by rows and columns and arranges items of different sizes from top to bottom according to the preset rules.
+
+
+> **NOTE**
+>
+> This component is supported since API version 9. Updates will be marked with a superscript to indicate their earliest API version.
+
+
+## Child Components
+
+
+The [\<FlowItem>](ts-container-flowitem.md) child component is supported.
+
+
+## APIs
+
+
+WaterFlow(options?: {footer?: CustomBuilder, scroller?: Scroller})
+
+**Parameters**
+
+| Name    | Type                                       | Mandatory| Description                                    |
+| ---------- | ----------------------------------------------- | ------ | -------------------------------------------- |
+| footer |  [CustomBuilder](ts-types.md#custombuilder8) | No  | Footer of the **\<WaterFlow>** component. |
+| scroller | [Scroller](ts-container-scroll.md#scroller) | No  | Controller, which can be bound to scrollable components.<br>The **\<WaterFlow>** component supports only the **scrollToIndex** API of the **\<Scroller>** component.|
+
+
+## Attributes
+
+
+In addition to the [universal attributes](ts-universal-attributes-size.md), the following attributes are supported.
+
+| Name| Type| Description|
+| -------- | -------- | -------- |
+| columnsTemplate | string | Number of columns in the layout. If this attribute is not set, one column is used by default.<br>For example, **'1fr 1fr 2fr'** indicates three columns, with the first column taking up 1/4 of the parent component's full width, the second column 1/4, and the third column 2/4. This attribute supports [auto-fill](#auto-fill).<br>Default value: **'1fr'**|
+| rowsTemplate | string | Number of rows in the layout. If this attribute is not set, one row is used by default.<br>For example, **'1fr 1fr 2fr'** indicates three rows, with the first row taking up 1/4 of the parent component's full height, the second row 1/4, and the third row 2/4. This attribute supports [auto-fill](#auto-fill).<br>Default value: **'1fr'**|
+| itemConstraintSize | [ConstraintSizeOptions](ts-types.md#constraintsizeoptions) | Size constraints of the child components during layout.              |
+| columnsGap | Length |Gap between columns.<br>Default value: **0**|
+| rowsGap | Length |Gap between rows.<br> Default value: **0**|
+| layoutDirection | [FlexDirection](ts-appendix-enums.md#flexdirection) |Main axis direction of the layout.<br>Default value: **FlexDirection.Column**|
+
+The priority of **layoutDirection** is higher than that of **rowsTemplate** and **columnsTemplate**. Depending on the **layoutDirection** settings, there are three layout modes:
+
+- **layoutDirection** is set to **FlexDirection.Column** or **FlexDirection.ColumnReverse**
+
+	In this case, **columnsTemplate** is valid. If it is not set, the default value is used. For example, if **columnsTemplate** is set to **"1fr 1fr"** and **rowsTemplate** **"1fr 1fr 1fr"**, child components are arranged in vertical layout, with the cross axis equally divided into two columns.
+
+- **layoutDirection** set to **FlexDirection.Row** or **FlexDirection.RowReverse**
+
+	In this case, **rowsTemplate** is valid. If it is not set, the default value is used. For example, if **columnsTemplate** is set to **"1fr 1fr"** and **rowsTemplate** **"1fr 1fr 1fr"**, child components are arranged in horizontal layout, with the cross axis equally divided into three columns.
+
+- **layoutDirection** is not set
+
+	In this case, the default value of **layoutDirection** is used, which is **FlexDirection.Column**, and **columnsTemplate** is valid. For example, if **columnsTemplate** is set to **"1fr 1fr"** and **rowsTemplate** **"1fr 1fr 1fr"**, child components are arranged in vertical layout, with the cross axis equally divided into two columns.
+
+## Events
+
+
+In addition to the [universal events](ts-universal-events-click.md), the following events are supported.
+
+
+| Name| Description|
+| -------- | -------- |
+| onReachStart(event: () => void) | Triggered when the component reaches the start.|
+| onReachEnd(event: () => void)   | Triggered when the component reaches the end.|
+
+
+## auto-fill
+
+The **columnsTemplate** and **rowsTemplate** attributes supports **auto-fill** in the following format:
+
+```css
+repeat(auto-fill, track-size)
+```
+
+Where, **repeat** and **auto-fill** are keywords, and **track-size** indicates the row height or column width. The supported units include px, vp, %, and digits. The value of **track-size** must contain at least one valid row height or column width.
+
+
+## Example
+
+
+```ts
+// WaterFlowDataSource.ets
+
+// Object that implements the IDataSource API, which is used by the <WaterFlow> component to load data.
+export class WaterFlowDataSource implements IDataSource {
+
+  private dataArray: number[] = []
+  private listeners: DataChangeListener[] = []
+
+  constructor() {
+      for (let i = 0; i < 100; i++) {
+          this.dataArray.push(i)
+      }
+  }
+
+  // Obtain the data corresponding to the specified index.
+  public getData(index: number): any {
+      return this.dataArray[index]
+  }
+
+  // Notify the controller of data reloading.
+  notifyDataReload(): void {
+      this.listeners.forEach(listener => {
+          listener.onDataReloaded()
+      })
+  }
+
+  // Notify the controller of data addition.
+  notifyDataAdd(index: number): void {
+      this.listeners.forEach(listener => {
+          listener.onDataAdded(index)
+      })
+  }
+
+  // Notify the controller of data changes.
+  notifyDataChange(index: number): void {
+      this.listeners.forEach(listener => {
+          listener.onDataChanged(index)
+      })
+  }
+
+  // Notify the controller of data deletion.
+  notifyDataDelete(index: number): void {
+      this.listeners.forEach(listener => {
+          listener.onDataDeleted(index)
+      })
+  }
+
+  // Notify the controller of the data location change.
+  notifyDataMove(from: number, to: number): void {
+      this.listeners.forEach(listener => {
+          listener.onDataMoved(from, to)
+      })
+  }
+
+  // Obtain the total number of data records.
+  public totalCount(): number {
+      return this.dataArray.length
+  }
+
+  // Register the data change listener.
+  registerDataChangeListener(listener: DataChangeListener): void {
+      if (this.listeners.indexOf(listener) < 0) {
+          this.listeners.push(listener)
+      }
+  }
+
+  // Unregister the data change listener.
+  unregisterDataChangeListener(listener: DataChangeListener): void {
+      const pos = this.listeners.indexOf(listener)
+      if (pos >= 0) {
+          this.listeners.splice(pos, 1)
+      }
+  }
+
+  // Add data.
+  public Add1stItem(): void {
+      this.dataArray.splice(0, 0, this.dataArray.length)
+      this.notifyDataAdd(0)
+  }
+
+  // Add an item to the end of the data.
+  public AddLastItem(): void {
+      this.dataArray.splice(this.dataArray.length, 0, this.dataArray.length)
+      this.notifyDataAdd(this.dataArray.length-1)
+  }
+
+  // Add an item to the position corresponding to the specified index.
+  public AddItem(index: number): void {
+      this.dataArray.splice(index, 0, this.dataArray.length)
+      this.notifyDataAdd(index)
+  }
+
+  // Delete the first item.
+  public Delete1stItem(): void {
+      this.dataArray.splice(0, 1)
+      this.notifyDataDelete(0)
+  }
+
+  // Delete the second item.
+  public Delete2ndItem(): void {
+      this.dataArray.splice(1, 1)
+      this.notifyDataDelete(1)
+  }
+
+  // Delete the last item.
+  public DeleteLastItem(): void {
+      this.dataArray.splice(-1, 1)
+      this.notifyDataDelete(this.dataArray.length)
+  }
+
+  // Reload data.
+  public Reload(): void {
+      this.dataArray.splice(1, 1)
+      this.dataArray.splice(3, 2)
+      this.notifyDataReload()
+  }
+}
+```
+
+```ts
+// WaterflowDemo.ets
+import { WaterFlowDataSource } from './WaterFlowDataSource'
+
+@Entry
+@Component
+struct WaterflowDemo {
+  @State minSize: number = 50
+  @State maxSize: number = 100
+  @State fontSize: number = 24
+  @State colors: number[] = [0xFFC0CB, 0xDA70D6, 0x6B8E23, 0x6A5ACD, 0x00FFFF, 0x00FF7F]
+  scroller: Scroller = new Scroller()
+  datasource: WaterFlowDataSource = new WaterFlowDataSource()
+  private itemWidthArray: number[] = []
+  private itemHeightArray: number[] = []
+
+  // Calculate the width and height of a flow item. 
+  getSize() {
+    let ret = Math.floor(Math.random() * this.maxSize)
+    return (ret > this.minSize ? ret : this.minSize)
+  }
+
+  // Save the width and height of the flow item.  
+  getItemSizeArray() {
+    for (let i = 0; i < 100; i++) {
+      this.itemWidthArray.push(this.getSize())
+      this.itemHeightArray.push(this.getSize())
+    }
+  }
+    
+  aboutToAppear() {
+    this.getItemSizeArray()
+  }
+    
+  @Builder itemFoot() {
+    Column() {
+      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.bind(this), scroller: this.scroller }) {
+        LazyForEach(this.datasource, (item: number) => {
+          FlowItem() {
+            Column() {
+              Text("N" + item).fontSize(12).height('16')
+              Image('res/waterFlowTest(' + item % 5 + ').jpg')
+                .objectFit(ImageFit.Fill)
+            }
+          }
+          .width(this.itemWidthArray[item])
+          .height(this.itemHeightArray[item])
+          .backgroundColor(this.colors[item % 5])
+        }, item => item)
+      }
+      .columnsTemplate("1fr 1fr 1fr 1fr")
+      .itemConstraintSize({
+        minWidth: 0,
+        maxWidth: '100%',
+        minHeight: 0,
+        maxHeight: '100%'
+      })
+      .columnsGap(10)
+      .rowsGap(5)
+      .onReachStart(() => {
+        console.info("onReachStart")
+      })
+      .onReachEnd(() => {
+        console.info("onReachEnd")
+      })
+      .backgroundColor(0xFAEEE0)
+      .width('100%')
+      .height('80%')
+      .layoutDirection(FlexDirection.Column)
+    }
+  }
+}
+```
+
+![en-us_image_WaterFlow.gif](figures/waterflow.gif)
diff --git a/en/application-dev/website.md b/en/application-dev/website.md
index 616b92cf75..8183965d59 100644
--- a/en/application-dev/website.md
+++ b/en/application-dev/website.md
@@ -737,6 +737,7 @@
       - [Swiper](reference/arkui-ts/ts-container-swiper.md)
       - [Tabs](reference/arkui-ts/ts-container-tabs.md)
       - [TabContent](reference/arkui-ts/ts-container-tabcontent.md)
+      - [WaterFlow](reference/arkui-ts/ts-container-waterflow.md)
     - Media Component
       - [Video](reference/arkui-ts/ts-media-components-video.md)
     - Drawing Components
diff --git a/zh-cn/application-dev/reference/arkui-ts/Readme-CN.md b/zh-cn/application-dev/reference/arkui-ts/Readme-CN.md
index 2020b9ebb6..fa859bbe06 100644
--- a/zh-cn/application-dev/reference/arkui-ts/Readme-CN.md
+++ b/zh-cn/application-dev/reference/arkui-ts/Readme-CN.md
@@ -124,6 +124,7 @@
   - [Swiper](ts-container-swiper.md)
   - [Tabs](ts-container-tabs.md)
   - [TabContent](ts-container-tabcontent.md)
+  - [WaterFlow](ts-container-waterflow.md)
 - 媒体组件
   - [Video](ts-media-components-video.md)
 - 绘制组件
diff --git a/zh-cn/application-dev/reference/arkui-ts/ts-components-summary.md b/zh-cn/application-dev/reference/arkui-ts/ts-components-summary.md
index 1becf8095e..6504c28f95 100644
--- a/zh-cn/application-dev/reference/arkui-ts/ts-components-summary.md
+++ b/zh-cn/application-dev/reference/arkui-ts/ts-components-summary.md
@@ -69,6 +69,12 @@
 - [Swiper](ts-container-swiper.md)
 
     滑块视图容器组件，提供子组件滑动轮播显示的能力。
+- [WaterFlow](ts-container-waterflow.md)
+
+    瀑布流容器组件，由“行”和“列”分割的单元格所组成，通过容器自身的排列规则，将不同大小的“项目”自上而下，如瀑布般紧密布局。
+- [FlowItem](ts-container-flowitem.md)
+
+    瀑布流组件WaterFlow的子组件，用来展示瀑布流具体item。
 
 
 ## 导航
diff --git a/zh-cn/application-dev/reference/arkui-ts/ts-container-flowitem.md b/zh-cn/application-dev/reference/arkui-ts/ts-container-flowitem.md
new file mode 100644
index 0000000000..4628ea7bb5
--- /dev/null
+++ b/zh-cn/application-dev/reference/arkui-ts/ts-container-flowitem.md
@@ -0,0 +1,31 @@
+# FlowItem
+
+
+[瀑布流组件](ts-container-waterflow.md)的子组件，用来展示瀑布流具体item。
+
+
+> **说明：**
+>
+> 该组件从API Version 9开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
+
+
+## 子组件
+
+
+支持单个子组件。
+
+
+## 接口
+
+FlowItem()
+
+使用该接口来创建瀑布流子组件。
+
+
+## 属性
+
+无
+
+## 示例
+
+详见[瀑布流组件示例](ts-container-waterflow.md#示例)。
\ No newline at end of file
diff --git a/zh-cn/application-dev/reference/arkui-ts/ts-container-scroll.md b/zh-cn/application-dev/reference/arkui-ts/ts-container-scroll.md
index 4c61cf94af..1f86949d0e 100644
--- a/zh-cn/application-dev/reference/arkui-ts/ts-container-scroll.md
+++ b/zh-cn/application-dev/reference/arkui-ts/ts-container-scroll.md
@@ -61,7 +61,7 @@ Scroll(scroller?: Scroller)
 
 ## Scroller
 
-可滚动容器组件的控制器，可以将此组件绑定至容器组件，然后通过它控制容器组件的滚动，同一个控制器不可以控制多个容器组件，目前支持绑定到List、Scroll、ScrollBar、Grid上。
+可滚动容器组件的控制器，可以将此组件绑定至容器组件，然后通过它控制容器组件的滚动，同一个控制器不可以控制多个容器组件，目前支持绑定到List、Scroll、ScrollBar、Grid、WaterFlow上。
 
 
 ### 导入对象
diff --git a/zh-cn/application-dev/reference/arkui-ts/ts-container-waterflow.md b/zh-cn/application-dev/reference/arkui-ts/ts-container-waterflow.md
new file mode 100644
index 0000000000..fed88989ee
--- /dev/null
+++ b/zh-cn/application-dev/reference/arkui-ts/ts-container-waterflow.md
@@ -0,0 +1,296 @@
+# WaterFlow
+
+
+瀑布流容器，由“行”和“列”分割的单元格所组成，通过容器自身的排列规则，将不同大小的“项目”自上而下，如瀑布般紧密布局。
+
+
+> **说明：**
+>
+> 该组件从API Version 9 开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
+
+
+## 子组件
+
+
+包含[FlowItem](ts-container-flowitem.md)子组件。
+
+>  **说明：**
+>
+>  WaterFlow子组件的visibility属性设置为None时不显示，但依然会占用子组件对应的网格。
+
+## 接口
+
+
+WaterFlow(options?: {footer?: CustomBuilder, scroller?: Scroller})
+
+**参数：**
+
+| 参数名     | 参数类型                                        | 必填 | 参数描述                                     |
+| ---------- | ----------------------------------------------- | ------ | -------------------------------------------- |
+| footer |  [CustomBuilder](ts-types.md#custombuilder8) | 否   | 设置WaterFlow尾部组件。  |
+| scroller | [Scroller](ts-container-scroll.md#scroller) | 否   | 可滚动组件的控制器，与可滚动组件绑定。<br/>目前瀑布流仅支持Scroller组件的scrollToIndex接口。 |
+
+
+## 属性
+
+
+除支持[通用属性](ts-universal-attributes-size.md)外，还支持以下属性：
+
+| 名称 | 参数类型 | 描述 |
+| -------- | -------- | -------- |
+| columnsTemplate | string | 设置当前瀑布流组件布局列的数量，不设置时默认1列。<br/>例如, '1fr 1fr 2fr' 是将父组件分3列，将父组件允许的宽分为4等份，第一列占1份，第二列占1份，第三列占2份。并支持[auto-fill](#auto-fill说明)。<br>默认值：'1fr' |
+| rowsTemplate | string | 设置当前瀑布流组件布局行的数量，不设置时默认1行。<br/>例如, '1fr 1fr 2fr'是将父组件分三行，将父组件允许的高分为4等份，第一行占1份，第二行占一份，第三行占2份。并支持[auto-fill](#auto-fill说明)。<br/>默认值：'1fr' |
+| itemConstraintSize | [ConstraintSizeOptions](ts-types.md#constraintsizeoptions) | 设置约束尺寸，子组件布局时，进行尺寸范围限制。               |
+| columnsGap | Length |设置列与列的间距。 <br>默认值：0|
+| rowsGap | Length |设置行与行的间距。<br> 默认值：0|
+| layoutDirection | [FlexDirection](ts-appendix-enums.md#flexdirection) |设置布局的主轴方向。<br/>默认值：FlexDirection.Column|
+
+layoutDirection优先级高于rowsTemplate和columnsTemplate。根据layoutDirection设置情况，分为以下三种设置模式:
+
+- layoutDirection设置纵向布局（FlexDirection.Column 或 FlexDirection.ColumnReverse）
+
+	此时columnsTemplate有效（如果未设置，取默认值）。例如columnsTemplate设置为"1fr 1fr"、rowsTemplate设置为"1fr 1fr 1fr"时，瀑布流组件纵向布局，辅轴均分成横向2列。
+
+- layoutDirection设置横向布局（FlexDirection.Row 或 FlexDirection.RowReverse）
+
+	此时rowsTemplate有效（如果未设置，取默认值）。例如columnsTemplate设置为"1fr 1fr"、rowsTemplate设置为"1fr 1fr 1fr"时，瀑布流组件横向布局，辅轴均分成纵向3列。
+
+- layoutDirection未设置布局方向
+
+	布局方向为layoutDirection的默认值：FlexDirection.Column，此时columnsTemplate有效。例如columnsTemplate设置为"1fr 1fr"、rowsTemplate设置为"1fr 1fr 1fr"时，瀑布流组件纵向布局，辅轴均分成横向2列。
+
+## 事件
+
+
+除支持[通用事件](ts-universal-events-click.md)外，还支持以下事件：
+
+
+| 名称 | 功能描述 |
+| -------- | -------- |
+| onReachStart(event: () => void) | 瀑布流组件到达起始位置时触发。 |
+| onReachEnd(event: () => void)   | 瀑布流组件到底末尾位置时触发。 |
+
+
+## auto-fill说明
+
+WaterFlow的columnsTemplate、rowsTemplate属性的auto-fill仅支持以下格式：
+
+```css
+repeat(auto-fill, track-size)
+```
+
+其中repeat、auto-fill为关键字。track-size为行高或者列宽，支持的单位包括px、vp、%或有效数字，track-size至少包括一个有效行高或者列宽。
+
+
+## 示例
+
+
+```ts
+// 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): any {
+      return this.dataArray[index]
+  }
+
+  // 通知控制器数据重新加载
+  notifyDataReload(): void {
+      this.listeners.forEach(listener => {
+          listener.onDataReloaded()
+      })
+  }
+
+  // 通知控制器数据增加
+  notifyDataAdd(index: number): void {
+      this.listeners.forEach(listener => {
+          listener.onDataAdded(index)
+      })
+  }
+
+  // 通知控制器数据变化
+  notifyDataChange(index: number): void {
+      this.listeners.forEach(listener => {
+          listener.onDataChanged(index)
+      })
+  }
+
+  // 通知控制器数据删除
+  notifyDataDelete(index: number): void {
+      this.listeners.forEach(listener => {
+          listener.onDataDeleted(index)
+      })
+  }
+
+  // 通知控制器数据位置变化
+  notifyDataMove(from: number, to: number): void {
+      this.listeners.forEach(listener => {
+          listener.onDataMoved(from, to)
+      })
+  }
+
+  // 获取数据总数
+  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 Reload(): void {
+      this.dataArray.splice(1, 1)
+      this.dataArray.splice(3, 2)
+      this.notifyDataReload()
+  }
+}
+```
+
+```ts
+// WaterflowDemo.ets
+import { WaterFlowDataSource } from './WaterFlowDataSource'
+
+@Entry
+@Component
+struct WaterflowDemo {
+  @State minSize: number = 50
+  @State maxSize: number = 100
+  @State fontSize: number = 24
+  @State colors: number[] = [0xFFC0CB, 0xDA70D6, 0x6B8E23, 0x6A5ACD, 0x00FFFF, 0x00FF7F]
+  scroller: Scroller = new Scroller()
+  datasource: WaterFlowDataSource = new WaterFlowDataSource()
+  private itemWidthArray: number[] = []
+  private itemHeightArray: number[] = []
+
+  // 计算flow item宽/高  
+  getSize() {
+    let ret = Math.floor(Math.random() * this.maxSize)
+    return (ret > this.minSize ? ret : this.minSize)
+  }
+
+  // 保存flow item宽/高   
+  getItemSizeArray() {
+    for (let i = 0; i < 100; i++) {
+      this.itemWidthArray.push(this.getSize())
+      this.itemHeightArray.push(this.getSize())
+    }
+  }
+    
+  aboutToAppear() {
+    this.getItemSizeArray()
+  }
+    
+  @Builder itemFoot() {
+    Column() {
+      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.bind(this), scroller: this.scroller }) {
+        LazyForEach(this.datasource, (item: number) => {
+          FlowItem() {
+            Column() {
+              Text("N" + item).fontSize(12).height('16')
+              Image('res/waterFlowTest(' + item % 5 + ').jpg')
+                .objectFit(ImageFit.Fill)
+                .width('100%')
+                .layoutWeight(1)
+            }
+          }
+          .width(this.itemWidthArray[item])
+          .height(this.itemHeightArray[item])
+          .backgroundColor(this.colors[item % 5])
+        }, item => item)
+      }
+      .columnsTemplate("1fr 1fr 1fr 1fr")
+      .itemConstraintSize({
+        minWidth: 0,
+        maxWidth: '100%',
+        minHeight: 0,
+        maxHeight: '100%'
+      })
+      .columnsGap(10)
+      .rowsGap(5)
+      .onReachStart(() => {
+        console.info("onReachStart")
+      })
+      .onReachEnd(() => {
+        console.info("onReachEnd")
+      })
+      .backgroundColor(0xFAEEE0)
+      .width('100%')
+      .height('80%')
+      .layoutDirection(FlexDirection.Column)
+    }
+  }
+}
+```
+
+![zh-cn_image_WaterFlow.gif](figures/waterflow.gif)
diff --git a/zh-cn/application-dev/website.md b/zh-cn/application-dev/website.md
index 3accc5ef54..647ea4be8e 100644
--- a/zh-cn/application-dev/website.md
+++ b/zh-cn/application-dev/website.md
@@ -790,6 +790,7 @@
       - [Swiper](reference/arkui-ts/ts-container-swiper.md)
       - [Tabs](reference/arkui-ts/ts-container-tabs.md)
       - [TabContent](reference/arkui-ts/ts-container-tabcontent.md)
+      - [WaterFlow](reference/arkui-ts/ts-container-waterflow.md)
     - 媒体组件
       - [Video](reference/arkui-ts/ts-media-components-video.md)
     - 绘制组件
-- 
GitLab