1# List 2 3<!--Kit: ArkUI--> 4<!--Subsystem: ArkUI--> 5<!--Owner: @yylong--> 6<!--Designer: @yylong--> 7<!--Tester: @liuzhenshuo--> 8<!--Adviser: @HelloCrease--> 9 10列表包含一系列相同宽度的列表项。适合连续、多行呈现同类数据，例如图片和文本。 11 12> **说明：** 13> 14> 该组件从API version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 15> 16> 组件内部已绑定手势实现跟手滚动等功能，需要增加自定义手势操作时请参考[手势拦截增强](ts-gesture-blocking-enhancement.md)进行处理。 17 18 19 20## 子组件 21 22仅支持[ListItem](ts-container-listitem.md)、[ListItemGroup](ts-container-listitemgroup.md)子组件和自定义组件。自定义组件在List下使用时，建议使用ListItem或ListItemGroup作为自定组件的顶层组件，不建议给自定义组件设置属性和事件方法。 23支持通过渲染控制类型（[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)）动态生成子组件，更推荐使用LazyForEach或Repeat以优化性能。 24 25> **说明：** 26> 27> 如果在处理大量子组件时遇到卡顿问题，请考虑采用懒加载、缓存列表项、动态预加载、组件复用和布局优化等方法来进行优化。最佳实践请参考[优化长列表加载慢丢帧问题](https://developer.huawei.com/consumer/cn/doc/best-practices/bpta-best-practices-long-list)。 28> 29> List的子组件的索引值计算规则： 30> 31> - 按子组件的顺序依次递增。 32> 33> - if/else语句中，只有条件成立的分支内的子组件会参与索引值计算，条件不成立的分支内子组件不计算索引值。 34> 35> - ForEach/LazyForEach/Repeat语句中，会计算展开所有子节点索引值。 36> 37> - [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)发生变化以后，会更新子节点索引值。 38> 39> - ListItemGroup作为一个整体计算一个索引值，ListItemGroup内部的ListItem不计算索引值。 40> 41> - List子组件visibility属性设置为Hidden或None依然会计算索引值。 42 43 44## 接口 45 46List(options?: [ListOptions](#listoptions18对象说明)) 47 48创建List列表容器。 49 50**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 51 52**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 53 54**系统能力：** SystemCapability.ArkUI.ArkUI.Full 55 56**参数：** 57 58| 参数名 | 类型 | 必填 | 说明 | 59| ------ | ---- | ---- | ---- | 60| options | [ListOptions](#listoptions18对象说明) | 否 | 设置List组件参数。 | 61 62## ListOptions<sup>18+</sup>对象说明 63 64用于设置List组件参数。 65 66> **说明：** 67> 68> 为规范匿名对象的定义，API 18版本修改了此处的元素定义。其中，保留了历史匿名对象的起始版本信息，会出现外层元素@since版本号高于内层元素版本号的情况，但这不影响接口的使用。 69 70**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。 71 72**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 73 74**系统能力：** SystemCapability.ArkUI.ArkUI.Full 75 76| 名称 | 类型 | 只读 | 可选 | 说明 | 77| ------------ | ------------------------------------------- | ---- | -- | ------------------------------------------------------------ | 78| initialIndex<sup>7+</sup> | number | 否 | 是 | 设置当前List初次加载时显示区域起始位置的item索引值。<br/>默认值：0<br/>**说明：** <br/>设置为负数或超过了当前List最后一个item的索引值时视为无效取值，无效取值按默认值显示。<br/>从API version 14开始，如果在List组件创建完成后首次布局前（如List的onAttach事件中），调用Scroller滚动控制器中不带动画的scrollToIndex或scrollEdge方法，会覆盖initialIndex设置的值。<br/>设置了initialIndex后，List从initialIndex对应的子组件开始布局，在这之前的子组件未参与布局，无法计算准确大小，因此通过[currentOffset](ts-container-scroll.md#currentoffset)接口获取到的List的滚动偏移量通过估算得出，可能会有误差。<br/>**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 79| 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开始，该接口支持在原子化服务中使用。| 80| scroller<sup>7+</sup> | [Scroller](ts-container-scroll.md#scroller) | 否 | 是 | 可滚动组件的控制器。与List绑定后，可以通过它控制List的滚动。<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开始，该接口支持在原子化服务中使用。 | 81 82## 属性 83 84除支持[通用属性](ts-component-general-attributes.md)和[滚动组件通用属性](ts-container-scrollable-common.md#属性)外，还支持以下属性： 85 86> **说明：** 87> 88> List组件[通用属性clip](ts-universal-attributes-sharp-clipping.md)的默认值为true。 89 90### listDirection 91 92listDirection(value: Axis) 93 94设置List组件排列方向。 95 96**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 97 98**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 99 100**系统能力：** SystemCapability.ArkUI.ArkUI.Full 101 102**参数：** 103 104| 参数名 | 类型 | 必填 | 说明 | 105| ------ | --------------------------------- | ---- | ------------------------------------------ | 106| value | [Axis](ts-appendix-enums.md#axis) | 是 | 组件的排列方向。<br/>默认值：Axis.Vertical | 107 108### divider 109 110divider(value: [ListDividerOptions](#listdivideroptions18对象说明) | null) 111 112设置ListItem分割线样式，默认无分割线。 113 114List的分割线画在主轴方向两个子组件之间，第一个子组件上方和最后一个子组件下方不会绘制分割线。 115 116多列模式下，ListItem与ListItem之间的分割线起始边距从每一列的交叉轴方向起始边开始计算，单列模式从List交叉轴方向起始边开始计算。 117 118ListItem设置[多态样式](ts-universal-attributes-polymorphic-style.md)时，被按压的子组件上下的分割线不绘制。 119 120**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 121 122**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 123 124**系统能力：** SystemCapability.ArkUI.ArkUI.Full 125 126**参数：** 127 128| 参数名 | 类型 | 必填 | 说明 | 129| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 130| value | [ListDividerOptions](#listdivideroptions18对象说明) \| null | 是 | ListItem分割线样式。<br/>默认值：null | 131 132### scrollBar 133 134scrollBar(value: BarState) 135 136设置滚动条状态。 137 138**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 139 140**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 141 142**系统能力：** SystemCapability.ArkUI.ArkUI.Full 143 144**参数：** 145 146| 参数名 | 类型 | 必填 | 说明 | 147| ------ | ----------------------------------------- | ---- | ------------------------------------------------------------ | 148| value | [BarState](ts-appendix-enums.md#barstate) | 是 | 滚动条状态。<br/>默认值：API version 9及以下版本默认值为BarState.Off，API version 10及以上版本的默认值为BarState.Auto。 | 149 150### cachedCount 151 152cachedCount(value: number) 153 154设置列表中ListItem/ListItemGroup的预加载数量，懒加载场景只会预加载List显示区域外上下各cachedCount行的ListItem，非懒加载场景会全部加载。懒加载、非懒加载都只布局List显示区域+List显示区域外cachedCount的内容。<!--Del-->具体使用可参考[减少应用白块说明](../../../performance/arkts-performance-improvement-recommendation.md#减少应用滑动白块)。<!--DelEnd--> 155 156List设置cachedCount后，显示区域外上下各会预加载并布局cachedCount行ListItem。计算ListItem行数时，会计算ListItemGroup内部的ListItem行数。如果ListItemGroup内没有ListItem，则整个ListItemGroup算一行。 157 158List下嵌套使用LazyForEach，并且LazyForEach下嵌套使用ListItemGroup时，LazyForEach会在List显示区域外上下各会创建cachedCount个ListItemGroup。 159 160**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 161 162**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 163 164**系统能力：** SystemCapability.ArkUI.ArkUI.Full 165 166**参数：** 167 168| 参数名 | 类型 | 必填 | 说明 | 169| ------ | ------ | ---- | ------------------------------------------------------------ | 170| value | number | 是 | ListItem/ListItemGroup的预加载数量。<br/>默认值：根据屏幕内显示的节点个数设置，最大值为16。<br/>取值范围：[0, +∞) | 171 172### cachedCount<sup>14+</sup> 173 174cachedCount(count: number, show: boolean) 175 176设置列表中ListItem/ListItemGroup的预加载数量，并配置是否显示预加载节点。 177 178List设置cachedCount后，显示区域外上下各会预加载并布局cachedCount行ListItem。计算ListItem行数时，会计算ListItemGroup内部的ListItem行数。如果ListItemGroup内没有ListItem，则整个ListItemGroup算一行。配合[裁剪](ts-universal-attributes-sharp-clipping.md#clip12)或[内容裁剪](ts-container-scrollable-common.md#clipcontent14)属性可以显示出预加载节点。 179 180> **说明：** 181> 182> 通常建议设置cachedCount=n/2（n代表一屏显示的列表项数量），同时需考虑其他因素以实现体验和内存使用的平衡。最佳实践请参考[优化长列表加载慢丢帧问题-缓存列表项](https://developer.huawei.com/consumer/cn/doc/best-practices/bpta-best-practices-long-list#section11667144010222)。 183 184 185**卡片能力：** 从API version 14开始，该接口支持在ArkTS卡片中使用。 186 187**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 188 189**系统能力：** SystemCapability.ArkUI.ArkUI.Full 190 191**参数：** 192 193| 参数名 | 类型 | 必填 | 说明 | 194| ------ | ------ | ---- | -------------------------------------- | 195| count | number | 是 | 预加载的ListItem的数量。<br/>默认值：根据屏幕内显示的节点个数设置，最大值为16。 <br/>取值范围：[0, +∞) | 196| show | boolean | 是 | 被预加载的ListItem是否需要显示。设置为true时显示预加载的ListItem，设置为false时不显示预加载的ListItem。 <br/> 默认值：false | 197 198### edgeEffect 199 200edgeEffect(value: EdgeEffect, options?: EdgeEffectOptions) 201 202设置边缘滑动效果。 203 204> **说明：** 205> 206> 当List组件的内容区小于一屏时，默认没有回弹效果。若要启用回弹效果，可以通过设置edgeEffect属性的options参数为{ alwaysEnabled: true }来实现。 207 208**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 209 210**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 211 212**系统能力：** SystemCapability.ArkUI.ArkUI.Full 213 214**参数：** 215 216| 参数名 | 类型 | 必填 | 说明 | 217| --------------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 218| value | [EdgeEffect](ts-appendix-enums.md#edgeeffect) | 是 | List组件的边缘滑动效果，支持弹簧效果和阴影效果。<br/>默认值：EdgeEffect.Spring| 219| options<sup>11+</sup> | [EdgeEffectOptions](ts-container-scrollable-common.md#edgeeffectoptions11对象说明) | 否 | 组件内容大小小于组件自身时，是否开启滑动效果。设置为{ alwaysEnabled: true }会开启滑动效果，{ alwaysEnabled: false }不开启。<br/>默认值：{ alwaysEnabled: false }| 220 221### chainAnimation 222 223chainAnimation(value: boolean) 224 225设置当前List是否启用链式联动动效。 226 227 228> **说明：** 229> 230> - 链式联动效果是指在手指划动过程中，手指拖动的ListItem是主动对象，相邻的ListItem为从动对象，主动对象驱动从动对象联动，驱动效果遵循弹簧物理动效。 231> - 链式动效的驱动效果体现在ListItem之间的间距上。静止状态下的间距可以通过List组件space参数设置，如果不设置space参数并且启用了链式动效，该间距默认为20vp。 232> - 链式动效启用后，List的分割线不显示。 233> - 链式动效生效的前提是List处于单列模式并且边缘效果为EdgeEffect.Spring类型。 234 235**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 236 237**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 238 239**系统能力：** SystemCapability.ArkUI.ArkUI.Full 240 241**参数：** 242 243| 参数名 | 类型 | 必填 | 说明 | 244| ------ | ------- | ---- | ------------------------------------------------------------ | 245| value | boolean | 是 | 是否启用链式联动动效。<br/>默认值：false，不启用链式联动。true，启用链式联动。 | 246 247### multiSelectable<sup>8+</sup> 248 249multiSelectable(value: boolean) 250 251设置是否开启鼠标框选。 252 253**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 254 255**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 256 257**系统能力：** SystemCapability.ArkUI.ArkUI.Full 258 259**参数：** 260 261| 参数名 | 类型 | 必填 | 说明 | 262| ------ | ------- | ---- | ------------------------------------------------------------ | 263| value | boolean | 是 | 是否开启鼠标框选。<br/>默认值：false，关闭框选。true，开启框选。 | 264 265### lanes<sup>9+</sup> 266 267lanes(value: number | LengthConstrain, gutter?: Dimension) 268 269设置List组件的布局列数或行数。gutter为列间距，当列数大于1时生效。 270 271规则如下： 272 273- lanes为指定的数量时，列宽由List组件的交叉轴尺寸除以列数得到。 274- lanes设置了{minLength，maxLength}时，根据List组件的宽度自适应决定lanes数量（即列数），保证缩放过程中lane的宽度符合{minLength，maxLength}的限制。其中，minLength条件会被优先满足，即优先保证ListItem的交叉轴尺寸符合最小限制。 275- lanes设置了{minLength，maxLength}，如果父组件交叉轴方向尺寸约束为无穷大时，固定按一列排列，List的列宽等于显示区域内最大的ListItem的列宽。 276- ListItemGroup在多列模式下也是独占一行，ListItemGroup中的ListItem按照List组件的lanes属性设置值来布局。 277- lanes设置了{minLength，maxLength}时，计算ListItemGroup中的列数时会按照ListItemGroup的交叉轴尺寸计算。当ListItemGroup交叉轴尺寸与List交叉轴尺寸不一致时ListItemGroup中的列数与List中的列数可能不一样。 278 279**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 280 281**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 282 283**系统能力：** SystemCapability.ArkUI.ArkUI.Full 284 285**参数：** 286 287| 参数名 | 类型 | 必填 | 说明 | 288| -------------------- | ------------------------------------------------------------ | ---- | ---------------------------------------- | 289| value | number \| [LengthConstrain](ts-types.md#lengthconstrain) | 是 | List组件的布局列数或行数。<br/>默认值：1 <br/>取值范围：[1, +∞)| 290| gutter<sup>10+</sup> | [Dimension](ts-types.md#dimension10) | 否 | 列间距。<br />默认值：0 <br/>取值范围：[0, +∞)| 291 292### alignListItem<sup>9+</sup> 293 294alignListItem(value: ListItemAlign) 295 296设置List交叉轴方向宽度大于ListItem交叉轴宽度 * lanes + (lanes - 1) * gutter时，ListItem在List交叉轴方向的布局方式。 297 298**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 299 300**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 301 302**系统能力：** SystemCapability.ArkUI.ArkUI.Full 303 304**参数：** 305 306| 参数名 | 类型 | 必填 | 说明 | 307| ------ | ---------------------------------------- | ---- | ------------------------------------------------------ | 308| value | [ListItemAlign](#listitemalign9枚举说明) | 是 | 交叉轴方向的布局方式。<br/>默认值：ListItemAlign.Start | 309 310### sticky<sup>9+</sup> 311 312sticky(value: StickyStyle) 313 314配合[ListItemGroup](ts-container-listitemgroup.md)组件使用，设置ListItemGroup中header是否要吸顶或footer是否要吸底。sticky属性可以设置为 StickyStyle.Header \| StickyStyle.Footer 以同时支持header吸顶和footer吸底。 315 316> **说明：** 317> 318> 由于浮点数计算精度，设置sticky后，在List滑动过程中小概率产生缝隙，可以通过[pixelRound](ts-universal-attributes-pixelRoundForComponent.md#pixelround)指定当前组件向下像素取整解决该问题。 319 320**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 321 322**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 323 324**系统能力：** SystemCapability.ArkUI.ArkUI.Full 325 326**参数：** 327 328| 参数名 | 类型 | 必填 | 说明 | 329| ------ | ------------------------------------ | ---- | ---------------------------------------------------------- | 330| value | [StickyStyle](#stickystyle9枚举说明) | 是 | ListItemGroup吸顶或吸底效果。<br/>默认值：StickyStyle.None | 331 332### scrollSnapAlign<sup>10+</sup> 333 334scrollSnapAlign(value: ScrollSnapAlign) 335 336设置列表项滚动结束对齐效果。 337 338只支持item等高场景限位，不等高场景可能存在不准确的情况。对齐动画期间onWillScroll事件上报的滚动操作来源类型为ScrollSource.FLING。 339 340**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 341 342**系统能力：** SystemCapability.ArkUI.ArkUI.Full 343 344**参数：** 345 346| 参数名 | 类型 | 必填 | 说明 | 347| ------ | --------------------------------------------- | ---- | --------------------------------------------------------- | 348| value | [ScrollSnapAlign](#scrollsnapalign10枚举说明) | 是 | 列表项滚动结束对齐效果。<br/>默认值：ScrollSnapAlign.NONE | 349 350### enableScrollInteraction<sup>10+</sup> 351 352enableScrollInteraction(value: boolean) 353 354设置是否支持滚动手势。 355 356**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 357 358**系统能力：** SystemCapability.ArkUI.ArkUI.Full 359 360**参数：** 361 362| 参数名 | 类型 | 必填 | 说明 | 363| ------ | ------- | ---- | ----------------------------------- | 364| value | boolean | 是 | 是否支持滚动手势。设置为true时可以通过手指或者鼠标滚动，设置为false时无法通过手指或者鼠标滚动，但不影响控制器[Scroller](ts-container-scroll.md#scroller)的滚动接口。<br/>默认值：true | 365 366> **说明：** 367> 368> 组件无法通过鼠标按下拖动操作进行滚动。 369 370### nestedScroll<sup>10+</sup> 371 372nestedScroll(value: NestedScrollOptions) 373 374设置前后两个方向的嵌套滚动模式，实现与父组件的滚动联动。 375 376**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 377 378**系统能力：** SystemCapability.ArkUI.ArkUI.Full 379 380**参数：** 381 382| 参数名 | 类型 | 必填 | 说明 | 383| ------ | ------------------------------------------------------------ | ---- | -------------- | 384| value | [NestedScrollOptions](ts-container-scrollable-common.md#nestedscrolloptions10对象说明) | 是 | 嵌套滚动选项。<br/>默认值：{ scrollForward: NestedScrollMode.SELF_ONLY, scrollBackward: NestedScrollMode.SELF_ONLY } | 385 386### friction<sup>10+</sup> 387 388friction(value: number | Resource) 389 390设置摩擦系数，手动划动滚动区域时生效，仅影响惯性滚动过程。设置为小于等于0的值时，按默认值处理。 391 392**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 393 394**系统能力：** SystemCapability.ArkUI.ArkUI.Full 395 396**参数：** 397 398| 参数名 | 类型 | 必填 | 说明 | 399| ------ | ---------------------------------------------------- | ---- | ------------------------------------------------------------ | 400| 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。 | 401 402### contentStartOffset<sup>11+</sup> 403 404contentStartOffset(value: number) 405 406设置内容区域起始偏移量。列表滚动到起始位置时，列表内容与列表显示区域边界保留指定距离。 407 408contentStartOffset + contentEndOffset超过List内容区长度后contentStartOffset和contentEndOffset会置0。 409 410**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 411 412**系统能力：** SystemCapability.ArkUI.ArkUI.Full 413 414**参数：** 415 416| 参数名 | 类型 | 必填 | 说明 | 417| ------ | ------ | ---- | ----------------------------------------------- | 418| value | number | 是 | 内容区域起始偏移量。<br/>默认值：0<br/>单位：vp <br/>**说明：**<br/>设置为负数时，按默认值处理。| 419 420### contentEndOffset<sup>11+</sup> 421 422contentEndOffset(value: number) 423 424设置内容区末尾偏移量。列表滚动到末尾位置时，列表内容与列表显示区域边界保留指定距离。 425 426contentStartOffset + contentEndOffset超过List内容区长度后contentStartOffset和contentEndOffset会置0。 427 428**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 429 430**系统能力：** SystemCapability.ArkUI.ArkUI.Full 431 432**参数：** 433 434| 参数名 | 类型 | 必填 | 说明 | 435| ------ | ------ | ---- | --------------------------------------------- | 436| value | number | 是 | 内容区末尾偏移量。<br/>默认值：0<br/>单位：vp <br/>**说明：**<br/>设置为负数时，按默认值处理。| 437 438### childrenMainSize<sup>12+</sup> 439 440childrenMainSize(value: ChildrenMainSize) 441 442设置List组件的子组件在主轴方向的大小信息。 443 444> **说明：** 445> - 该属性通过向List组件提供所有子组件在主轴方向的大小信息，确保在面对子组件主轴大小不一致、增删子组件、使用[scrollToIndex](ts-container-scroll.md#scrolltoindex)等场景时，List组件能够维护其滑动位置准确性。这样，[scrollTo](ts-container-scroll.md#scrollto)可以准确的跳转到指定位置，[currentOffset](ts-container-scroll.md#currentoffset)可以获取到当前准确的滑动位置，内置滚动条可以实现平滑移动无跳变。 446> - 当子组件是ListItemGroup时，需要根据ListItemGroup的列数、ListItemGroup中ListItem在主轴方向的间距以及ListItemGroup中header、footer和ListItem的大小，来准确计算出ListItemGroup在主轴方向的整体大小，并传递给List组件。 447> - 如果子组件有ListItemGroup，必须为每一个ListItemGroup设置[childrenMainSize](./ts-container-listitemgroup.md#childrenmainsize12)属性。List组件和每一个ListItemGroup组件都要通过childrenMainSize属性接口一对一绑定一个ChildrenMainSize对象。 448> - 多列场景使用LazyForEach生成子组件时，需确保LazyForEach全部生成ListItemGroup组件或者全部生成ListItem组件。 449 450**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 451 452**系统能力：** SystemCapability.ArkUI.ArkUI.Full 453 454**参数：** 455 456| 参数名 | 类型 | 必填 | 说明 | 457| ---------- | ------ | ---- | ------------------------------- | 458| value | [ChildrenMainSize](ts-container-scrollable-common.md#childrenmainsize12对象说明) | 是 | 该对象用来维护子组件在主轴方向的大小信息。| 459 460### maintainVisibleContentPosition<sup>12+</sup> 461 462maintainVisibleContentPosition(enabled: boolean) 463 464设置显示区域上方插入或删除数据时是否要保持可见内容位置不变。 465 466**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 467 468**系统能力：** SystemCapability.ArkUI.ArkUI.Full 469 470**参数：** 471 472| 参数名 | 类型 | 必填 | 说明 | 473| ------ | ------- | ---- | ------------------------------------------------------------ | 474| enabled | boolean | 是 | 设置显示区域上方插入或删除数据时是否要保持可见内容位置不变。<br/>默认值：false，显示区域上方插入或删除数据时可见内容位置会跟随变化。 true：显示区域上方插入或删除数据时可见内容位置不变。| 475 476> **说明：** 477> - 只有使用LazyForEach在显示区域外插入或删除数据时，属性设置为true才能保持可见内容位置不变。使用ForEach插入或删除数据、使用LazyForEach重新加载数据时，即使maintainVisibleContentPosition属性设置为true，可见区内容位置也会跟随变化。 478> - 从API version 20开始，使用[Repeat](../../../ui/state-management/arkts-new-rendering-control-repeat.md)在懒加载场景下，显示区域外插入或删除数据时，属性设置为true也能保持可见内容位置不变。 479> - maintainVisibleContentPosition属性设置为true后，在显示区域上方插入或删除数据，会触发onDidScroll、onScrollIndex事件。 480> - maintainVisibleContentPosition属性设置为true后，在多列场景下，一次插入或删除整行数据，可以保持可见内容位置不变，如果不是插入或删除整行数据，可见内容位置还是会发生变化。 481 482### stackFromEnd<sup>19+</sup> 483 484stackFromEnd(enabled: boolean) 485 486设置List组件是否从末尾开始布局。 487 488**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 489 490**系统能力：** SystemCapability.ArkUI.ArkUI.Full 491 492**参数：** 493 494| 参数名 | 类型 | 必填 | 说明 | 495| ------ | ------- | ---- | ------------------------------------------------------------ | 496| enabled | boolean | 是 | 设置List组件是否从末尾开始布局。<br/>默认值：false，List从顶部开始布局。 true：List组件从末尾开始布局。| 497 498> **说明：** 499> - stackFromEnd属性设置为true后，当List内容小于List组件高度时，内容底部对齐。 500> - stackFromEnd属性设置为true后，显示区域内有ListItem变高，或有插入ListItem，内容上方的ListItem往上移动。 501> - stackFromEnd属性设置为true后，[ListOptions](#listoptions18对象说明)中initialIndex参数默认值为总item个数-1。 502 503### focusWrapMode<sup>20+</sup> 504 505focusWrapMode(mode: Optional\<FocusWrapMode\>) 506 507设置方向键走焦模式。 508 509**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 510 511**系统能力：** SystemCapability.ArkUI.ArkUI.Full 512 513**参数：** 514 515| 参数名 | 类型 | 必填 | 说明 | 516| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 517| mode | Optional\<[FocusWrapMode](ts-appendix-enums.md#focuswrapmode20)\> | 是 | 交叉轴方向键走焦模式。<br/>默认值：FocusWrapMode.DEFAULT<br/>**说明：** <br/>异常值按默认值处理，即交叉轴方向键不能换行。 | 518 519### syncLoad<sup>20+</sup> 520 521syncLoad(enable: boolean) 522 523设置是否同步加载List区域内所有子组件。 524 525**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。 526 527**系统能力：** SystemCapability.ArkUI.ArkUI.Full 528 529**参数：** 530 531| 参数名 | 类型 | 必填 | 说明 | 532| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 533| enable | boolean | 是 | 是否同步加载List区域内所有子组件。<br/>true表示同步加载，false表示异步加载。默认值：true。<br/>**说明：** <br/>设置为false时，在首次显示、不带动画scrollToIndex跳转场景，若当帧布局耗时超过50ms，会将List区域内尚未布局的子组件延后到下一帧进行布局。 | 534 535### editMode<sup>(deprecated)</sup> 536 537editMode(value: boolean) 538 539设置当前List组件是否处于可编辑模式。可参考[示例3](#示例3设置编辑模式)实现删除选中的list项。 540 541从API version 9开始废弃不再使用，无替代接口。 542 543**系统能力：** SystemCapability.ArkUI.ArkUI.Full 544 545**参数：** 546 547| 参数名 | 类型 | 必填 | 说明 | 548| ------ | ------ | ---- | -------------------------------------------------- | 549| value | boolean | 是 | 当前List组件是否处于可编辑模式。<br/>默认值：false，当前List组件不处于可编辑模式。 | 550 551## ListItemAlign<sup>9+</sup>枚举说明 552 553设置子组件在List交叉轴方向的对齐方式。 554 555**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 556 557**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 558 559**系统能力：** SystemCapability.ArkUI.ArkUI.Full 560 561| 名称 | 值 | 说明 | 562| ------ | ------ | ------------------------- | 563| Start | 0 | ListItem在List中，交叉轴方向首部对齐。 | 564| Center | 1 | ListItem在List中，交叉轴方向居中对齐。 | 565| End | 2 | ListItem在List中，交叉轴方向尾部对齐。 | 566 567## StickyStyle<sup>9+</sup>枚举说明 568 569ListItemGroup吸顶或吸底效果枚举。 570 571**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 572 573**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 574 575**系统能力：** SystemCapability.ArkUI.ArkUI.Full 576 577| 名称 | 值 | 说明 | 578| ------ | ------ | ---------------------------------- | 579| None | 0 | ListItemGroup的header不吸顶，footer不吸底。 | 580| Header | 1 | ListItemGroup的header吸顶，footer不吸底。 | 581| Footer | 2 | ListItemGroup的footer吸底，header不吸顶。 | 582 583## ScrollSnapAlign<sup>10+</sup>枚举说明 584 585设置列表项滚动结束对齐效果。 586 587**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 588 589**系统能力：** SystemCapability.ArkUI.ArkUI.Full 590 591| 名称 | 值 | 说明 | 592| ------ | ------ | ---------------------------------------- | 593| NONE | 0 | 默认无项目滚动对齐效果。 | 594| START | 1 | 视图中的第一项将在列表的开头对齐。<br/>**说明：**<br/>当列表位移至末端，需要将末端的item完整显示，可能出现开头不对齐的情况。 | 595| CENTER | 2 | 视图中的中间项将在列表中心对齐。<br/>**说明：**<br/>顶端和末尾的item都可以在列表中心对齐，列表显示可能露出空白。 | 596| END | 3 | 视图中的最后一项将在列表末尾对齐。<br/>**说明：**<br/>当列表位移至顶端，需要将顶端的item完整显示，可能出现末尾不对齐的情况。 | 597## CloseSwipeActionOptions<sup>11+</sup>对象说明 598 599收起[EXPANDED](ts-container-listitem.md#swipeactionstate11枚举说明)状态[ListItem](ts-container-listitem.md)回调事件集合，用于设置收起动画完成后回调事件。 600 601**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 602 603**系统能力：** SystemCapability.ArkUI.ArkUI.Full 604 605| 名称 | 类型 | 只读 | 可选 | 说明 | 606| ------- | -------- | ---- | -- | ---------------------- | 607| onFinish | ()=>void | 否 | 是 | 在收起动画完成后触发。 | 608 609## ListDividerOptions<sup>18+</sup>对象说明 610 611用于设置List或ListItemGroup组件的分割线样式。 612 613> **说明：** 614> 615> 为规范匿名对象的定义，API 18版本修改了此处的元素定义。其中，保留了历史匿名对象的起始版本信息，会出现外层元素@since版本号高于内层元素版本号的情况，但这不影响接口的使用。 616 617**卡片能力：** 从API version 18开始，该接口支持在ArkTS卡片中使用。 618 619**原子化服务API：** 从API version 18开始，该接口支持在原子化服务中使用。 620 621**系统能力：** SystemCapability.ArkUI.ArkUI.Full 622 623| 名称 | 类型 | 只读 | 可选 | 说明 | 624| ------- | -------- | ---- | -- | ---------------------- | 625| strokeWidth<sup>7+</sup> | [Length](ts-types.md#length) | 否 | 否 | 分割线的线宽。<br/>单位：vp<br/>**说明：** <br/>设置为负数，百分比，或者大于等于List内容区长度时，按0处理。<br/>**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。| 626| color<sup>7+</sup> | [ResourceColor](ts-types.md#resourcecolor) | 否 | 是 | 分割线颜色。<br/>默认值：0x08000000<br/>**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。<br/>**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 | 627| 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开始，该接口支持在原子化服务中使用。| 628| 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开始，该接口支持在原子化服务中使用。| 629 630## 事件 631 632除支持[通用事件](ts-component-general-events.md)和[滚动组件通用事件](ts-container-scrollable-common.md#事件)外，还支持以下事件： 633 634### onScrollIndex 635 636onScrollIndex(event: (start: number, end: number, center: number) => void) 637 638有子组件划入或划出List显示区域时触发。计算索引值时，ListItemGroup作为一个整体占一个索引值，不计算ListItemGroup内部ListItem的索引值。 639 640List的边缘效果为弹簧效果时，在List划动到边缘继续划动和松手回弹过程不会触发onScrollIndex事件。 641 642触发该事件的条件：列表初始化时会触发一次，List显示区域内第一个子组件的索引值或最后一个子组件的索引值有变化时会触发。 643 644从API version 10开始，List显示区域中间位置子组件变化时也会触发该事件。 645 646**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 647 648**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 649 650**系统能力：** SystemCapability.ArkUI.ArkUI.Full 651 652**参数：** 653 654| 参数名 | 类型 | 必填 | 说明 | 655| -------------------- | ------ | ---- | -------------------------------------- | 656| start | number | 是 | List显示区域内第一个子组件的索引值 | 657| end | number | 是 | List显示区域内最后一个子组件的索引值。 | 658| center<sup>10+</sup> | number | 是 | List显示区域内中间位置子组件的索引值。 | 659 660### onReachStart 661 662onReachStart(event: () => void) 663 664列表到达起始位置时触发。 665 666List初始化时如果initialIndex为0会触发一次，List滚动到起始位置时触发一次。List边缘效果为弹簧效果时，划动经过起始位置时触发一次，回弹回起始位置时再触发一次。 667 668**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 669 670**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 671 672**系统能力：** SystemCapability.ArkUI.ArkUI.Full 673 674**参数：** 675 676| 参数名 | 类型 | 必填 | 说明 | 677| ------ | ------ | ------ | ------| 678| event | () => void | 是 | 列表到达起始位置时触发的回调。 | 679 680### onReachEnd 681 682onReachEnd(event: () => void) 683 684列表到达末尾位置时触发。不满一屏并且最后一个子组件末端在List内时触发。 685 686List边缘效果为弹簧效果时，划动经过末尾位置时触发一次，回弹回末尾位置时再触发一次。 687 688**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 689 690**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 691 692**系统能力：** SystemCapability.ArkUI.ArkUI.Full 693 694**参数：** 695 696| 参数名 | 类型 | 必填 | 说明 | 697| ------ | ------ | ------ | ------| 698| event | () => void | 是 | 列表到达末尾位置时触发的回调。 | 699 700### onScrollFrameBegin<sup>9+</sup> 701 702onScrollFrameBegin(event: OnScrollFrameBeginCallback) 703 704该接口回调时，事件参数传入即将发生的滑动量，事件处理函数中可根据应用场景计算实际需要的滑动量并作为事件处理函数的返回值返回，列表将按照返回值的实际滑动量进行滑动。 705 706当listDirection的值为Axis.Vertical时，返回垂直方向滑动量，当listDirection的值为Axis.Horizontal时，返回水平方向滑动量。 707 708满足以下任一条件时触发该事件： 709 7101. 用户交互（如手指滑动、键鼠操作等）触发滚动。 7112. List惯性滚动。 7123. 调用[fling](ts-container-scroll.md#fling12)接口触发滚动。 713 714不触发该事件的条件： 715 7161. 调用除[fling](ts-container-scroll.md#fling12)接口外的其他滚动控制接口。 7172. 越界回弹。 7183. 拖动滚动条。 719 720**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 721 722**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 723 724**系统能力：** SystemCapability.ArkUI.ArkUI.Full 725 726**参数：** 727 728| 参数名 | 类型 | 必填 | 说明 | 729| ------ | ----------------------------------- | ---- | -------------------------- | 730| event | [OnScrollFrameBeginCallback](ts-container-scroll.md#onscrollframebegincallback18) | 是 | 每帧滚动开始回调函数。 | 731 732### onScrollStart<sup>9+</sup> 733 734onScrollStart(event: () => void) 735 736列表滑动开始时触发。手指拖动列表或列表的滚动条触发的滑动开始时，会触发该事件。使用[Scroller](ts-container-scroll.md#scroller)滑动控制器触发的带动画的滑动，动画开始时会触发该事件。 737 738**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 739 740**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 741 742**系统能力：** SystemCapability.ArkUI.ArkUI.Full 743 744**参数：** 745 746| 参数名 | 类型 | 必填 | 说明 | 747| ------ | ------ | ------ | ------| 748| event | () => void | 是 | 列表滑动开始时触发的回调。 | 749 750### onScrollStop 751 752onScrollStop(event: () => void) 753 754列表滑动停止时触发。手拖动列表或列表的滚动条触发的滑动，手离开屏幕后滑动停止时会触发该事件。使用[Scroller](ts-container-scroll.md#scroller)滑动控制器触发的带动画的滑动，动画停止会触发该事件。 755 756**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 757 758**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 759 760**系统能力：** SystemCapability.ArkUI.ArkUI.Full 761 762**参数：** 763 764| 参数名 | 类型 | 必填 | 说明 | 765| ------ | ------ | ------ | ------| 766| event | () => void | 是 | 列表滑动停止时触发的回调。 | 767 768### onItemMove 769 770onItemMove(event: (from: number, to: number) => boolean) 771 772列表元素发生移动时触发。 773 774**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 775 776**系统能力：** SystemCapability.ArkUI.ArkUI.Full 777 778**参数：** 779 780| 参数名 | 类型 | 必填 | 说明 | 781| ------ | ------ | ---- | -------------- | 782| from | number | 是 | 移动前索引值。 | 783| to | number | 是 | 移动后索引值。 | 784 785**返回值：** 786 787| 类型 | 说明 | 788| ------- | -------------- | 789| boolean | 是否已经移动。返回值为true时列表元素发生移动，返回值为false时列表元素没有移动。 | 790 791### onItemDragStart<sup>8+</sup> 792 793onItemDragStart(event: (event: ItemDragInfo, itemIndex: number) => ((() => any) \| void)) 794 795开始拖拽列表元素时触发。 796 797**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 798 799**系统能力：** SystemCapability.ArkUI.ArkUI.Full 800 801**参数：** 802 803| 参数名 | 类型 | 必填 | 说明 | 804| --------- | --------------------------------------------------------- | ---- | ---------------------- | 805| event | [ItemDragInfo](ts-container-scrollable-common.md#itemdraginfo对象说明) | 是 | 拖拽点的信息。 | 806| itemIndex | number | 是 | 被拖拽列表元素索引值。 | 807 808### onItemDragEnter<sup>8+</sup> 809 810onItemDragEnter(event: (event: ItemDragInfo) => void) 811 812拖拽列表元素进入列表范围内时触发。 813 814**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 815 816**系统能力：** SystemCapability.ArkUI.ArkUI.Full 817 818**参数：** 819 820| 参数名 | 类型 | 必填 | 说明 | 821| ------ | --------------------------------------------------------- | ---- | -------------- | 822| event | [ItemDragInfo](ts-container-scrollable-common.md#itemdraginfo对象说明) | 是 | 拖拽点的信息。 | 823 824### onItemDragMove<sup>8+</sup> 825 826onItemDragMove(event: (event: ItemDragInfo, itemIndex: number, insertIndex: number) => void) 827 828拖拽列表元素在列表范围内移动时触发。 829 830**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 831 832**系统能力：** SystemCapability.ArkUI.ArkUI.Full 833 834**参数：** 835 836| 参数名 | 类型 | 必填 | 说明 | 837| ----------- | --------------------------------------------------------- | ---- | -------------- | 838| event | [ItemDragInfo](ts-container-scrollable-common.md#itemdraginfo对象说明) | 是 | 拖拽点的信息。 | 839| itemIndex | number | 是 | 拖拽起始位置。 | 840| insertIndex | number | 是 | 拖拽插入位置。 | 841 842### onItemDragLeave<sup>8+</sup> 843 844onItemDragLeave(event: (event: ItemDragInfo, itemIndex: number) => void) 845 846拖拽列表元素离开列表范围时触发。 847 848**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 849 850**系统能力：** SystemCapability.ArkUI.ArkUI.Full 851 852**参数：** 853 854| 参数名 | 类型 | 必填 | 说明 | 855| --------- | --------------------------------------------------------- | ---- | -------------------------- | 856| event | [ItemDragInfo](ts-container-scrollable-common.md#itemdraginfo对象说明) | 是 | 拖拽点的信息。 | 857| itemIndex | number | 是 | 拖拽离开的列表元素索引值。 | 858 859### onItemDrop<sup>8+</sup> 860 861onItemDrop(event: (event: ItemDragInfo, itemIndex: number, insertIndex: number, isSuccess: boolean) => void) 862 863绑定该事件的列表可作为拖拽释放目标，当在列表范围内停止拖拽时触发。 864 865跨List拖拽时，当拖拽释放的位置绑定了onItemDrop时isSuccess为true，否则为false。List内部拖拽时，isSuccess为onItemMove事件的返回值。 866 867**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 868 869**系统能力：** SystemCapability.ArkUI.ArkUI.Full 870 871**参数：** 872 873| 参数名 | 类型 | 必填 | 说明 | 874| ----------- | --------------------------------------------------------- | ---- | -------------- | 875| event | [ItemDragInfo](ts-container-scrollable-common.md#itemdraginfo对象说明) | 是 | 拖拽点的信息。 | 876| itemIndex | number | 是 | 拖拽起始位置。 | 877| insertIndex | number | 是 | 拖拽插入位置。 | 878| isSuccess | boolean | 是 | 是否成功释放。返回值为true时列表元素成功释放，返回值为false时列表元素没有成功释放。 | 879 880### onScrollVisibleContentChange<sup>12+</sup> 881onScrollVisibleContentChange(handler: OnScrollVisibleContentChangeCallback) 882 883有子组件划入或划出List显示区域时触发。计算触发条件时，每一个ListItem、ListItemGroup中的header或footer都算一个子组件。 884 885List的边缘效果为弹簧效果时，在List划动到边缘继续划动和松手回弹过程不会触发onScrollVisibleContentChange事件。 886 887触发该事件的条件：列表初始化时会触发一次，List显示区域内第一个子组件的索引值或最后一个子组件的索引值有变化时会触发。 888 889**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 890 891**系统能力：** SystemCapability.ArkUI.ArkUI.Full 892 893**参数：** 894 895| 参数名 | 类型 | 必填 | 说明 | 896| ------ | ------ | ------ | ------| 897| handler | [OnScrollVisibleContentChangeCallback](#onscrollvisiblecontentchangecallback12) | 是 | 当前显示内容发生改变的时候触发回调。 | 898 899### onItemDelete<sup>(deprecated)</sup> 900 901onItemDelete(event: (index: number) => boolean) 902 903当List组件在编辑模式时，点击ListItem右边出现的删除按钮时触发。 904 905从API version 9开始废弃不再使用，无替代接口。 906 907**系统能力：** SystemCapability.ArkUI.ArkUI.Full 908 909**参数：** 910 911| 参数名 | 类型 | 必填 | 说明 | 912| ------ | ------ | ---- | ------------------------ | 913| index | number | 是 | 被删除的列表项的索引值。 | 914 915**返回值：** 916 917| 类型 | 说明 | 918| ------- | -------------- | 919| boolean | 是否已经删除。 | 920 921### onScroll<sup>(deprecated)</sup> 922onScroll(event: (scrollOffset: number, scrollState: [ScrollState](#scrollstate枚举说明)) => void) 923 924列表滑动时触发。 925 926从API version 12开始废弃不再使用，推荐使用[onDidScroll](ts-container-scrollable-common.md#ondidscroll12)事件替代。 927 928**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 929 930**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 931 932**系统能力：** SystemCapability.ArkUI.ArkUI.Full 933 934**参数：** 935| 参数名 | 类型 | 必填 | 说明 | 936| ------ | ------ | ------ | ------| 937| scrollOffset | number | 是 | 每帧滚动的偏移量，List的内容向上滚动时偏移量为正，向下滚动时偏移量为负。<br/>单位vp。 | 938| scrollState | [ScrollState](ts-container-list.md#scrollstate枚举说明) | 是 | 当前滑动状态。 | 939 940## ScrollState枚举说明 941 942滑动状态枚举。 943 944**卡片能力：** 从API version 9开始，该接口支持在ArkTS卡片中使用。 945 946**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。 947 948**系统能力：** SystemCapability.ArkUI.ArkUI.Full 949 950| 名称 | 值 | 说明 | 951| ------ | ------ | ---------------------------------------- | 952| Idle | 0 | 空闲状态。滚动状态回归空闲时触发，控制器提供的无动画方法控制滚动时触发。 | 953| Scroll | 1 | 滚动状态。手指拖动List，拖动滚动条和滚动鼠标滚轮时触发。| 954| Fling | 2 | 惯性滚动状态。动画控制的滚动都会触发。包括快速划动松手后的惯性滚动， <br/>划动到边缘回弹的滚动，快速拖动内置滚动条松手后的惯性滚动， <br/>使用滚动控制器提供的带动画的方法控制的滚动。 | 955 956 957## ListScroller<sup>11+</sup> 958 959List组件的滚动控制器，通过它控制List组件的滚动，仅支持一对一绑定到List组件。 960 961**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 962 963**系统能力：** SystemCapability.ArkUI.ArkUI.Full 964 965> **说明：** 966> 967> ListScroller继承自[Scroller](ts-container-scroll.md#scroller)，具有[Scroller](ts-container-scroll.md#scroller)的全部方法。 968 969 970### 导入对象 971 972``` 973listScroller: ListScroller = new ListScroller(); 974``` 975 976 977### getItemRectInGroup<sup>11+</sup> 978 979getItemRectInGroup(index: number, indexInGroup: number): RectResult 980 981获取[ListItemGroup](ts-container-listitemgroup.md)中的[ListItem](ts-container-listitem.md)的大小和相对于List的位置。 982 983**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 984 985**系统能力：** SystemCapability.ArkUI.ArkUI.Full 986 987**参数：** 988 989| 参数名 | 类型 | 必填 | 说明 | 990| ----- | ------ | ---- | ----------------- | 991| index | number | 是 | ListItemGroup在List中的索引值。 | 992| indexInGroup | number | 是 | ListItem在ListItemGroup中的索引值。 | 993 994> **说明：** 995> 996> - index必须是当前显示区域显示的子组件的索引值，否则视index为非法值。 997> - 索引值为index的子组件必须是ListItemGroup，否则视index为非法值。 998> - indexInGroup必须是当前显示区域内ListItemGroup中显示的ListItem的索引值，否则视indexInGroup为非法值。 999> - index或者indexInGroup为非法值时返回的大小和位置均为0。 1000 1001**返回值：** 1002 1003| 类型 | 说明 | 1004| ------------------- | -------- | 1005| [RectResult](ts-universal-attributes-on-child-touch-test.md#rectresult) | ListItemGroup中的ListItem的大小和相对于List的位置。<br/>单位：vp。 | 1006 1007 1008**错误码**： 1009 1010以下错误码详细介绍请参考[通用错误码](../../errorcode-universal.md)和[滚动类组件错误码](../errorcode-scroll.md)。 1011 1012| 错误码ID | 错误信息 | 1013| ------- | -------- | 1014| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 1015| 100004 | Controller not bound to component. | 1016### getVisibleListContentInfo<sup>14+</sup> 1017 1018getVisibleListContentInfo(x: number, y: number): VisibleListContentInfo 1019 1020根据坐标获取子组件的索引信息。 1021 1022**原子化服务API：** 从API version 14开始，该接口支持在原子化服务中使用。 1023 1024**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1025 1026**参数：** 1027 1028| 参数名 | 类型 | 必填 | 说明 | 1029| ----- | ------ | ---- | ----------------- | 1030| x | number | 是 | x轴坐标，单位为vp。 | 1031| y | number | 是 | y轴坐标，单位为vp。 | 1032 1033**返回值：** 1034 1035| 类型 | 说明 | 1036| ------------------- | -------- | 1037| [VisibleListContentInfo](#visiblelistcontentinfo12对象说明) | 入参坐标处的子组件的索引信息。| 1038 1039> **说明：** 1040> 1041> - 入参坐标(x, y)的基准点是List组件的位置。 1042> - 如果该坐标位置处于ListItem范围内，且该ListItem父组件是List，则返回值对象成员index为该ListItem在List中的索引值，itemGroupArea返回undefined，itemIndexInGroup返回undefined。 1043> - 如果该坐标位置处于ListItem范围内，且该ListItem父组件是ListItemGroup，则返回值对象成员index为该ListItemGroup在List中的索引值，itemGroupArea返回ListItemGroupArea.IN_LIST_ITEM_AREA，itemIndexInGroup返回该ListItem在ListItemGroup中的索引值。 1044> - 如果该坐标位置不处于ListItem范围内，但是处于ListItemGroup的header或者footer范围内，则返回值对象成员index为该ListItemGroup在List中的索引值，itemIndexInGroup返回undefined。如果坐标位置处于header范围，itemGroupArea返回ListItemGroupArea.IN_HEADER_AREA。如果坐标位置处于footer范围，itemGroupArea返回ListItemGroupArea.IN_FOOTER_AREA。 1045> - 如果该坐标位置既不处于ListItem范围内，也不处于ListItemGroup的header或者footer范围内，但是处于ListItemGroup的范围内，则返回值对象成员index为该ListItemGroup在List中的索引值，itemIndexInGroup返回undefined，itemGroupArea返回ListItemGroupArea.NONE。 1046> - 如果该坐标位置既不处于ListItem范围内，也不处于ListItemGroup的范围内，则返回值对象成员index为-1，itemIndexInGroup返回undefined，itemGroupArea返回undefined。 1047 1048**错误码**： 1049 1050以下错误码详细介绍请参考[通用错误码](../../errorcode-universal.md)和[滚动类组件错误码](../errorcode-scroll.md)。 1051 1052| 错误码ID | 错误信息 | 1053| ------- | -------- | 1054| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 1055| 100004 |The controller not bound to component.| 1056### scrollToItemInGroup<sup>11+</sup> 1057 1058scrollToItemInGroup(index: number, indexInGroup: number, smooth?: boolean, align?: ScrollAlign): void 1059 1060滑动到指定的ListItemGroup中指定的ListItem。 1061 1062**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1063 1064**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1065 1066**参数：** 1067 1068| 参数名 | 类型 | 必填 | 说明 | 1069| --------------------- | -------- | ---- | ------------------------------------------------------------ | 1070| index | number | 是 | 要滑动到的目标元素所在的ListItemGroup在当前容器中的索引值。 <br/>**说明：** <br/>index值设置成负值或者大于当前容器子组件的最大索引值，视为异常值，本次跳转不生效。 | 1071| indexInGroup | number | 是 | 要滑动到的目标元素在index指定的ListItemGroup中的索引值。 <br/>**说明：** <br/>indexInGroup值设置成负值或者大于index指定的ListItemGroup容器子组件的最大索引值，视为异常值，本次跳转不生效。| 1072| smooth | boolean | 否 | 设置该次滑动是否有动效，true表示有动效，false表示没有动效。<br/>默认值：false<br/>**说明：** <br/>开启动效时，会对经过的所有item进行加载和布局计算，当大量加载item时会导致性能问题。 | 1073| align | [ScrollAlign](ts-container-scroll.md#scrollalign10枚举说明) | 否 | 指定滑动到的元素与当前容器的对齐方式。<br/>默认值：ScrollAlign.START。 | 1074 1075**错误码**： 1076 1077以下错误码详细介绍请参考[通用错误码](../../errorcode-universal.md)和[滚动类组件错误码](../errorcode-scroll.md)。 1078 1079| 错误码ID | 错误信息 | 1080| ------- | -------- | 1081| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 1082| 100004 | Controller not bound to component. | 1083 1084### closeAllSwipeActions<sup>11+</sup> 1085 1086closeAllSwipeActions(options?: CloseSwipeActionOptions): void 1087 1088将[EXPANDED](ts-container-listitem.md#swipeactionstate11枚举说明)状态的[ListItem](ts-container-listitem.md)收起，并设置回调事件。 1089 1090**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1091 1092**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1093 1094**参数：** 1095 1096| 参数名 | 类型 | 必填 | 说明 | 1097| ------- | ------------------------------------ | ---- | ----------------------------------------------- | 1098| options | [CloseSwipeActionOptions](#closeswipeactionoptions11对象说明) | 否 | 收起[EXPANDED](ts-container-listitem.md#swipeactionstate11枚举说明)状态的[ListItem](ts-container-listitem.md)的回调事件集合。 | 1099 1100 1101**错误码**： 1102 1103以下错误码详细介绍请参考[通用错误码](../../errorcode-universal.md)和[滚动类组件错误码](../errorcode-scroll.md)。 1104 1105| 错误码ID | 错误信息 | 1106| ------- | -------- | 1107| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameters types; 3. Parameter verification failed. | 1108| 100004 | Controller not bound to component. | 1109 1110> **说明：** 1111> 1112> - ListScroller必须绑定到List组件上。 1113 1114## OnScrollVisibleContentChangeCallback<sup>12+</sup> 1115 1116type OnScrollVisibleContentChangeCallback = (start: VisibleListContentInfo, end: VisibleListContentInfo) => void 1117 1118有子组件划入或划出List显示区域时触发。 1119 1120start和end的index同时返回-1，代表List从有数据变成空的List。 1121 1122start和end的index同时返回0，代表List内只有一个子组件。 1123 1124**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1125 1126**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1127 1128**参数：** 1129 1130| 参数名 | 类型 | 必填 | 说明 | 1131| ------ | ------ | ------ | ------| 1132| start | [VisibleListContentInfo](#visiblelistcontentinfo12对象说明) | 是 | 1. 通过该参数获取List显示区域第一个子组件在List中的索引值。<br/>2. 如果当前List显示区域第一个子组件是ListItemGroup，可以获取当前List显示区域第一个组件属于该ListItemGroup的哪一区域。<br/>3. 如果当前List显示区域第一个组件是ListItemGroup内的ListItem，可以获取该ListItem在ListItemGroup内的索引值。 | 1133| end | [VisibleListContentInfo](#visiblelistcontentinfo12对象说明) | 是 | 1. 通过该参数获取List显示区域最后一个子组件在List中的索引值。<br/>2. 如果当前List显示区域最后一个子组件是ListItemGroup，可以获取当前List显示区域最后一个组件属于该ListItemGroup的哪一区域。<br/>3. 如果当前List显示区域最后一个组件是ListItemGroup内的ListItem，可以获取该ListItem在ListItemGroup内的索引值。 | 1134 1135## VisibleListContentInfo<sup>12+</sup>对象说明 1136 1137用于表示List可见内容区子组件的详细信息。 1138 1139**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1140 1141**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1142 1143| 名称 | 类型 | 只读 | 可选 | 说明 | 1144| ------ | ------ | -- | ------ | ------| 1145| index | number | 否 | 否 | 表示ListItem或ListItemGroup在List中的索引值。 | 1146| itemGroupArea | [ListItemGroupArea](#listitemgrouparea12枚举说明) | 否 | 是 | 表示处于ListItemGroup的哪一个区域。 | 1147| itemIndexInGroup | number | 否 | 是 | 表示ListItem在ListItemGroup中的索引值。 | 1148 1149## ListItemGroupArea<sup>12+</sup>枚举说明 1150 1151枚举了ListItemGroup各个区域。 1152 1153**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1154 1155**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1156 1157| 名称 | 值 | 说明 | 1158| ------ | ------ | ---------------------------------------- | 1159| NONE | 0 | ListItemGroup内部ListItem区域、header区域以及footer区域以外的区域。 | 1160| IN_LIST_ITEM_AREA | 1 | ListItemGroup内部ListItem区域。 | 1161| IN_HEADER_AREA | 2 | ListItemGroup内部header区域。 | 1162| IN_FOOTER_AREA | 3 | ListItemGroup内部footer区域。 | 1163 1164## UIListEvent<sup>19+</sup> 1165frameNode中[getEvent('List')](../js-apis-arkui-frameNode.md#geteventlist19)方法的返回值，可用于给List节点设置滚动事件。 1166 1167UIListEvent继承于[UIScrollableCommonEvent](./ts-container-scrollable-common.md#uiscrollablecommonevent19)。 1168 1169### setOnWillScroll<sup>19+</sup> 1170 1171setOnWillScroll(callback: OnWillScrollCallback | undefined): void 1172 1173设置[onWillScroll](./ts-container-scrollable-common.md#onwillscroll12)事件的回调。 1174 1175方法入参为undefined时，会重置事件回调。 1176 1177**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 1178 1179**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1180 1181**参数：** 1182 1183| 参数名 | 类型 | 必填 | 说明 | 1184| ------ | ------ | ---- | -------------------------- | 1185| callback | [OnWillScrollCallback](./ts-container-scrollable-common.md#onwillscrollcallback12) \| undefined | 是 | onWillScroll事件的回调函数。 | 1186 1187### setOnDidScroll<sup>19+</sup> 1188 1189setOnDidScroll(callback: OnScrollCallback | undefined): void 1190 1191设置[onDidScroll](./ts-container-scrollable-common.md#ondidscroll12)事件的回调。 1192 1193方法入参为undefined时，会重置事件回调。 1194 1195**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 1196 1197**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1198 1199**参数：** 1200 1201| 参数名 | 类型 | 必填 | 说明 | 1202| ------ | ------ | ---- | -------------------------- | 1203| callback | [OnScrollCallback](./ts-container-scrollable-common.md#onscrollcallback12) \| undefined | 是 | onDidScroll事件的回调函数。 | 1204 1205### setOnScrollIndex<sup>19+</sup> 1206 1207setOnScrollIndex(callback: OnListScrollIndexCallback | undefined): void 1208 1209设置[onScrollIndex](#onscrollindex)事件的回调。 1210 1211方法入参为undefined时，会重置事件回调。 1212 1213**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 1214 1215**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1216 1217**参数：** 1218 1219| 参数名 | 类型 | 必填 | 说明 | 1220| ------ | ------ | ---- | -------------------------- | 1221| callback | [OnListScrollIndexCallback](#onlistscrollindexcallback19) \| undefined | 是 | onScrollIndex事件的回调函数。 | 1222 1223### setOnScrollVisibleContentChange<sup>19+</sup> 1224 1225setOnScrollVisibleContentChange(callback: OnScrollVisibleContentChangeCallback | undefined): void 1226 1227设置[onScrollVisibleContentChange](#onscrollvisiblecontentchange12)事件的回调。 1228 1229方法入参为undefined时，会重置事件回调。 1230 1231**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 1232 1233**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1234 1235**参数：** 1236 1237| 参数名 | 类型 | 必填 | 说明 | 1238| ------ | ------ | ---- | -------------------------- | 1239| callback | [OnScrollVisibleContentChangeCallback](./ts-container-list.md#onscrollvisiblecontentchangecallback12) \| undefined | 是 | onScrollVisibleContentChange事件的回调函数。 | 1240 1241## OnListScrollIndexCallback<sup>19+</sup> 1242type OnListScrollIndexCallback = (start: number, end: number, center: number) => void 1243 1244List组件可见区域item变化事件的回调类型。 1245 1246**卡片能力：** 从API version 19开始，该接口支持在ArkTS卡片中使用。 1247 1248**原子化服务API：** 从API version 19开始，该接口支持在原子化服务中使用。 1249 1250**系统能力：** SystemCapability.ArkUI.ArkUI.Full 1251 1252**参数：** 1253 1254| 参数名 | 类型 | 必填 | 说明 | 1255| -------------------- | ------ | ---- | -------------------------------------- | 1256| start | number | 是 | List显示区域内第一个子组件的索引值。 | 1257| end | number | 是 | List显示区域内最后一个子组件的索引值。 | 1258| center | number | 是 | List显示区域内中间位置子组件的索引值。 | 1259 1260## 示例 1261 1262### 示例1（添加滚动事件） 1263该示例实现了设置纵向列表，并在当前显示界面发生改变时回调索引。 1264 1265ListDataSource实现了LazyForEach数据源接口[IDataSource](ts-rendering-control-lazyforeach.md#idatasource)，用于通过LazyForEach给List提供子组件。 1266 1267<!--code_no_check--> 1268```ts 1269// ListDataSource.ets 1270export class ListDataSource implements IDataSource { 1271 private list: number[] = []; 1272 private listeners: DataChangeListener[] = []; 1273 1274 constructor(list: number[]) { 1275 this.list = list; 1276 } 1277 1278 totalCount(): number { 1279 return this.list.length; 1280 } 1281 1282 getData(index: number): number { 1283 return this.list[index]; 1284 } 1285 1286 registerDataChangeListener(listener: DataChangeListener): void { 1287 if (this.listeners.indexOf(listener) < 0) { 1288 this.listeners.push(listener); 1289 } 1290 } 1291 1292 unregisterDataChangeListener(listener: DataChangeListener): void { 1293 const pos = this.listeners.indexOf(listener); 1294 if (pos >= 0) { 1295 this.listeners.splice(pos, 1); 1296 } 1297 } 1298 1299 // 通知控制器数据删除 1300 notifyDataDelete(index: number): void { 1301 this.listeners.forEach(listener => { 1302 listener.onDataDelete(index); 1303 }); 1304 } 1305 1306 // 通知控制器添加数据 1307 notifyDataAdd(index: number): void { 1308 this.listeners.forEach(listener => { 1309 listener.onDataAdd(index); 1310 }); 1311 } 1312 1313 // 在指定索引位置删除一个元素 1314 public deleteItem(index: number): void { 1315 this.list.splice(index, 1); 1316 this.notifyDataDelete(index); 1317 } 1318 1319 // 在指定索引位置插入一个元素 1320 public insertItem(index: number, data: number): void { 1321 this.list.splice(index, 0, data); 1322 this.notifyDataAdd(index); 1323 } 1324} 1325``` 1326 1327<!--code_no_check--> 1328```ts 1329// xxx.ets 1330import { ListDataSource } from './ListDataSource'; 1331 1332@Entry 1333@Component 1334struct ListExample { 1335 private arr: ListDataSource = new ListDataSource([0, 1, 2, 3, 4, 5, 6, 7, 8, 9]); 1336 1337 build() { 1338 Column() { 1339 List({ space: 20, initialIndex: 0 }) { 1340 LazyForEach(this.arr, (item: number) => { 1341 ListItem() { 1342 Text('' + item) 1343 .width('100%').height(100).fontSize(16) 1344 .textAlign(TextAlign.Center).borderRadius(10).backgroundColor(0xFFFFFF) 1345 } 1346 }, (item: number) => item.toString()) 1347 } 1348 .listDirection(Axis.Vertical) // 排列方向 1349 .scrollBar(BarState.Off) 1350 .friction(0.6) 1351 .divider({ strokeWidth: 2, color: 0xFFFFFF, startMargin: 20, endMargin: 20 }) // 每行之间的分界线 1352 .edgeEffect(EdgeEffect.Spring) // 边缘效果设置为Spring 1353 .onScrollIndex((firstIndex: number, lastIndex: number, centerIndex: number) => { 1354 console.info('first' + firstIndex); 1355 console.info('last' + lastIndex); 1356 console.info('center' + centerIndex); 1357 }) 1358 .onScrollVisibleContentChange((start: VisibleListContentInfo, end: VisibleListContentInfo) => { 1359 console.info(' start index: ' + start.index + 1360 ' start item group area: ' + start.itemGroupArea + 1361 ' start index in group: ' + start.itemIndexInGroup); 1362 console.info(' end index: ' + end.index + 1363 ' end item group area: ' + end.itemGroupArea + 1364 ' end index in group: ' + end.itemIndexInGroup); 1365 }) 1366 .onDidScroll((scrollOffset: number, scrollState: ScrollState) => { 1367 console.info(`onScroll scrollState = ScrollState` + scrollState + `, scrollOffset = ` + scrollOffset); 1368 }) 1369 .width('90%') 1370 } 1371 .width('100%') 1372 .height('100%') 1373 .backgroundColor(0xDCDCDC) 1374 .padding({ top: 5 }) 1375 } 1376} 1377``` 1378 1379 1380 1381 1382### 示例2（设置子元素对齐） 1383该示例展示了不同ListItemAlign枚举值下，List组件交叉轴方向子元素对齐效果。 1384 1385ListDataSource说明及完整代码参考[示例1添加滚动事件](#示例1添加滚动事件)。 1386 1387<!--code_no_check--> 1388```ts 1389// xxx.ets 1390import { ListDataSource } from './ListDataSource'; 1391 1392@Entry 1393@Component 1394struct ListLanesExample { 1395 arr: ListDataSource = new ListDataSource([0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19]); 1396 @State alignListItem: ListItemAlign = ListItemAlign.Start; 1397 1398 build() { 1399 Column() { 1400 List({ space: 20, initialIndex: 0 }) { 1401 LazyForEach(this.arr, (item: string) => { 1402 ListItem() { 1403 Text('' + item) 1404 .width('100%') 1405 .height(100) 1406 .fontSize(16) 1407 .textAlign(TextAlign.Center) 1408 .borderRadius(10) 1409 .backgroundColor(0xFFFFFF) 1410 } 1411 .border({ width: 2, color: Color.Green }) 1412 }, (item: string) => item) 1413 } 1414 .height(300) 1415 .width('90%') 1416 .friction(0.6) 1417 .border({ width: 3, color: Color.Red }) 1418 .lanes({ minLength: 40, maxLength: 40 }) 1419 .alignListItem(this.alignListItem) 1420 .scrollBar(BarState.Off) 1421 1422 Button('点击更改alignListItem:' + this.alignListItem).onClick(() => { 1423 if (this.alignListItem == ListItemAlign.Start) { 1424 this.alignListItem = ListItemAlign.Center; 1425 } else if (this.alignListItem == ListItemAlign.Center) { 1426 this.alignListItem = ListItemAlign.End; 1427 } else { 1428 this.alignListItem = ListItemAlign.Start; 1429 } 1430 }) 1431 }.width('100%').height('100%').backgroundColor(0xDCDCDC).padding({ top: 5 }) 1432 } 1433} 1434``` 1435 1436 1437 1438 1439### 示例3（设置编辑模式） 1440该示例展示了如何设置当前List组件是否处于可编辑模式。 1441 1442ListDataSource说明及完整代码参考[示例1添加滚动事件](#示例1添加滚动事件)。 1443 1444<!--code_no_check--> 1445```ts 1446// xxx.ets 1447import { ListDataSource } from './ListDataSource'; 1448 1449@Entry 1450@Component 1451struct ListExample { 1452 arr: ListDataSource=new ListDataSource([0, 1, 2, 3, 4, 5, 6, 7, 8, 9]); 1453 @State editFlag: boolean = false; 1454 1455 build() { 1456 Stack({ alignContent: Alignment.TopStart }) { 1457 Column() { 1458 List({ space: 20, initialIndex: 0 }) { 1459 LazyForEach(this.arr, (item: number, index?: number) => { 1460 ListItem() { 1461 Flex({ direction: FlexDirection.Row, alignItems: ItemAlign.Center }) { 1462 Text('' + item) 1463 .width('100%') 1464 .height(80) 1465 .fontSize(20) 1466 .textAlign(TextAlign.Center) 1467 .borderRadius(10) 1468 .backgroundColor(0xFFFFFF) 1469 .flexShrink(1) 1470 if (this.editFlag) { 1471 Button() { 1472 Text('delete').fontSize(16) 1473 }.width('30%').height(40) 1474 .onClick(() => { 1475 if (index != undefined) { 1476 console.info(this.arr.getData(index) + 'Delete'); 1477 this.arr.deleteItem(index); 1478 console.info(JSON.stringify(this.arr)); 1479 this.editFlag = false; 1480 } 1481 }).stateEffect(true) 1482 } 1483 } 1484 } 1485 }, (item: number) => item.toString()) 1486 }.width('90%') 1487 .scrollBar(BarState.Off) 1488 .friction(0.6) 1489 }.width('100%') 1490 1491 Button('edit list') 1492 .onClick(() => { 1493 this.editFlag = !this.editFlag; 1494 }).margin({ top: 5, left: 20 }) 1495 }.width('100%').height('100%').backgroundColor(0xDCDCDC).padding({ top: 5 }) 1496 } 1497} 1498``` 1499 1500 1501 1502### 示例4（设置限位对齐） 1503该示例展示了List组件设置居中限位的实现效果。 1504 1505ListDataSource说明及完整代码参考[示例1添加滚动事件](#示例1添加滚动事件)。 1506 1507<!--code_no_check--> 1508```ts 1509// xxx.ets 1510import { ListDataSource } from './ListDataSource'; 1511 1512@Entry 1513@Component 1514struct ListExample { 1515 private arr: ListDataSource=new ListDataSource([]); 1516 private scrollerForList: Scroller = new Scroller(); 1517 1518 aboutToAppear() { 1519 let list: number[] = []; 1520 for (let i = 0; i < 20; i++) { 1521 list.push(i); 1522 } 1523 this.arr = new ListDataSource(list); 1524 } 1525 1526 build() { 1527 Column() { 1528 Row() { 1529 List({ space: 20, initialIndex: 3, scroller: this.scrollerForList }) { 1530 LazyForEach(this.arr, (item: number) => { 1531 ListItem() { 1532 Text('' + item) 1533 .width('100%').height(100).fontSize(16) 1534 .textAlign(TextAlign.Center) 1535 } 1536 .borderRadius(10).backgroundColor(0xFFFFFF) 1537 .width('60%') 1538 .height('80%') 1539 }, (item: number) => JSON.stringify(item)) 1540 } 1541 .chainAnimation(true) 1542 .edgeEffect(EdgeEffect.Spring) 1543 .listDirection(Axis.Horizontal) 1544 .height('100%') 1545 .width('100%') 1546 .scrollSnapAlign(ScrollSnapAlign.CENTER) 1547 .borderRadius(10) 1548 .backgroundColor(0xDCDCDC) 1549 } 1550 .width('100%') 1551 .height('100%') 1552 .backgroundColor(0xDCDCDC) 1553 .padding({ top: 10 }) 1554 } 1555 } 1556} 1557 1558``` 1559 1560 1561 1562### 示例5（跳转准确） 1563该示例通过设置childrenMainSize属性，实现了List在子组件高度不一致时调用scrollTo接口也可以跳转准确。 1564 1565如果配合状态管理V2使用，详情见：[List与makeObserved](../../../ui/state-management/arkts-v1-v2-migration-application-and-others.md#滑动组件)。 1566 1567ListDataSource说明及完整代码参考[示例1添加滚动事件](#示例1添加滚动事件)。 1568 1569<!--code_no_check--> 1570```ts 1571// xxx.ets 1572import { ListDataSource } from './ListDataSource'; 1573 1574@Entry 1575@Component 1576struct ListExample { 1577 private arr: ListDataSource = new ListDataSource([]); 1578 private scroller: ListScroller = new ListScroller(); 1579 @State listSpace: number = 10; 1580 @State listChildrenSize: ChildrenMainSize = new ChildrenMainSize(100); 1581 aboutToAppear(){ 1582 // 初始化数据源。 1583 let list: number[] = []; 1584 for (let i = 0; i < 10; i++) { 1585 list.push(i); 1586 } 1587 this.arr = new ListDataSource(list); 1588 // 前5个item的主轴大小不是默认大小100，因此需要通过ChildrenMainSize通知List。 1589 this.listChildrenSize.splice(0, 5, [300, 300, 300, 300, 300]); 1590 } 1591 1592 build() { 1593 Column() { 1594 List({ space: this.listSpace, initialIndex: 4, scroller: this.scroller }) { 1595 LazyForEach(this.arr, (item: number) => { 1596 ListItem() { 1597 Text('item-' + item) 1598 .height( item < 5 ? 300 : this.listChildrenSize.childDefaultSize) 1599 .width('90%') 1600 .fontSize(16) 1601 .textAlign(TextAlign.Center) 1602 .borderRadius(10) 1603 .backgroundColor(0xFFFFFF) 1604 } 1605 }, (item: string) => item) 1606 } 1607 .backgroundColor(Color.Gray) 1608 .layoutWeight(1) 1609 .scrollBar(BarState.On) 1610 .childrenMainSize(this.listChildrenSize) 1611 .alignListItem(ListItemAlign.Center) 1612 Row(){ 1613 Button() { Text('item size + 50') }.onClick(()=>{ 1614 this.listChildrenSize.childDefaultSize += 50; 1615 }).height('50%').width('30%') 1616 Button() { Text('item size - 50') }.onClick(()=>{ 1617 if (this.listChildrenSize.childDefaultSize === 0) { 1618 return; 1619 } 1620 this.listChildrenSize.childDefaultSize -= 50; 1621 }).height('50%').width('30%') 1622 Button() { Text('scrollTo (0, 310)') }.onClick(()=>{ 1623 // 310: 跳转到item 1顶部与List顶部平齐的位置。 1624 // 如果不设置childrenMainSize，item高度不一致时scrollTo会不准确。 1625 this.scroller.scrollTo({ xOffset: 0, yOffset: 310 }) 1626 }).height('50%').width('30%') 1627 }.height('20%') 1628 } 1629 } 1630} 1631 1632``` 1633 1634 1635 1636### 示例6（获得子组件索引信息） 1637该示例展示了含有group时，获得List组件的Item索引相关信息。 1638```ts 1639// xxx.ets 1640class TimeTableDataSource implements IDataSource { 1641 private list: TimeTable[] = []; 1642 1643 constructor(list: TimeTable[]) { 1644 this.list = list; 1645 } 1646 1647 totalCount(): number { 1648 return this.list.length; 1649 } 1650 1651 getData(index: number): TimeTable { 1652 return this.list[index]; 1653 } 1654 1655 registerDataChangeListener(listener: DataChangeListener): void { 1656 } 1657 1658 unregisterDataChangeListener(listener: DataChangeListener): void { 1659 } 1660} 1661 1662class ProjectsDataSource implements IDataSource { 1663 private list: string[] = []; 1664 1665 constructor(list: string[]) { 1666 this.list = list; 1667 } 1668 1669 totalCount(): number { 1670 return this.list.length; 1671 } 1672 1673 getData(index: number): string { 1674 return this.list[index]; 1675 } 1676 1677 registerDataChangeListener(listener: DataChangeListener): void { 1678 } 1679 1680 unregisterDataChangeListener(listener: DataChangeListener): void { 1681 } 1682} 1683 1684@Entry 1685@Component 1686struct ListItemGroupExample { 1687 private timeTable: TimeTable[] = [ 1688 { 1689 title: '星期一', 1690 projects: ['语文', '数学', '英语'] 1691 }, 1692 { 1693 title: '星期二', 1694 projects: ['物理', '化学', '生物'] 1695 }, 1696 { 1697 title: '星期三', 1698 projects: ['历史', '地理', '政治'] 1699 }, 1700 { 1701 title: '星期四', 1702 projects: ['美术', '音乐', '体育'] 1703 } 1704]; 1705 private scroller: ListScroller = new ListScroller(); 1706 @State listIndexInfo: VisibleListContentInfo = { index: -1 }; 1707 @State mess:string = "null"; 1708 @State itemBackgroundColorArr: boolean[] = [false]; 1709 @Builder 1710 itemHead(text: string) { 1711 Text(text) 1712 .fontSize(20) 1713 .backgroundColor(0xAABBCC) 1714 .width('100%') 1715 .padding(10) 1716 } 1717 1718 @Builder 1719 itemFoot(num: number) { 1720 Text('共' + num + "节课") 1721 .fontSize(16) 1722 .backgroundColor(0xAABBCC) 1723 .width('100%') 1724 .padding(5) 1725 } 1726 1727 build() { 1728 Column() { 1729 List({ space: 20, scroller: this.scroller}) { 1730 LazyForEach(new TimeTableDataSource(this.timeTable), (item: TimeTable, index: number) => { 1731 ListItemGroup({ header: this.itemHead(item.title), footer: this.itemFoot(item.projects.length) }) { 1732 LazyForEach(new ProjectsDataSource(item.projects), (project: string, subIndex: number) => { 1733 ListItem() { 1734 Text(project) 1735 .width('100%') 1736 .height(100) 1737 .fontSize(20) 1738 .textAlign(TextAlign.Center) 1739 .backgroundColor(this.itemBackgroundColorArr[index * 3 +subIndex] ? 0x68B4FF: 0xFFFFFF) 1740 } 1741 }, (item: string) => item) 1742 } 1743 .divider({ strokeWidth: 1, color: Color.Blue }) // 每行之间的分界线 1744 },(item: string) => item) 1745 } 1746 .width('90%') 1747 .sticky(StickyStyle.Header | StickyStyle.Footer) 1748 .scrollBar(BarState.Off) 1749 .gesture( 1750 PanGesture() 1751 .onActionUpdate((event: GestureEvent) => { 1752 if (event.fingerList[0] != undefined && event.fingerList[0].localX != undefined && event.fingerList[0].localY != undefined) { 1753 this.listIndexInfo = this.scroller.getVisibleListContentInfo(event.fingerList[0].localX, event.fingerList[0].localY); 1754 let itemIndex:string = 'undefined'; 1755 if (this.listIndexInfo.itemIndexInGroup != undefined ) { 1756 itemIndex = this.listIndexInfo.itemIndexInGroup.toString(); 1757 if (this.listIndexInfo.index != undefined && this.listIndexInfo.index >= 0 && 1758 this.listIndexInfo.itemIndexInGroup >= 0 ) { 1759 this.itemBackgroundColorArr[this.listIndexInfo.index * 3 + this.listIndexInfo.itemIndexInGroup] = true; 1760 } 1761 } 1762 this.mess = 'index:' + this.listIndexInfo.index.toString() + ' itemIndex:' + itemIndex; 1763 } 1764 })) 1765 .gesture( 1766 TapGesture({ count: 1 }) 1767 .onAction((event: GestureEvent) => { 1768 if (event) { 1769 this.itemBackgroundColorArr.splice(0,this.itemBackgroundColorArr.length); 1770 } 1771 }) 1772 ) 1773 Text('您当前位置Item索引为'+ this.mess) 1774 .fontColor(Color.Red) 1775 .height(50) 1776 }.width('100%').height('90%').backgroundColor(0xDCDCDC).padding({ top: 5 }) 1777 } 1778} 1779 1780interface TimeTable { 1781 title: string; 1782 projects: string[]; 1783} 1784 1785``` 1786 1787 1788 1789### 示例7（设置边缘渐隐） 1790该示例实现了List组件开启边缘渐隐效果并设置边缘渐隐长度。 1791 1792ListDataSource说明及完整代码参考[示例1添加滚动事件](#示例1添加滚动事件)。 1793 1794<!--code_no_check--> 1795```ts 1796import { LengthMetrics } from '@kit.ArkUI' 1797import { ListDataSource } from './ListDataSource'; 1798@Entry 1799@Component 1800struct ListExample { 1801 private arr: ListDataSource=new ListDataSource([0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11]); 1802 scrollerForList: Scroller = new Scroller(); 1803 1804 build() { 1805 Column() { 1806 1807 List({ space: 20, initialIndex: 0, scroller: this.scrollerForList }) { 1808 LazyForEach(this.arr, (item: number) => { 1809 ListItem() { 1810 Text('' + item) 1811 .width('100%').height(100).fontSize(16) 1812 .textAlign(TextAlign.Center).borderRadius(10).backgroundColor(0xFFFFFF) 1813 } 1814 }, (item: number) => item.toString()) 1815 } 1816 .fadingEdge(true, { fadingEdgeLength: LengthMetrics.vp(80) }) 1817 } 1818 .width('100%') 1819 .height('100%') 1820 .backgroundColor(0xDCDCDC) 1821 .padding({ top: 5 }) 1822 } 1823} 1824``` 1825 1826 1827 1828### 示例8（单边边缘效果） 1829 1830该示例通过edgeEffect接口，实现了List组件设置单边边缘效果。 1831 1832ListDataSource说明及完整代码参考[示例1添加滚动事件](#示例1添加滚动事件)。 1833 1834<!--code_no_check--> 1835```ts 1836// xxx.ets 1837import { ListDataSource } from './ListDataSource'; 1838 1839@Entry 1840@Component 1841struct ListExample { 1842 private arr: ListDataSource = new ListDataSource([0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11]); 1843 scrollerForList: Scroller = new Scroller(); 1844 build() { 1845 Column() { 1846 List({ space: 20, initialIndex: 0, scroller: this.scrollerForList }) { 1847 LazyForEach(this.arr, (item: number) => { 1848 ListItem() { 1849 Text('' + item) 1850 .width('100%').height(100).fontSize(16) 1851 .textAlign(TextAlign.Center).borderRadius(10).backgroundColor(0xFFFFFF) 1852 } 1853 }, (item: string) => item) 1854 } 1855 .edgeEffect(EdgeEffect.Spring, {alwaysEnabled: true, effectEdge: EffectEdge.START}) 1856 .width('90%').height('90%') 1857 } 1858 .width('100%') 1859 .height('100%') 1860 .backgroundColor(0xDCDCDC) 1861 .padding({ top: 5 }) 1862 } 1863} 1864``` 1865 1866 1867 1868### 示例9（设置折行走焦） 1869 1870该示例通过focusWrapMode接口，实现了List组件方向键走焦换行效果。 1871 1872```ts 1873@Entry 1874@Component 1875struct ListExample { 1876 @State arr: number[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] 1877 build() { 1878 Stack({ alignContent: Alignment.TopStart }) { 1879 Column() { 1880 List({ space: 40, initialIndex: 0 }) { 1881 ForEach(this.arr, (item: number, index?: number) => { 1882 ListItem() { 1883 Flex({ direction: FlexDirection.Row, alignItems: ItemAlign.Center }) { 1884 Text('' + item) 1885 .width(150) 1886 .height(93) 1887 .fontSize(30) 1888 .textAlign(TextAlign.Center) 1889 .borderRadius(10) 1890 .backgroundColor(0xFFFFFF) 1891 .flexShrink(1) 1892 .focusable(true) 1893 .offset({ left: 5 }) 1894 } 1895 } 1896 }, (item: string) => item) 1897 } 1898 .lanes(2) 1899 .contentStartOffset(20) 1900 .contentEndOffset(20) 1901 .width('100%') 1902 .scrollBar(BarState.Off) 1903 .friction(0.6) 1904 .focusWrapMode(FocusWrapMode.WRAP_WITH_ARROW) 1905 .alignListItem(ListItemAlign.Center) 1906 .offset({ left: 20 }) 1907 }.width('90%') 1908 }.width('100%').height('100%').backgroundColor(0xDCDCDC).padding({ top: 5 }) 1909 } 1910} 1911``` 1912 1913 1914 1915### 示例10（设置显示区域外插入数据时，保持显示内容不变） 1916 1917该示例通过maintainVisibleContentPosition接口，实现了上滑无限加载历史消息场景。 1918 1919ListDataSource说明及完整代码参考[示例1添加滚动事件](#示例1添加滚动事件)。 1920 1921<!--code_no_check--> 1922```ts 1923import { ListDataSource } from './ListDataSource'; 1924 1925@Entry 1926@Component 1927struct ListExample { 1928 private arr: ListDataSource = new ListDataSource([990, 991, 992, 993, 994, 995, 996, 997, 998, 999]); 1929 build() { 1930 Column() { 1931 List({ space: 20, initialIndex: 9 }) { 1932 LazyForEach(this.arr, (item: number) => { 1933 ListItem() { 1934 Text('message:' + item) 1935 .width('100%').height(100) 1936 .fontSize(16) 1937 .textAlign(TextAlign.Center) 1938 .borderRadius(10) 1939 .backgroundColor(0xFFFFFF) 1940 } 1941 }, (item: number) => item.toString()) 1942 } 1943 .maintainVisibleContentPosition(true) 1944 .onScrollIndex((start:number)=>{ 1945 if (start < 5) { 1946 for (let i = 0; i < 10; i++) { 1947 this.arr.insertItem(0, this.arr.getData(0) - 1); 1948 } 1949 } 1950 }) 1951 } 1952 .width('100%') 1953 .height('100%') 1954 .backgroundColor(0xDCDCDC) 1955 .padding(12) 1956 } 1957} 1958``` 1959 1960 1961 1962### 示例11（设置滚动条的边距） 1963 1964该示例展示了在设置了[contentStartOffset](#contentstartoffset11)、[contentEndOffset](#contentendoffset11)属性的情况下，设置滚动条边距的效果。 1965 1966<!--code_no_check--> 1967```ts 1968// xxx.ets 1969import { LengthMetrics } from '@kit.ArkUI'; 1970 1971@Entry 1972@Component 1973struct ListScrollBarMarginExample { 1974 @State arr: number[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]; 1975 1976 build() { 1977 Column() { 1978 List({ space: 40, initialIndex: 0 }) { 1979 ForEach(this.arr, (item: number, index?: number) => { 1980 ListItem() { 1981 Text('' + item) 1982 .width('100%') 1983 .height(100) 1984 .fontSize(16) 1985 .textAlign(TextAlign.Center) 1986 .borderRadius(10) 1987 .backgroundColor(0xFFFFFF) 1988 } 1989 }, (item: string) => item) 1990 } 1991 .contentStartOffset(20) 1992 .contentEndOffset(20) 1993 .scrollBar(BarState.On) 1994 .scrollBarMargin({ start: LengthMetrics.vp(20), end: LengthMetrics.vp(20) }) 1995 .width('90%') 1996 } 1997 .width('100%') 1998 .height('100%') 1999 .backgroundColor(0xDCDCDC) 2000 .padding({ top: 5 }) 2001 } 2002} 2003``` 2004 2005
