鸿蒙5.0开发进阶：UI框架-ArkTS组件（List）

往期鸿蒙全套实战文章必看：（文中附带全栈鸿蒙学习资料）

• 鸿蒙开发核心知识点，看这篇文章就够了

• 最新版！鸿蒙HarmonyOS Next应用开发实战学习路线

• 鸿蒙HarmonyOS NEXT开发技术最全学习路线指南

• 鸿蒙应用开发实战项目，看这一篇文章就够了（部分项目附源码）

---

List

列表包含一系列相同宽度的列表项。适合连续、多行呈现同类数据，例如图片和文本。

说明

• 该组件从API Version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。

• 该组件内容区小于一屏时，默认没有回弹效果。需要回弹效果，可以通过edgeEffect属性的options参数进行设置。

• List组件通用属性clip的默认值为true。

• 要使List处于可编辑模式需配合onItemDelete事件和ListItem的editable属性，即可编辑模式实现删除列表项功能，需满足以下条件（该功能从API9开始废弃）：

  • editMode属性设置为true。

  • 绑定onItemDelete事件，且事件回调返回true。

  • ListItem的editable属性设置为true。

• 实现ListItem拖拽，需满足以下条件：

  • editMode属性设置为true（从API9开始无需设置editMode属性）。

  • 绑定onDragStart事件，且事件回调中返回浮动UI布局。

子组件

仅支持ListItem、ListItemGroup子组件，支持渲染控制类型（if/else、ForEach、LazyForEach和Repeat）。

说明

List的子组件的索引值计算规则：

按子组件的顺序依次递增。

if/else语句中，只有条件成立的分支内的子组件会参与索引值计算，条件不成立的分支内子组件不计算索引值。

ForEach/LazyForEach/Repeat语句中，会计算展开所有子节点索引值。

if/else、ForEach、LazyForEach和Repeat发生变化以后，会更新子节点索引值。

ListItemGroup作为一个整体计算一个索引值，ListItemGroup内部的ListItem不计算索引值。

List子组件visibility属性设置为Hidden或None依然会计算索引值。

List子组件的visibility属性设置为None时不显示，但该子组件上下的space还会生效。

接口

List(value?:{space?: number | string, initialIndex?: number, scroller?: Scroller})

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
space	number | string	否	子组件主轴方向的间隔。 默认值：0 参数类型为number时单位为vp 说明： 设置为负数或者大于等于List内容区长度时，按默认值显示。 space参数值小于List分割线宽度时，子组件主轴方向的间隔取分割线宽度。
initialIndex	number	否	设置当前List初次加载时显示区域起始位置的item索引值。 默认值：0 说明： 设置为负数或超过了当前List最后一个item的索引值时视为无效取值，无效取值按默认值显示。
scroller	Scroller	否	可滚动组件的控制器。用于与可滚动组件进行绑定。 说明： 不允许和其他滚动类组件绑定同一个滚动控制对象。

属性

除支持通用属性和滚动组件通用属性外，还支持以下属性：

listDirection

listDirection(value: Axis)

设置List组件排列方向。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	Axis	是	组件的排列方向。 默认值：Axis.Vertical

divider

divider(value: {strokeWidth: Length; color?: ResourceColor; startMargin?: Length; endMargin?: Length;} | null,)

设置ListItem分割线样式，默认无分割线。

endMargin + startMargin 超过列宽度后startMargin和endMargin会置0。

strokeWidth, startMargin和endMargin不支持设置百分比。

List的分割线画在主轴方向两个子组件之间，第一个子组件上方和最后一个子组件下方不会绘制分割线。

多列模式下，ListItem与ListItem之间的分割线起始边距从每一列的交叉轴方向起始边开始计算，其他情况从List交叉轴方向起始边开始计算。

ListItem设置多态样式时，被按压的子组件上下的分割线不绘制。

卡片能力： 从API version 9开始，该接口支持在ArkTS卡片中使用。

元服务API： 从API version 11开始，该接口支持在元服务中使用。

系统能力： SystemCapability.ArkUI.ArkUI.Full

参数：

参数名	类型	必填	说明
value	{ strokeWidth: Length, color?:ResourceColor, startMargin?: Length, endMargin?: