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