# List >![](../../public_sys-resources/icon-note.gif) **NOTE:** >This component is supported since API version 7. Updates will be marked with a superscript to indicate their earliest API version. The **** component provides a list container that presents a series of list items arranged in a column with the same width. It supports presentations of the same type of data in a multiple and coherent row style, for example, images or text. ## Required Permissions None ## Child Components This component contains the child component [](ts-container-listitem.md). ## APIs List\(value:\{space?: number, initialIndex?: number\}\) - Parameters

Name

Type

Mandatory

Default Value

Description

space

number

No

0

Spacing between list items.

initialIndex

number

No

0

Item displayed at the beginning of the component when the current list is loaded for the first time, that is, the first item to be displayed. If the configured sequence number is greater than the sequence number of the last item, the setting does not take effect.
## Attributes

Name

Type

Default Value

Description

listDirection

Axis

Vertical

Direction in which the list items are arranged. For details, see Axis enums.

divider

{

strokeWidth: Length,

color?:Color,

startMargin?: Length,

endMargin?: Length

}

-

Style of the divider for the list items. By default, there is no divider.

strokeWidth: stroke width of the divider.

color: color of the divider.

startMargin: distance between the divider and the start of the list.

endMargin: distance between the divider and the end of the list.

editMode

boolean

false

Whether the <List> component is in editable mode.

edgeEffect

EdgeEffect

Spring

Sliding effect. For details, see EdgeEffect enums.

chainAnimation

boolean

false

Whether to display chained animations on this list when it slides or its top and bottom are dragged. The list items are separated with even space, and one item animation starts after the previous animation during basic sliding interactions. The chained animation effect is similar with spring physics.

  • false: No chained animations are displayed.
  • true: Chained animations are displayed.
- EdgeEffect enums

Name

Description

Spring

Similar to the physical dynamic effect of a spring. After scrolling to the edge, you can continue to scroll for a distance based on the initial speed or by touching the knob of the scrollbar. After you release your hand, the knob is rebounded.

None

No effect after the scroll bar is moved to the edge.
## Events

Name

Description

onItemDelete(index: number) => boolean

Triggered when a list item is deleted.

onScrollIndex(firstIndex: number, lastIndex: number) => void

Triggered when the start position and end position of the current list are changed.

onItemDragEnter(callback: (event: ItemDragInfo) => void)

Triggered when the list item that is bound to the drag event enters a valid drop target.

  • itemIndex: original index of the list item that is being dragged.
  • insertIndex: index of the list item after it is dragged and inserted into the list.
NOTE:

This event is valid only when the onDrop event is listened to.

onItemDragMove(callback: (event: ItemDragInfo, itemIndex: number, insertIndex: number) => void)

Triggered when the list item that is bound to the drag event enters a valid drop target.

  • itemIndex: original index of the list item that is being dragged.
  • insertIndex: index of the list item after it is dragged and inserted into the list.
NOTE:

This event is valid only when the onDrop event is listened to.

onItemDragLeave(callback: (event: ItemDragInfo, itemIndex: number) => void)

Triggered when the list item that is bound to the drag event leaves a valid drop target.

  • itemIndex: original index of the list item that is being dragged.
NOTE:

This event is valid only when the onDrop event is listened to.

onItemDragStart(callback: (event: ItemDragInfo, itemIndex: number) => CustomBuilder)

Triggered when the list item that is bound to the drag event is dragged for the first time.

  • itemIndex: original index of the list item that is being dragged.
  • Return value: floating UI layout of the list item that is being dragged.
NOTE:

This event is valid only when the onDrop event is listened to.

onItemDrop(callback: (event: ItemDragInfo, itemIndex: number, insertIndex: number, isSuccess: boolean) => void)

Triggered when the list item that is bound to the drag event is dropped on a valid drop target.

  • itemIndex: original index of the list item that is being dragged.
  • insertIndex: index of the list item after it is dragged and inserted into the list.
  • isSuccess: whether the insertion is successful after the list item is dropped.
NOTE:

This event is valid only when the onDrop event is listened to.
>![](../../public_sys-resources/icon-note.gif) **NOTE:** >To enable the editable mode for a list, the following conditions must be met: >- **editMode** is set to **true**. >- The list is bound to the **onItemDelete** event and the event returns **true** during event callback. >- The **editable** attribute of **ListItem** is set to **true**. >To enable for a list item, the following conditions must be met: >- **editMode** is set to **true**. >- The list item is bound to the **onItemDragStart** event and the event returns a floating UI during event callback. - ItemDragInfo attributes

Name

Type

Description

x

number

X-coordinate of the item that is being dragged.

y

number

Y-coordinate of the item that is being dragged.
## Example ``` @Entry @Component struct ListExample { private arr: number[] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] @State editFlag: boolean = false build() { Stack({ alignContent: Alignment.TopStart }) { Column() { List({ space: 20, initialIndex: 0 }) { ForEach(this.arr, (item) => { ListItem() { Text('' + item) .width('100%').height(100).fontSize(16) .textAlign(TextAlign.Center).borderRadius(10).backgroundColor(0xFFFFFF) }.editable(true) }, item => item) } .listDirection(Axis.Vertical) //Arrangement direction .divider({ strokeWidth: 2, color: 0xFFFFFF, startMargin: 20, endMargin: 20 }) // Divider line .edgeEffect(EdgeEffect.None) // No effect when sliding to the edge .chainAnimation(false) // Chained animations are disabled. .onScrollIndex((firstIndex: number, lastIndex: number) => { console.info('first' + firstIndex) console.info('last' + lastIndex) }) .editMode(this.editFlag) .onItemDelete((index: number) => { console.info(this.arr[index] + 'Delete') this.arr.splice(index, 1) console.info(JSON.stringify(this.arr)) this.editFlag = false return true }).width('90%') }.width('100%') Button('edit list') .onClick(() => { this.editFlag = !this.editFlag }).margin({ top: 5, left: 20 }) }.width('100%').height('100%').backgroundColor(0xDCDCDC).padding({ top: 5 }) } } ``` ![](figures/list.gif) ``` @Entry @Component struct DragListExample { @State number1: string[] = ['0', '1', '2'] @State number2: string[] = ['one', 'two', 'three'] @State text: string = '' @State bool1: boolean = false @State bool2: boolean = false @Builder pixelMapBuilder() { Text('-1') .width('100%').height(100).fontSize(16) .textAlign(TextAlign.Center).borderRadius(10).backgroundColor(0xFFFFFF) } build() { Column() { List() { ForEach(this.number1, (item) => { ListItem() { Text('' + item) .width('100%').height(100).fontSize(16) .textAlign(TextAlign.Center).borderRadius(10).backgroundColor(0xF666FF) } }, item => item) } .editMode(true) .width('90%').divider({ strokeWidth: 2, color: 0xFFFFFF, startMargin: 20, endMargin: 20 }) .onItemDelete((index: number) => { console.info(this.Number1[index] + 'Delete') this.Number1.splice(index, 1) console.info(JSON.stringify(this.Number1)) return true }) .onItemDragStart((event: ItemDragInfo, itemIndex: number) => { this.bool1 = true this.text = this.number1[itemIndex] console.log("List1 onItemDragStart, itemIndex:" + itemIndex + ", ItemDragInfo:"+`${JSON.stringify(event)}`) return this.pixelMapBuilder }) .onItemDragEnter((event: ItemDragInfo) => { console.log("List1 onItemDragEnter") }) .onItemDragMove((event: ItemDragInfo, itemIndex: number, insertIndex: number) => { console.log("List1 onItemDragMove, itemIndex:" + itemIndex + ", insertIndex:" + insertIndex) }) .onItemDragLeave((event: ItemDragInfo, itemIndex: number) => { console.log("List1 onItemDragLeave, itemIndex:" + itemIndex) }) .onItemDrop((event: ItemDragInfo, itemIndex: number, insertIndex: number, isSuccess: boolean) => { if (isSuccess) { if (this.bool2) { this.number2.splice(itemIndex, 1) this.number1.splice(insertIndex, 0, this.text) this.bool1 = false this.bool2 = false } else if (this.bool1) { this.number1.splice(itemIndex, 1) this.number1.splice(insertIndex, 0, this.text) this.bool1 = false this.bool2 = false } } console.log("List1 onItemDrop, itemIndex:" + itemIndex + ", insertIndex:" + insertIndex + ", isSuccess:" + isSuccess) }) Divider().strokeWidth(5).color(0x2788D9).lineCap(LineCapStyle.Round).margin(20) List() { ForEach(this.Number2, (item) => { ListItem() { Text('' + item) .width('100%').height(100).fontSize(16) .textAlign(TextAlign.Center).borderRadius(10).backgroundColor(0xFFF888) } }, item => item) } .edgeEffect(EdgeEffect.None) .width('90%') .editMode(true) .divider({ strokeWidth: 2, color: 0xFFFFFF, startMargin: 20, endMargin: 20 }) .onItemDragStart((event: ItemDragInfo, itemIndex: number) => { this.bool2 = true this.text = this.number2[itemIndex] console.log("List2 onItemDragStart, itemIndex:" + itemIndex) return this.pixelMapBuilder }) .onItemDragEnter((event: ItemDragInfo) => { console.log("List2 onItemDragEnter") }) .onItemDragMove((event: ItemDragInfo, itemIndex: number, insertIndex: number) => { console.log("List2 onItemDragMove, itemIndex:" + itemIndex + ", insertIndex:" + insertIndex) }) .onItemDragLeave((event: ItemDragInfo, itemIndex: number) => { console.log("List2 onItemDragLeave, itemIndex:" + itemIndex) }) .onItemDrop((event: ItemDragInfo, itemIndex: number, insertIndex: number, isSuccess: boolean) => { if (isSuccess) { if (this.bool1) { this.number1.splice(itemIndex, 1) this.number2.splice(insertIndex, 0, this.text) this.bool1 = false this.bool2 = false } else if (this.bool2) { this.number2.splice(itemIndex, 1) this.number2.splice(insertIndex, 0, this.text) this.bool1 = false this.bool2 = false } } console.log("List2 onItemDrop, itemIndex:" + itemIndex + ", insertIndex:" + insertIndex + ", isSuccess:" + isSuccess) }) }.width('100%').height('100%').backgroundColor(0xE600000).padding({ top: 25 }) } } ``` ![](figures/gif-4.gif)