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