仓颉鸿蒙HarmonyOS NEXT原生UI组件List（安卓Flutter的ListView，iOS的UITableView）
百分之百的移动App都需要用到的组件List，不容错过的UI组件
一个包含一系列相同宽度的列表项的容器组件。适合连续、多行呈现同类数据，例如图片和文本。
子组件
仅支持ListItem、ListItemGroup子组件。
构造函数
说明
混合页面场景下List创建时仅支持space参数。
init(Int64, Int32, Scroller, () -> Unit)
public init(space!: Int64 = spaceDefault, initialIndex!: Int32 = initialIndexDefault, scroller!: ?Scroller = Option<Scroller>.None, child!: () -> Unit)
创建一个可包含子组件的List容器。
| 参数名 | 参数类型 | 必填 | 默认值 | 描述 |
|---|---|---|---|---|
| space | Int64 | 否 | 0 | 列表项间距。 |
| initialIndex | Int32 | 否 | 0 | list内容长度需要超过list容器长度时生效。设置当前List初次加载时视口起始位置显示的item，即显示第一个item，如果设置的值超过了当前List最后一个item的索引值，则设置为不生效。 |
| scroller | Option |
否 | Option |
可滚动组件的控制器。用于与可滚动组件进行绑定。 |
| child | () -> Unit | 否 | 声明容器内的ListItem子组件。 |
函数
listDirection(Axis)
public func listDirection(value: Axis): This
设置List组件排列方向。
| 参数名 | 参数类型 | 必填 | 默认值 | 描述 |
|---|---|---|---|---|
| value | Axis | 是 | - | 组件排列方向参照Axis枚举说明。 |
divider(Length, Color, Length, Length)
public func divider(strokeWidth!: Length, color!: Color = Color.BLACK, startMargin!: Length = 0.vp, endMargin!: Length = 0.vp): This
用于设置ListItem分割线样式，默认无分割线。
| 参数名 | 参数类型 | 必填 | 默认值 | 描述 |
|---|---|---|---|---|
| strokeWidth | Length | 是 | - | 分割线的线宽。 |
| color | Color | 否 | Color.BLACK | 分割线的颜色。 |
| startMargin | Length | 否 | 0.vp | 分割线距离列表侧边起始端的距离。 |
| endMargin | Length | 否 | 0.vp | 分割线距离列表侧边结束端的距离。 |
divider(Length, CJResource, Length, Length)
public func divider(strokeWidth!: Length, color!: CJResource, startMargin!: Length = 0.vp, endMargin!: Length= 0.vp): This
用于设置ListItem分割线样式，默认无分割线。
| 参数名 | 参数类型 | 必填 | 默认值 | 描述 |
|---|---|---|---|---|
| strokeWidth | Length | 是 | - | 分割线的线宽。 |
| color | CJResource | 是 | - | 分割线的颜色。 |
| startMargin | Length | 否 | 0.vp | 分割线距离列表侧边起始端的距离。 |
| endMargin | Length | 否 | 0.vp | 分割线距离列表侧边结束端的距离。 |
divider(CJResource, Color, CJResource, CJResource)
public func divider(strokeWidth!: CJResource, color!: Color, startMargin!: CJResource, endMargin!: CJResource): This
用于设置ListItem分割线样式，默认无分割线。
| 参数名 | 参数类型 | 必填 | 默认值 | 描述 |
|---|---|---|---|---|
| strokeWidth | CJResource | 是 | - | 分割线的线宽。 |
| color | Color | 是 | - | 分割线的颜色。 |
| startMargin | CJResource | 是 | - | 分割线距离列表侧边起始端的距离。 |
| endMargin | CJResource | 是 | - | 分割线距离列表侧边结束端的距离。 |
divider(CJResource, CJResource, CJResource, CJResource)
public func divider(strokeWidth!: CJResource, color!: CJResource, startMargin!: CJResource, endMargin!: CJResource): This
用于设置ListItem分割线样式，默认无分割线。
| 参数名 | 参数类型 | 必填 | 默认值 | 描述 |
|---|---|---|---|---|
| strokeWidth | CJResource | 是 | - | 分割线的线宽。 |
| color | CJResource | 是 | - | 分割线的颜色。 |
| startMargin | CJResource | 是 | - | 分割线距离列表侧边起始端的距离。 |
| endMargin | CJResource | 是 | - | 分割线距离列表侧边结束端的距离。 |
scrollBar(BarState)
public func scrollBar(value: BarState): This
设置滚动条状态。
| 参数名 | 参数类型 | 必填 | 默认值 | 描述 |
|---|---|---|---|---|
| value | BarState | 是 | BarState.Auto | 滚动条状态。 |
cachedCount(Int32)
public func cachedCount(value: Int32): This
设置列表中ListItem/ListItemGroup的预加载数量。
| 参数名 | 参数类型 | 必填 | 默认值 | 描述 |
|---|---|---|---|---|
| value | Int32 | 是 | - | 列表中ListItem/ListItemGroup的预加载数量，其中ListItemGroup将作为一个整体进行计算，ListItemGroup中的所有ListItem会一次性全部加载出来。具体使用可参考减少应用白块说明。 |
editMode(Bool)
public func editMode(flag: Bool): This
设置当前List组件是否处于可编辑模式。
| 参数名 | 参数类型 | 必填 | 默认值 | 描述 |
|---|---|---|---|---|
| flag | Bool | 是 | - | 当前List组件是否处于可编辑模式。 |
edgeEffect(EdgeEffect)
public func edgeEffect(value: EdgeEffect): This
设置组件的滑动效果。
| 参数名 | 参数类型 | 必填 | 默认值 | 描述 |
|---|---|---|---|---|
| value | EdgeEffect | 是 | EdgeEffect.Spring | 设置组件的滑动效果。 |
chainAnimation(Bool)
public func chainAnimation(flag: Bool): This
设置当前List是否启用链式联动动效，开启后列表滑动以及顶部和底部拖拽时会有链式联动的效果。链式联动效果：List内的list-item间隔一定距离，在基本的滑动交互行为下，主动对象驱动从动对象进行联动，驱动效果遵循弹簧物理动效。
| 参数名 | 参数类型 | 必填 | 默认值 | 描述 |
|---|---|---|---|---|
| flag | Bool | 是 | - | 当前List是否启用链式联动动效。- false：不启用链式联动。- true：启用链式联动。说明：链式动效生效后，List的分割线不显示。链式动效生效需要满足以下前提条件：- List边缘效果为Spring类型。- List没有启用多列模式。 |
multiSelectable(Bool)
public func multiSelectable(flag: Bool): This
是否开启鼠标框选。
| 参数名 | 参数类型 | 必填 | 默认值 | 描述 |
|---|---|---|---|---|
| flag | Bool | 是 | - | 是否开启鼠标框选。- false：关闭框选。- true：开启框选。 |
lanes(Int32)
public func lanes(value: Int32): This
设置List组件在交叉轴方向的子组件个数。
| 参数名 | 参数类型 | 必填 | 默认值 | 描述 |
|---|---|---|---|---|
| value | Int32 | 是 | - | 设置List组件在交叉轴方向的子组件个数。 根据指定的数量与List组件的交叉轴宽度来决定每列的宽度。 |
lanes(Length, Length)
public func lanes(minLength!: Length, maxLength!: Length): This
设置List组件在交叉轴方向的子组件的最小和最大宽度的限制。（其中，minLength条件会被优先满足，即优先保证符合ListItem的宽度符合最小宽度限制。）
| 参数名 | 参数类型 | 必填 | 默认值 | 描述 |
|---|---|---|---|---|
| minLength | Length | 是 | - | 最小宽度限制。 |
| maxLength | Length | 是 | - | 最大宽度限制。 |
alignListItem(ListItemAlign)
public func alignListItem(value: ListItemAlign): This
设置ListItem在List交叉轴方向的布局方式。
| 参数名 | 参数类型 | 必填 | 默认值 | 描述 |
|---|---|---|---|---|
| value | ListItemAlign | 是 | - | List交叉轴方向宽度大于ListItem交叉轴宽度 * lanes时，ListItem在List交叉轴方向的布局方式，默认为首部对齐。 |
sticky(StickyStyle)
public func sticky(value: StickyStyle): This
设置ListItemGroup中header和footer是否要吸顶或吸底。
| 参数名 | 参数类型 | 必填 | 默认值 | 描述 |
|---|---|---|---|---|
| value | StickyStyle | 是 | - | 配合ListItemGroup组件使用，设置ListItemGroup中header和footer是否要吸顶或吸底。 |
nestedScroll(NestedScrollOptions)
public func nestedScroll(value: NestedScrollOptions): This
设置向前向后两个方向上的嵌套滚动模式，实现与父组件的滚动联动。
| 参数名 | 参数类型 | 必填 | 默认值 | 描述 |
|---|---|---|---|---|
| value | NestedScrollOptions | 是 | - | 设置向前向后两个方向上的嵌套滚动模式，实现与父组件的滚动联动。 |
枚举说明
Axis
组件排列方向。
| 枚举值 | 描述 |
|---|---|
| Vertical | 方向为纵向。 |
| Horizontal | 方向为横向。 |
ListItemAlign
ListItem在List中，交叉轴方向的对齐方式。
| 枚举值 | 描述 |
|---|---|
| Start | ListItem在List中，交叉轴方向首部对齐。 |
| Center | ListItem在List中，交叉轴方向居中对齐。 |
| End | ListItem在List中，交叉轴方向尾部对齐。 |
StickyStyle
ListItemGroup的header和footer是否吸顶或吸底。
| 枚举值 | 描述 |
|---|---|
| None | ListItemGroup的header不吸顶，footer不吸底。 |
| Header | ListItemGroup的header吸顶。 |
| Footer | ListItemGroup的footer吸底。 |
| Both | ListItemGroup的headerh吸顶，footer吸底。 |
BarState
滚动条的状态。
| 枚举值 | 描述 |
|---|---|
| Off | 不显示。 |
| Auto | 按需显示(触摸时显示，2s后消失)。 |
| On | 常驻显示。 |
ScrollState
滑动状态。
| 枚举值 | 描述 |
|---|---|
| Idle | 未滑动状态。 |
| Scrolling | 手指拖动状态。 |
| Fling | 惯性滑动状态。 |
NestedScrollMode
可滚动组件的嵌套滚动选项。
| 枚举值 | 描述 |
|---|---|
| SELF_ONLY | 只自身滚动，不与父组件联动。 |
| SELF_FIRST | 自身先滚动，自身滚动到边缘以后父组件滚动。父组件滚动到边缘以后，如果父组件有边缘效果，则父组件触发边缘效果，否则子组件触发边缘效果。 |
| PARENT_FIRST | 父组件先滚动，父组件滚动到边缘以后自身滚动。自身滚动到边缘后，如果有边缘效果，会触发自身的边缘效果，否则触发父组件的边缘效果。 |
| PARALLEL | 自身和父组件同时滚动，自身和父组件都到达边缘以后，如果自身有边缘效果，则自身触发边缘效果，否则父组件触发边缘效果。 |
自定义类型说明
NestedScrollOptions
public NestedScrollOptions(scrollForward: NestedScrollMode, let scrollBackward: NestedScrollMode)
创建一个NestedScrollOptions类型的对象。
| 参数名 | 参数类型 | 必填 | 默认值 | 属性描述 |
|---|---|---|---|---|
| scrollForward | NestedScrollMode | 是 | - | 可滚动组件往末尾端滚动时的嵌套滚动选项。 |
| scrollBackward | NestedScrollMode | 是 | - | 可滚动组件往起始端滚动时的嵌套滚动选项。 |
事件
onItemDelete((Int32) -> Bool)
public func onItemDelete(callback: (Int32) -> Bool): This
当List组件在编辑模式时，点击ListItem右边出现的删除按钮时触发。
说明
onItemDelete暂不支持混合页面场景。
| 参数名 | 参数类型 | 描述 |
|---|---|---|
| callback | (Int32) -> Bool | 当List组件在编辑模式时，点击ListItem右边出现的删除按钮时触发。从API version9开始废弃。 |
onScroll(Float64, ScrollState) -> Unit
public func onScroll(callback: (Float64, ScrollState) -> Unit): This
列表滑动时触发。
说明
onScroll暂不支持混合页面场景。
| 参数名 | 参数类型 | 描述 |
|---|---|---|
| callback | (Float64, ScrollState) -> Unit | 列表滑动时触发。- 第一个参数: 滑动偏移量。- 第二个参数: ScrollState，当前滑动状态。 |
onScrollIndex((Int32, Int32) -> Unit)
public func onScrollIndex(callback: (Int32, Int32) -> Unit): This
列表滑动时触发，获取滑动起始位置索引值和滑动结束位置索引值。
说明
onScrollIndex暂不支持混合页面场景。
| 参数名 | 参数类型 | 描述 |
|---|---|---|
| callback | (Int32, Int32) -> Unit | 列表滑动事件回调。计算索引值时，ListItemGroup作为一个整体占一个索引值，不计算ListItemGroup内部ListItem的索引值。- 第一个参数: 滑动起始位置索引值。- 第二个参数: 滑动结束位置索引值。 |
onReachStart(() -> Unit)
public func onReachStart(callback: () -> Unit): This
列表到达起始位置时触发。
说明
onReachStart暂不支持混合页面场景。
| 参数名 | 参数类型 | 描述 |
|---|---|---|
| callback | () -> Unit | 列表到达起始位置事件回调。 |
onReachEnd(() -> Unit)
public func onReachEnd(callback: () -> Unit): This
列表到底末尾位置时触发。
说明
onReachEnd暂不支持混合页面场景。
| 参数名 | 参数类型 | 描述 |
|---|---|---|
| callback | () -> Unit | 列表到底末尾位置事件回调。 |
onScrollStart(() -> Unit)
public func onScrollStart(callback: () -> Unit): This
列表滑动开始时触发。
说明
onScrollStart暂不支持混合页面场景。
| 参数名 | 参数类型 | 描述 |
|---|---|---|
| callback | () -> Unit | 列表滑动开始事件回调。。手指拖动列表或列表的滚动条触发的滑动开始时，会触发该事件。使用Scroller滑动控制器触发的带动画的滑动，动画开始时会触发该事件。 |
onScrollStop(() -> Unit)
public func onScrollStop(callback: () -> Unit): This
列表滑动停止时触发。
说明
onScrollStop暂不支持混合页面场景。
| 参数名 | 参数类型 | 描述 |
|---|---|---|
| callback | () -> Unit | 列表滑动停止事件回调。。手拖动列表或列表的滚动条触发的滑动，手离开屏幕并且滑动停止时会触发该事件；使用Scroller滑动控制器触发的滑动，不会触发该事件。 |
onScrollFrameBegin((Float64, ScrollState) -> Float64)
public func onScrollFrameBegin(callback: (Float64, ScrollState) -> Float64): This
列表开始滑动时触发。
说明
onScrollFrameBegin暂不支持混合页面场景。
| 参数名 | 参数类型 | 描述 |
|---|---|---|
| callback | (Float64, ScrollState) -> Float64 | 列表开始滑动事件回调，事件参数传入即将发生的滑动量，事件处理函数中可根据应用场景计算实际需要的滑动量并作为事件处理函数的返回值返回，列表将按照返回值的实际滑动量进行滑动。- 第一个参数：即将发生的滑动量，单位vp。- 第二个参数：当前滑动状态。- 第三个参数：实际滑动量，单位vp。触发该事件的条件：手指拖动List、List惯性划动时每帧开始时触发；List超出边缘回弹、使用滚动控制器和拖动滚动条的滚动不会触发。 |
示例代码
示例1：创建纵向排列的ListItem。
import ohos.base.*
import ohos.component.*
import ohos.state_manage.*
import ohos.state_macro_manage.*
import std.collection.*
@Entry
@Component
class MyView {
let arr =[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
func build() {
Stack(Alignment.TopStart){
Column() {
List( space: 20, initialIndex: 0 ) {
ForEach(this.arr, itemGeneratorFunc: {item:Int64,_:Int64 =>
ListItem() {
Text("${item}")
.width(100.percent).height(100).fontSize(16)
.textAlign(TextAlign.Center).borderRadius(10).backgroundColor(0xFFFFFF)
}
})
}.id("list")
.listDirection(Axis.Vertical) // 排列方向
.scrollBar(BarState.Off)
//.friction(0.6)
.divider(strokeWidth: 2.px, color: Color(0xFFFFFF), startMargin: 20.px, endMargin: 20.px) // 每行之间的分界线
.edgeEffect(EdgeEffect.Spring) // 边缘效果设置为Spring
.onScrollIndex({firstIndex: Int32, lastIndex: Int32 =>
BaseLog.info("first" + firstIndex.toString())
BaseLog.info("last" + lastIndex.toString())
})
.width(90.percent)
}
.width(100.percent)
.height(100.percent)
.backgroundColor(0xDCDCDC)
.padding(top: 5.px )
}
}
}
示例2：设定List在交叉轴的对齐方式。
import ohos.base.*
import ohos.component.*
import ohos.state_manage.*
import ohos.state_macro_manage.*
import std.collection.*
@Entry
@Component
class MyView {
let arr: Array<String> = ["0", "1", "2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "12", "13", "14", "15",
"16", "17", "18", "19"]
@State var alignListItem: ListItemAlign = ListItemAlign.Start
func build() {
Column() {
List(space: 20, initialIndex: 0) {
ForEach(
this.arr,
itemGeneratorFunc: {
item: String, _: Int64 => ListItem() {
Text("${item}")
.width(100.percent)
.height(100)
.fontSize(16)
.textAlign(TextAlign.Center)
.borderRadius(10).backgroundColor(0xFFFFFF)
}.border(width: 2.px, color: Color.GREEN).width(55)
}
)
}
.height(300)
.width(90.percent)
.border(width: 3.px, color: Color.RED)
.lanes(7)
.alignListItem(
this.alignListItem)
.scrollBar(BarState.Off)
Button("点击更改alignListItem:${this.alignListItem.getValue()}").onClick(
{
event => match (this.alignListItem) {
case ListItemAlign.Start =>
this.alignListItem = ListItemAlign.Center
case ListItemAlign.Center =>
this.alignListItem = ListItemAlign.End
case ListItemAlign.End =>
this.alignListItem = ListItemAlign.Start
}
})
}.width(100.percent).height(100.percent).backgroundColor(0xDCDCDC).padding(top: 5.px)
}
}
示例3：删除指定ListItem。
import ohos.base.*
import ohos.component.*
import ohos.state_manage.*
import ohos.state_macro_manage.*
import std.collection.*
@Entry
@Component
class MyView {
@State var arr:ObservedArrayList<Int64> = ObservedArrayList<Int64>([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])
@State var editFlag: Bool = false
func build() {
Stack( Alignment.TopStart ) {
Column() {
List(space: 20, initialIndex: 0 ) {
ForEach(this.arr, itemGeneratorFunc:{item: Int64,index: Int64 =>
ListItem() {
Flex(FlexParams(direction:FlexDirection.Row, alignItems:ItemAlign.Center)) {
Text("${item}" )
.width(100.percent)
.height(80)
.fontSize(20)
.textAlign(TextAlign.Center)
.borderRadius(10)
.backgroundColor(0xFFFFFF)
.flexShrink(1)
if (this.editFlag) {
Button() {
Text("delete").fontSize(16)
}.width(30.percent).height(40)
.onClick({event =>
if (index >=0 && index<this.arr.size) {
//BaseLog.info( "${this.arr[index]}Delete")
this.arr.remove(index)
//AppLog.info(this.arr.size.toString())
this.editFlag = false
}
}).stateEffect(true)
}
}
}
})
}.width(90.percent)
.scrollBar(BarState.Off)
}.width(100.percent)
Button("edit list")
.onClick({event=>
this.editFlag = !this.editFlag
}).margin(top: 5, left: 20 )
}.width(100.percent).height(100.percent).backgroundColor(0xDCDCDC).padding(top: 5)
}
}
示例4：创建横向排列的List。
import ohos.base.*
import ohos.component.*
import ohos.state_manage.*
import ohos.state_macro_manage.*
import std.collection.*
@Entry
@Component
class MyView {
let arr: ArrayList<Int64> = ArrayList<Int64>([0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19])
let scrollerForList = Scroller()
func build() {
Column() {
Row() {
List(space: 20, initialIndex: 3, scroller: this.scrollerForList ) {
ForEach(this.arr, itemGeneratorFunc:{item:Int64,_:Int64=>
ListItem() {
Text("${item}")
.width(100.percent).height(100).fontSize(16)
.textAlign(TextAlign.Center)
}
.borderRadius(10).backgroundColor(0xFFFFFF)
.width(60.percent)
.height(80.percent)
} )
}
.chainAnimation(true)
.edgeEffect(EdgeEffect.Spring)
.listDirection(Axis.Horizontal)
.height(100.percent)
.width(100.percent)
.borderRadius(10.px)
.backgroundColor(0xDCDCDC)
}
.width(100.percent)
.height(100.percent)
.backgroundColor(0xDCDCDC)
.padding(top: 10.px )
}
}
}
还没有申请仓颉内测资格的朋友可以看一下下面这篇文章
华为仓颉编程语言内测申请攻略《附带仓颉鸿蒙开发权限》
如对您有帮助，帮忙点个“在看 、关注” 让更多的人受益~！
技术交流群可加wx“LB-9191” 备注cangjie
浙公网安备 33010602011771号