!14264 List Scroll组件滚动事件修改

Merge pull request !14264 from yeyinglong/scroll

zh-cn/application-dev/reference/arkui-ts/ts-container-list.md

@@ -70,7 +70,8 @@ List(value?:{space?: number | string, initialIndex?: number, scroller?
 | onScrollIndex(event: (start: number, end: number) => void) | 列表滑动时触发。<br/>计算索引值时，ListItemGroup作为一个整体占一个索引值，不计算ListItemGroup内部ListItem的索引值。<br/>- start: 滑动起始位置索引值。<br/>- end: 滑动结束位置索引值。 |
 | onReachStart(event: () => void) | 列表到达起始位置时触发。 |
 | onReachEnd(event: () => void) | 列表到底末尾位置时触发。 |
-| onScrollBegin<sup>9+</sup>(event: (dx: number, dy: number) => { dxRemain: number, dyRemain: number }) | 列表开始滑动时触发，事件参数传入即将发生的滑动量，事件处理函数中可根据应用场景计算实际需要的滑动量并作为事件处理函数的返回值返回，列表将按照返回值的实际滑动量进行滑动。<br/>\- dx：即将发生的水平方向滑动量。<br/>\- dy：即将发生的竖直方向滑动量。<br/>- dxRemain：水平方向实际滑动量。<br/>\- dyRemain：竖直方向实际滑动量。 |
+| onScrollFrameBegin<sup>9+</sup>(event: (offset: number, state: ScrollState) => { offsetRemain }) | 列表开始滑动时触发，事件参数传入即将发生的滑动量，事件处理函数中可根据应用场景计算实际需要的滑动量并作为事件处理函数的返回值返回，列表将按照返回值的实际滑动量进行滑动。<br/>\- offset：即将发生的滑动量。<br/>\- state：当前滑动状态。<br/>- offsetRemain：水平方向实际滑动量。 |
+| onScrollStart<sup>9+</sup>(event: () => void) | 列表滑动开始时触发。手指拖动列表或列表的滚动条触发的滑动开始时，会触发该事件。使用[Scroller](ts-container-scroll.md#scroller)滑动控制器触发的滑动，不会触发该事件。 |
 | onScrollStop(event: () => void) | 列表滑动停止时触发。手拖动列表或列表的滚动条触发的滑动，手离开屏幕并且滑动停止时会触发该事件；使用[Scroller](ts-container-scroll.md#scroller)滑动控制器触发的滑动，不会触发该事件。 |
 | onItemMove(event: (from: number, to: number) => boolean) | 列表元素发生移动时触发。<br/>- from: 移动前索引值。<br/>- to: 移动后索引值。 |
 | onItemDragStart(event: (event: ItemDragInfo, itemIndex: number) => ((() => any) \| void) | 开始拖拽列表元素时触发。<br/>- event: 见[ItemDragInfo对象说明](ts-container-grid.md#itemdraginfo对象说明)。<br/>- itemIndex: 被拖拽列表元素索引值。 |

zh-cn/application-dev/reference/arkui-ts/ts-container-scroll.md

@@ -42,14 +42,16 @@ Scroll(scroller?: Scroller)
 
 | 名称                                                         | 功能描述                                                     |
 | ------------------------------------------------------------ | ------------------------------------------------------------ |
-| onScrollBegin<sup>9+</sup>(event: (dx: number, dy: number) => { dxRemain: number, dyRemain: number }) | 滚动开始事件回调。<br>参数：<br>- dx：即将发生的水平方向滚动量。<br>- dy：即将发生的竖直方向滚动量。<br>返回值：<br>- dxRemain：水平方向滚动剩余量。<br>- dyRemain：竖直方向滚动剩余量。 |
+| onScrollFrameBegin<sup>9+</sup>(event: (offset: number, state: ScrollState) => { offsetRemain }) | 每帧开始滚动时触发，事件参数传入即将发生的滚动量，事件处理函数中可根据应用场景计算实际需要的滚动量并作为事件处理函数的返回值返回，Scroll将按照返回值的实际滚动量进行滚动。<br/>\- offset：即将发生的滚动量。<br/>\- state：当前滚动状态。<br/>- offsetRemain：水平方向实际滚动量。 |
 | onScroll(event: (xOffset: number, yOffset: number) => void)  | 滚动事件回调,&nbsp;返回滚动时水平、竖直方向偏移量。          |
 | onScrollEdge(event: (side: Edge) => void)                    | 滚动到边缘事件回调。                                         |
-| onScrollEnd(event: () => void)                               | 滚动停止事件回调。                                           |
+| onScrollEnd(event: () => void)                               | 滚动停止事件回调。<br>该事件从API9开始废弃，使用onScrollStop事件替代。     |
+| onScrollStart<sup>9+</sup>(event: () => void) | 滚动开始时触发。手指拖动Scroll或拖动Scroll的滚动条触发的滚动开始时，会触发该事件。使用[Scroller](#scroller)滚动控制器触发的滚动，不会触发该事件。 |
+| onScrollStop<sup>9+</sup>(event: () => void) | 滚动停止时触发。手拖动Scroll或拖动Scroll的滚动条触发的滚动，手离开屏幕并且滚动停止时会触发该事件；使用[Scroller](#scroller)滚动控制器触发的滚动，不会触发该事件。 |
 
 >  **说明：**
 >
->  若通过onScrollBegin事件和scrollBy方法实现容器嵌套滚动，需设置子滚动节点的EdgeEffect为None。如Scroll嵌套List滚动时，List组件的edgeEffect属性需设置为EdgeEffect.None。
+>  若通过onScrollFrameBegin事件和scrollBy方法实现容器嵌套滚动，需设置子滚动节点的EdgeEffect为None。如Scroll嵌套List滚动时，List组件的edgeEffect属性需设置为EdgeEffect.None。
 
 ## Scroller
 
@@ -268,13 +270,13 @@ struct NestedScroll {
           .onReachEnd(() => {
             this.listPosition = 2
           })
-          .onScrollBegin((dx: number, dy: number) => {
-            if ((this.listPosition == 0 && dy >= 0) || (this.listPosition == 2 && dy <= 0)) {
-              this.scrollerForScroll.scrollBy(0, -dy)
-              return { dxRemain: dx, dyRemain: 0 }
+          .onScrollFrameBegin((offset: number) => {
+            if ((this.listPosition == 0 && offset >= 0) || (this.listPosition == 2 && offset <= 0)) {
+              this.scrollerForScroll.scrollBy(0, -offset)
+              return { offsetRemain: 0 }
             }
             this.listPosition = 1
-            return { dxRemain: dx, dyRemain: dy };
+            return { offsetRemain: offset };
           })
 
           Text("Scroll Area")