鸿蒙HarmonyOS开发实战：用List和ForEach快速搞定通讯录App的列表页（附完整代码）

鸿蒙HarmonyOS通讯录开发实战：从零构建高性能联系人列表

通讯录应用作为移动设备的基础功能之一，几乎存在于每台智能手机中。在鸿蒙生态中，利用List和ForEach组件可以快速实现一个功能完善、性能优异的通讯录界面。本文将带你从数据建模开始，逐步实现带字母索引、分组展示的完整通讯录解决方案。

1. 通讯录应用架构设计

一个完整的通讯录应用通常包含以下几个核心模块：

• 数据层：负责联系人数据的存储与管理
• 业务逻辑层：处理排序、搜索等核心功能
• 视图层：展示联系人列表及交互界面

我们重点关注视图层的实现，特别是如何利用HarmonyOS的ArkUI框架高效渲染联系人列表。

1.1 数据模型设计

首先定义联系人的数据结构：

interface Contact { id: string; // 唯一标识 name: string; // 姓名 phone: string; // 电话号码 avatar?: string; // 头像URL department?: string; // 部门信息 email?: string; // 电子邮箱 }

对于分组展示，我们需要将联系人按首字母分类：

interface ContactGroup { index: string; // 字母索引(A-Z) contacts: Contact[]; // 该分组下的联系人 }

1.2 状态管理方案

在鸿蒙应用中，我们可以使用@State和@Link装饰器管理应用状态：

@Entry @Component struct ContactList { @State contactGroups: ContactGroup[] = []; @State selectedIndex: number = 0; // 控制器用于联动列表滚动 private listScroller: Scroller = new Scroller(); // 初始化模拟数据 aboutToAppear() { this.loadContacts(); } loadContacts() { // 实际项目中这里应该是网络请求或数据库查询 this.contactGroups = generateMockData(); } build() { // 界面构建代码 } }

2. 列表视图实现

2.1 基础列表构建

使用List和ForEach组件渲染联系人分组：

List({ scroller: this.listScroller }) { ForEach(this.contactGroups, (group: ContactGroup) => { ListItemGroup({ header: this.renderGroupHeader(group.index) }) { ForEach(group.contacts, (contact: Contact) => { ListItem() { this.renderContactItem(contact) } }) } }) } .width('100%') .height('100%')

2.2 自定义列表项样式

为联系人列表项创建自定义渲染函数：

@Builder renderContactItem(contact: Contact) { Row() { Image(contact.avatar || $r('app.media.default_avatar')) .width(40) .height(40) .borderRadius(20) .margin(10) Column() { Text(contact.name) .fontSize(18) .fontWeight(FontWeight.Medium) Text(contact.phone) .fontSize(14) .fontColor(Color.Gray) } .alignItems(HorizontalAlign.Start) .margin({ right: 10 }) } .width('100%') .justifyContent(FlexAlign.Start) }

2.3 分组标题实现

创建分组标题的渲染函数：

@Builder renderGroupHeader(index: string) { Row() { Text(index) .fontSize(18) .fontWeight(FontWeight.Bold) .fontColor(Color.White) } .width('100%') .padding(10) .backgroundColor('#007DFF') }

3. 字母索引功能实现

3.1 AlphabetIndexer组件集成

在列表右侧添加字母索引器：

Stack({ alignContent: Alignment.End }) { // 列表组件... AlphabetIndexer({ arrayValue: ['A', 'B', 'C', ..., 'Z'], selected: 0 }) .selected(this.selectedIndex) .onSelect((index: number) => { this.listScroller.scrollToIndex(index) }) .margin({ right: 5 }) }

3.2 滚动联动处理

实现列表滚动与索引器的同步：

List({ scroller: this.listScroller }) { // ... } .onScrollIndex((index: number) => { this.selectedIndex = index }) .sticky(StickyStyle.Header) // 分组标题吸顶效果

4. 性能优化技巧

4.1 大数据量处理

当联系人数量较大时，需要考虑性能优化：

// 使用LazyForEach替代ForEach处理大数据集 LazyForEach(this.contactGroups, (group: ContactGroup) => { // ... }, (group: ContactGroup) => group.index)

4.2 内存优化策略

• 图片懒加载：只在列表项可见时加载头像
• 虚拟滚动：只渲染可视区域内的列表项
• 缓存机制：缓存已处理的联系人数据

4.3 列表项复用配置

ListItem() { // ... } .reuseId(contact.id) // 设置复用标识

5. 完整代码实现

以下是通讯录列表页的完整实现：

@Entry @Component struct ContactList { @State contactGroups: ContactGroup[] = []; @State selectedIndex: number = 0; private listScroller: Scroller = new Scroller(); aboutToAppear() { this.loadContacts(); } loadContacts() { // 模拟数据生成 const groups: ContactGroup[] = []; const letters = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'.split(''); letters.forEach(letter => { const count = Math.floor(Math.random() * 10) + 1; const contacts: Contact[] = []; for (let i = 0; i < count; i++) { contacts.push({ id: `${letter}-${i}`, name: `${letter}联系人${i}`, phone: `138${Math.floor(10000000 + Math.random() * 90000000)}`, avatar: '' }); } if (contacts.length > 0) { groups.push({ index: letter, contacts: contacts }); } }); this.contactGroups = groups; } @Builder renderGroupHeader(index: string) { Row() { Text(index) .fontSize(18) .fontWeight(FontWeight.Bold) .fontColor(Color.White) } .width('100%') .padding(10) .backgroundColor('#007DFF') } @Builder renderContactItem(contact: Contact) { Row() { Image(contact.avatar || $r('app.media.default_avatar')) .width(40) .height(40) .borderRadius(20) .margin(10) Column() { Text(contact.name) .fontSize(18) .fontWeight(FontWeight.Medium) Text(contact.phone) .fontSize(14) .fontColor(Color.Gray) } .alignItems(HorizontalAlign.Start) .margin({ right: 10 }) } .width('100%') .justifyContent(FlexAlign.Start) } build() { Column() { Stack({ alignContent: Alignment.End }) { Column() { List({ scroller: this.listScroller }) { ForEach(this.contactGroups, (group: ContactGroup) => { ListItemGroup({ header: this.renderGroupHeader(group.index) }) { ForEach(group.contacts, (contact: Contact) => { ListItem() { this.renderContactItem(contact) } .reuseId(contact.id) }) } }) } .onScrollIndex((index: number) => { this.selectedIndex = index }) .sticky(StickyStyle.Header) .divider({ strokeWidth: 1, color: '#EEEEEE', startMargin: 60, endMargin: 10 }) } .height('100%') .width('100%') AlphabetIndexer({ arrayValue: 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'.split(''), selected: 0 }) .selected(this.selectedIndex) .onSelect((index: number) => { this.listScroller.scrollToIndex(index) }) .margin({ right: 5 }) } } .width('100%') .height('100%') .backgroundColor('#FFFFFF') } }

6. 扩展功能实现

6.1 搜索功能集成

在列表顶部添加搜索栏：

Column() { Search({ placeholder: '搜索联系人' }) .onChange((value: string) => { this.filterContacts(value); }) .margin(10) // 列表组件... }

6.2 联系人详情页跳转

实现列表项点击跳转：

ListItem() { this.renderContactItem(contact) } .onClick(() => { router.push({ url: 'pages/ContactDetail', params: { contactId: contact.id } }); })

6.3 侧滑操作实现

为列表项添加侧滑操作菜单：

ListItem() { this.renderContactItem(contact) } .swipeAction({ end: this.renderSwipeActions(contact) })

7. 常见问题解决

7.1 性能问题排查

当列表滚动卡顿时，可以检查：

• 是否使用了复杂的列表项布局
• 图片资源是否过大
• 是否在build方法中执行了耗时操作

7.2 内存泄漏预防

• 及时取消事件监听
• 避免在全局对象中保存大量数据
• 使用aboutToDisappear生命周期释放资源

7.3 兼容性处理

• 不同设备尺寸适配
• 暗黑模式支持
• 多语言适配

在实际项目中，我们还需要考虑数据持久化、网络同步等功能。通过合理使用HarmonyOS提供的List组件和相关API，可以构建出既美观又高性能的通讯录界面。