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