仓颉 ArkUI ListItem 组件完全指南：从基础创建到侧滑交互实战

文档知识库教程OpenHarmony【免费下载链接】CangjieCorpus本仓库为仓颉编程语言语料库聚焦 仓颉编程语言 核心知识体系整合官方开发指南、API 文档、典型代码示例及语法规范等多维度资源经结构化处理与专业标注构建为支持 RAG检索增强生成技术 的高质量知识基座适配智能编码助手、学习辅助工具等应用开发需求。 欢迎开发者基于本语料库构建仓颉语言智能应用推动鸿蒙开发生态智能化升级项目地址https://gitcode.com/Cangjie/CangjieCorpus点击查看免费下载本文以 OpenHarmony 仓颉CangjieArkUI 声明式开发框架中的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() - Unit是-容器内的 ListItem 子组件。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 OptionScroller.None, child!: () - Unit )参数名类型必填默认值说明space?Int64否None子组件主轴方向的间隔。initialIndex?Int32否None设置 List 初次加载时视口起始位置显示的 item若设置值超过最后一个 item 的索引则不生效。scroller?Scroller否OptionScroller.None可滚动组件的控制器用于与可滚动组件绑定。child() - Unit是-声明容器内的 List 子组件。在 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(OptionListDividerOptions)设置列表项分割线样式默认无分割线。组件属性func selectable(?Bool)控制列表项是否可选择public func selectable(value: ?Bool): This功能设置当前ListItem元素是否可选择。系统能力SystemCapability.ArkUI.ArkUI.Full起始版本22参数参数名类型必填默认值说明value?Bool是-ListItem 元素是否可选择。初始值true。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?CustomBuilder否None命名参数。ListItem 向右划动时 item 左边的组件List 垂直布局时或 ListItem 向下划动时 item 上方的组件List 水平布局时。初始值{}。end?CustomBuilder否None命名参数。ListItem 向左划动时 item 右边的组件List 垂直布局时或 ListItem 向上划动时 item 下方的组件List 水平布局时。初始值{}。edgeEffect?SwipeEdgeEffect否Option.None命名参数。滑动效果。初始值SwipeEdgeEffect.Spring。onOffsetChange?(Float64) - Unit否None命名参数。滑动操作偏移量更改时调用。初始值{_: Float64 }。四个参数全部为命名参数其中start与end的类型 CustomBuilder 是() - Unit的类型别名即一个无参无返回值的闭包内部编写滑出组件的内容。start与end的方向语义与 List 的滚动方向有关List 垂直布局默认start是右滑时左侧划出的组件end是左滑时右侧划出的组件List 水平布局start是下滑时上方划出的组件end是上滑时下方划出的组件。SwipeEdgeEffect 滑动效果枚举SwipeEdgeEffect 枚举定义于cj-common-types.md具体定义如下public enum SwipeEdgeEffect : EquatableSwipeEdgeEffect { | Spring | None | ... }枚举值功能说明SpringListItem 划动距离超过划出组件大小后可以继续划动松手后按照弹簧阻尼曲线回弹。NoneListItem 划动距离不能超过划出组件大小。SwipeEdgeEffect.Spring允许过度滑动并回弹交互反馈更生动是默认的滑动效果SwipeEdgeEffect.None将划动距离限制在划出组件的大小内滑动更干脆、可控。该枚举实现了EquatableSwipeEdgeEffect并提供了与!运算符用于判断两个滑动效果是否相等。onOffsetChange 偏移量回调onOffsetChange在滑动偏移量发生变化时回调回调参数为当前偏移量Float64类型。开发者可以借此实现滑出组件随滑动距离动态变化的联动效果例如滑出按钮透明度随偏移量渐变偏移量超过阈值时高亮显示确认删除状态与edgeEffect配合实现超过最大偏移触发回弹/粘滞等自定义手势逻辑。组件事件func onSelect(?(Bool) - Unit)选择状态变化回调public func onSelect(event: ?(Bool) - Unit): This功能ListItem 元素被选择的状态改变时触发回调。系统能力SystemCapability.ArkUI.ArkUI.Full起始版本22参数参数名类型必填默认值说明event?(Bool) - Unit是-选择状态改变时的回调函数。初始值{ res: Bool }。回调参数res表示选择状态true表示该列表项被选中false表示被取消选中。注意该事件与selectable(true)配合才有意义——若某列表项selectable(false)则不会触发选择状态变化。典型用途单选场景下高亮当前选中项并记录选中索引多选模式下维护已选集合、联动全选按钮状态将选择状态同步到数据源或服务端。完整示例创建 ListItem 的基本用法文档示例通过ListForEach循环渲染 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) } }示例要点解读数据源let arr [0, 1, 2, ..., 9]定义 10 个列表项数据。List 容器List(space: 20, initialIndex: 0)设置列表项主轴间隔 20首次加载从索引 0 开始显示.scrollBar(BarState.Off)关闭滚动条。ForEach 循环渲染ForEach(this.arr, itemGeneratorFunc: {item: Int64, _: Int64 ListItem() {...}})基于数据源逐一生成ListItemitem为当前数据、第二个参数为索引。关于ForEach的详细用法可参考循环渲染。列表项样式每个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【免费下载链接】CangjieCorpus本仓库为仓颉编程语言语料库聚焦 仓颉编程语言 核心知识体系整合官方开发指南、API 文档、典型代码示例及语法规范等多维度资源经结构化处理与专业标注构建为支持 RAG检索增强生成技术 的高质量知识基座适配智能编码助手、学习辅助工具等应用开发需求。 欢迎开发者基于本语料库构建仓颉语言智能应用推动鸿蒙开发生态智能化升级项目地址https://gitcode.com/Cangjie/CangjieCorpus点击查看免费下载相关推荐OpenHarmony ArkUI 仓颉版 Slider 滑动条组件从创建参数到 onChange 事件的完整实战OpenHarmony ArkUI 仓颉版 Slider 滑动条组件从创建参数到 onChange 事件的完整实战 本篇围绕 OpenHarmony ArkU文档知识库教程OpenHarmony仓颉 ArkUI ListItemGroup 分组列表组件完全指南从 API 详解到吸顶吸底实战仓颉 ArkUI ListItemGroup 分组列表组件完全指南从 API 详解到吸顶吸底实战 分组列表如通讯录按字母分组、课程表按星期分组、设置页按功能文档知识库教程OpenHarmony仓颉 ArkUI 按钮组件Button开发指南创建、样式、事件与场景实战仓颉 ArkUI 按钮组件Button开发指南创建、样式、事件与场景实战 Button 是 ArkUI 中最常用的交互组件用于响应用户点击操作支持胶囊文档知识库教程OpenHarmony上一篇Crystal与Ruby语法对比面向开发者的完整指南与关键差异解析下一篇Catppuccin壁纸色彩心理学不同色调如何影响你的工作心情创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考