鸿蒙列表页开发：ComposeListItem 高级组件实战指南
在鸿蒙应用开发中，列表页几乎是每个项目的标配——设置菜单、消息中心、商品清单等场景都需要高效且美观的列表展示。过去，开发者需要手动组合 Row、Column、Image 和 Text 来拼凑列表项，代码冗长且需反复调整间距和对齐。随着 ArkUI 的演进，@ohos.arkui.advanced.ComposeListItem 组件专为标准化列表场景设计，内置成熟布局逻辑，能快速搭建符合设计规范的高质量列表页面。## 组件结构与基础配置
ComposeListItem 采用“三段式”布局：左侧区域、中间内容区和右侧操作区，覆盖绝大多数列表场景。使用前需从高级组件库导入：
import { ComposeListItem, IconType } from '@ohos.arkui.advanced.ComposeListItem'
组件通过 contentItem 和 operateItem 两个主要参数控制内容。contentItem 负责定义左侧图标及中间文本信息，operateItem 配置右侧交互元素（如箭头、按钮、开关）。这种分离式设计让代码结构清晰，修改某一侧不会影响其他部分。
基础用法只需传入简单文本和图标资源，系统自动处理内边距、字体大小及对齐方式，确保不同屏幕密度下视觉一致，无需为像素级对齐费神。
## 左侧图标与多行文本规范
列表左侧通常展示品牌标识、功能图标或用户头像。ComposeListItem 通过 iconStyle 属性提供丰富预设类型，开发者无需手动计算图标尺寸，只需选择 IconType 枚举值即可：
- NORMAL_ICON：常规功能图标，尺寸 16×16dp
- SYSTEM_ICON：系统级图标，尺寸 24×24dp
- HEAD_SCULPTURE：用户头像，尺寸 40×40dp，自动裁剪为圆形
- APP_ICON：应用图标，尺寸 64×64dp
- BADGE：小型状态标记，尺寸 8×8dp
中间文本区域支持多层级信息展示：primaryText 显示主标题，内容过长时自动截断并显示省略号；secondaryText 适合辅助信息（如时间、状态）；description 字段用于更详细的描述。以下代码展示典型的用户列表项：
ComposeListItem({
contentItem: {
iconStyle: IconType.HEAD_SCULPTURE,
icon: $r('app.media.avatar_default'),
primaryText: '张三',
secondaryText: '在线',
description: '最近登录时间：今天 10:30'
}
})
左侧显示圆形头像，中间三行文字层次分明，阅读体验极佳。
## 右侧操作区与交互实现
列表的交互价值通过 operateItem 参数实现，支持箭头、图标、按钮、开关等多种形态。最简单的场景是展示向右箭头，暗示点击进入详情页：
operateItem: {
arrow: {
value: true,
action: () => {
// 跳转逻辑
router.pushUrl({ url: 'pages/DetailPage' })
}
}
}
如需更复杂操作（如右侧直接放置“删除”按钮或开关控件），可通过 button 属性定义按钮文本和点击回调；switch、checkbox 或 radio 属性允许嵌入状态控制组件，通过 isCheck 状态变量和 onChange 回调实现双向绑定。以下为开关控制示例（常用于设置页面的功能启停）：
@State isNotifyEnabled: boolean = true
ComposeListItem({
contentItem: {
iconStyle: IconType.SYSTEM_ICON,
icon: $r('sys.media.ic_notification'),
primaryText: '通知提醒',
secondaryText: '接收重要消息推送'
},
operateItem: {
switch: {
isCheck: this.isNotifyEnabled,
onChange: (value: boolean) => {
this.isNotifyEnabled = value
// 执行保存逻辑
}
}
}
})
开关状态由 isNotifyEnabled 驱动，用户切换时触发 onChange 回调，可在此更新后端配置或本地存储，无需额外编写布局代码。
## 实战案例：从简单列表到复杂交互
在实际业务中，可将上述特性组合构建丰富功能。例如消息中心页面，左侧显示发送者头像（HEAD_SCULPTURE），中间显示发送者名称（primaryText）和消息摘要（secondaryText），右侧根据消息类型动态显示“已读”标记图标或“回复”按钮。对于更高定制化场景，ComposeListItem 支持在右侧同时配置图标和文本，或组合多个操作项，甚至混合使用箭头和按钮。
所有事件绑定遵循 ArkTS 标准事件处理机制，与现有项目架构无缝融合。无论是简单页面跳转还是复杂状态管理，该组件都提供足够扩展能力，让代码保持简洁的同时不失功能完整性。
通过合理利用 ComposeListItem 的标准化能力，原本需要数十行代码的列表项可缩减为寥寥数行，极大提升开发效率。统一的组件规范保证了应用整体 UI 风格的一致性，在面对快速迭代的业务需求时，这种高效稳定的开发模式尤为珍贵。
来源：https://www.infoq.cn/article/f70f6f68f2d4ff9f93ff2a4b0
原文发布时间：2026-06-03
Re: 鸿蒙列表页开发：ComposeListItem 高级组件实战指南
这篇帖子写得非常详细，正好解决了我在鸿蒙列表开发中的一些困惑。之前一直手动拼 Row 和 Column，代码多了确实难维护，尤其是不同屏幕密度的对齐问题改起来很麻烦。你提到的 `ComposeListItem` 三段式结构和图标预设类型很实用，特别是头像自动裁剪成圆形的设计，省去了很多样式代码。 右侧操作区支持开关、按钮、箭头等多种形态这点也很关键，我平时做设置页就经常需要这种组合。文中那个通知提醒的开关示例逻辑很清晰，`isCheck` 双向绑定 + `onChange` 回调正好覆盖了状态同步需求。 有一点想问下：对于左侧图标和中间文本同时存在且文本较长时，组件内部是怎么处理溢出的？比如 `primaryText` 过长时是自动截断还是可以设置显示行数？另外，如果需要在列表项中嵌入自定义布局（比如一个横向滚动的标签组），`ComposeListItem` 是否支持自定义插槽，还是只能通过预设的那些属性来组合？ 感谢分享这么好的实战指南，对新手和想提升开发效率的人帮助很大。Re: 鸿蒙列表页开发：ComposeListItem 高级组件实战指南
这篇文章写得很实用，尤其是对 `ComposeListItem` 三段式布局的拆解非常清晰。之前自己在手写列表项时确实经常纠结间距和对齐，现在有这种标准化组件能省不少事。左侧图标的几种预设类型和右侧开关、箭头的交互示例也正好是我当前项目里需要的，准备直接拿来用了。谢谢分享！Re: 鸿蒙列表页开发：ComposeListItem 高级组件实战指南
这篇文章写得非常实用！之前用 Row 和 Column 拼列表确实又臭又长，尤其是多级文本对齐和右侧开关交互总要调半天。ComposeListItem 这个组件直接把常见场景封装好了，三段式布局加上预设的图标尺寸，省了很多心。 想请教一下楼主：在实际项目中，如果一屏要渲染上百条列表项，这个组件的性能表现怎么样？会不会因为封装层次多反而增加开销？谢谢分享！
页:
[1]