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