[HarmonyOS NEXT 实战案例六:List系列] 垂直列表组件实战：打造高效联系人列表 进阶篇

项目已开源，开源地址： https://gitcode.com/nutpi/HarmonyosNextCaseStudyTutorial ， 欢迎fork & star

效果演示

一、List组件进阶特性

在基础篇中，我们已经学习了如何创建一个简单的垂直联系人列表。在本篇教程中，我们将深入探讨List组件的进阶特性，包括列表交互、状态管理、样式定制等方面。

1.1 List组件的进阶属性

1.2 ListItem的进阶特性

二、联系人列表的交互增强

在基础版本的联系人列表基础上，我们可以添加更多的交互功能，使列表更加实用和用户友好。

2.1 添加列表项选中效果

我们可以为联系人列表项添加选中效果，当用户点击列表项时，该项会显示为选中状态：

@Component
export struct AdvancedVerticalList {
    // 联系人数据
    private contacts:ContactType[] = [...] // 与基础版相同
    
    // 当前选中的联系人索引
    @State selectedIndex: number = -1
    
    build() {
        Column() {
            // 标题栏（与基础版相同）
            
            // 联系人列表
            List() {
                ForEach(this.contacts, (contact:ContactType, index: number) => {
                    ListItem() {
                        Row() {
                            // 头像和联系人信息（与基础版相同）
                        }
                        .width('100%')
                        .padding({ left: 16, right: 16, top: 12, bottom: 12 })
                        .backgroundColor(this.selectedIndex === index ? '#F0F0F0' : '#FFFFFF')
                    }
                    .height(64)
                    .onClick(() => {
                        this.selectedIndex = index
                        // 可以在这里添加其他操作，如显示详情等
                    })
                })
            }
            // List属性设置（与基础版相同）
        }
        // Column属性设置（与基础版相同）
    }
}

在这个示例中：

1. 添加了一个@State装饰的selectedIndex状态变量，用于跟踪当前选中的联系人索引
2. 在Row组件上添加了backgroundColor属性，根据selectedIndex动态设置背景色
3. 为ListItem添加了onClick事件处理函数，点击时更新selectedIndex

2.2 实现列表项滑动操作

在移动应用中，滑动列表项显示操作按钮是一种常见的交互模式。我们可以使用ListItem的swipeAction属性来实现这一功能：

ListItem() {
    Row() {
        // 头像和联系人信息（与基础版相同）
    }
    .width('100%')
    .padding({ left: 16, right: 16, top: 12, bottom: 12 })
}
.height(64)
.swipeAction({
    end: this.getDeleteButton(index),  // 右侧滑出的删除按钮
    start: this.getCallButton(index)   // 左侧滑出的拨打电话按钮
})

其中，getDeleteButton和getCallButton是自定义的Builder函数：

@Builder getDeleteButton(index: number) {
    Button({
        type: ButtonType.Capsule
    }) {
        Image($r('app.media.ic_delete'))
            .width(24)
            .height(24)
    }
    .width(40)
    .height(40)
    .backgroundColor('#FF4081')
    .margin(12)
    .onClick(() => {
        // 实现删除联系人的逻辑
        this.contacts.splice(index, 1)
    })
}

@Builder getCallButton(index: number) {
    Button({
        type: ButtonType.Capsule
    }) {
        Image($r('app.media.ic_call'))
            .width(24)
            .height(24)
    }
    .width(40)
    .height(40)
    .backgroundColor('#4CAF50')
    .margin(12)
    .onClick(() => {
        // 实现拨打电话的逻辑
        console.info(`拨打电话：${this.contacts[index].phone}`)
    })
}

2.3 添加列表滚动控制

我们可以添加控制列表滚动的功能，例如滚动到顶部或特定位置：

@Component
export struct AdvancedVerticalList {
    // 联系人数据和状态变量
    
    // 列表控制器
    private listController: ListController = new ListController()
    
    build() {
        Column() {
            // 标题栏
            Row() {
                Text('联系人列表')
                    .fontSize(24)
                    .fontWeight(FontWeight.Bold)
                
                Blank()
                
                Button('回到顶部')
                    .fontSize(14)
                    .onClick(() => {
                        this.listController.scrollTo(0)
                    })
            }
            .width('100%')
            .height(56)
            .padding({ left: 16, right: 16 })
            .backgroundColor('#F1F3F5')
            
            // 联系人列表
            List({ space: 0, controller: this.listController }) {
                // 列表内容（与之前相同）
            }
            // List属性设置（与基础版相同）
        }
        // Column属性设置（与基础版相同）
    }
}

在这个示例中：

1. 创建了一个ListController实例，用于控制列表的滚动
2. 在List组件的构造参数中传入controller
3. 在标题栏添加了一个"回到顶部"按钮，点击时调用scrollTo方法滚动到列表顶部

三、列表样式进阶定制

除了基本的样式设置外，我们还可以对列表进行更多的样式定制，使其更加美观和符合应用的设计风格。

3.1 自定义滚动条

List() {
    // 列表内容
}
.width('100%')
.layoutWeight(1)
.divider({
    strokeWidth: 1,
    color: '#E5E5E5',
    startMargin: 72,
    endMargin: 16
})
.scrollBar({
    width: 4,
    color: '#66000000',
    shape: ScrollBarShape.Rectangle
})

滚动条配置说明：

3.2 自定义边缘效果

List() {
    // 列表内容
}
.width('100%')
.layoutWeight(1)
.divider({
    strokeWidth: 1,
    color: '#E5E5E5',
    startMargin: 72,
    endMargin: 16
})
.edgeEffect(EdgeEffect.Spring) // 设置边缘效果为弹簧效果

EdgeEffect枚举值说明：

3.3 链式动画效果

List() {
    // 列表内容
}
.width('100%')
.layoutWeight(1)
.divider({
    strokeWidth: 1,
    color: '#E5E5E5',
    startMargin: 72,
    endMargin: 16
})
.chainAnimation(true) // 启用链式动画

启用链式动画后，列表项会在滚动时产生连锁的动画效果，增强视觉体验。

四、列表状态管理

在实际应用中，列表的状态管理是一个重要的方面，包括数据的增删改查、选中状态管理等。

4.1 实现联系人搜索功能

我们可以添加一个搜索框，用于筛选联系人列表：

@Component
export struct AdvancedVerticalList {
    // 联系人数据
    private contacts:ContactType[] = [...] // 与基础版相同
    
    // 搜索关键词
    @State searchText: string = ''
    
    // 获取筛选后的联系人列表
    private getFilteredContacts(): ContactType[] {
        if (!this.searchText) {
            return this.contacts
        }
        
        return this.contacts.filter(contact => 
            contact.name.includes(this.searchText) || 
            contact.phone.includes(this.searchText)
        )
    }
    
    build() {
        Column() {
            // 标题栏
            Row() {
                Text('联系人列表')
                    .fontSize(24)
                    .fontWeight(FontWeight.Bold)
            }
            .width('100%')
            .height(56)
            .padding({ left: 16 })
            .backgroundColor('#F1F3F5')
            
            // 搜索框
            TextInput({ placeholder: '搜索联系人', text: this.searchText })
                .width('90%')
                .height(40)
                .margin({ top: 8, bottom: 8 })
                .onChange((value: string) => {
                    this.searchText = value
                })
            
            // 联系人列表
            List() {
                ForEach(this.getFilteredContacts(), (contact:ContactType, index: number) => {
                    // 列表项内容（与基础版相同）
                })
            }
            // List属性设置（与基础版相同）
        }
        // Column属性设置（与基础版相同）
    }
}

在这个示例中：

1. 添加了一个@State装饰的searchText状态变量，用于存储搜索关键词
2. 添加了getFilteredContacts方法，根据searchText筛选联系人
3. 在Column中添加了TextInput组件作为搜索框
4. 在ForEach中使用getFilteredContacts()替代原来的this.contacts

4.2 实现联系人分组

在大型联系人列表中，通常会按照字母或其他规则对联系人进行分组。我们可以使用ListItemGroup组件来实现这一功能：

@Component
export struct AdvancedVerticalList {
    // 联系人数据（按首字母排序）
    private contacts:ContactType[] = [...] // 与基础版相同，但已排序
    
    // 获取分组后的联系人数据
    private getGroupedContacts(): { [key: string]: ContactType[] } {
        const grouped: { [key: string]: ContactType[] } = {}
        
        this.contacts.forEach(contact => {
            const firstLetter = contact.name.charAt(0).toUpperCase()
            if (!grouped[firstLetter]) {
                grouped[firstLetter] = []
            }
            grouped[firstLetter].push(contact)
        })
        
        return grouped
    }
    
    build() {
        Column() {
            // 标题栏（与基础版相同）
            
            // 联系人列表（分组显示）
            List() {
                ForEach(Object.keys(this.getGroupedContacts()).sort(), (letter: string) => {
                    ListItemGroup({
                        header: this.getGroupHeader(letter)
                    }) {
                        ForEach(this.getGroupedContacts()[letter], (contact:ContactType) => {
                            ListItem() {
                                // 列表项内容（与基础版相同）
                            }
                            .height(64)
                        })
                    }
                })
            }
            // List属性设置（与基础版相同）
        }
        // Column属性设置（与基础版相同）
    }
    
    @Builder getGroupHeader(letter: string) {
        Text(letter)
            .fontSize(16)
            .fontWeight(FontWeight.Bold)
            .backgroundColor('#F0F0F0')
            .width('100%')
            .padding(8)
    }
}

在这个示例中：

1. 添加了getGroupedContacts方法，将联系人按首字母分组
2. 使用ForEach遍历分组的键（字母）
3. 对每个字母组使用ListItemGroup组件
4. 使用getGroupHeader Builder函数创建组标题

总结

在本篇教程中，我们深入探讨了HarmonyOS NEXT的List组件的进阶特性和用法。我们学习了如何：

1. 使用List和ListItem的进阶属性增强列表功能
2. 添加列表项选中效果和滑动操作
3. 实现列表滚动控制
4. 自定义列表样式，包括滚动条、边缘效果和链式动画
5. 实现联系人搜索和分组功能