鸿蒙OpenHarmony【List】ArkTS滚动与滑动

子组件

仅支持[ListItem]、[ListItemGroup]子组件，支持渲染控制类型（[if/else]、[ForEach]、[LazyForEach]和[Repeat]。
说明
List的子组件的索引值盘算规则：
按子组件的次序依次递增。
if/else语句中，只有条件建立的分支内的子组件会参与索引值盘算，条件不建立的分支内子组件不盘算索引值。
ForEach/LazyForEach/Repeat语句中，管帐算睁开所有子节点索引值。
[if/else]、[ForEach]、[LazyForEach]和[Repeat]发生变革以后，会更新子节点索引值。
ListItemGroup作为一个整体盘算一个索引值，ListItemGroup内部的ListItem不盘算索引值。
List子组件visibility属性设置为Hidden或None依然管帐算索引值。
List子组件的visibility属性设置为None时不显示，但该子组件上下的space还会生效。
接口

List(value?:{space?: number | string, initialIndex?: number, scroller?: Scroller})
卡片本领： 从API version 9开始，该接口支持在ArkTS卡片中使用。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系本领： SystemCapability.ArkUI.ArkUI.Full
参数：
参数名类型必填说明spacenumberstring否initialIndexnumber否设置当前List初次加载时视口起始位置显示的item的索引值。默认值：0**说明：**设置为负数或超过了当前List最后一个item的索引值时视为无效取值，无效取值按默认值显示。scroller[Scroller]否可滚动组件的控制器。用于与可滚动组件举行绑定。**说明：**不允许和其他滚动类组件绑定同一个滚动控制对象。 属性

除支持[通用属性]和[滚动组件通用属性]外，还支持以下属性：
listDirection

listDirection(value: Axis)
设置List组件排列方向。
卡片本领： 从API version 9开始，该接口支持在ArkTS卡片中使用。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系本领： SystemCapability.ArkUI.ArkUI.Full
参数：
参数名类型必填说明value[Axis]是组件的排列方向。默认值：Axis.Vertical divider

divider(value: {strokeWidth: Length; color?: ResourceColor; startMargin?: Length; endMargin?: Length;} | null,)
设置ListItem分割线样式，默认无分割线。
endMargin + startMargin 超过列宽度后startMargin和endMargin会置0。
strokeWidth, startMargin和endMargin不支持设置百分比。
List的分割线画在主轴方向两个子组件之间，第一个子组件上方和最后一个子组件下方不会绘制分割线。
多列模式下，ListItem与ListItem之间的分割线起始边距从每一列的交叉轴方向起始边开始盘算，其他环境从List交叉轴方向起始边开始盘算。
ListItem设置[多态样式]时，被按压的子组件上下的分割线不绘制。
卡片本领： 从API version 9开始，该接口支持在ArkTS卡片中使用。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系本领： SystemCapability.ArkUI.ArkUI.Full
参数：
参数名类型必填说明value{strokeWidth: [Length],color?:[ResourceColor],startMargin?: [Length],endMargin?: [Length]}null是 scrollBar

scrollBar(value: BarState)
设置滚动条状态。
卡片本领： 从API version 9开始，该接口支持在ArkTS卡片中使用。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系本领： SystemCapability.ArkUI.ArkUI.Full
参数：
参数名类型必填说明value[BarState]是滚动条状态。默认值：BarState.Auto**说明：**API version 9及以下版本默认值为BarState.Off，API version 10及以上版本的默认值为BarState.Auto。 cachedCount

cachedCount(value: number)
设置列表中ListItem/ListItemGroup的预加载数目，懒加载场景只会预加载List显示地区外cachedCount的内容，非懒加载场景会全部加载。懒加载、非懒加载都只布局List显示地区+List显示地区外cachedCount的内容。
List设置cachedCount后，显示地区外上下各会预加载并布局cachedCount行ListItem。盘算ListItem行数时，管帐算ListItemGroup内部的ListItem行数。如果ListItemGroup内没有ListItem，则整个ListItemGroup算一行。
List下嵌套使用LazyForEach，而且LazyForEach下嵌套使用ListItemGroup时，LazyForEach会在List显示地区外上下各会创建cachedCount个ListItemGroup。
卡片本领： 从API version 9开始，该接口支持在ArkTS卡片中使用。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系本领： SystemCapability.ArkUI.ArkUI.Full
参数：
参数名类型必填说明valuenumber是ListItem/ListItemGroup的预加载数目。默认值：1 editMode(deprecated)

editMode(value: boolean)
设置当前List组件是否处于可编辑模式。可参考[示例3]实现删除选中的list项。
从API version9开始废弃不再使用，无替代接口。
体系本领： SystemCapability.ArkUI.ArkUI.Full
参数：
参数名类型必填说明valueboolean是当前List组件是否处于可编辑模式。默认值：false edgeEffect

edgeEffect(value: EdgeEffect, options?: EdgeEffectOptions)
设置边缘滑动结果。
卡片本领： 从API version 9开始，该接口支持在ArkTS卡片中使用。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系本领： SystemCapability.ArkUI.ArkUI.Full
参数：
参数名类型必填说明value[EdgeEffect]是List组件的边缘滑动结果，支持弹簧结果和阴影结果。默认值：EdgeEffect.Springoptions11+[EdgeEffectOptions]否组件内容大小小于组件自身时，是否开启滑动结果。设置为{ alwaysEnabled: true }会开启滑动结果，{ alwaysEnabled: false }不开启。默认值：{ alwaysEnabled: false } chainAnimation

chainAnimation(value: boolean)
设置当前List是否启用链式联动动效，开启后列表滑动以及顶部和底部拖拽时会有链式联动的结果。
链式联动结果：List内的ListItem隔断一定距离，该距离可以通过List组件space参数设置，默认为20vp。在手指划动过程中，手指拖动的ListItem是自动对象，相邻的ListItem为从动对象，自动对象驱动从动对象联动，驱动结果遵循弹簧物理动效。
链式动效生效后，List的分割线不显示。
链式动效生效必要满足以下条件条件：
1、List边缘结果为Spring类型。
2、List没有启用多列模式。
卡片本领： 从API version 9开始，该接口支持在ArkTS卡片中使用。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系本领： SystemCapability.ArkUI.ArkUI.Full
参数：
参数名类型必填说明valueboolean是是否启用链式联动动效。默认值：false，不启用链式联动。true，启用链式联动。 multiSelectable8+

multiSelectable(value: boolean)
设置是否开启鼠标框选。
卡片本领： 从API version 9开始，该接口支持在ArkTS卡片中使用。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系本领： SystemCapability.ArkUI.ArkUI.Full
参数：
参数名类型必填说明valueboolean是是否开启鼠标框选。默认值：false，关闭框选。true，开启框选。 lanes9+

lanes(value: number | LengthConstrain, gutter?: Dimension)
设置List组件的布局列数或行数。gutter为列间距，当列数大于1时生效。
规则如下：

• lanes为指定的数目时，根据指定的数目与List组件的交叉轴尺寸除以列数作为列的宽度。
  
• lanes设置了{minLength，maxLength}时，根据List组件的宽度自适应决定lanes数目（即列数），包管缩放过程中lane的宽度符合{minLength，maxLength}的限制。此中，minLength条件会被优先满足，即优先包管符合ListItem的交叉轴尺寸符合最小限制。
  
• lanes设置了{minLength，maxLength}，如果父组件交叉轴方向尺寸约束为无穷大时，固定按一列排列，列宽度按显示地区内最大的ListItem盘算。
  
• ListItemGroup在多列模式下也是独占一行，ListItemGroup中的ListItem按照List组件的lanes属性设置值来布局。
  
• lanes设置了{minLength，maxLength}时，盘算列数会按照ListItemGroup的交叉轴尺寸盘算。当ListItemGroup交叉轴尺寸与List交叉轴尺寸不同等时ListItemGroup中的列数与List中的列数大概不一样。
  

卡片本领： 从API version 9开始，该接口支持在ArkTS卡片中使用。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系本领： SystemCapability.ArkUI.ArkUI.Full
参数：
参数名类型必填说明valuenumber[LengthConstrain]是gutter10+[Dimension]否列间距。默认值：0 alignListItem9+

alignListItem(value: ListItemAlign)
设置List交叉轴方向宽度大于ListItem交叉轴宽度 * lanes时，ListItem在List交叉轴方向的布局方式。
卡片本领： 从API version 9开始，该接口支持在ArkTS卡片中使用。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系本领： SystemCapability.ArkUI.ArkUI.Full
参数：
参数名类型必填说明value[ListItemAlign]是交叉轴方向的布局方式。默认值：ListItemAlign.Start sticky9+

sticky(value: StickyStyle)
共同[ListItemGroup]组件使用，设置ListItemGroup中header和footer是否要吸顶或吸底。sticky属性可以设置为 StickyStyle.Header | StickyStyle.Footer 以同时支持header吸顶和footer吸底。
卡片本领： 从API version 9开始，该接口支持在ArkTS卡片中使用。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系本领： SystemCapability.ArkUI.ArkUI.Full
参数：
参数名类型必填说明value[StickyStyle]是ListItemGroup吸顶或吸底结果。默认值：StickyStyle.None scrollSnapAlign10+

scrollSnapAlign(value: ScrollSnapAlign)
设置列表项滚动竣事对齐结果。
只支持ListItem等高环境下，设置列表项滚动竣事对齐结果。
触控板和鼠标滑动List竣事后不支持对齐结果。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系本领： SystemCapability.ArkUI.ArkUI.Full
参数：
参数名类型必填说明value[ScrollSnapAlign]是列表项滚动竣事对齐结果。默认值：ScrollSnapAlign.NONE enableScrollInteraction10+

enableScrollInteraction(value: boolean)
设置是否支持滚动手势，当设置为false时，无法通过手指或者鼠标滚动，但不影响控制器的滚动接口。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系本领： SystemCapability.ArkUI.ArkUI.Full
参数：
参数名类型必填说明valueboolean是是否支持滚动手势。默认值：true nestedScroll10+

nestedScroll(value: NestedScrollOptions)
设置向前向后两个方向上的嵌套滚动模式，实现与父组件的滚动联动。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系本领： SystemCapability.ArkUI.ArkUI.Full
参数：
参数名类型必填说明value[NestedScrollOptions]是嵌套滚动选项。 friction10+

friction(value: number | Resource)
设置摩擦系数，手动划动滚动地区时生效，只对惯性滚动过程有影响，对惯性滚动过程中的链式结果有间接影响。设置为小于即是0的值时，按默认值处理。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系本领： SystemCapability.ArkUI.ArkUI.Full
参数：
参数名类型必填说明valuenumber[Resource]是 contentStartOffset11+

contentStartOffset(value: number)
设置内容地区起始偏移量。列表滚动到起始位置时，列表内容与列表显示地区边界生存指定距离。
元服务API： 从API version 12开始，该接口支持在元服务中使用。
体系本领： SystemCapability.ArkUI.ArkUI.Full
参数：
参数名类型必填说明valuenumber是内容地区起始偏移量。默认值：0单位：vp contentEndOffset11+

contentEndOffset(value: number)
设置内容区末端偏移量。列表滚动到末端位置时，列表内容与列表显示地区边界生存指定距离。
元服务API： 从API version 12开始，该接口支持在元服务中使用。
体系本领： SystemCapability.ArkUI.ArkUI.Full
参数：
参数名类型必填说明valuenumber是内容区末端偏移量。默认值：0单位：vp childrenMainSize12+

childrenMainSize(value: ChildrenMainSize)
设置List组件的子组件在主轴方向的大小信息。
元服务API： 从API version 12开始，该接口支持在元服务中使用。
体系本领： SystemCapability.ArkUI.ArkUI.Full
参数：
参数名类型必填说明value[ChildrenMainSize]是1. 作用：通过ChildrenMainSize对象向List组件准确提供所有子组件在主轴方向的大小信息，可以或许使List组件在子组件的主轴大小不同等、增删子组件、使用[scrollToIndex]等场景也能维护自己准确的滑动位置，进而使[scrollTo]能跳转到准确的指定位置，[currentOffset]可以或许获取到当前准确的滑动位置，内置滚动条可以或许平滑移动无跳变。2.使用约束：（1）提供的主轴方向大小必须与子组件现实在主轴方向的大小同等，子组件在主轴方向大小变革或者增删子组件时都必须通过ChildrenMainSize对象方法通知List组件。（2）当子组件是ListItemGroup时，必要根据ListItemGroup的列数，ListItemGroup中ListItem在主轴方向的间距，ListItemGroup中header,footer,ListItem的大小准确盘算出ListItemGroup整体在主轴方向的大小，并提供给List组件。（3）如果子组件有ListItemGroup，必须给每一个ListItemGroup也设置childrenMainSize属性，List组件和每一个ListItemGroup组件都要通过childrenMainSize属性接口一对一绑定着一个ChildrenMainSize对象。（4）多列场景使用LazyForEach生成子组件时，需确保LazyForEach全部生成ListItemGroup组件或者全部生成ListItem组件。 maintainVisibleContentPosition12+

maintainVisibleContentPosition(enabled: boolean)
设置显示地区上方插入或删除数据时是否要保持可见内容位置不变。
元服务API： 从API version 12开始，该接口支持在元服务中使用。
体系本领： SystemCapability.ArkUI.ArkUI.Full
参数：
参数名类型必填说明enabledboolean是设置显示地区上方插入或删除数据时是否要保持可见内容位置不变。默认值：false，显示地区上方插入或删除数据时可见内容位置会跟随变革。 true：显示地区上方插入或删除数据时可见内容位置不变。 说明

• 只有使用LazyForEach在显示地区外插入或删除数据时，才能保持可见内容位置不变。使用ForEach插入或删除数据或使用LazyForEach重新加载数据时，纵然maintainVisibleContentPosition属性设置为true，可见区内容位置也会跟随变革。
  
• maintainVisibleContentPosition属性设置为true后，在显示地区上方插入或删除数据，会触发onDidScroll、onScrollIndex事件。
  
• maintainVisibleContentPosition属性设置为true后，在多列场景下，一次插入或删除整行数据，可以保持可见内容位置不变，如果不是插入或删除整行数据，可见内容位置照旧会发生变革。
  

ListItemAlign9+枚举说明

卡片本领： 从API version 9开始，该接口支持在ArkTS卡片中使用。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系本领： SystemCapability.ArkUI.ArkUI.Full
名称枚举值形貌Start0ListItem在List中，交叉轴方向首部对齐。Center1ListItem在List中，交叉轴方向居中对齐。End2ListItem在List中，交叉轴方向尾部对齐。 StickyStyle9+枚举说明

卡片本领： 从API version 9开始，该接口支持在ArkTS卡片中使用。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系本领： SystemCapability.ArkUI.ArkUI.Full
名称枚举值形貌None0ListItemGroup的header不吸顶，footer不吸底。Header1ListItemGroup的header吸顶，footer不吸底。Footer2ListItemGroup的footer吸底，header不吸顶。 ScrollSnapAlign10+枚举说明

设置列表项滚动竣事对齐结果。
左右和上下这种两头对齐的样式：当列表位移至末了，则必要将末了的item完备显示，同时不能露出边界空白地区，此时另一端可以出现不限位对齐的征象。
只支持item等高场景限位，不等高场景大概存在不准确的环境。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系本领： SystemCapability.ArkUI.ArkUI.Full
名称枚举值形貌NONE0默认无项目滚动对齐结果。START1视图中的第一项将在列表的开头对齐。**说明：**当列表位移至末了，必要将末了的item完备显示，大概出现开头不对齐的环境。CENTER2视图中的中间项将在列表中心对齐。**说明：**顶端和末端的item都可以在列表中心对齐，列表显示大概露出空白，第一个或最后一个item会对齐到中间位置。END3视图中的最后一项将在列表末端对齐。**说明：**当列表位移至顶端，必要将顶端的item完备显示，大概出现末端不对齐的环境。 CloseSwipeActionOptions11+对象说明

收起[EXPANDED]状态[ListItem]回调事件聚集，用于设置收起动画完成后回调事件。
元服务API： 从API version 12开始，该接口支持在元服务中使用。
体系本领： SystemCapability.ArkUI.ArkUI.Full
名称类型必填说明onFinish()=>void否在收起动画完成后触发。 事件

除支持[通用事件]和[滚动组件通用事件]外，还支持以下事件：
onItemDelete(deprecated)

onItemDelete(event: (index: number) => boolean)
当List组件在编辑模式时，点击ListItem右边出现的删除按钮时触发。
从API version9开始废弃不再使用，无替代接口。
体系本领： SystemCapability.ArkUI.ArkUI.Full
参数：
参数名类型必填说明indexnumber是被删除的列表项的索引值。 返回值：
类型说明boolean是否已经删除。 onScrollIndex

onScrollIndex(event: (start: number, end: number, center: number) => void)
有子组件划入或划出List显示地区时触发。盘算索引值时，ListItemGroup作为一个整体占一个索引值，不盘算ListItemGroup内部ListItem的索引值。
List的边缘结果为弹簧结果时，在List划动到边缘继承划动和放手回弹过程不会触发onScrollIndex事件。
触发该事件的条件：列表初始化时会触发一次，List显示地区内第一个子组件的索引值或最后一个子组件的索引值有变革时会触发。
从API version 10开始，List显示地区中间位置子组件变革时也会触发该事件。
卡片本领： 从API version 9开始，该接口支持在ArkTS卡片中使用。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系本领： SystemCapability.ArkUI.ArkUI.Full
参数：
参数名类型必填说明startnumber是List显示地区内第一个子组件的索引值endnumber是List显示地区内最后一个子组件的索引值。center10+number是List显示地区内中间位置子组件的索引值。 onReachStart

onReachStart(event: () => void)
列表到达起始位置时触发。
List初始化时如果initialIndex为0会触发一次，List滚动到起始位置时触发一次。List边缘结果为弹簧结果时，划动经过起始位置时触发一次，回弹回起始位置时再触发一次。
卡片本领： 从API version 9开始，该接口支持在ArkTS卡片中使用。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系本领： SystemCapability.ArkUI.ArkUI.Full
onReachEnd

onReachEnd(event: () => void)
列表到底末端位置时触发。
List边缘结果为弹簧结果时，划动经过末端位置时触发一次，回弹回末端位置时再触发一次。
卡片本领： 从API version 9开始，该接口支持在ArkTS卡片中使用。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系本领： SystemCapability.ArkUI.ArkUI.Full
onScrollFrameBegin9+

onScrollFrameBegin(event: (offset: number, state: ScrollState) => { offsetRemain：number })
列表开始滑动时触发，事件参数传入即将发生的滑动量，事件处理函数中可根据应用场景盘算现实必要的滑动量并作为事件处理函数的返回值返回，列表将按照返回值的现实滑动量举行滑动。
当listDirection的值为Axis.Vertical时，返回垂直方向滑动量，当listDirection的值为Axis.Horizontal时，返回水平方向滑动量。
触发该事件的条件：手指拖动List、List惯性划动时每帧开始时触发；List超出边缘回弹、使用滚动控制器和拖动滚动条的滚动不会触发。
卡片本领： 从API version 9开始，该接口支持在ArkTS卡片中使用。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系本领： SystemCapability.ArkUI.ArkUI.Full
参数：
参数名类型必填说明offsetnumber是即将发生的滑动量，单位vp。state[ScrollState]是当前滑动状态。 返回值：
类型说明{ offsetRemain: number }现实滑动量，单位vp。 onScrollStart9+

onScrollStart(event: () => void)
列表滑动开始时触发。手指拖动列表或列表的滚动条触发的滑动开始时，会触发该事件。使用[Scroller]滑动控制器触发的动员画的滑动，动画开始时会触发该事件
卡片本领： 从API version 9开始，该接口支持在ArkTS卡片中使用。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系本领： SystemCapability.ArkUI.ArkUI.Full
onScrollStop

onScrollStop(event: () => void)
列表滑动制止时触发。手拖动列表或列表的滚动条触发的滑动，手离开屏幕而且滑动制止时会触发该事件。使用[Scroller]滑动控制器触发的动员画的滑动，动画制止会触发该事件。
卡片本领： 从API version 9开始，该接口支持在ArkTS卡片中使用。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系本领： SystemCapability.ArkUI.ArkUI.Full
onItemMove

onItemMove(event: (from: number, to: number) => boolean)
列表元素发生移动时触发。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系本领： SystemCapability.ArkUI.ArkUI.Full
参数：
参数名类型必填说明fromnumber是移动前索引值。tonumber是移动后索引值。 返回值：
类型说明boolean是否已经移动。 onItemDragStart8+

onItemDragStart(event: (event: ItemDragInfo, itemIndex: number) => ((() => any) | void))
开始拖拽列表元素时触发。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系本领： SystemCapability.ArkUI.ArkUI.Full
参数：
参数名类型必填说明event[ItemDragInfo]是拖拽点的信息。itemIndexnumber是被拖拽列表元素索引值。 onItemDragEnter8+

onItemDragEnter(event: (event: ItemDragInfo) => void)
拖拽进入列表元素范围内时触发。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系本领： SystemCapability.ArkUI.ArkUI.Full
参数：
参数名类型必填说明event[ItemDragInfo]是拖拽点的信息。 onItemDragMove8+

onItemDragMove(event: (event: ItemDragInfo, itemIndex: number, insertIndex: number) => void)
拖拽在列表元素范围内移动时触发。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系本领： SystemCapability.ArkUI.ArkUI.Full
参数：
参数名类型必填说明event[ItemDragInfo]是拖拽点的信息。itemIndexnumber是拖拽起始位置。insertIndexnumber是拖拽插入位置。 onItemDragLeave8+

onItemDragLeave(event: (event: ItemDragInfo, itemIndex: number) => void)
拖拽离开列表元素时触发。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系本领： SystemCapability.ArkUI.ArkUI.Full
参数：
参数名类型必填说明event[ItemDragInfo]是拖拽点的信息。itemIndexnumber是拖拽离开的列表元素索引值。 onItemDrop8+

onItemDrop(event: (event: ItemDragInfo, itemIndex: number, insertIndex: number, isSuccess: boolean) => void)
绑定该事件的列表元素可作为拖拽释放目的，当在列表元素内制止拖拽时触发。
跨List拖拽时，当拖拽释放的位置绑定了onItemDrop时会返回true，否则为false。List内部拖拽时，isSuccess为onItemMove事件的返回值。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系本领： SystemCapability.ArkUI.ArkUI.Full
参数：
参数名类型必填说明event[ItemDragInfo]是拖拽点的信息。itemIndexnumber是拖拽起始位置。insertIndexnumber是拖拽插入位置。isSuccessboolean是是否乐成释放 onScroll(deprecated)

onScroll(event: (scrollOffset: number, scrollState: [ScrollState]) => void)
列表滑动时触发。
从API version 12开始废弃不再使用，推荐使用[onDidScroll]事件替代。
卡片本领： 从API version 9开始，该接口支持在ArkTS卡片中使用。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系本领： SystemCapability.ArkUI.ArkUI.Full
参数：
参数名类型必填说明scrollOffsetnumber是每帧滚动的偏移量，List的内容向上滚动时偏移量为正，向下滚动时偏移量为负。单位vp。scrollState[ScrollState]是当前滑动状态。 onScrollVisibleContentChange12+

onScrollVisibleContentChange(handler: OnScrollVisibleContentChangeCallback)
有子组件划入或划出List显示地区时触发。盘算触发条件时，每一个ListItem、ListItemGroup中的header或footer都算一个子组件。
List的边缘结果为弹簧结果时，在List划动到边缘继承划动和放手回弹过程不会触发onScrollVisibleContentChange事件。
触发该事件的条件：列表初始化时会触发一次，List显示地区内第一个子组件的索引值或最后一个子组件的索引值有变革时会触发。
元服务API： 从API version 12开始，该接口支持在元服务中使用。
体系本领： SystemCapability.ArkUI.ArkUI.Full
参数：
参数名类型必填说明handler[OnScrollVisibleContentChangeCallback]是当前显示内容发生改变的时候触发回调。 ScrollState枚举说明

卡片本领： 从API version 9开始，该接口支持在ArkTS卡片中使用。
元服务API： 从API version 11开始，该接口支持在元服务中使用。
体系本领： SystemCapability.ArkUI.ArkUI.Full
名称枚举值形貌Idle0空闲状态。滚动状态回归空闲时触发，控制器提供的无动画方法控制滚动时触发。Scroll1滚动状态。手指拖动List，拖动滚动条和滚动鼠标滚轮时触发。Fling2惯性滚动状态。动画控制的滚动都会触发。包括快速划动放手后的惯性滚动，划动到边缘回弹的滚动，快速拖动内置滚动条放手后的惯性滚动，使用滚动控制器提供的动员画的方法控制的滚动。 ListScroller11+对象说明

List组件的滚动控制器，通过它控制List组件的滚动，仅支持一对一绑定到List组件。
说明
ListScroller继承自[Scroller]，具有[Scroller]的全部方法。
导入对象

1. listScroller: ListScroller = new ListScroller()

复制代码

getItemRectInGroup11+

getItemRectInGroup(index: number, indexInGroup: number): RectResult
获取[ListItemGroup]中的[ListItem]的大小和相对于List的位置。
元服务API： 从API version 12开始，该接口支持在元服务中使用。
体系本领： SystemCapability.ArkUI.ArkUI.Full
参数：
参数名类型必填说明indexnumber是ListItemGroup在List中的索引值。indexInGroupnumber是ListItem在ListItemGroup中的索引值。 说明

• index必须是当前显示地区显示的子组件的索引值，否则视index为非法值。
  
• 索引值为index的子组件必须是ListItemGroup，否则视index为非法值。
  
• indexInGroup必须是当前显示地区内ListItemGroup中显示的ListItem的索引值，否则视indexInGroup为非法值。
  
• index或者indexInGroup为非法值时返回的大小和位置均为0。
  

返回值：
类型说明[RectResult]ListItemGroup中的ListItem的大小和相对于List的位置。单位：vp。 错误码ID错误信息401Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed.100004Controller not bound to component. scrollToItemInGroup11+

scrollToItemInGroup(index: number, indexInGroup: number, smooth?: boolean, align?: ScrollAlign): void
滑动到指定的ListItemGroup中指定的ListItem。
开启smooth动效时，会对经过的所有item举行加载和布局盘算，当大量加载item时会导致性能问题。
元服务API： 从API version 12开始，该接口支持在元服务中使用。
体系本领： SystemCapability.ArkUI.ArkUI.Full
参数：
参数名类型必填说明indexnumber是要滑动到的目的元素所在的ListItemGroup在当前容器中的索引值。**说明：**index值设置成负值或者大于当前容器子组件的最大索引值，视为非常值，本次跳转不生效。indexInGroupnumber是要滑动到的目的元素在index指定的ListItemGroup中的索引值。**说明：**indexInGroup值设置成负值或者大于index指定的ListItemGroup容器子组件的最大索引值，视为非常值，本次跳转不生效。smoothboolean否设置滑动到列表项在列表中的索引值时是否有动效，true表示有动效，false表示没有动效。默认值：false。align[ScrollAlign]否指定滑动到的元素与当前容器的对齐方式。默认值：ScrollAlign.START。 错误码ID错误信息401Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed.100004Controller not bound to component. closeAllSwipeActions11+

closeAllSwipeActions(options?: [CloseSwipeActionOptions]): void
将[EXPANDED]状态的[ListItem]收起，并设置回调事件。
元服务API： 从API version 12开始，该接口支持在元服务中使用。
体系本领： SystemCapability.ArkUI.ArkUI.Full
参数：
参数名类型必填说明options[CloseSwipeActionOptions]否收起[EXPANDED]状态的[ListItem]的回调事件聚集。 错误码ID错误信息401Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed.100004Controller not bound to component. 说明

• ListScroller必须绑定到List组件上。
  

OnScrollVisibleContentChangeCallback12+

type OnScrollVisibleContentChangeCallback = (start: VisibleListContentInfo, end: VisibleListContentInfo) => void
有子组件划入或划出List显示地区时触发。
元服务API： 从API version 12开始，该接口支持在元服务中使用。
体系本领： SystemCapability.ArkUI.ArkUI.Full
参数名类型必填说明start[VisibleListContentInfo]是当前显示界面第一个ListItem或ListItemGroup的具体信息。end[VisibleListContentInfo]是当前显示界面最后一个ListItem或ListItemGroup的具体信息。 VisibleListContentInfo12+对象说明

元服务API： 从API version 12开始，该接口支持在元服务中使用。
体系本领： SystemCapability.ArkUI.ArkUI.Full
名称类型必填说明indexnumber是List显示地区内ListItem或ListItemGroup的索引值。itemGroupArea[ListItemGroupArea]否如果当前可视页面的上边或下边在某个ListItemGroup之中，将会显示它所处的位置。itemIndexInGroupnumber否如果当前可视页面的上边或下边在某个Group之中，将会显示Start或End的ListItem在Group中的索引。 ListItemGroupArea12+枚举说明

元服务API： 从API version 12开始，该接口支持在元服务中使用。
体系本领： SystemCapability.ArkUI.ArkUI.Full
名称枚举值形貌NONE0当前页面可视边处于none位置。例如，ListItemGroup中既没有header、footer，也没有ListItem。IN_LIST_ITEM_AREA1当前页面可视边处于ListItem位置。IN_HEADER_AREA2当前页面可视边处于header位置。IN_FOOTER_AREA3当前页面可视边处于footer位置。 示例

示例1

该示例实现了设置纵向列表，并在当前显示界面发生改变时回调索引。

1. // xxx.ets
2. @Entry
3. @Component
4. struct ListExample {
5.   private arr: number[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
7.   build() {
8.     Column() {
9.       List({ space: 20, initialIndex: 0 }) {
10.         ForEach(this.arr, (item: number) => {
11.           ListItem() {
12.             Text('' + item)
13.               .width('100%').height(100).fontSize(16)
14.               .textAlign(TextAlign.Center).borderRadius(10).backgroundColor(0xFFFFFF)
15.           }
16.         }, (item: string) => item)
17.       }
18.       .listDirection(Axis.Vertical) // 排列方向
19.       .scrollBar(BarState.Off)
20.       .friction(0.6)
21.       .divider({ strokeWidth: 2, color: 0xFFFFFF, startMargin: 20, endMargin: 20 }) // 每行之间的分界线
22.       .edgeEffect(EdgeEffect.Spring) // 边缘效果设置为Spring
23.       .onScrollIndex((firstIndex: number, lastIndex: number, centerIndex: number) => {
24.         console.info('first' + firstIndex)
25.         console.info('last' + lastIndex)
26.         console.info('center' + centerIndex)
27.       })
28.       .onScrollVisibleContentChange((start: VisibleListContentInfo, end: VisibleListContentInfo) => {
29.         console.log(' start index: ' + start.index +
30.                     ' start item group area: ' + start.itemGroupArea +
31.                     ' start index in group: ' + start.itemIndexInGroup)
32.         console.log(' end index: ' + end.index +
33.                     ' end item group area: ' + end.itemGroupArea +
34.                     ' end index in group: ' + end.itemIndexInGroup)
35.       })
36.       .onDidScroll((scrollOffset: number, scrollState: ScrollState) => {
37.         console.info(`onScroll scrollState = ScrollState` + scrollState + `, scrollOffset = ` + scrollOffset)
38.       })
39.       .width('90%')
40.     }
41.     .width('100%')
42.     .height('100%')
43.     .backgroundColor(0xDCDCDC)
44.     .padding({ top: 5 })
45.   }
46. }

复制代码

示例2

1. // xxx.ets
2. @Entry
3. @Component
4. struct ListLanesExample {
5.   @State arr: string[] = ["0", "1", "2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "12", "13", "14", "15", "16", "17", "18", "19"]
6.   @State alignListItem: ListItemAlign = ListItemAlign.Start
8.   build() {
9.     Column() {
10.       List({ space: 20, initialIndex: 0 }) {
11.         ForEach(this.arr, (item: string) => {
12.           ListItem() {
13.             Text('' + item)
14.               .width('100%')
15.               .height(100)
16.               .fontSize(16)
17.               .textAlign(TextAlign.Center)
18.               .borderRadius(10)
19.               .backgroundColor(0xFFFFFF)
20.           }
21.           .border({ width: 2, color: Color.Green })
22.         }, (item: string) => item)
23.       }
24.       .height(300)
25.       .width("90%")
26.       .friction(0.6)
27.       .border({ width: 3, color: Color.Red })
28.       .lanes({ minLength: 40, maxLength: 40 })
29.       .alignListItem(this.alignListItem)
30.       .scrollBar(BarState.Off)
32.       Button("点击更改alignListItem:" + this.alignListItem).onClick(() => {
33.         if (this.alignListItem == ListItemAlign.Start) {
34.           this.alignListItem = ListItemAlign.Center
35.         } else if (this.alignListItem == ListItemAlign.Center) {
36.           this.alignListItem = ListItemAlign.End
37.         } else {
38.           this.alignListItem = ListItemAlign.Start
39.         }
40.       })
41.     }.width('100%').height('100%').backgroundColor(0xDCDCDC).padding({ top: 5 })
42.   }
43. }

复制代码

示例3

1. // xxx.ets
2. @Entry
3. @Component
4. struct ListExample {
5.   @State arr: number[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
6.   @State editFlag: boolean = false
8.   build() {
9.     Stack({ alignContent: Alignment.TopStart }) {
10.       Column() {
11.         List({ space: 20, initialIndex: 0 }) {
12.           ForEach(this.arr, (item: number, index?: number) => {
13.             ListItem() {
14.               Flex({ direction: FlexDirection.Row, alignItems: ItemAlign.Center }) {
15.                 Text('' + item)
16.                   .width('100%')
17.                   .height(80)
18.                   .fontSize(20)
19.                   .textAlign(TextAlign.Center)
20.                   .borderRadius(10)
21.                   .backgroundColor(0xFFFFFF)
22.                   .flexShrink(1)
23.                 if (this.editFlag) {
24.                   Button() {
25.                     Text("delete").fontSize(16)
26.                   }.width('30%').height(40)
27.                   .onClick(() => {
28.                     if (index != undefined) {
29.                       console.info(this.arr[index] + 'Delete')
30.                       this.arr.splice(index, 1)
31.                       console.info(JSON.stringify(this.arr))
32.                       this.editFlag = false
33.                     }
34.                   }).stateEffect(true)
35.                 }
36.               }
37.             }
38.           }, (item: string) => item)
39.         }.width('90%')
40.         .scrollBar(BarState.Off)
41.         .friction(0.6)
42.       }.width('100%')
44.       Button('edit list')
45.         .onClick(() => {
46.           this.editFlag = !this.editFlag
47.         }).margin({ top: 5, left: 20 })
48.     }.width('100%').height('100%').backgroundColor(0xDCDCDC).padding({ top: 5 })
49.   }
50. }

复制代码

示例4

1. // xxx.ets
2. @Entry
3. @Component
4. struct ListExample {
5.   private arr: number[] = []
6.   private scrollerForList: Scroller = new Scroller()
8.   aboutToAppear() {
9.     for (let i = 0; i < 20; i++) {
10.       this.arr.push(i)
11.     }
12.   }
13.   build() {
14.     Column() {
15.       Row() {
16.         List({ space: 20, initialIndex: 3, scroller: this.scrollerForList }) {
17.           ForEach(this.arr, (item: number) => {
18.             ListItem() {
19.               Text('' + item)
20.                 .width('100%').height(100).fontSize(16)
21.                 .textAlign(TextAlign.Center)
22.             }
23.             .borderRadius(10).backgroundColor(0xFFFFFF)
24.             .width('60%')
25.             .height('80%')
26.           }, (item: number) => JSON.stringify(item))
27.         }
28.         .chainAnimation(true)
29.         .edgeEffect(EdgeEffect.Spring)
30.         .listDirection(Axis.Horizontal)
31.         .height('100%')
32.         .width('100%')
33.         .scrollSnapAlign(ScrollSnapAlign.CENTER)
34.         .borderRadius(10)
35.         .backgroundColor(0xDCDCDC)
36.       }
37.       .width('100%')
38.       .height('100%')
39.       .backgroundColor(0xDCDCDC)
40.       .padding({ top: 10 })
41.     }
42.   }
43. }

复制代码

示例5

该示例通过设置childrenMainSize属性，实现了List在子组件高度不同等时调用scrollTo接口也可以跳转准确。

1. // xxx.ets
2. @Entry
3. @Component
4. struct ListExample {
5.   private arr: number[] = []
6.   private scroller: ListScroller = new ListScroller()
7.   @State listSpace: number = 10
8.   @State listChildrenSize: ChildrenMainSize = new ChildrenMainSize(100)
9.   aboutToAppear(){
10.     // 初始化数据源。
11.     for (let i = 0; i < 10; i++) {
12.       this.arr.push(i)
13.     }
14.     // 前5个item的主轴大小不是默认大小100，因此需要通过ChildrenMainSize通知List。
15.     this.listChildrenSize.splice(0, 5, [300, 300, 300, 300, 300])
16.   }
17.   build() {
18.     Column() {
19.       List({ space: this.listSpace, initialIndex: 4, scroller: this.scroller }) {
20.         ForEach(this.arr, (item: number) => {
21.           ListItem() {
22.             Text('item-' + item)
23.               .height( item < 5 ? 300 : this.listChildrenSize.childDefaultSize)
24.               .width('90%')
25.               .fontSize(16)
26.               .textAlign(TextAlign.Center)
27.               .borderRadius(10)
28.               .backgroundColor(0xFFFFFF)
29.           }
30.         }, (item: string) => item)
31.       }
32.       .backgroundColor(Color.Gray)
33.       .layoutWeight(1)
34.       .scrollBar(BarState.On)
35.       .childrenMainSize(this.listChildrenSize)
36.       .alignListItem(ListItemAlign.Center)
37.       Row(){
38.         Button() { Text('item size + 50') }.onClick(()=>{
39.           this.listChildrenSize.childDefaultSize += 50
40.         }).height('50%').width('30%')
41.         Button() { Text('item size - 50') }.onClick(()=>{
42.           if (this.listChildrenSize.childDefaultSize === 0) {
43.             return
44.           }
45.           this.listChildrenSize.childDefaultSize -= 50
46.         }).height('50%').width('30%')
47.         Button() { Text('scrollTo (0, 310)') }.onClick(()=>{
48.           // 310: 跳转到item 1顶部与List顶部平齐的位置。
49.           // 如果不设置childrenMainSize，item高度不一致时scrollTo会不准确。
50.           this.scroller.scrollTo({xOffset: 0, yOffset: 310})
51.         }).height('50%').width('30%')
52.       }.height('20%')
53.     }
54.   }
55. }

复制代码

免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！更多信息从访问主页：qidao123.com:ToB企服之家，中国第一个企服评测及商务社交产业平台。