企业官网建设流程全解析

• 文档
• 知识库
• 教程
• OpenHarmony

本文以 OpenHarmony 仓颉（Cangjie）ArkUI 声明式开发框架中的ListItem组件为对象，系统讲解其创建方式、selectable可选性控制、swipeAction划出组件配置与onSelect选择回调，并结合仓库中的 List 容器、SwipeEdgeEffect枚举与侧滑删除实战代码，帮助开发者快速掌握列表项组件的全部能力。

ListItem 是什么

ListItem是 ArkUI 声明式 UI 中用来展示列表具体item（列表项）的容器组件，必须配合 List 组件来使用，其父组件只能是List。在 List 组件参考文档中明确说明：List的子组件仅支持ListItem与ListItemGroup，而 ListItemGroup 的子组件又只能是ListItem。因此三者构成了"容器 → 分组 → 列表项"的层级关系。

从列表开发指南可知，ListItem表示单个列表项，可以包含单个子组件；List作为容器会自动按滚动方向排列子组件，向列表中添加或移除组件会重新排列。典型的应用场景包括通讯录、消息列表、购物清单、设置页等需要连续展示同类数据的界面。

导入模块与基本结构

使用ListItem前需要导入 ArkUI 声明式开发接口：

import kit.ArkUI.*

ListItem的子组件规则为：可以包含单个子组件。也就是说，一个ListItem内部只允许声明一个直接的子组件，如果希望同时展示多个元素，应使用Column、Row、Flex、Stack等布局容器进行组合。

说明：List的子组件索引值按子组件顺序依次递增；ListItemGroup作为一个整体计算一个索引值，其内部的ListItem不参与索引值计算；if/else中只有条件成立分支内的子组件参与索引值计算；ForEach/LazyForEach会展开计算所有子节点索引值。

创建 ListItem 组件

init(() -> Unit)

ListItem的构造函数用于创建一个列表项组件：

public init(child: () -> Unit)

功能：创建ListItem组件。系统能力：SystemCapability.ArkUI.ArkUI.Full起始版本：22

参数：

child是声明式闭包，内部编写的组件树即为列表项的实际内容。由于ListItem只支持单个直接子组件，child内通常是一个布局容器（如Column、Row、Flex），或单个文本、图片等基础组件。

ListItem支持全部通用属性和全部通用事件，这意味着诸如宽高、背景、边框、圆角、对齐、id、点击事件（onClick）等能力都可以直接作用于ListItem本身。

使用 List 容器承载 ListItem

由于ListItem必须配合List使用，这里先给出 List 的初始化方法，方便后续示例理解：

public init( space!: ?Int64 = None, initialIndex!: ?Int32 = None, scroller!: ?Scroller = Option<Scroller>.None, child!: () -> Unit )

在 List 中还有若干与ListItem密切相关的容器级属性：

• lanes(?Int32)：设置列表中列或行的数量，初始值 1（单列）。也支持lanes(minLength!: ?Length, maxLength!: ?Length)按最小/最大长度自适应确定列数。
• alignListItem(?ListItemAlign)：当 List 交叉轴宽度大于ListItem交叉轴宽度 × lanes 时，设置ListItem在交叉轴方向的布局方式，初始值ListItemAlign.Start。
• multiSelectable(?Bool)：是否启用多选，初始值 false。
• cachedCount(?Int32)：设置列表项的预加载数量，初始值 1，配合LazyForEach懒加载可减少滑动白块，但会增大 CPU、内存开销。
• divider(Option<ListDividerOptions>)：设置列表项分割线样式，默认无分割线。

组件属性

func selectable(?Bool)：控制列表项是否可选择

public func selectable(value: ?Bool): This

功能：设置当前ListItem元素是否可选择。系统能力：SystemCapability.ArkUI.ArkUI.Full起始版本：22

参数：

selectable决定该列表项是否参与选择交互。当设置为false时，该列表项将不会被选中（例如点击选中、键盘焦点选中等），典型使用场景是列表中的"禁用项"、分隔项或仅展示不可操作的条目。它与List的multiSelectable共同构成选择体系的开关：容器决定是否允许多选，单个ListItem决定自身是否可选。

func swipeAction(...)：设置 ListItem 的划出组件

swipeAction是ListItem最常用的交互能力，用于实现列表项左右滑动后露出操作按钮的"侧滑菜单"效果（如侧滑删除、置顶、收藏等）：

public func swipeAction( start!: ?CustomBuilder = None, end!: ?CustomBuilder = None, edgeEffect!: ?SwipeEdgeEffect = Option.None, onOffsetChange!: ?(Float64) -> Unit = None ): This

功能：用于设置ListItem的划出组件。系统能力：SystemCapability.ArkUI.ArkUI.Full起始版本：22

参数：

四个参数全部为命名参数，其中start与end的类型 CustomBuilder 是() -> Unit的类型别名，即一个无参无返回值的闭包，内部编写滑出组件的内容。

start与end的方向语义与 List 的滚动方向有关：

• List 垂直布局（默认）：start是右滑时左侧划出的组件，end是左滑时右侧划出的组件；
• List 水平布局：start是下滑时上方划出的组件，end是上滑时下方划出的组件。

SwipeEdgeEffect 滑动效果枚举

SwipeEdgeEffect 枚举定义于cj-common-types.md，具体定义如下：

public enum SwipeEdgeEffect <: Equatable<SwipeEdgeEffect> { | Spring | None | ... }

• SwipeEdgeEffect.Spring允许"过度滑动"并回弹，交互反馈更生动，是默认的滑动效果；
• SwipeEdgeEffect.None将划动距离限制在划出组件的大小内，滑动更干脆、可控。

该枚举实现了Equatable<SwipeEdgeEffect>，并提供了==与!=运算符用于判断两个滑动效果是否相等。

onOffsetChange 偏移量回调

onOffsetChange在滑动偏移量发生变化时回调，回调参数为当前偏移量（Float64类型）。开发者可以借此实现滑出组件随滑动距离动态变化的联动效果，例如：

• 滑出按钮透明度随偏移量渐变；
• 偏移量超过阈值时高亮显示"确认删除"状态；
• 与edgeEffect配合实现"超过最大偏移触发回弹/粘滞"等自定义手势逻辑。

组件事件

func onSelect(?(Bool) -> Unit)：选择状态变化回调

public func onSelect(event: ?(Bool) -> Unit): This

功能：ListItem 元素被选择的状态改变时触发回调。系统能力：SystemCapability.ArkUI.ArkUI.Full起始版本：22

参数：

回调参数res表示选择状态：true表示该列表项被选中，false表示被取消选中。注意该事件与selectable(true)配合才有意义——若某列表项selectable(false)，则不会触发选择状态变化。典型用途：

• 单选场景下高亮当前选中项并记录选中索引；
• 多选模式下维护已选集合、联动"全选"按钮状态；
• 将选择状态同步到数据源或服务端。

完整示例：创建 ListItem 的基本用法

文档示例通过List+ForEach循环渲染 10 个ListItem，每个列表项内放置一个居中的Text文本：

package ohos_app_cangjie_entry import kit.ArkUI.* import ohos.arkui.state_macro_manage.* @Entry @Component class EntryView { let arr = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] func build() { 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) } } ) } .scrollBar(BarState.Off) .width(90.percent) } .width(100.percent) .height(100.percent) .backgroundColor(0xDCDCDC) .padding(top: 5.px) } }

示例要点解读：

1. 数据源：let arr = [0, 1, 2, ..., 9]定义 10 个列表项数据。
2. List 容器：List(space: 20, initialIndex: 0)设置列表项主轴间隔 20，首次加载从索引 0 开始显示；.scrollBar(BarState.Off)关闭滚动条。
3. ForEach 循环渲染：ForEach(this.arr, itemGeneratorFunc: {item: Int64, _: Int64 => ListItem() {...}})基于数据源逐一生成ListItem，item为当前数据、第二个参数为索引。关于ForEach的详细用法可参考循环渲染。
4. 列表项样式：每个ListItem内只有一个Text子组件（符合"仅包含单个子组件"的约束），并设置了宽高、字号、居中、圆角与背景色。

实战进阶：基于 swipeAction 实现侧滑删除

列表开发指南中给出了"响应列表项侧滑"的完整实战方案，这是swipeAction最典型的落地场景（如通讯录消息列表左滑删除）。

其实现思路为：end参数对应 ListItem 左滑时尾端划出的自定义组件（即删除按钮）；初始化end时将当前列表项的索引传入删除按钮组件，用户点击删除按钮时依据索引删除对应数据。

第一步：构建尾端滑出组件

使用@Builder定义一个接收索引参数的构建函数，内部放置圆形删除按钮：

@Builder func itemEnd(index: Int64) { // 构建尾端滑出组件 Button(ButtonOptions(shape: ButtonType.Circle)) { Image(@r(app.media.ic_public_delete_filled)) .width(20) .height(20) } .onClick({ event => // this.messages为列表数据源，可根据实际场景构造。点击后从数据源删除指定数据项。 this.message.remove(index) }) }

第二步：将 swipeAction 绑定到 ListItem

通过ForEach基于数据源循环渲染ListItem，并将索引index绑定到itemEnd：

// 构建List时，通过ForEach基于数据源this.messages循环渲染ListItem。 ListItem(){ Text('1111').height(20) } .swipeAction(end: { => bind(this.itemEnd, this)(index)}) // index为该ListItem在List中的索引值

这里使用bind(this.itemEnd, this)(index)将成员函数itemEnd绑定到组件实例并传入当前索引，从而让每个列表项的删除按钮都对应自己的数据下标。当用户左滑列表项露出删除按钮并点击后，即可从数据源中删除对应条目，实现侧滑删除。

小结

ListItem是 ArkUI 列表体系的基石组件，围绕它可以快速构建出功能完整、交互丰富的列表界面：

• 基础能力：配合 List 容器，通过init(child)声明单个子组件，并支持全部通用属性与通用事件；
• 选择能力：selectable控制单个列表项是否可选，onSelect监听选择状态变化，与List的multiSelectable搭配实现单选/多选；
• 侧滑能力：swipeAction(start/end/edgeEffect/onOffsetChange)配置左右划出组件，配合 SwipeEdgeEffect 的Spring/None两种滑动效果与onOffsetChange偏移量回调，可实现侧滑删除、置顶、收藏等常见交互，并支持水平与垂直两种列表方向的划出语义。

如需深入了解列表容器的分组、懒加载、多列布局等能力，可继续阅读 List、ListItemGroup 组件参考，以及创建列表（List）开发指南。

• 文档
• 知识库
• 教程
• OpenHarmony