1# List 2 3列表包含一系列相同宽度的列表项。适合连续、多行呈现同类数据，例如图片和文本。 4 5> **说明：** 6> 7> - 该组件从API Version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。 8> 9> - 该组件回弹的前提是要有滚动。内容小于一屏时，没有回弹效果。 10 11 12## 子组件 13 14包含[ListItem](ts-container-listitem.md)子组件。 15 16 17## 接口 18 19List(value?:{space?: number | string, initialIndex?: number, scroller?: Scroller}) 20 21**参数：** 22 23| 参数名 | 参数类型 | 必填 | 参数描述 | 24| ------------ | ------ | ---- | ---------------------------------------- | 25| space | number \| string | 否 | 列表项间距。<br/>默认值：0 | 26| initialIndex | number | 否 | 设置当前List初次加载时视口起始位置显示的item的索引值。如果设置的值超过了当前List最后一个item的索引值，则设置不生效。<br/>默认值：0 | 27| scroller | [Scroller](ts-container-scroll.md#scroller) | 否 | 可滚动组件的控制器。用于与可滚动组件进行绑定。 | 28 29## 属性 30 31| 名称 | 参数类型 | 描述 | 32| ---------------------------- | ---------------------------------------- | ---------------------------------------- | 33| listDirection | [Axis](ts-appendix-enums.md#axis) | 设置List组件排列方向参照Axis枚举说明。<br/>默认值：Vertical | 34| divider | {<br/>strokeWidth: [Length](ts-types.md#length),<br/>color?: [ResourceColor](ts-types.md#resourcecolor8),<br/>startMargin?: [Length](ts-types.md#length),<br/>endMargin?: [Length](ts-types.md#length)<br/>} \| null | 用于设置ListItem分割线样式，默认无分割线。<br/>strokeWidth: 分割线的线宽。<br/>color: 分割线的颜色。<br/>startMargin： 分割线与列表侧边起始端的距离。<br/>endMargin: 分割线与列表侧边结束端的距离。 | 35| scrollBar | [BarState](ts-appendix-enums.md#barstate) | 设置滚动条状态。<br/>默认值：BarState.Off | 36| cachedCount | number | 设置预加载的ListItem的数量。具体使用可参考[减少应用白块说明](../../ui/ts-performance-improvement-recommendation.md#减少应用滑动白块)。<br/>默认值：1 | 37| editMode | boolean | 声明当前List组件是否处于可编辑模式。<br/>默认值：false | 38| edgeEffect | [EdgeEffect](ts-appendix-enums.md#edgeeffect) | 滑动效果，目前支持的滑动效果参见EdgeEffect的枚举说明。<br/>默认值：EdgeEffect.Spring | 39| chainAnimation | boolean | 用于设置当前list是否启用链式联动动效，开启后列表滑动以及顶部和底部拖拽时会有链式联动的效果。链式联动效果：list内的list-item间隔一定距离，在基本的滑动交互行为下，主动对象驱动从动对象进行联动，驱动效果遵循弹簧物理动效。<br/>- false：不启用链式联动。<br/>- true：启用链式联动。<br/>默认值：false | 40| multiSelectable<sup>8+</sup> | boolean | 是否开启鼠标框选。<br/>>默认值：false<br/>- false：关闭框选。<br/>- true：开启框选。 | 41 42 43## 事件 44 45| 名称 | 功能描述 | 46| ---------------------------------------- | ------------------------ | 47| onItemDelete(event: (index: number) => boolean) | 列表项删除时触发。 | 48| onScroll(event: (scrollOffset: number, scrollState: ScrollState) => void) | 列表滑动时触发，返回值scrollOffset为滑动偏移量，scrollState为当前滑动状态。 | 49| onScrollIndex(event: (start: number, end: number) => void) | 列表滑动时触发，返回值分别为滑动起始位置索引值与滑动结束位置索引值。 | 50| onReachStart(event: () => void) | 列表到达起始位置时触发。 | 51| onReachEnd(event: () => void) | 列表到底末尾位置时触发。 | 52| onScrollStop(event: () => void) | 列表滑动停止时触发。 | 53| onItemMove(event: (from: number, to: number) => boolean) | 列表元素发生移动时触发，返回值from、to分别为移动前索引值与移动后索引值。 | 54| onItemDragStart(event: (event: ItemDragInfo, itemIndex: number) => ((() => any) \| void)) | 开始拖拽列表元素时触发，返回值event见ItemDragInfo对象说明，itemIndex为被拖拽列表元素索引值。 | 55| onItemDragEnter(event: (event: ItemDragInfo) => void) | 拖拽进入列表元素范围内时触发，返回值event见ItemDragInfo对象说明。 | 56| onItemDragMove(event: (event: ItemDragInfo, itemIndex: number, insertIndex: number) => void) | 拖拽在列表元素范围内移动时触发，返回值event见ItemDragInfo对象说明，itemIndex为拖拽起始位置，insertIndex为拖拽插入位置。 | 57| onItemDragLeave(event: (event: ItemDragInfo, itemIndex: number) => void) | 拖拽离开列表元素时触发，返回值event见ItemDragInfo对象说明，itemIndex为拖拽离开的列表元素索引值。 | 58| onItemDrop(event: (event: ItemDragInfo, itemIndex: number, insertIndex: number, isSuccess: boolean) => void) | 绑定该事件的列表元素可作为拖拽释放目标，当在列表元素内停止拖拽时触发，返回值event见ItemDragInfo对象说明，itemIndex为拖拽起始位置，insertIndex为拖拽插入位置，isSuccess为是否成功释放。 | 59 60## ScrollState枚举说明 61 62| 名称 | 描述 | 63| ------ | ------------------------- | 64| Idle | 未滑动状态。 | 65| Scroll | 惯性滑动状态。 | 66| Fling | 手指拖动状态。 | 67 68> **说明：** 69> 70> List使能可编辑模式需配合onItemDelete事件和ListItem的editable属性，即可编辑模式实现删除列表项功能，需满足以下条件： 71> 72> - editMode属性设置为true。 73> 74> - 绑定onItemDelete事件，且事件回调返回true。 75> 76> - ListItem的editable属性设置为true。 77> 78> 实现ListItem拖拽，需满足以下条件： 79> 80> - editMode属性设置为true。 81> 82> - 绑定onDragStart事件，且事件回调中返回浮动UI布局。 83 84 85## 示例 86 87```ts 88// xxx.ets 89@Entry 90@Component 91struct ListExample { 92 private arr: number[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] 93 @State editFlag: boolean = false 94 95 build() { 96 Stack({ alignContent: Alignment.TopStart }) { 97 Column() { 98 List({ space: 20, initialIndex: 0 }) { 99 ForEach(this.arr, (item) => { 100 ListItem() { 101 Text('' + item) 102 .width('100%').height(100).fontSize(16) 103 .textAlign(TextAlign.Center).borderRadius(10).backgroundColor(0xFFFFFF) 104 }.editable(true) 105 }, item => item) 106 } 107 .listDirection(Axis.Vertical) // 排列方向 108 .divider({ strokeWidth: 2, color: 0xFFFFFF, startMargin: 20, endMargin: 20 }) // 每行之间的分界线 109 .edgeEffect(EdgeEffect.None) // 滑动到边缘无效果 110 .chainAnimation(false) // 联动特效关闭 111 .onScrollIndex((firstIndex: number, lastIndex: number) => { 112 console.info('first' + firstIndex) 113 console.info('last' + lastIndex) 114 }) 115 .editMode(this.editFlag) 116 .onItemDelete((index: number) => { 117 console.info(this.arr[index] + 'Delete') 118 this.arr.splice(index, 1) 119 console.info(JSON.stringify(this.arr)) 120 this.editFlag = false 121 return true 122 }).width('90%') 123 }.width('100%') 124 125 Button('edit list') 126 .onClick(() => { 127 this.editFlag = !this.editFlag 128 }).margin({ top: 5, left: 20 }) 129 }.width('100%').height('100%').backgroundColor(0xDCDCDC).padding({ top: 5 }) 130 } 131} 132``` 133 134 135
