通讯录
大约 3 分钟
UIKit-HarmonyOS 集成文档
通讯录
环信单群聊 ChatUIKit 提供 ContactListPage
和 ContactListView
两种方式方便用户快速集成通讯录页面和自定义通讯录页面。
通讯录页面用于展示通讯录列表,包括联系人搜索,添加联系人,群组列表入口,联系人列表。
昵称在中文或者英文的情况下可以实现按首字母分类。
通讯录

使用示例
ContactListPage
:ChatUIKit
提供的默认联系人列表页面。页面包含标题栏和联系人列表。应用程序可以采用组件导航(Navigation)跳转到ContactListPage
。ContactListView
:组件包含联系人区域,开发者可以在应用页面中集成自定义的联系人页面。
使用 ContactListPage
使用鸿蒙提供的组件导航 Navigation 跳转到会话列表页面 ContactListPage
。
this.pathStack.pushPath({ name: 'ContactListPage' });
使用 ContactListView
开发者可以通过添加联系人列表组件 ContactListView
将其嵌入到自己的页面中,以便进行更多的定制化开发。联系人列表组件不包含标题栏,需要开发者自己实现。
ContactListView
组件已经封装了联系人列表的主要逻辑,开发者需要实现列表项的点击事件以及点击搜索框的事件。
使用 ContactListView

示例如下:
- 编写包含 NavDestination 子组件的页面。
import {
ChatKitContact,
ChatPageParams,
ComposeTitleBar,
ContactListView,
ConversationType,
KitCallback
} from '@easemob/chatuikit';
@ComponentV2
export struct ContactsPage {
navPathStack: NavPathStack = new NavPathStack();
@Event onItemClick: KitCallback<ChatKitContact> = (item: ChatKitContact) => {
this.navPathStack.pushPath({ name: "ChatPage", param: {
conversationId: item.id,
conversationType: ConversationType.Chat
} as ChatPageParams });
};
@Event onSearchClick: KitCallback = () => {
this.navPathStack.pushPath({ name: "SearchContactPage" });
}
build() {
NavDestination() {
Column() {
ComposeTitleBar({
titlePosition: HorizontalAlign.Center,
primaryTitle: '联系人列表',
onBackPress: () => {
this.navPathStack.pop();
}
});
ContactListView({
onItemClick: this.onItemClick,
onSearchClick: this.onSearchClick
})
.layoutWeight(1);
}
}
.hideTitleBar(true)
.onReady((context) => {
this.navPathStack = context.pathStack;
});
}
}
@Builder
export function ContactsPageBuilder() {
ContactsPage()
}
- 将页面配置到系统配置文件
route_map.json
中(参见 系统路由表)。
// 1. 工程配置文件 module.json5 中配置 {"routerMap": "$profile:route_map"}
// 2. 在 route_map.json 注册 ContactsPage 信息
{
"routerMap": [
{
"name": "ContactsPage",
"pageSourceFile": "src/main/ets/pages/ContactsPage.ets",
"buildFunction": "ContactsPageBuilder",
"data": {
"description" : "Contact list page"
}
}
]
}
- 跳转到 ContactsPage 页面。
@Entry
@ComponentV2
struct Index {
pathStack: NavPathStack = new NavPathStack();
build() {
Navigation(this.pathStack) {
Column() {
Button('Contact list page', { stateEffect: true, type: ButtonType.Capsule })
.width('80%')
.height(40)
.margin(20)
.onClick(() => {
this.pathStack.pushPathByName('ContactsPage', null);
});
}.width('100%').height('100%');
}
.title("Navigation")
.mode(NavigationMode.Stack);
}
}
使用 ContactListView 定制化
自定义列表项点击事件
开发者如果使用的是组件 ContactListView
,需要实现列表项的点击事件。
自定义列表项点击事件

示例如下:
@ComponentV2
export struct ContactsPage {
navPathStack: NavPathStack = new NavPathStack();
@Event onItemClick: KitCallback<ChatKitContact> = (item: ChatKitContact) => {
this.navPathStack.pushPath({ name: "ChatPage", param: {
conversationId: item.id,
conversationType: ConversationType.Chat
} as ChatPageParams });
};
build() {
NavDestination() {
Column() {
ContactListView({
onItemClick: this.onItemClick
})
}
}
.onReady((context) => {
this.navPathStack = context.pathStack;
});
}
}
自定义搜索框事件
搜索框部分,开发者可以做到以下定制化:
- 是否显示搜索框;
- 自定义搜索框点击事件;
- 自定义搜索框布局。
隐藏搜索框

点击搜索框

自定义搜索框布局

示例如下:
@ComponentV2
export struct ContactsPage {
navPathStack: NavPathStack = new NavPathStack();
@Event onSearchClick: KitCallback = () => {
this.navPathStack.pushPath({ name: "SearchContactPage" });
}
// 搜索框自定义构件函数
@Builder
customSearchBuilder(onClick: KitCallback) {
Row() {
Text('搜索')
.width('80%')
.height('80%')
.backgroundColor(Color.Gray)
.textAlign(TextAlign.Center)
.borderRadius(5)
.onClick(() => {
onClick();
});
}
.justifyContent(FlexAlign.Center)
.width('100%')
.height(50);
}
build() {
NavDestination() {
Column() {
ContactListView({
showSearchView: true, // 决定是否展示搜索框
onSearchClick: this.onSearchClick, // 处理点击搜索框的事件
searchBuilder: this.customSearchBuilder // 自定义搜索框布局
});
}
}
.onReady((context) => {
this.navPathStack = context.pathStack;
});
}
}
自定义联系人列表更多功能项
开发者可以在联系人列表的头部增加自定义的功能布局,比如增加群组列表的入口,黑名单的入口等。
自定义联系人列表更多功能项

示例代码如下:
@ComponentV2
export struct ContactsPage {
navPathStack: NavPathStack = new NavPathStack();
@Event onMoreActionClick: KitCallback<number> = (index) => {
if (index === 0) {
// 处理点击好友请求列表项的逻辑
} else if (index === 1) {
this.navPathStack?.pushPath({name: "GroupListPage"});
}
}
@Builder
moreActionBuilder(onClick: KitCallback<number>) {
ListItem() {
Column() {
ComposeBadgeListItem({
title: $r('app.string.new_request')
})
.onClick(() => {
onClick(0);
})
ComposeBadgeListItem({
title: $r('app.string.group_chat')
})
.onClick(() => {
onClick(1);
})
}
}
}
build() {
NavDestination() {
Column() {
ContactListView({
......
moreActionBuilder: this.moreActionBuilder,
onMoreActionClick: this.onMoreActionClick
});
}
}
.onReady((context) => {
this.navPathStack = context.pathStack;
});
}
}