鸿蒙列表页开发：ComposeListItem 高级组件实战指南

鸿蒙AI

在鸿蒙应用开发中，列表页几乎是每个项目的标配——设置菜单、消息中心、商品清单等场景都需要高效且美观的列表展示。过去，开发者需要手动组合 Row、Column、Image 和 Text 来拼凑列表项，代码冗长且需反复调整间距和对齐。随着 ArkUI 的演进，@ohos.arkui.advanced.ComposeListItem 组件专为标准化列表场景设计，内置成熟布局逻辑，能快速搭建符合设计规范的高质量列表页面。

## 组件结构与基础配置

ComposeListItem 采用“三段式”布局：左侧区域、中间内容区和右侧操作区，覆盖绝大多数列表场景。使用前需从高级组件库导入：

2. 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 字段用于更详细的描述。以下代码展示典型的用户列表项：

2. ComposeListItem({
3.   contentItem: {
4.     iconStyle: IconType.HEAD_SCULPTURE,
5.     icon: $r('app.media.avatar_default'),
6.     primaryText: '张三',
7.     secondaryText: '在线',
8.     description: '最近登录时间：今天 10:30'
9.   }
10. })

复制代码

左侧显示圆形头像，中间三行文字层次分明，阅读体验极佳。

## 右侧操作区与交互实现

列表的交互价值通过 operateItem 参数实现，支持箭头、图标、按钮、开关等多种形态。最简单的场景是展示向右箭头，暗示点击进入详情页：

2. operateItem: {
3.   arrow: {
4.     value: true,
5.     action: () => {
6.       // 跳转逻辑
7.       router.pushUrl({ url: 'pages/DetailPage' })
8.     }
9.   }
10. }

复制代码

如需更复杂操作（如右侧直接放置“删除”按钮或开关控件），可通过 button 属性定义按钮文本和点击回调；switch、checkbox 或 radio 属性允许嵌入状态控制组件，通过 isCheck 状态变量和 onChange 回调实现双向绑定。以下为开关控制示例（常用于设置页面的功能启停）：

2. @State isNotifyEnabled: boolean = true
4. ComposeListItem({
5.   contentItem: {
6.     iconStyle: IconType.SYSTEM_ICON,
7.     icon: $r('sys.media.ic_notification'),
8.     primaryText: '通知提醒',
9.     secondaryText: '接收重要消息推送'
10.   },
11.   operateItem: {
12.     switch: {
13.       isCheck: this.isNotifyEnabled,
14.       onChange: (value: boolean) => {
15.         this.isNotifyEnabled = value
16.         // 执行保存逻辑
17.       }
18.     }
19.   }
20. })

复制代码

开关状态由 isNotifyEnabled 驱动，用户切换时触发 onChange 回调，可在此更新后端配置或本地存储，无需额外编写布局代码。

## 实战案例：从简单列表到复杂交互

在实际业务中，可将上述特性组合构建丰富功能。例如消息中心页面，左侧显示发送者头像（HEAD_SCULPTURE），中间显示发送者名称（primaryText）和消息摘要（secondaryText），右侧根据消息类型动态显示“已读”标记图标或“回复”按钮。对于更高定制化场景，ComposeListItem 支持在右侧同时配置图标和文本，或组合多个操作项，甚至混合使用箭头和按钮。

所有事件绑定遵循 ArkTS 标准事件处理机制，与现有项目架构无缝融合。无论是简单页面跳转还是复杂状态管理，该组件都提供足够扩展能力，让代码保持简洁的同时不失功能完整性。

通过合理利用 ComposeListItem 的标准化能力，原本需要数十行代码的列表项可缩减为寥寥数行，极大提升开发效率。统一的组件规范保证了应用整体 UI 风格的一致性，在面对快速迭代的业务需求时，这种高效稳定的开发模式尤为珍贵。

---

来源：https://www.infoq.cn/article/f70f6f68f2d4ff9f93ff2a4b0
原文发布时间：2026-06-03

热心网友4

这篇帖子写得非常详细，正好解决了我在鸿蒙列表开发中的一些困惑。之前一直手动拼 Row 和 Column，代码多了确实难维护，尤其是不同屏幕密度的对齐问题改起来很麻烦。你提到的 `ComposeListItem` 三段式结构和图标预设类型很实用，特别是头像自动裁剪成圆形的设计，省去了很多样式代码。 右侧操作区支持开关、按钮、箭头等多种形态这点也很关键，我平时做设置页就经常需要这种组合。文中那个通知提醒的开关示例逻辑很清晰，`isCheck` 双向绑定 + `onChange` 回调正好覆盖了状态同步需求。 有一点想问下：对于左侧图标和中间文本同时存在且文本较长时，组件内部是怎么处理溢出的？比如 `primaryText` 过长时是自动截断还是可以设置显示行数？另外，如果需要在列表项中嵌入自定义布局（比如一个横向滚动的标签组），`ComposeListItem` 是否支持自定义插槽，还是只能通过预设的那些属性来组合？ 感谢分享这么好的实战指南，对新手和想提升开发效率的人帮助很大。