1# List 2 3列表包含一系列相同宽度的列表项。适合连续、多行呈现同类数据，例如图片和文本。 4 5> **说明：** 6> 7> 该组件从API Version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 8 9 10## 子组件 11 12仅支持[ListItem](ts-container-listitem.md)、[ListItemGroup](ts-container-listitemgroup.md)子组件，支持渲染控制类型（[if/else](../../../quick-start/arkts-rendering-control-ifelse.md)、[ForEach](../../../quick-start/arkts-rendering-control-foreach.md)、[LazyForEach](../../../quick-start/arkts-rendering-control-lazyforeach.md)和[Repeat](../../../quick-start/arkts-new-rendering-control-repeat.md)）。 13 14> **说明：** 15> 16> List的子组件的索引值计算规则： 17> 18> - 按子组件的顺序依次递增。 19> 20> - if/else语句中，只有条件成立的分支内的子组件会参与索引值计算，条件不成立的分支内子组件不计算索引值。 21> 22> - ForEach/LazyForEach/Repeat语句中，会计算展开所有子节点索引值。 23> 24> - [if/else](../../../quick-start/arkts-rendering-control-ifelse.md)、[ForEach](../../../quick-start/arkts-rendering-control-foreach.md)、[LazyForEach](../../../quick-start/arkts-rendering-control-lazyforeach.md)和[Repeat](../../../quick-start/arkts-new-rendering-control-repeat.md)发生变化以后，会更新子节点索引值。 25> 26> - ListItemGroup作为一个整体计算一个索引值，ListItemGroup内部的ListItem不计算索引值。 27> 28> - List子组件visibility属性设置为Hidden或None依然会计算索引值。 29 30 31## 接口 32 33List(value?:{initialIndex?: number, space?: number | string, scroller?: Scroller}) 34 35**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 36 37**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 38 39**系统能力：** SystemCapability.ArkUI.ArkUI.Full 40 41**参数：** 42 43| 参数名 | 类型 | 必填 | 说明 | 44| ------------ | ------------------------------------------- | ---- | ------------------------------------------------------------ | 45| initialIndex | number | 否 | 设置当前List初次加载时显示区域起始位置的item索引值。<br/>默认值：0<br/>**说明：** <br/>设置为负数或超过了当前List最后一个item的索引值时视为无效取值，无效取值按默认值显示。 | 46| space | number \| string | 否 | 子组件主轴方向的间隔。<br/>默认值：0<br/>参数类型为number时单位为vp。<br/>**说明：** <br/>设置为负数或者大于等于List内容区长度时，按默认值显示。<br/>space参数值小于List分割线宽度时，子组件主轴方向的间隔取分割线宽度。<br/> List子组件的visibility属性设置为None时不显示，但该子组件上下的space还会生效。| 47| scroller | [Scroller](ts-container-scroll.md#scroller) | 否 | 可滚动组件的控制器。用于与可滚动组件进行绑定。<br/>**说明：** <br/>不允许和其他滚动类组件绑定同一个滚动控制对象。 | 48 49## 属性 50 51除支持[通用属性](ts-component-general-attributes.md)和[滚动组件通用属性](ts-container-scrollable-common.md#属性)外，还支持以下属性： 52 53> **说明：** 54> 55> List组件[通用属性clip](ts-universal-attributes-sharp-clipping.md)的默认值为true。 56 57### listDirection 58 59listDirection(value: Axis) 60 61设置List组件排列方向。 62 63**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 64 65**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 66 67**系统能力：** SystemCapability.ArkUI.ArkUI.Full 68 69**参数：** 70 71| 参数名 | 类型 | 必填 | 说明 | 72| ------ | --------------------------------- | ---- | ------------------------------------------ | 73| value | [Axis](ts-appendix-enums.md#axis) | 是 | 组件的排列方向。<br/>默认值：Axis.Vertical | 74 75### divider 76 77divider(value: {strokeWidth: Length; color?: ResourceColor; startMargin?: Length; endMargin?: Length;} | null,) 78 79设置ListItem分割线样式，默认无分割线。 80 81endMargin + startMargin 超过列宽度后startMargin和endMargin会置0。 82 83strokeWidth, startMargin和endMargin不支持设置百分比。 84 85List的分割线画在主轴方向两个子组件之间，第一个子组件上方和最后一个子组件下方不会绘制分割线。 86 87多列模式下，ListItem与ListItem之间的分割线起始边距从每一列的交叉轴方向起始边开始计算，其他情况从List交叉轴方向起始边开始计算。 88 89ListItem设置[多态样式](ts-universal-attributes-polymorphic-style.md)时，被按压的子组件上下的分割线不绘制。 90 91**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 92 93**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 94 95**系统能力：** SystemCapability.ArkUI.ArkUI.Full 96 97**参数：** 98 99| 参数名 | 类型 | 必填 | 说明 | 100| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 101| value | {<br/>strokeWidth: [Length](ts-types.md#length),<br/>color?:[ResourceColor](ts-types.md#resourcecolor),<br/>startMargin?: [Length](ts-types.md#length),<br/>endMargin?: [Length](ts-types.md#length)<br/>} \| null | 是 | ListItem分割线样式。<br/>- strokeWidth: 分割线的线宽。<br/>- color: 分割线的颜色。<br/>默认值：0x08000000<br/>- startMargin: 分割线与列表侧边起始端的距离。<br/>默认值：0，单位：vp<br/>- endMargin: 分割线与列表侧边结束端的距离。<br/>默认值：0，单位：vp | 102 103### scrollBar 104 105scrollBar(value: BarState) 106 107设置滚动条状态。 108 109**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 110 111**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 112 113**系统能力：** SystemCapability.ArkUI.ArkUI.Full 114 115**参数：** 116 117| 参数名 | 类型 | 必填 | 说明 | 118| ------ | ----------------------------------------- | ---- | ------------------------------------------------------------ | 119| value | [BarState](ts-appendix-enums.md#barstate) | 是 | 滚动条状态。<br/>默认值：BarState.Auto<br/>**说明：** <br/>API version 9及以下版本默认值为BarState.Off，API version 10及以上版本的默认值为BarState.Auto。 | 120 121### cachedCount 122 123cachedCount(value: number) 124 125设置列表中ListItem/ListItemGroup的预加载数量，懒加载场景只会预加载List显示区域外cachedCount的内容，非懒加载场景会全部加载。懒加载、非懒加载都只布局List显示区域+List显示区域外cachedCount的内容。<!--Del-->具体使用可参考[减少应用白块说明](../../../performance/arkts-performance-improvement-recommendation.md#减少应用滑动白块)。<!--DelEnd--> 126 127List设置cachedCount后，显示区域外上下各会预加载并布局cachedCount行ListItem。计算ListItem行数时，会计算ListItemGroup内部的ListItem行数。如果ListItemGroup内没有ListItem，则整个ListItemGroup算一行。 128 129List下嵌套使用LazyForEach，并且LazyForEach下嵌套使用ListItemGroup时，LazyForEach会在List显示区域外上下各会创建cachedCount个ListItemGroup。 130 131**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 132 133**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 134 135**系统能力：** SystemCapability.ArkUI.ArkUI.Full 136 137**参数：** 138 139| 参数名 | 类型 | 必填 | 说明 | 140| ------ | ------ | ---- | ------------------------------------------------------------ | 141| value | number | 是 | ListItem/ListItemGroup的预加载数量。<br/>默认值：根据屏幕内显示的节点个数设置，最大值为16。<br/>取值范围：[0, +∞) | 142 143### cachedCount<sup>14+</sup> 144 145cachedCount(count: number, show: boolean) 146 147设置列表中ListItem/ListItemGroup的预加载数量，并配置是否显示预加载节点。 148 149List设置cachedCount后，显示区域外上下各会预加载并布局cachedCount行ListItem。计算ListItem行数时，会计算ListItemGroup内部的ListItem行数。如果ListItemGroup内没有ListItem，则整个ListItemGroup算一行。配合[裁剪](ts-universal-attributes-sharp-clipping.md#clip12)或[内容裁剪](ts-container-scrollable-common.md#clipcontent14)属性可以显示出预加载节点。 150 151**卡片能力：** 从API version 14开始，该接口支持在ArkTS卡片中使用。 152 153**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 154 155**系统能力：** SystemCapability.ArkUI.ArkUI.Full 156 157**参数：** 158 159| 参数名 | 类型 | 必填 | 说明 | 160| ------ | ------ | ---- | -------------------------------------- | 161| count | number | 是 | 预加载的ListItem的数量。<br/>默认值：根据屏幕内显示的节点个数设置，最大值为16。<br/>取值范围：[0, +∞) | 162| show | boolean | 是 | 被预加载的ListItem是否需要显示。 <br/> 默认值：false，不显示预加载的ListItem。 | 163 164### editMode<sup>(deprecated)</sup> 165 166editMode(value: boolean) 167 168设置当前List组件是否处于可编辑模式。可参考[示例3](#示例3设置编辑模式)实现删除选中的list项。 169 170从API version9开始废弃不再使用，无替代接口。 171 172**系统能力：** SystemCapability.ArkUI.ArkUI.Full 173 174**参数：** 175 176| 参数名 | 类型 | 必填 | 说明 | 177| ------ | ------ | ---- | -------------------------------------------------- | 178| value | boolean | 是 | 当前List组件是否处于可编辑模式。<br/>默认值：false，当前List组件不处于可编辑模式。 | 179 180### edgeEffect 181 182edgeEffect(value: EdgeEffect, options?: EdgeEffectOptions) 183 184设置边缘滑动效果。 185 186> **说明：** 187> 188> 当List组件的内容区小于一屏时，默认没有回弹效果。若要启用回弹效果，可以通过设置edgeEffect属性的options参数来实现。 189 190**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 191 192**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 193 194**系统能力：** SystemCapability.ArkUI.ArkUI.Full 195 196**参数：** 197 198| 参数名 | 类型 | 必填 | 说明 | 199| --------------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 200| value | [EdgeEffect](ts-appendix-enums.md#edgeeffect) | 是 | List组件的边缘滑动效果，支持弹簧效果和阴影效果。<br/>默认值：EdgeEffect.Spring | 201| options<sup>11+</sup> | [EdgeEffectOptions](ts-container-scrollable-common.md#edgeeffectoptions11对象说明) | 否 | 组件内容大小小于组件自身时，是否开启滑动效果。设置为{ alwaysEnabled: true }会开启滑动效果，{ alwaysEnabled: false }不开启。<br/>默认值：{ alwaysEnabled: false } | 202 203### chainAnimation 204 205chainAnimation(value: boolean) 206 207设置当前List是否启用链式联动动效，开启后列表滑动以及顶部和底部拖拽时会有链式联动的效果。 208 209链式联动效果：List内的ListItem间隔一定距离，该距离可以通过List组件space参数设置，默认为20vp。在手指划动过程中，手指拖动的ListItem是主动对象，相邻的ListItem为从动对象，主动对象驱动从动对象联动，驱动效果遵循弹簧物理动效。 210 211链式动效生效后，List的分割线不显示。 212 213链式动效生效需要满足以下前提条件： 214 215 1、List边缘效果为Spring类型。 216 217 2、List没有启用多列模式。 218 219**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 220 221**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 222 223**系统能力：** SystemCapability.ArkUI.ArkUI.Full 224 225**参数：** 226 227| 参数名 | 类型 | 必填 | 说明 | 228| ------ | ------- | ---- | ------------------------------------------------------------ | 229| value | boolean | 是 | 是否启用链式联动动效。<br/>默认值：false，不启用链式联动。true，启用链式联动。 | 230 231### multiSelectable<sup>8+</sup> 232 233multiSelectable(value: boolean) 234 235设置是否开启鼠标框选。 236 237**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 238 239**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 240 241**系统能力：** SystemCapability.ArkUI.ArkUI.Full 242 243**参数：** 244 245| 参数名 | 类型 | 必填 | 说明 | 246| ------ | ------- | ---- | ------------------------------------------------------------ | 247| value | boolean | 是 | 是否开启鼠标框选。<br/>默认值：false，关闭框选。true，开启框选。 | 248 249### lanes<sup>9+</sup> 250 251lanes(value: number | LengthConstrain, gutter?: Dimension) 252 253设置List组件的布局列数或行数。gutter为列间距，当列数大于1时生效。 254 255规则如下： 256 257- lanes为指定的数量时，根据指定的数量与List组件的交叉轴尺寸除以列数作为列的宽度。 258- lanes设置了{minLength，maxLength}时，根据List组件的宽度自适应决定lanes数量（即列数），保证缩放过程中lane的宽度符合{minLength，maxLength}的限制。其中，minLength条件会被优先满足，即优先保证符合ListItem的交叉轴尺寸符合最小限制。 259- lanes设置了{minLength，maxLength}，如果父组件交叉轴方向尺寸约束为无穷大时，固定按一列排列，列宽度按显示区域内最大的ListItem计算。 260- ListItemGroup在多列模式下也是独占一行，ListItemGroup中的ListItem按照List组件的lanes属性设置值来布局。 261- lanes设置了{minLength，maxLength}时，计算列数会按照ListItemGroup的交叉轴尺寸计算。当ListItemGroup交叉轴尺寸与List交叉轴尺寸不一致时ListItemGroup中的列数与List中的列数可能不一样。 262 263**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 264 265**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 266 267**系统能力：** SystemCapability.ArkUI.ArkUI.Full 268 269**参数：** 270 271| 参数名 | 类型 | 必填 | 说明 | 272| -------------------- | ------------------------------------------------------------ | ---- | ---------------------------------------- | 273| value | number \| [LengthConstrain](ts-types.md#lengthconstrain) | 是 | List组件的布局列数或行数。<br/>默认值：1 | 274| gutter<sup>10+</sup> | [Dimension](ts-types.md#dimension10) | 否 | 列间距。<br />默认值：0 | 275 276### alignListItem<sup>9+</sup> 277 278alignListItem(value: ListItemAlign) 279 280设置List交叉轴方向宽度大于ListItem交叉轴宽度 * lanes时，ListItem在List交叉轴方向的布局方式。 281 282**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 283 284**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 285 286**系统能力：** SystemCapability.ArkUI.ArkUI.Full 287 288**参数：** 289 290| 参数名 | 类型 | 必填 | 说明 | 291| ------ | ---------------------------------------- | ---- | ------------------------------------------------------ | 292| value | [ListItemAlign](#listitemalign9枚举说明) | 是 | 交叉轴方向的布局方式。<br/>默认值：ListItemAlign.Start | 293 294### sticky<sup>9+</sup> 295 296sticky(value: StickyStyle) 297 298配合[ListItemGroup](ts-container-listitemgroup.md)组件使用，设置ListItemGroup中header和footer是否要吸顶或吸底。sticky属性可以设置为 StickyStyle.Header \| StickyStyle.Footer 以同时支持header吸顶和footer吸底。 299 300> **说明：** 301> 302> 由于浮点数计算精度，设置sticky后，在List滑动过程中小概率产生缝隙，可以通过[pixelRound](ts-universal-attributes-pixelRound.md#pixelround)指定当前组件向下像素取整解决该问题。 303 304**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 305 306**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 307 308**系统能力：** SystemCapability.ArkUI.ArkUI.Full 309 310**参数：** 311 312| 参数名 | 类型 | 必填 | 说明 | 313| ------ | ------------------------------------ | ---- | ---------------------------------------------------------- | 314| value | [StickyStyle](#stickystyle9枚举说明) | 是 | ListItemGroup吸顶或吸底效果。<br/>默认值：StickyStyle.None | 315 316### scrollSnapAlign<sup>10+</sup> 317 318scrollSnapAlign(value: ScrollSnapAlign) 319 320设置列表项滚动结束对齐效果。 321 322只支持ListItem等高情况下，设置列表项滚动结束对齐效果。 323 324触控板和鼠标滑动List结束后不支持对齐效果。 325 326**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 327 328**系统能力：** SystemCapability.ArkUI.ArkUI.Full 329 330**参数：** 331 332| 参数名 | 类型 | 必填 | 说明 | 333| ------ | --------------------------------------------- | ---- | --------------------------------------------------------- | 334| value | [ScrollSnapAlign](#scrollsnapalign10枚举说明) | 是 | 列表项滚动结束对齐效果。<br/>默认值：ScrollSnapAlign.NONE | 335 336### enableScrollInteraction<sup>10+</sup> 337 338enableScrollInteraction(value: boolean) 339 340设置是否支持滚动手势，当设置为false时，无法通过手指或者鼠标滚动，但不影响控制器的滚动接口。 341 342**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 343 344**系统能力：** SystemCapability.ArkUI.ArkUI.Full 345 346**参数：** 347 348| 参数名 | 类型 | 必填 | 说明 | 349| ------ | ------- | ---- | ----------------------------------- | 350| value | boolean | 是 | 是否支持滚动手势。<br/>默认值：true | 351 352### nestedScroll<sup>10+</sup> 353 354nestedScroll(value: NestedScrollOptions) 355 356设置向前向后两个方向上的嵌套滚动模式，实现与父组件的滚动联动。 357 358**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 359 360**系统能力：** SystemCapability.ArkUI.ArkUI.Full 361 362**参数：** 363 364| 参数名 | 类型 | 必填 | 说明 | 365| ------ | ------------------------------------------------------------ | ---- | -------------- | 366| value | [NestedScrollOptions](ts-container-scrollable-common.md#nestedscrolloptions10对象说明) | 是 | 嵌套滚动选项。 | 367 368### friction<sup>10+</sup> 369 370friction(value: number | Resource) 371 372设置摩擦系数，手动划动滚动区域时生效，只对惯性滚动过程有影响，对惯性滚动过程中的链式效果有间接影响。设置为小于等于0的值时，按默认值处理。 373 374**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 375 376**系统能力：** SystemCapability.ArkUI.ArkUI.Full 377 378**参数：** 379 380| 参数名 | 类型 | 必填 | 说明 | 381| ------ | ---------------------------------------------------- | ---- | ------------------------------------------------------------ | 382| value | number \| [Resource](ts-types.md#resource) | 是 | 摩擦系数。<br/>默认值：非可穿戴设备为0.6，可穿戴设备为0.9。<br/>从API version 11开始，非可穿戴设备默认值为0.7。<br/>从API version 12开始，非可穿戴设备默认值为0.75。 | 383 384### contentStartOffset<sup>11+</sup> 385 386contentStartOffset(value: number) 387 388设置内容区域起始偏移量。列表滚动到起始位置时，列表内容与列表显示区域边界保留指定距离。 389 390**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 391 392**系统能力：** SystemCapability.ArkUI.ArkUI.Full 393 394**参数：** 395 396| 参数名 | 类型 | 必填 | 说明 | 397| ------ | ------ | ---- | ----------------------------------------------- | 398| value | number | 是 | 内容区域起始偏移量。<br/>默认值：0<br/>单位：vp | 399 400### contentEndOffset<sup>11+</sup> 401 402contentEndOffset(value: number) 403 404设置内容区末尾偏移量。列表滚动到末尾位置时，列表内容与列表显示区域边界保留指定距离。 405 406**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 407 408**系统能力：** SystemCapability.ArkUI.ArkUI.Full 409 410**参数：** 411 412| 参数名 | 类型 | 必填 | 说明 | 413| ------ | ------ | ---- | --------------------------------------------- | 414| value | number | 是 | 内容区末尾偏移量。<br/>默认值：0<br/>单位：vp | 415 416### childrenMainSize<sup>12+</sup> 417 418childrenMainSize(value: ChildrenMainSize) 419 420设置List组件的子组件在主轴方向的大小信息。 421 422**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 423 424**系统能力：** SystemCapability.ArkUI.ArkUI.Full 425 426**参数：** 427 428| 参数名 | 类型 | 必填 | 说明 | 429| ---------- | ------ | ---- | ------------------------------- | 430| value | [ChildrenMainSize](ts-container-scrollable-common.md#childrenmainsize12对象说明) | 是 | 1. 作用：<br/>通过ChildrenMainSize对象向List组件准确提供所有子组件在主轴方向的大小信息，能够使List组件在子组件的主轴大小不一致、增删子组件、使用[scrollToIndex](ts-container-scroll.md#scrolltoindex)等场景也能维护自己准确的滑动位置，进而使[scrollTo](ts-container-scroll.md#scrollto)能跳转到准确的指定位置，[currentOffset](ts-container-scroll.md#currentoffset)能够获取到当前准确的滑动位置，内置滚动条能够平滑移动无跳变。<br/>2.使用约束：<br/>（1）提供的主轴方向大小必须与子组件实际在主轴方向的大小一致，子组件在主轴方向大小变化或者增删子组件时都必须通过ChildrenMainSize对象方法通知List组件。<br/>（2）当子组件是ListItemGroup时，需要根据ListItemGroup的列数，ListItemGroup中ListItem在主轴方向的间距，ListItemGroup中header,footer,ListItem的大小准确计算出ListItemGroup整体在主轴方向的大小，并提供给List组件。<br/>（3）如果子组件有ListItemGroup，必须给每一个ListItemGroup也设置childrenMainSize属性，List组件和每一个ListItemGroup组件都要通过childrenMainSize属性接口一对一绑定着一个ChildrenMainSize对象。<br/>（4）多列场景使用LazyForEach生成子组件时，需确保LazyForEach全部生成ListItemGroup组件或者全部生成ListItem组件。 431 432### maintainVisibleContentPosition<sup>12+</sup> 433 434maintainVisibleContentPosition(enabled: boolean) 435 436设置显示区域上方插入或删除数据时是否要保持可见内容位置不变。 437 438**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 439 440**系统能力：** SystemCapability.ArkUI.ArkUI.Full 441 442**参数：** 443 444| 参数名 | 类型 | 必填 | 说明 | 445| ------ | ------- | ---- | ------------------------------------------------------------ | 446| enabled | boolean | 是 | 设置显示区域上方插入或删除数据时是否要保持可见内容位置不变。<br/>默认值：false，显示区域上方插入或删除数据时可见内容位置会跟随变化。 true：显示区域上方插入或删除数据时可见内容位置不变。| 447 448> **说明：** 449> - 只有使用LazyForEach在显示区域外插入或删除数据时，才能保持可见内容位置不变。使用ForEach插入或删除数据或使用LazyForEach重新加载数据时，即使maintainVisibleContentPosition属性设置为true，可见区内容位置也会跟随变化。 450> - maintainVisibleContentPosition属性设置为true后，在显示区域上方插入或删除数据，会触发onDidScroll、onScrollIndex事件。 451> - maintainVisibleContentPosition属性设置为true后，在多列场景下，一次插入或删除整行数据，可以保持可见内容位置不变，如果不是插入或删除整行数据，可见内容位置还是会发生变化。 452 453## ListItemAlign<sup>9+</sup>枚举说明 454 455**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 456 457**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 458 459**系统能力：** SystemCapability.ArkUI.ArkUI.Full 460 461| 名称 | 值 | 说明 | 462| ------ | ------ | ------------------------- | 463| Start | 0 | ListItem在List中，交叉轴方向首部对齐。 | 464| Center | 1 | ListItem在List中，交叉轴方向居中对齐。 | 465| End | 2 | ListItem在List中，交叉轴方向尾部对齐。 | 466 467## StickyStyle<sup>9+</sup>枚举说明 468 469**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 470 471**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 472 473**系统能力：** SystemCapability.ArkUI.ArkUI.Full 474 475| 名称 | 值 | 说明 | 476| ------ | ------ | ---------------------------------- | 477| None | 0 | ListItemGroup的header不吸顶，footer不吸底。 | 478| Header | 1 | ListItemGroup的header吸顶，footer不吸底。 | 479| Footer | 2 | ListItemGroup的footer吸底，header不吸顶。 | 480 481## ScrollSnapAlign<sup>10+</sup>枚举说明 482 483设置列表项滚动结束对齐效果。 484 485左右和上下这种两端对齐的样式：当列表位移至末端，则需要将末端的item完整显示，同时不能露出边界空白区域，此时另一端可以出现不限位对齐的现象。 486 487只支持item等高场景限位，不等高场景可能存在不准确的情况。 488 489**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 490 491**系统能力：** SystemCapability.ArkUI.ArkUI.Full 492 493| 名称 | 值 | 说明 | 494| ------ | ------ | ---------------------------------------- | 495| NONE | 0 | 默认无项目滚动对齐效果。 | 496| START | 1 | 视图中的第一项将在列表的开头对齐。<br/>**说明：**<br/>当列表位移至末端，需要将末端的item完整显示，可能出现开头不对齐的情况。 | 497| CENTER | 2 | 视图中的中间项将在列表中心对齐。<br/>**说明：**<br/>顶端和末尾的item都可以在列表中心对齐，列表显示可能露出空白，<br/>第一个或最后一个item会对齐到中间位置。 | 498| END | 3 | 视图中的最后一项将在列表末尾对齐。<br/>**说明：**<br/>当列表位移至顶端，需要将顶端的item完整显示，可能出现末尾不对齐的情况。 | 499## CloseSwipeActionOptions<sup>11+</sup>对象说明 500 501收起[EXPANDED](ts-container-listitem.md#swipeactionstate11枚举说明)状态[ListItem](ts-container-listitem.md)回调事件集合，用于设置收起动画完成后回调事件。 502 503**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 504 505**系统能力：** SystemCapability.ArkUI.ArkUI.Full 506 507| 名称 | 类型 | 必填 | 说明 | 508| ------- | -------- | ---- | ---------------------- | 509| onFinish | ()=>void | 否 | 在收起动画完成后触发。 | 510 511## 事件 512 513除支持[通用事件](ts-component-general-events.md)和[滚动组件通用事件](ts-container-scrollable-common.md#事件)外，还支持以下事件： 514 515### onItemDelete<sup>(deprecated)</sup> 516 517onItemDelete(event: (index: number) => boolean) 518 519当List组件在编辑模式时，点击ListItem右边出现的删除按钮时触发。 520 521从API version9开始废弃不再使用，无替代接口。 522 523**系统能力：** SystemCapability.ArkUI.ArkUI.Full 524 525**参数：** 526 527| 参数名 | 类型 | 必填 | 说明 | 528| ------ | ------ | ---- | ------------------------ | 529| index | number | 是 | 被删除的列表项的索引值。 | 530 531**返回值：** 532 533| 类型 | 说明 | 534| ------- | -------------- | 535| boolean | 是否已经删除。 | 536 537### onScrollIndex 538 539onScrollIndex(event: (start: number, end: number, center: number) => void) 540 541有子组件划入或划出List显示区域时触发。计算索引值时，ListItemGroup作为一个整体占一个索引值，不计算ListItemGroup内部ListItem的索引值。 542 543List的边缘效果为弹簧效果时，在List划动到边缘继续划动和松手回弹过程不会触发onScrollIndex事件。 544 545触发该事件的条件：列表初始化时会触发一次，List显示区域内第一个子组件的索引值或最后一个子组件的索引值有变化时会触发。 546 547从API version 10开始，List显示区域中间位置子组件变化时也会触发该事件。 548 549**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 550 551**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 552 553**系统能力：** SystemCapability.ArkUI.ArkUI.Full 554 555**参数：** 556 557| 参数名 | 类型 | 必填 | 说明 | 558| -------------------- | ------ | ---- | -------------------------------------- | 559| start | number | 是 | List显示区域内第一个子组件的索引值 | 560| end | number | 是 | List显示区域内最后一个子组件的索引值。 | 561| center<sup>10+</sup> | number | 是 | List显示区域内中间位置子组件的索引值。 | 562 563### onReachStart 564 565onReachStart(event: () => void) 566 567列表到达起始位置时触发。 568 569List初始化时如果initialIndex为0会触发一次，List滚动到起始位置时触发一次。List边缘效果为弹簧效果时，划动经过起始位置时触发一次，回弹回起始位置时再触发一次。 570 571**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 572 573**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 574 575**系统能力：** SystemCapability.ArkUI.ArkUI.Full 576 577### onReachEnd 578 579onReachEnd(event: () => void) 580 581列表到底末尾位置时触发。 582 583List边缘效果为弹簧效果时，划动经过末尾位置时触发一次，回弹回末尾位置时再触发一次。 584 585**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 586 587**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 588 589**系统能力：** SystemCapability.ArkUI.ArkUI.Full 590 591### onScrollFrameBegin<sup>9+</sup> 592 593onScrollFrameBegin(event: (offset: number, state: ScrollState) => { offsetRemain: number }) 594 595列表开始滑动时触发，事件参数传入即将发生的滑动量，事件处理函数中可根据应用场景计算实际需要的滑动量并作为事件处理函数的返回值返回，列表将按照返回值的实际滑动量进行滑动。 596 597当listDirection的值为Axis.Vertical时，返回垂直方向滑动量，当listDirection的值为Axis.Horizontal时，返回水平方向滑动量。 598 599触发该事件的条件：手指拖动List、List惯性划动时每帧开始时触发；List超出边缘回弹、使用滚动控制器和拖动滚动条的滚动不会触发。 600 601**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 602 603**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 604 605**系统能力：** SystemCapability.ArkUI.ArkUI.Full 606 607**参数：** 608 609| 参数名 | 类型 | 必填 | 说明 | 610| ------ | ----------------------------------- | ---- | -------------------------- | 611| offset | number | 是 | 即将发生的滑动量，单位vp。 | 612| state | [ScrollState](#scrollstate枚举说明) | 是 | 当前滑动状态。 | 613 614**返回值：** 615 616| 类型 | 说明 | 617| ------------------------ | -------------------- | 618| { offsetRemain: number } | 实际滑动量，单位vp。 | 619 620### onScrollStart<sup>9+</sup> 621 622onScrollStart(event: () => void) 623 624列表滑动开始时触发。手指拖动列表或列表的滚动条触发的滑动开始时，会触发该事件。使用[Scroller](ts-container-scroll.md#scroller)滑动控制器触发的带动画的滑动，动画开始时会触发该事件 625 626**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 627 628**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 629 630**系统能力：** SystemCapability.ArkUI.ArkUI.Full 631 632### onScrollStop 633 634onScrollStop(event: () => void) 635 636列表滑动停止时触发。手拖动列表或列表的滚动条触发的滑动，手离开屏幕并且滑动停止时会触发该事件。使用[Scroller](ts-container-scroll.md#scroller)滑动控制器触发的带动画的滑动，动画停止会触发该事件。 637 638**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 639 640**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 641 642**系统能力：** SystemCapability.ArkUI.ArkUI.Full 643 644### onItemMove 645 646onItemMove(event: (from: number, to: number) => boolean) 647 648列表元素发生移动时触发。 649 650**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 651 652**系统能力：** SystemCapability.ArkUI.ArkUI.Full 653 654**参数：** 655 656| 参数名 | 类型 | 必填 | 说明 | 657| ------ | ------ | ---- | -------------- | 658| from | number | 是 | 移动前索引值。 | 659| to | number | 是 | 移动后索引值。 | 660 661**返回值：** 662 663| 类型 | 说明 | 664| ------- | -------------- | 665| boolean | 是否已经移动。 | 666 667### onItemDragStart<sup>8+</sup> 668 669onItemDragStart(event: (event: ItemDragInfo, itemIndex: number) => ((() => any) \| void)) 670 671开始拖拽列表元素时触发。 672 673**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 674 675**系统能力：** SystemCapability.ArkUI.ArkUI.Full 676 677**参数：** 678 679| 参数名 | 类型 | 必填 | 说明 | 680| --------- | --------------------------------------------------------- | ---- | ---------------------- | 681| event | [ItemDragInfo](ts-container-scrollable-common.md#itemdraginfo对象说明) | 是 | 拖拽点的信息。 | 682| itemIndex | number | 是 | 被拖拽列表元素索引值。 | 683 684### onItemDragEnter<sup>8+</sup> 685 686onItemDragEnter(event: (event: ItemDragInfo) => void) 687 688拖拽列表元素进入列表范围内时触发。 689 690**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 691 692**系统能力：** SystemCapability.ArkUI.ArkUI.Full 693 694**参数：** 695 696| 参数名 | 类型 | 必填 | 说明 | 697| ------ | --------------------------------------------------------- | ---- | -------------- | 698| event | [ItemDragInfo](ts-container-scrollable-common.md#itemdraginfo对象说明) | 是 | 拖拽点的信息。 | 699 700### onItemDragMove<sup>8+</sup> 701 702onItemDragMove(event: (event: ItemDragInfo, itemIndex: number, insertIndex: number) => void) 703 704拖拽列表元素在列表范围内移动时触发。 705 706**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 707 708**系统能力：** SystemCapability.ArkUI.ArkUI.Full 709 710**参数：** 711 712| 参数名 | 类型 | 必填 | 说明 | 713| ----------- | --------------------------------------------------------- | ---- | -------------- | 714| event | [ItemDragInfo](ts-container-scrollable-common.md#itemdraginfo对象说明) | 是 | 拖拽点的信息。 | 715| itemIndex | number | 是 | 拖拽起始位置。 | 716| insertIndex | number | 是 | 拖拽插入位置。 | 717 718### onItemDragLeave<sup>8+</sup> 719 720onItemDragLeave(event: (event: ItemDragInfo, itemIndex: number) => void) 721 722拖拽列表元素离开列表范围时触发。 723 724**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 725 726**系统能力：** SystemCapability.ArkUI.ArkUI.Full 727 728**参数：** 729 730| 参数名 | 类型 | 必填 | 说明 | 731| --------- | --------------------------------------------------------- | ---- | -------------------------- | 732| event | [ItemDragInfo](ts-container-scrollable-common.md#itemdraginfo对象说明) | 是 | 拖拽点的信息。 | 733| itemIndex | number | 是 | 拖拽离开的列表元素索引值。 | 734 735### onItemDrop<sup>8+</sup> 736 737onItemDrop(event: (event: ItemDragInfo, itemIndex: number, insertIndex: number, isSuccess: boolean) => void) 738 739绑定该事件的列表可作为拖拽释放目标，当在列表范围内停止拖拽时触发。 740 741跨List拖拽时，当拖拽释放的位置绑定了onItemDrop时会返回true，否则为false。List内部拖拽时，isSuccess为onItemMove事件的返回值。 742 743**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 744 745**系统能力：** SystemCapability.ArkUI.ArkUI.Full 746 747**参数：** 748 749| 参数名 | 类型 | 必填 | 说明 | 750| ----------- | --------------------------------------------------------- | ---- | -------------- | 751| event | [ItemDragInfo](ts-container-scrollable-common.md#itemdraginfo对象说明) | 是 | 拖拽点的信息。 | 752| itemIndex | number | 是 | 拖拽起始位置。 | 753| insertIndex | number | 是 | 拖拽插入位置。 | 754| isSuccess | boolean | 是 | 是否成功释放 | 755 756 757### onScroll<sup>(deprecated)</sup> 758onScroll(event: (scrollOffset: number, scrollState: [ScrollState](#scrollstate枚举说明)) => void) 759 760列表滑动时触发。 761 762从API version 12开始废弃不再使用，推荐使用[onDidScroll](ts-container-scrollable-common.md#ondidscroll12)事件替代。 763 764**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 765 766**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 767 768**系统能力：** SystemCapability.ArkUI.ArkUI.Full 769 770**参数：** 771| 参数名 | 类型 | 必填 | 说明 | 772| ------ | ------ | ------ | ------| 773| scrollOffset | number | 是 | 每帧滚动的偏移量，List的内容向上滚动时偏移量为正，向下滚动时偏移量为负。<br/>单位vp。 | 774| scrollState | [ScrollState](ts-container-list.md#scrollstate枚举说明) | 是 | 当前滑动状态。 | 775 776### onScrollVisibleContentChange<sup>12+</sup> 777onScrollVisibleContentChange(handler: OnScrollVisibleContentChangeCallback) 778 779有子组件划入或划出List显示区域时触发。计算触发条件时，每一个ListItem、ListItemGroup中的header或footer都算一个子组件。 780 781List的边缘效果为弹簧效果时，在List划动到边缘继续划动和松手回弹过程不会触发onScrollVisibleContentChange事件。 782 783触发该事件的条件：列表初始化时会触发一次，List显示区域内第一个子组件的索引值或最后一个子组件的索引值有变化时会触发。 784 785**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 786 787**系统能力：** SystemCapability.ArkUI.ArkUI.Full 788 789**参数：** 790 791| 参数名 | 类型 | 必填 | 说明 | 792| ------ | ------ | ------ | ------| 793| handler | [OnScrollVisibleContentChangeCallback](#onscrollvisiblecontentchangecallback12) | 是 | 当前显示内容发生改变的时候触发回调。 | 794 795## ScrollState枚举说明 796 797**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 798 799**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 800 801**系统能力：** SystemCapability.ArkUI.ArkUI.Full 802 803| 名称 | 值 | 说明 | 804| ------ | ------ | ---------------------------------------- | 805| Idle | 0 | 空闲状态。滚动状态回归空闲时触发，控制器提供的无动画方法控制滚动时触发。 | 806| Scroll | 1 | 滚动状态。手指拖动List，拖动滚动条和滚动鼠标滚轮时触发。| 807| Fling | 2 | 惯性滚动状态。动画控制的滚动都会触发。包括快速划动松手后的惯性滚动， <br/>划动到边缘回弹的滚动，快速拖动内置滚动条松手后的惯性滚动， <br/>使用滚动控制器提供的带动画的方法控制的滚动。 | 808 809 810## ListScroller<sup>11+</sup> 811 812List组件的滚动控制器，通过它控制List组件的滚动，仅支持一对一绑定到List组件。 813 814 815> **说明：** 816> 817> ListScroller继承自[Scroller](ts-container-scroll.md#scroller)，具有[Scroller](ts-container-scroll.md#scroller)的全部方法。 818 819 820### 导入对象 821 822``` 823listScroller: ListScroller = new ListScroller() 824``` 825 826 827### getItemRectInGroup<sup>11+</sup> 828 829getItemRectInGroup(index: number, indexInGroup: number): RectResult 830 831获取[ListItemGroup](ts-container-listitemgroup.md)中的[ListItem](ts-container-listitem.md)的大小和相对于List的位置。 832 833**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 834 835**系统能力：** SystemCapability.ArkUI.ArkUI.Full 836 837**参数：** 838 839| 参数名 | 类型 | 必填 | 说明 | 840| ----- | ------ | ---- | ----------------- | 841| index | number | 是 | ListItemGroup在List中的索引值。 | 842| indexInGroup | number | 是 | ListItem在ListItemGroup中的索引值。 | 843 844> **说明：** 845> 846> - index必须是当前显示区域显示的子组件的索引值，否则视index为非法值。 847> - 索引值为index的子组件必须是ListItemGroup，否则视index为非法值。 848> - indexInGroup必须是当前显示区域内ListItemGroup中显示的ListItem的索引值，否则视indexInGroup为非法值。 849> - index或者indexInGroup为非法值时返回的大小和位置均为0。 850 851**返回值：** 852 853| 类型 | 说明 | 854| ------------------- | -------- | 855| [RectResult](ts-types.md#rectresult10) | ListItemGroup中的ListItem的大小和相对于List的位置。<br/>单位：vp。 | 856 857 858**错误码**： 859 860以下错误码详细介绍请参考[通用错误码](../../errorcode-universal.md)。 861 862| 错误码ID | 错误信息 | 863| ------- | -------- | 864| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 865| 100004 | Controller not bound to component. | 866### getVisibleListContentInfo<sup>14+</sup> 867 868getVisibleListContentInfo(x:number, y: number): VisibleListContentInfo 869 870根据坐标获取子组件的索引信息。 871 872**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 873 874**系统能力：** SystemCapability.ArkUI.ArkUI.Full 875 876**参数：** 877 878| 参数名 | 类型 | 必填 | 说明 | 879| ----- | ------ | ---- | ----------------- | 880| x | number | 是 | x轴坐标，单位为vp。 | 881| y | number | 是 | y轴坐标，单位为vp。 | 882 883> **说明：** 884> 885> x或y为非法值时返回的 [VisibleListContentInfo](#visiblelistcontentinfo12对象说明)对象中index为-1，itemGroupArea返回undefined，itemIndexInGroup返回undefined。 886 887**返回值：** 888 889| 类型 | 说明 | 890| ------------------- | -------- | 891| [VisibleListContentInfo](#visiblelistcontentinfo12对象说明) | 获得子组件的索引信息。 | 892 893**错误码**： 894 895以下错误码详细介绍请参考[通用错误码](../../errorcode-universal.md)。 896 897| 错误码ID | 错误信息 | 898| ------- | -------- | 899| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 900| 100004 |The controller not bound to component.| 901### scrollToItemInGroup<sup>11+</sup> 902 903scrollToItemInGroup(index: number, indexInGroup: number, smooth?: boolean, align?: ScrollAlign): void 904 905滑动到指定的ListItemGroup中指定的ListItem。 906 907开启smooth动效时，会对经过的所有item进行加载和布局计算，当大量加载item时会导致性能问题。 908 909**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 910 911**系统能力：** SystemCapability.ArkUI.ArkUI.Full 912 913**参数：** 914 915| 参数名 | 类型 | 必填 | 说明 | 916| --------------------- | -------- | ---- | ------------------------------------------------------------ | 917| index | number | 是 | 要滑动到的目标元素所在的ListItemGroup在当前容器中的索引值。 <br/>**说明：** <br/>index值设置成负值或者大于当前容器子组件的最大索引值，视为异常值，本次跳转不生效。 | 918| indexInGroup | number | 是 | 要滑动到的目标元素在index指定的ListItemGroup中的索引值。 <br/>**说明：** <br/>indexInGroup值设置成负值或者大于index指定的ListItemGroup容器子组件的最大索引值，视为异常值，本次跳转不生效。| 919| smooth | boolean | 否 | 设置滑动到列表项在列表中的索引值时是否有动效，true表示有动效，false表示没有动效。<br/>默认值：false。 | 920| align | [ScrollAlign](ts-container-scroll.md#scrollalign10枚举说明) | 否 | 指定滑动到的元素与当前容器的对齐方式。<br/>默认值：ScrollAlign.START。 | 921 922**错误码**： 923 924以下错误码详细介绍请参考[通用错误码](../../errorcode-universal.md)。 925 926| 错误码ID | 错误信息 | 927| ------- | -------- | 928| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 929| 100004 | Controller not bound to component. | 930 931### closeAllSwipeActions<sup>11+</sup> 932 933closeAllSwipeActions(options?: [CloseSwipeActionOptions](#closeswipeactionoptions11对象说明)): void 934 935将[EXPANDED](ts-container-listitem.md#swipeactionstate11枚举说明)状态的[ListItem](ts-container-listitem.md)收起，并设置回调事件。 936 937**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 938 939**系统能力：** SystemCapability.ArkUI.ArkUI.Full 940 941**参数：** 942 943| 参数名 | 类型 | 必填 | 说明 | 944| ------- | ------------------------------------ | ---- | ----------------------------------------------- | 945| options | [CloseSwipeActionOptions](#closeswipeactionoptions11对象说明) | 否 | 收起[EXPANDED](ts-container-listitem.md#swipeactionstate11枚举说明)状态的[ListItem](ts-container-listitem.md)的回调事件集合。 | 946 947 948**错误码**： 949 950以下错误码详细介绍请参考[通用错误码](../../errorcode-universal.md)。 951 952| 错误码ID | 错误信息 | 953| ------- | -------- | 954| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 955| 100004 | Controller not bound to component. | 956 957> **说明：** 958> 959> - ListScroller必须绑定到List组件上。 960 961## OnScrollVisibleContentChangeCallback<sup>12+</sup> 962 963type OnScrollVisibleContentChangeCallback = (start: VisibleListContentInfo, end: VisibleListContentInfo) => void 964 965有子组件划入或划出List显示区域时触发。 966 967**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 968 969**系统能力：** SystemCapability.ArkUI.ArkUI.Full 970 971| 参数名 | 类型 | 必填 | 说明 | 972| ------ | ------ | ------ | ------| 973| start | [VisibleListContentInfo](#visiblelistcontentinfo12对象说明) | 是 | 当前显示界面第一个ListItem或ListItemGroup的详细信息。 | 974| end | [VisibleListContentInfo](#visiblelistcontentinfo12对象说明) | 是 | 当前显示界面最后一个ListItem或ListItemGroup的详细信息。 | 975 976## VisibleListContentInfo<sup>12+</sup>对象说明 977 978**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 979 980**系统能力：** SystemCapability.ArkUI.ArkUI.Full 981 982| 名称 | 类型 | 必填 | 说明 | 983| ------ | ------ | ------ | ------| 984| index | number | 是 | List显示区域内ListItem或ListItemGroup的索引值。 | 985| itemGroupArea | [ListItemGroupArea](#listitemgrouparea12枚举说明) | 否 | 如果当前可视页面的上边或下边在某个ListItemGroup之中，将会显示它所处的位置。 | 986| itemIndexInGroup | number | 否 | 如果当前可视页面的上边或下边在某个Group之中，将会显示Start或End的ListItem在Group中的索引。 | 987 988## ListItemGroupArea<sup>12+</sup>枚举说明 989 990**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 991 992**系统能力：** SystemCapability.ArkUI.ArkUI.Full 993 994| 名称 | 值 | 说明 | 995| ------ | ------ | ---------------------------------------- | 996| NONE | 0 | 当前页面可视边处于none位置。例如，ListItemGroup中既没有header、footer，也没有ListItem。 | 997| IN_LIST_ITEM_AREA | 1 | 当前页面可视边处于ListItem位置。 | 998| IN_HEADER_AREA | 2 | 当前页面可视边处于header位置。 | 999| IN_FOOTER_AREA | 3 | 当前页面可视边处于footer位置。 | 1000 1001## 示例 1002 1003### 示例1（添加滚动事件） 1004该示例实现了设置纵向列表，并在当前显示界面发生改变时回调索引。 1005```ts 1006// xxx.ets 1007@Entry 1008@Component 1009struct ListExample { 1010 private arr: number[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] 1011 1012 build() { 1013 Column() { 1014 List({ space: 20, initialIndex: 0 }) { 1015 ForEach(this.arr, (item: number) => { 1016 ListItem() { 1017 Text('' + item) 1018 .width('100%').height(100).fontSize(16) 1019 .textAlign(TextAlign.Center).borderRadius(10).backgroundColor(0xFFFFFF) 1020 } 1021 }, (item: string) => item) 1022 } 1023 .listDirection(Axis.Vertical) // 排列方向 1024 .scrollBar(BarState.Off) 1025 .friction(0.6) 1026 .divider({ strokeWidth: 2, color: 0xFFFFFF, startMargin: 20, endMargin: 20 }) // 每行之间的分界线 1027 .edgeEffect(EdgeEffect.Spring) // 边缘效果设置为Spring 1028 .onScrollIndex((firstIndex: number, lastIndex: number, centerIndex: number) => { 1029 console.info('first' + firstIndex) 1030 console.info('last' + lastIndex) 1031 console.info('center' + centerIndex) 1032 }) 1033 .onScrollVisibleContentChange((start: VisibleListContentInfo, end: VisibleListContentInfo) => { 1034 console.log(' start index: ' + start.index + 1035 ' start item group area: ' + start.itemGroupArea + 1036 ' start index in group: ' + start.itemIndexInGroup) 1037 console.log(' end index: ' + end.index + 1038 ' end item group area: ' + end.itemGroupArea + 1039 ' end index in group: ' + end.itemIndexInGroup) 1040 }) 1041 .onDidScroll((scrollOffset: number, scrollState: ScrollState) => { 1042 console.info(`onScroll scrollState = ScrollState` + scrollState + `, scrollOffset = ` + scrollOffset) 1043 }) 1044 .width('90%') 1045 } 1046 .width('100%') 1047 .height('100%') 1048 .backgroundColor(0xDCDCDC) 1049 .padding({ top: 5 }) 1050 } 1051} 1052``` 1053 1054 1055 1056 1057### 示例2（设置子元素对齐） 1058该示例展示了不同ListItemAlign枚举值下，List组件交叉轴方向子元素对齐效果。 1059 1060```ts 1061// xxx.ets 1062@Entry 1063@Component 1064struct ListLanesExample { 1065 @State arr: string[] = ["0", "1", "2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "12", "13", "14", "15", "16", "17", "18", "19"] 1066 @State alignListItem: ListItemAlign = ListItemAlign.Start 1067 1068 build() { 1069 Column() { 1070 List({ space: 20, initialIndex: 0 }) { 1071 ForEach(this.arr, (item: string) => { 1072 ListItem() { 1073 Text('' + item) 1074 .width('100%') 1075 .height(100) 1076 .fontSize(16) 1077 .textAlign(TextAlign.Center) 1078 .borderRadius(10) 1079 .backgroundColor(0xFFFFFF) 1080 } 1081 .border({ width: 2, color: Color.Green }) 1082 }, (item: string) => item) 1083 } 1084 .height(300) 1085 .width("90%") 1086 .friction(0.6) 1087 .border({ width: 3, color: Color.Red }) 1088 .lanes({ minLength: 40, maxLength: 40 }) 1089 .alignListItem(this.alignListItem) 1090 .scrollBar(BarState.Off) 1091 1092 Button("点击更改alignListItem:" + this.alignListItem).onClick(() => { 1093 if (this.alignListItem == ListItemAlign.Start) { 1094 this.alignListItem = ListItemAlign.Center 1095 } else if (this.alignListItem == ListItemAlign.Center) { 1096 this.alignListItem = ListItemAlign.End 1097 } else { 1098 this.alignListItem = ListItemAlign.Start 1099 } 1100 }) 1101 }.width('100%').height('100%').backgroundColor(0xDCDCDC).padding({ top: 5 }) 1102 } 1103} 1104``` 1105 1106 1107 1108 1109### 示例3（设置编辑模式） 1110该示例展示了如何设置当前List组件是否处于可编辑模式。 1111 1112```ts 1113// xxx.ets 1114@Entry 1115@Component 1116struct ListExample { 1117 @State arr: number[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] 1118 @State editFlag: boolean = false 1119 1120 build() { 1121 Stack({ alignContent: Alignment.TopStart }) { 1122 Column() { 1123 List({ space: 20, initialIndex: 0 }) { 1124 ForEach(this.arr, (item: number, index?: number) => { 1125 ListItem() { 1126 Flex({ direction: FlexDirection.Row, alignItems: ItemAlign.Center }) { 1127 Text('' + item) 1128 .width('100%') 1129 .height(80) 1130 .fontSize(20) 1131 .textAlign(TextAlign.Center) 1132 .borderRadius(10) 1133 .backgroundColor(0xFFFFFF) 1134 .flexShrink(1) 1135 if (this.editFlag) { 1136 Button() { 1137 Text("delete").fontSize(16) 1138 }.width('30%').height(40) 1139 .onClick(() => { 1140 if (index != undefined) { 1141 console.info(this.arr[index] + 'Delete') 1142 this.arr.splice(index, 1) 1143 console.info(JSON.stringify(this.arr)) 1144 this.editFlag = false 1145 } 1146 }).stateEffect(true) 1147 } 1148 } 1149 } 1150 }, (item: string) => item) 1151 }.width('90%') 1152 .scrollBar(BarState.Off) 1153 .friction(0.6) 1154 }.width('100%') 1155 1156 Button('edit list') 1157 .onClick(() => { 1158 this.editFlag = !this.editFlag 1159 }).margin({ top: 5, left: 20 }) 1160 }.width('100%').height('100%').backgroundColor(0xDCDCDC).padding({ top: 5 }) 1161 } 1162} 1163``` 1164 1165 1166 1167### 示例4（设置限位对齐） 1168该示例展示了List组件设置居中限位的实现效果。 1169 1170```ts 1171// xxx.ets 1172@Entry 1173@Component 1174struct ListExample { 1175 private arr: number[] = [] 1176 private scrollerForList: Scroller = new Scroller() 1177 1178 aboutToAppear() { 1179 for (let i = 0; i < 20; i++) { 1180 this.arr.push(i) 1181 } 1182 } 1183 build() { 1184 Column() { 1185 Row() { 1186 List({ space: 20, initialIndex: 3, scroller: this.scrollerForList }) { 1187 ForEach(this.arr, (item: number) => { 1188 ListItem() { 1189 Text('' + item) 1190 .width('100%').height(100).fontSize(16) 1191 .textAlign(TextAlign.Center) 1192 } 1193 .borderRadius(10).backgroundColor(0xFFFFFF) 1194 .width('60%') 1195 .height('80%') 1196 }, (item: number) => JSON.stringify(item)) 1197 } 1198 .chainAnimation(true) 1199 .edgeEffect(EdgeEffect.Spring) 1200 .listDirection(Axis.Horizontal) 1201 .height('100%') 1202 .width('100%') 1203 .scrollSnapAlign(ScrollSnapAlign.CENTER) 1204 .borderRadius(10) 1205 .backgroundColor(0xDCDCDC) 1206 } 1207 .width('100%') 1208 .height('100%') 1209 .backgroundColor(0xDCDCDC) 1210 .padding({ top: 10 }) 1211 } 1212 } 1213} 1214 1215``` 1216 1217 1218 1219### 示例5（跳转准确） 1220该示例通过设置childrenMainSize属性，实现了List在子组件高度不一致时调用scrollTo接口也可以跳转准确。 1221 1222如果配合状态管理V2使用，详情见：[List与makeObserved](../../../quick-start/arkts-v1-v2-migration.md#list)。 1223```ts 1224// xxx.ets 1225@Entry 1226@Component 1227struct ListExample { 1228 private arr: number[] = [] 1229 private scroller: ListScroller = new ListScroller() 1230 @State listSpace: number = 10 1231 @State listChildrenSize: ChildrenMainSize = new ChildrenMainSize(100) 1232 aboutToAppear(){ 1233 // 初始化数据源。 1234 for (let i = 0; i < 10; i++) { 1235 this.arr.push(i) 1236 } 1237 // 前5个item的主轴大小不是默认大小100，因此需要通过ChildrenMainSize通知List。 1238 this.listChildrenSize.splice(0, 5, [300, 300, 300, 300, 300]) 1239 } 1240 build() { 1241 Column() { 1242 List({ space: this.listSpace, initialIndex: 4, scroller: this.scroller }) { 1243 ForEach(this.arr, (item: number) => { 1244 ListItem() { 1245 Text('item-' + item) 1246 .height( item < 5 ? 300 : this.listChildrenSize.childDefaultSize) 1247 .width('90%') 1248 .fontSize(16) 1249 .textAlign(TextAlign.Center) 1250 .borderRadius(10) 1251 .backgroundColor(0xFFFFFF) 1252 } 1253 }, (item: string) => item) 1254 } 1255 .backgroundColor(Color.Gray) 1256 .layoutWeight(1) 1257 .scrollBar(BarState.On) 1258 .childrenMainSize(this.listChildrenSize) 1259 .alignListItem(ListItemAlign.Center) 1260 Row(){ 1261 Button() { Text('item size + 50') }.onClick(()=>{ 1262 this.listChildrenSize.childDefaultSize += 50 1263 }).height('50%').width('30%') 1264 Button() { Text('item size - 50') }.onClick(()=>{ 1265 if (this.listChildrenSize.childDefaultSize === 0) { 1266 return 1267 } 1268 this.listChildrenSize.childDefaultSize -= 50 1269 }).height('50%').width('30%') 1270 Button() { Text('scrollTo (0, 310)') }.onClick(()=>{ 1271 // 310: 跳转到item 1顶部与List顶部平齐的位置。 1272 // 如果不设置childrenMainSize，item高度不一致时scrollTo会不准确。 1273 this.scroller.scrollTo({xOffset: 0, yOffset: 310}) 1274 }).height('50%').width('30%') 1275 }.height('20%') 1276 } 1277 } 1278} 1279 1280``` 1281 1282 1283 1284### 示例6（获得子组件索引信息） 1285该示例展示了含有group时，获得List组件的Item索引相关信息。 1286```ts 1287// xxx.ets 1288@Entry 1289@Component 1290struct ListItemGroupExample { 1291 private timeTable: TimeTable[] = [ 1292 { 1293 title: '星期一', 1294 projects: ['语文', '数学', '英语'] 1295 }, 1296 { 1297 title: '星期二', 1298 projects: ['物理', '化学', '生物'] 1299 }, 1300 { 1301 title: '星期三', 1302 projects: ['历史', '地理', '政治'] 1303 }, 1304 { 1305 title: '星期四', 1306 projects: ['美术', '音乐', '体育'] 1307 } 1308 ] 1309 private scroller: ListScroller = new ListScroller() 1310 @State listIndexInfo: VisibleListContentInfo = {index: -1} 1311 @State mess:string = "null" 1312 @State itemBackgroundColorArr: boolean[] = [false] 1313 @Builder 1314 itemHead(text: string) { 1315 Text(text) 1316 .fontSize(20) 1317 .backgroundColor(0xAABBCC) 1318 .width("100%") 1319 .padding(10) 1320 } 1321 1322 @Builder 1323 itemFoot(num: number) { 1324 Text('共' + num + "节课") 1325 .fontSize(16) 1326 .backgroundColor(0xAABBCC) 1327 .width("100%") 1328 .padding(5) 1329 } 1330 1331 build() { 1332 Column() { 1333 List({ space: 20, scroller: this.scroller}) { 1334 ForEach(this.timeTable, (item: TimeTable, index: number) => { 1335 ListItemGroup({ header: this.itemHead(item.title), footer: this.itemFoot(item.projects.length) }) { 1336 ForEach(item.projects, (project: string, subIndex: number) => { 1337 ListItem() { 1338 Text(project) 1339 .width("100%") 1340 .height(100) 1341 .fontSize(20) 1342 .textAlign(TextAlign.Center) 1343 .backgroundColor(this.itemBackgroundColorArr[index *3 +subIndex] ? 0x68B4FF: 0xFFFFFF) 1344 } 1345 }, (item: string) => item) 1346 } 1347 .divider({ strokeWidth: 1, color: Color.Blue }) // 每行之间的分界线 1348 },(item: string) => item) 1349 } 1350 .width('90%') 1351 .sticky(StickyStyle.Header | StickyStyle.Footer) 1352 .scrollBar(BarState.Off) 1353 .gesture( 1354 PanGesture() 1355 .onActionUpdate((event: GestureEvent) => { 1356 if (event.fingerList[0] != undefined && event.fingerList[0].localX != undefined && event.fingerList[0].localY != undefined) { 1357 this.listIndexInfo = this.scroller.getVisibleListContentInfo(event.fingerList[0].localX, event.fingerList[0].localY) 1358 let itemIndex:string = 'undefined'; 1359 if (this.listIndexInfo.itemIndexInGroup != undefined ) { 1360 itemIndex = this.listIndexInfo.itemIndexInGroup.toString() 1361 if (this.listIndexInfo.index != undefined && this.listIndexInfo.index >= 0 && 1362 this.listIndexInfo.itemIndexInGroup >= 0 ) { 1363 this.itemBackgroundColorArr[this.listIndexInfo.index * 3 + this.listIndexInfo.itemIndexInGroup] = true; 1364 } 1365 } 1366 this.mess = 'index:' + this.listIndexInfo.index.toString() + ' itemIndex:' + itemIndex 1367 } 1368 })) 1369 .gesture( 1370 TapGesture({ count: 1 }) 1371 .onAction((event: GestureEvent) => { 1372 if (event) { 1373 this.itemBackgroundColorArr.splice(0,this.itemBackgroundColorArr.length); 1374 } 1375 }) 1376 ) 1377 Text('您当前位置Item索引为'+ this.mess) 1378 .fontColor(Color.Red) 1379 .height(50) 1380 }.width('100%').height('90%').backgroundColor(0xDCDCDC).padding({ top: 5 }) 1381 } 1382} 1383 1384interface TimeTable { 1385 title: string; 1386 projects: string[]; 1387} 1388 1389``` 1390 1391 1392 1393### 示例7（设置边缘渐隐） 1394该示例实现了List组件开启边缘渐隐效果并设置边缘渐隐长度。 1395 1396```ts 1397import { LengthMetrics } from '@kit.ArkUI' 1398@Entry 1399@Component 1400struct ListExample { 1401 private arr: number[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11] 1402 scrollerForList: Scroller = new Scroller() 1403 build() { 1404 Column() { 1405 1406 List({ space: 20, initialIndex: 0, scroller: this.scrollerForList }) { 1407 ForEach(this.arr, (item: number) => { 1408 ListItem() { 1409 Text('' + item) 1410 .width('100%').height(100).fontSize(16) 1411 .textAlign(TextAlign.Center).borderRadius(10).backgroundColor(0xFFFFFF) 1412 } 1413 }, (item: string) => item) 1414 } 1415 .fadingEdge(true,{fadingEdgeLength:LengthMetrics.vp(80)}) 1416 } 1417 .width('100%') 1418 .height('100%') 1419 .backgroundColor(0xDCDCDC) 1420 .padding({ top: 5 }) 1421 } 1422} 1423``` 1424 1425
