文档反馈官招募中，报名立赚积分兑换代金券！> HOT
文档中心>即时通信 IM>聊天互动（含 UI）>单功能接入>联系人列表>HarmonyOS

HarmonyOS

最近更新时间：2025-11-17 11:28:42

我的收藏

本页目录：

组件概述

ContactList 是基于 ArkUI 构建的联系人列表组件，为用户提供完整的联系人管理功能。该组件支持好友列表展示、好友申请处理、群组列表管理、黑名单管理等功能，并提供了丰富的交互回调接口。
联系人列表
群组列表
好友申请列表




组件集成

ContactList 组件属于 TUIKit ArkUI 的一部分，集成 TUIKit ArkUI 即可获取并使用 ContactList 组件。集成方法请参考文档 TUIKit ArkUI 里的集成步骤。

组件构成

ContactList 是联系人列表里的主组件，对应着整个联系人列表页框架，提供了一个对外的初始化 init 方法：
方法名
参数
描述
init
contactStore: ContactListStore
联系人数据存储，默认请使用 ContactListStore.create() 创建。
onContactClick?: (item: ContactInfo) => void
点击联系人的回调，可选参数。
onGroupClick?: (item: ContactInfo) => void
点击群组的回调，可选参数。
onNewFriendsClick?: () => void;
点击新的好友申请的回调，可选参数。
onGroupApplicationsClick?: () => void;
点击群组申请的回调，可选参数。
onGroupListClick?: () => void;
点击群组列表的回调，可选参数。
onBlackListClick?: () => void;
点击黑名单的回调，可选参数。
ContactList 上半部分预留了各个子视图的入口 cell，例如好友申请、群聊申请、群组列表和黑名单列表。下半部分内嵌了联系人列表，如下图所示：

ContactList 是一个纯数据展示组件，不包含页面跳转逻辑。您需要在初始化时通过回调参数来处理子页面的跳转。
子页面（例如好友申请列表、群组列表等）提供了各自的 init 方法，详情如下：
子页面
方法名
参数
描述
好友申请页（FriendApplicationListView）
同名构造函数
contactStore: ContactListStore
联系人数据存储，从 ContactList 传过来。
群组申请页（GroupApplicationListView）
同名构造函数
contactStore: ContactListStore
联系人数据存储，从 ContactList 传过来。
群组列表页
（GroupListView）
同名构造函数
contactStore: ContactListStore
联系人数据存储，从 ContactList 传过来。
onShowProfile?: (group: ContactInfo) => void
点击群组查看详情的回调，可选参数。
黑名单列表页
（BlackListView）
同名构造函数
contactStore: ContactListStore
联系人数据存储，从 ContactList 传过来。
onShowProfile?: (item: ContactInfo) => void
点击黑名单用户查看详情的回调，可选参数。
为什么 ContactList 不包含子页面跳转逻辑？
ContactList 被设计为一个专注于数据展示的组件，而不是一个完整的页面容器。这种设计确保了组件的灵活性和可复用性：
导航控制权在外层：ContactList 通常被嵌入在更大的页面结构中，导航需要由外层统一管理。
适配不同场景：不同应用可能有不同的导航需求（模态弹窗、页面跳转、Tab 切换等）。
职责分离：ContactList 负责"通知"点击事件，外层页面负责具体的跳转逻辑。

基础用法

完整页面导航集成

在实际应用中，ContactList 主组件需要与各个子页面（GroupListView、FriendApplicationListView、GroupApplicationListView、BlackListView）进行导航集成。跳转示例图如下所示：

实现步骤如下：
1. 在 ContactList 的 同名构造函数 中设置回调：当用户点击某个功能入口时，触发对应的回调函数。
2. 在回调中处理跳转：使用 CustomDialogController 或状态变量控制子页面的显示。
3. 传递 contactStore：将父级的 contactStore 实例传递给子页面，确保数据一致性。
ContactList 的 同名构造函数 回调和建议跳转子页面的对应关系：
好友申请页：onNewFriendsClick?: () => void
群聊申请页：onGroupApplicationsClick?: () => void
群聊列表页：onGroupListClick?: () => void
黑名单列表页：onBlackListClick?: () => void
以下是完整的集成示例，展示如何使用 CustomDialogController 将这些组件粘合在一起。

import { ContactList } from '@tencentcloud/atomicx'
import { ContactListStore, ContactInfo } from '@tencentcloud/atomicxcore'

@Component
export struct ContactsPage {
    @ObjectLink contactListStore: ContactListStore;
      build() {
         ContactList({
          contactListStore: this.contactListStore,
          onContactClick: (contact: ContactInfo) => {
            // 处理联系人点击
          },
          onGroupClick: (group: ContactInfo) => {
            // 处理群组点击
          },

          onNewFriendsClick:() => {
            // 处理好友申请的点击
          },
          onGroupApplicationsClick: () => {
            // 处理群聊申请的点击
          },
          onGroupListClick: () => {
            // 处理已加入群聊的点击
          },
          onBlackListClick: () => {
            // 处理黑名单的点击
          },
        })
          .layoutWeight(1)
    }
}


集成要点说明

显示状态

使用 CustomDialogController 变量控制各个子页面的显示：
  private newContactsDialogController?: CustomDialogController;
  private newGroupsDialogController?: CustomDialogController;
  private myGroupDialogController?: CustomDialogController;
  private blackListDialogController?: CustomDialogController;

回调处理

在 ContactList 的回调中展示对应的 dialog，触发页面跳转：
ContactList(
    onNewFriendsClick: {
        this.showContactManagementDialog('newContacts');  // 触发跳转到好友申请页面
    },
    onGroupListClick: {
        this.showContactManagementDialog('myGroups');   // 触发跳转到群组列表页面
    }
    // ... 其他回调
)

数据共享

所有子页面共享同一个 ContactListStore 实例，避免资源浪费，确保数据一致性：
@State private contactListStore: ContactListStore = ContactListStore.create();

// 在所有组件中使用同一个 contactStore
ContactList(contactListStore: this.contactListStore, ...)
GroupListView(contactListStore: this.contactListStore, ...)
FriendApplicationListView(contactListStore: this.contactListStore)

页面返回处理

在子页面的回调中，将状态变量设置为 false 以返回上一页：
GroupListView({
    contactListStore: this.contactListStore,
    onShowProfile: (group: ContactInfo) => {
        // 关闭群组列表页面
        this.myGroupDialogController?.close();
        this.myGroupDialogController = undefined;
        // 执行其他操作，如跳转到聊天页面
    }
})

中国站
目录