tencent cloud

即时通信 IM

动态与公告
产品动态
公告
产品简介
产品概述
基本概念
应用场景
功能介绍
账号系统
用户资料与关系链
消息管理
群组相关
公众号系统
音视频通话 Call
使用限制
购买指南
计费概述
价格说明
购买指引
续费指引
停服说明
退费说明
开发指引
Demo 专区
开通服务
体验 Demo
快速跑通
下载中心
SDK & Demo 源码
更新日志
聊天互动(含 UI)
TUIKit 组件介绍
快速开始
全功能接入
单功能接入
AI 集成
构建基础界面
更多特性
定义外观
国际化界面语言
推送服务(Push)
服务概述
名词解释
开通服务
快速跑通
厂商通道
数据统计
排查工具
客户端 API
服务端 API
推送回调
高级功能
更新日志
错误码
常见问题
智能客服
功能概述
快速入门
集成指引
管理员操作手册
客服操作手册
更多实践
直播间搭建
AI 聊天机器人方案
超大娱乐协作社群
Discord 实现指南
游戏内集成 Chat 指南
类 WhatsApp Channel 搭建方案
发送红包
Chat 应对防火墙限制相关
无 UI 集成
快速开始
集成 SDK
初始化
登录登出
消息相关
会话相关
群组相关
社群话题
用户管理
离线推送
云端搜索
本地搜索
公众号
客户端 API
JavaScript
Android
iOS & macOS
Swift
Flutter
Electron
Unity
React Native
C 接口
C++
服务端 API
生成 UserSig
REST API
第三方回调
控制台指南
新版控制台介绍
创建并升级应用
基本配置
功能配置
账号管理
群组管理
公众号管理
回调配置
用量统计
资源包查看指南
实时监控
开发辅助工具
访问管理
高级功能
常见问题
uni-app 常见问题
购买相关问题
SDK 相关问题
账号鉴权相关问题
用户资料与关系链相关问题
消息相关问题
群组相关问题
直播群相关问题
昵称头像相关问题
协议与认证
服务等级协议
安全合规认证
IM 政策
隐私政策
数据隐私和安全协议
平滑迁移方案
平滑迁移完整版
平滑迁移简化版
错误码
联系我们

ContactList

PDF
聚焦模式
字号
最后更新时间: 2026-02-11 17:22:37

概述

ContactList 是一个高度可配置的联系人列表组件。该组件支持好友列表、群组列表、黑名单和申请管理,提供分组折叠、搜索过滤、自定义渲染等核心功能,适用于即时通信、社交应用等场景的联系人管理界面。


ContactList Props

字段
类型
默认值
描述
activeContactItem
ContactGroupItem | undefined
undefined
当前激活的联系人项
enableSearch
boolean
true
是否启用搜索功能
groupConfig
Partial<Record<ContactItemType, CustomGroupConfig>>
{}
自定义分组配置
className
string
undefined
自定义 CSS 类名
style
React.CSSProperties
undefined
自定义内联样式
searchPlaceholder
string
'Search contacts'
搜索框占位符文本
emptyText
string
'No contacts'
空状态提示文本
ContactItem
React.ComponentType<ContactListItemProps> | undefined
ContactListItem
自定义联系人项组件
ContactSearchComponent
React.ComponentType<ContactSearchProps> | undefined
ContactSearch
自定义搜索组件
GroupHeader
React.ComponentType<{ data: ContactGroup }> | undefined
默认分组头
自定义分组头部组件
PlaceholderEmptyList
React.ReactNode | undefined
默认空状态
自定义空状态组件
onContactItemClick
(item: ContactGroupItem) => void
undefined
联系人项点击事件
onFriendApplicationAction
(action: 'accept' | 'refuse', application: FriendApplication) => void
undefined
好友申请操作事件
onGroupApplicationAction
(action: 'accept' | 'refuse', application: GroupApplication) => void
undefined
群组申请操作事件

ContactInfo props

字段
类型
默认值
描述
contactItem
ContactGroupItem | undefined
undefined
当前显示的联系人项
showActions
boolean
true
是否显示操作按钮
PlaceholderEmpty
React.ReactNode | undefined
undefined
空状态占位组件
FriendInfoComponent
React.ComponentType<FriendInfoProps>
FriendInfo
好友信息组件
GroupInfoComponent
React.ComponentType<GroupInfoProps>
GroupInfo
群组信息组件
BlacklistInfoComponent
React.ComponentType<BlacklistInfoProps>
BlacklistInfo
黑名单信息组件
FriendApplicationInfoComponent
React.ComponentType<FriendApplicationInfoProps>
FriendApplicationInfo
好友申请信息组件
GroupApplicationInfoComponent
React.ComponentType<GroupApplicationInfoProps>
GroupApplicationInfo
群组申请信息组件
SearchGroupInfoComponent
React.ComponentType<SearchGroupInfoProps>
SearchGroupInfo
搜索群组信息组件
SearchUserInfoComponent
React.ComponentType<SearchUserInfoProps>
SearchUserInfo
搜索用户信息组件
onClose
() => void
undefined
关闭信息面板回调
onSendMessage
(friend: Friend) => void
undefined
发送消息回调
onDeleteFriend
(friend: Friend) => void
undefined
删除好友回调
onUpdateFriendRemark
(friend: Friend, remark: string) => void
undefined
更新好友备注回调
onAddToBlacklist
(friend: Friend) => void
undefined
添加到黑名单回调
onRemoveFromBlacklist
(profile: UserProfile) => void
undefined
从黑名单移除回调
onEnterGroup
(group: GroupModel) => void
undefined
进入群组回调
onLeaveGroup
(group: GroupModel) => void
undefined
退出群组回调
onDismissGroup
(group: GroupModel) => void
undefined
解散群组回调
onFriendApplicationAction
(action: 'accept' | 'refuse', application: FriendApplication) => void
undefined
好友申请操作回调
onGroupApplicationAction
(action: 'accept' | 'refuse', application: GroupApplication) => void
undefined
群组申请操作回调
onAddFriend
(user: UserProfile, wording: string) => void
undefined
添加好友回调
onJoinGroup
(group: GroupModel, note: string) => void
undefined
加入群组回调

基础使用

import { ContactList, ContactInfo } from '@tencentcloud/chat-uikit-react';

function App() {
return (
<div>
<ContactList />
<ContactInfo />
</div>
);
}

自定义能力

自定义联系列表搜索功能开关

通过设置 enableSearch 参数,您可以灵活地控制 ContactList 中的搜索好友群组功能的显示。
<ContactList enableSearch={false} />
效果如下图所示:




自定义联系列表联系人分组配置

groupConfig 用于自定义分组配置,包括标题、显示顺序、隐藏状态等,默认值为 {}
自定义分组标题
隐藏特定分组
import React from 'react';
import { ContactList } from '@tencentcloud/chat-uikit-react';
import { ContactItemType } from '@tencentcloud/chat-uikit-react';

function CustomGroupTitlesContactList() {
const groupConfig = {
[ContactItemType.FRIEND]: {
title: '我的好友',
order: 1
},
[ContactItemType.GROUP]: {
title: '我的群组',
order: 2
},
[ContactItemType.FRIEND_REQUEST]: {
title: '好友申请',
order: 0
}
};

return (
<ContactList
groupConfig={groupConfig}
onContactItemClick={(item) => {
console.log('联系人点击:', item);
}}
/>
);
}
效果如下图所示:



import React from 'react';
import { ContactList } from '@tencentcloud/chat-uikit-react';
import { ContactItemType } from '@tencentcloud/chat-uikit-react';

function HiddenGroupsContactList() {
const groupConfig = {
[ContactItemType.BLACK]: {
title: '黑名单',
hidden: true // 隐藏黑名单分组
},
[ContactItemType.GROUP_REQUEST]: {
title: '群组申请',
hidden: true // 隐藏群组申请分组
}
};

return (
<ContactList
groupConfig={groupConfig}
onContactItemClick={(item) => {
console.log('联系人点击:', item);
}}
/>
);
}
效果如下图所示:




自定义联系列表子项

ContactItem 用于自定义联系人项的渲染组件,默认值为内置的 ContactListItem 组件。
import React from 'react';
import { ContactList, Avatar } from '@tencentcloud/chat-uikit-react';
import type { ContactListItemProps } from '@tencentcloud/chat-uikit-react';

const SimpleContactItem: React.FC<ContactListItemProps> = ({
contactItem,
onClick,
activeContactItem
}) => {
const isActive = activeContactItem?.data.userID === contactItem.data.userID;

return (
<div
className={`simple-contact-item ${isActive ? 'active' : ''}`}
onClick={() => onClick?.(contactItem.type, contactItem.data)}
style={{
padding: '8px 12px',
borderBottom: '1px solid #f0f0f0',
cursor: 'pointer',
backgroundColor: isActive ? '#e6f7ff' : 'transparent'
}}
>
<div style={{ display: 'flex', alignItems: 'center', gap: '10px' }}>
<Avatar src={contactItem.data.avatar} alt="avatar" />
<span>{contactItem.data.nick || contactItem.data.name}</span>
</div>
</div>
);
};

function ContactListWithSimpleItems() {
return (
<ContactList
ContactItem={SimpleContactItem}
onContactItemClick={(item) => {
console.log('联系人点击:', item);
}}
/>
);
}
效果如下图所示:




自定义联系人详情操作按钮开关

showActions 用于控制是否显示操作按钮,默认值为 true
import React from 'react';
import { ContactInfo } from '@tencentcloud/chat-uikit-react';

function ReadOnlyContactInfo() {
const friendData = {
type: ContactItemType.FRIEND,
data: {
userID: 'user123',
nick: '张三',
avatar: 'https://example.com/avatar.jpg',
remark: '同事',
// ... 其他好友属性
},
};

return (
<ContactInfo
contactItem={friendData}
showActions={false} // 隐藏所有操作按钮,只显示信息
/>
);
}
效果如下图所示:




自定义联系人详情空状态

PlaceholderEmpty 用于自定义空状态显示内容,默认值为 undefined
import React from 'react';
import { ContactInfo } from '@tencentcloud/chat-uikit-react';

function CustomEmptyState() {
const EmptyPlaceholder = () => (
<div style={{
width: '100%',
textAlign: 'center',
padding: '40px 20px',
color: '#999',
fontSize: '14px',
background: '#fff',
}}>
<div style={{ fontSize: '48px', marginBottom: '16px' }}>👤</div>
<div>请选择一个联系人查看详细信息</div>
<div style={{ marginTop: '8px', fontSize: '12px' }}>
点击左侧联系人列表中的任意项目
</div>
</div>
);

return (
<ContactInfo
contactItem={undefined}
PlaceholderEmpty={<EmptyPlaceholder />}
/>
);
}
效果如下图所示:




自定义联系人详情组件

说明:
FriendInfoComponent 用于自定义好友信息组件,默认值为内置的 FriendInfo 组件。
GroupInfoComponent 用于自定义群组信息组件,默认值为内置的 GroupInfo 组件。
BlacklistInfoComponent 用于自定义黑名单信息组件,默认值为内置的 BlacklistInfo 组件。
FriendApplicationInfoComponent 用于自定义好友申请信息组件,默认值为内置的 FriendApplicationInfo 组件。
GroupApplicationInfoComponent 用于自定义群组申请信息组件,默认值为内置的 GroupApplicationInfo 组件。
自定义好友信息组件
自定义群组信息组件
自定义黑名单信息组件
自定义好友申请信息组件
自定义群组申请信息组件
import React from 'react';
import { ContactInfo } from '@tencentcloud/chat-uikit-react';
import type { FriendInfoProps, Friend } from '@tencentcloud/chat-uikit-react';
import { Button } from '@tencentcloud/uikit-base-component-react';

// 自定义好友信息组件
const CustomFriendInfo: React.FC<FriendInfoProps> = ({
friend,
showActions,
onClose,
onSendMessage,
onDeleteFriend
}) => {
return (
<div style={{ padding: '20px', border: '1px solid #e0e0e0', borderRadius: '8px' }}>
<div style={{ display: 'flex', alignItems: 'center', marginBottom: '16px' }}>
<img
src={friend.avatar}
alt="avatar"
style={{ width: '60px', height: '60px', borderRadius: '50%', marginRight: '16px' }}
/>
<div>
<h3 style={{ margin: '0 0 4px 0' }}>{friend.nick}</h3>
<p style={{ margin: '0', color: '#666' }}>备注: {friend.remark}</p>
</div>
</div>
<div style={{ display: 'flex', flexDirection: 'column', gap: '10px', marginBottom: '16px' }}>
<p><strong>用户ID:</strong> {friend.userID}</p>
<p><strong>个性签名:</strong> {friend.selfSignature}</p>
<p><strong>位置:</strong> {friend.location}</p>
</div>


{showActions && (
<div style={{ display: 'flex', gap: '8px' }}>
<Button onClick={() => onSendMessage?.(friend)}>发送消息</Button>
<Button onClick={() => onDeleteFriend?.(friend)}>删除好友</Button>
<Button onClick={onClose}>关闭</Button>
</div>
)}
</div>
);
};

function CustomFriendInfoDemo() {
const friendData = {
type: ContactItemType.FRIEND,
data: {
userID: 'user123',
nick: '张三',
avatar: 'https://example.com/avatar.jpg',
remark: '同事',
selfSignature: '热爱技术,热爱生活',
location: '北京',
// ... 其他属性
},
};

return (
<ContactInfo
contactItem={friendData}
FriendInfoComponent={CustomFriendInfo}
onSendMessage={(friend) => console.log('发送消息给:', friend.nick)}
onDeleteFriend={(friend) => console.log('删除好友:', friend.nick)}
/>
);
}
效果如下图所示:



import React from 'react';
import { ContactInfo, GroupMemberRole } from '@tencentcloud/uikit-component-react';
import type { GroupInfoProps, GroupModel } from '@tencentcloud/uikit-component-react';
import { Button } from '@tencentcloud/uikit-base-component-react';

// 自定义群组信息组件
const CustomGroupInfo: React.FC<GroupInfoProps> = ({
group,
showActions,
onClose,
onEnterGroup,
onLeaveGroup,
onDismissGroup
}) => {
const isOwner = group.selfInfo?.role === GroupMemberRole.OWNER; // 群主
const isAdmin = group.selfInfo?.role === GroupMemberRole.ADMIN; // 管理员

return (
<div style={{ padding: '20px', border: '1px solid #e0e0e0', borderRadius: '8px' }}>
<div style={{ display: 'flex', alignItems: 'center', marginBottom: '16px' }}>
<img
src={group.avatar}
alt="group avatar"
style={{ width: '60px', height: '60px', borderRadius: '8px', marginRight: '16px' }}
/>
<div>
<h3 style={{ margin: '0 0 4px 0' }}>{group.name}</h3>
<p style={{ margin: '0', color: '#666' }}>
群组ID: {group.groupID}
</p>
</div>
</div>
<div style={{ display: 'flex', flexDirection: 'column', gap: '10px', marginBottom: '16px' }}>
<p><strong>群组介绍:</strong> {group.introduction}</p>
<p><strong>群组公告:</strong> {group.notification}</p>
<p><strong>成员数量:</strong> {group.memberCount}/{group.maxMemberCount}</p>
<p><strong>我的角色:</strong> {
isOwner ? '群主' : isAdmin ? '管理员' : '普通成员'
}</p>
</div>

{showActions && (
<div style={{ display: 'flex', gap: '8px' }}>
<Button onClick={() => onEnterGroup?.(group)}>进入群组</Button>
<Button onClick={() => onLeaveGroup?.(group)}>退出群组</Button>
{isOwner && (
<Button onClick={() => onDismissGroup?.(group)}>解散群组</Button>
)}
<Button onClick={onClose}>关闭</Button>
</div>
)}
</div>
);
};

function CustomGroupInfoDemo() {
const groupData = {
type: ContactItemType.GROUP,
data: {
groupID: 'group123',
name: '技术交流群',
avatar: 'https://example.com/group-avatar.jpg',
type: 'Public',
introduction: '技术交流与分享',
notification: '欢迎加入技术交流群',
ownerID: 'owner123',
memberCount: 100,
maxMemberCount: 200,
selfInfo: {
userID: 'currentUser',
role: GroupMemberRole.OWNER, // 群主
nameCard: '群主',
joinTime: Date.now(),
},
},
};

return (
<ContactInfo
contactItem={groupData}
GroupInfoComponent={CustomGroupInfo}
onEnterGroup={(group) => console.log('进入群组:', group.name)}
onLeaveGroup={(group) => console.log('退出群组:', group.name)}
onDismissGroup={(group) => console.log('解散群组:', group.name)}
/>
);
}
效果如下图所示:



import React from 'react';
import { ContactInfo } from '@tencentcloud/uikit-component-react';
import type { BlacklistInfoProps, UserProfile } from '@tencentcloud/uikit-component-react';
import { Button } from '@tencentcloud/uikit-base-component-react';

// 自定义黑名单信息组件
const CustomBlacklistInfo: React.FC<BlacklistInfoProps> = ({
profile,
showActions,
onClose,
onRemoveFromBlacklist
}) => {
return (
<div style={{ padding: '20px', border: '1px solid #e0e0e0', borderRadius: '8px' }}>
<div style={{ display: 'flex', alignItems: 'center', marginBottom: '16px' }}>
<img
src={profile.src}
alt="avatar"
style={{ width: '60px', height: '60px', borderRadius: '50%', marginRight: '16px' }}
/>
<div>
<h3 style={{ margin: '0 0 4px 0', color: '#ff4d4f' }}>{profile.nick}</h3>
<p style={{ margin: '0', color: '#666' }}>用户ID: {profile.userID}</p>
</div>
</div>
<div style={{ display: 'flex', flexDirection: 'column', gap: '10px', marginBottom: '16px' }}>
<p><strong>个性签名:</strong> {profile.selfSignature}</p>
<p><strong>位置:</strong> {profile.location}</p>
<p style={{ color: '#ff4d4f', fontWeight: 'bold' }}>
⚠️ 此用户已被加入黑名单
</p>
</div>

{showActions && (
<div style={{ display: 'flex', gap: '8px' }}>
<Button
onClick={() => onRemoveFromBlacklist?.(profile)}
style={{ backgroundColor: '#52c41a', color: 'white', border: 'none' }}
>
移出黑名单
</Button>
<Button onClick={onClose}>关闭</Button>
</div>
)}
</div>
);
};

function CustomBlacklistInfoDemo() {
const blacklistData = {
type: ContactItemType.BLACK,
data: {
userID: 'user456',
nick: '李四',
src: 'https://example.com/avatar2.jpg',
gender: 1,
birthday: 19920101,
location: '深圳',
selfSignature: '被拉黑用户',
allowType: 1,
adminForbidType: 0,
},
};

return (
<ContactInfo
contactItem={blacklistData}
BlacklistInfoComponent={CustomBlacklistInfo}
onRemoveFromBlacklist={(profile) => console.log('移出黑名单:', profile.nick)}
/>
);
}
效果如下图所示:



import React from 'react';
import { ContactInfo } from '@tencentcloud/uikit-component-react';
import type { FriendApplicationInfoProps, FriendApplication } from '@tencentcloud/uikit-component-react';
import { Button } from '@tencentcloud/uikit-base-component-react';

// 自定义好友申请信息组件
const CustomFriendApplicationInfo: React.FC<FriendApplicationInfoProps> = ({
application,
showActions,
onClose,
onAccept,
onRefuse
}) => {
const formatTime = (timestamp: number) => {
return new Date(timestamp).toLocaleString();
};

return (
<div style={{ padding: '20px', border: '1px solid #e0e0e0', borderRadius: '8px' }}>
<div style={{ display: 'flex', alignItems: 'center', marginBottom: '16px' }}>
<img
src={application.src}
alt="avatar"
style={{ width: '60px', height: '60px', borderRadius: '50%', marginRight: '16px' }}
/>
<div>
<h3 style={{ margin: '0 0 4px 0' }}>{application.nick}</h3>
<p style={{ margin: '0', color: '#666' }}>申请时间: {formatTime(application.time)}</p>
</div>
</div>
<div style={{ display: 'flex', flexDirection: 'column', gap: '10px', marginBottom: '16px' }}>
<p><strong>申请来源:</strong> {application.source}</p>
<p><strong>申请附言:</strong> {application.wording}</p>
<p style={{ color: '#1890ff', fontWeight: 'bold' }}>
📝 新的好友申请
</p>
</div>

{showActions && (
<div style={{ display: 'flex', gap: '8px' }}>
<Button
onClick={() => onAccept?.(application)}
style={{ backgroundColor: '#52c41a', color: 'white', border: 'none' }}
>
接受申请
</Button>
<Button
onClick={() => onRefuse?.(application)}
style={{ backgroundColor: '#ff4d4f', color: 'white', border: 'none' }}
>
拒绝申请
</Button>
<Button onClick={onClose}>关闭</Button>
</div>
)}
</div>
);
};

function CustomFriendApplicationInfoDemo() {
const applicationData = {
type: ContactItemType.FRIEND_REQUEST,
data: {
userID: 'user789',
nick: '王五',
src: 'https://example.com/avatar3.jpg',
time: Date.now(),
source: '搜索添加',
g: '你好,我想加你为好友,一起交流技术',
type: 1,
},
};

return (
<ContactInfo
contactItem={applicationData}
FriendApplicationInfoComponent={CustomFriendApplicationInfo}
onFriendApplicationAction={(action, application) => {
if (action === 'accept') {
console.log('接受好友申请:', application.nick);
} else {
console.log('拒绝好友申请:', application.nick);
}
}}
/>
);
}
效果如下图所示:



import React from 'react';
import { ContactInfo } from '@tencentcloud/uikit-component-react';
import type { GroupApplicationInfoProps, GroupApplication } from '@tencentcloud/uikit-component-react';
import { Button } from '@tencentcloud/uikit-base-component-react';

// 自定义群组申请信息组件
const CustomGroupApplicationInfo: React.FC<GroupApplicationInfoProps> = ({
application,
showActions,
onClose,
onAccept,
onRefuse
}) => {
const getApplicationTypeText = (type: number) => {
return type === 0 ? '用户申请加入' : '邀请用户加入';
};

return (
<div style={{ padding: '20px', border: '1px solid #e0e0e0', borderRadius: '8px' }}>
<div style={{ display: 'flex', alignItems: 'center', marginBottom: '16px' }}>
<div style={{ width: '60px', height: '60px', borderRadius: '8px', marginRight: '16px', backgroundColor: '#f0f0f0', display: 'flex', alignItems: 'center', justifyContent: 'center' }}>
👥
</div>
<div>
<h3 style={{ margin: '0 0 4px 0' }}>{application.groupName}</h3>
<p style={{ margin: '0', color: '#666' }}>
{getApplicationTypeText(application.applicationType)}
</p>
</div>
</div>
<div style={{ display: 'flex', flexDirection: 'column', gap: '10px', marginBottom: '16px' }}>
<p><strong>申请人:</strong> {application.applicantNick}</p>
<p><strong>群组ID:</strong> {application.groupID}</p>
<p><strong>申请备注:</strong> {application.note}</p>
<p style={{ color: '#1890ff', fontWeight: 'bold' }}>
📋 群组申请待处理
</p>
</div>

{showActions && (
<div style={{ display: 'flex', gap: '8px' }}>
<Button
onClick={() => onAccept?.(application)}
style={{ backgroundColor: '#52c41a', color: 'white', border: 'none' }}
>
同意申请
</Button>
<Button
onClick={() => onRefuse?.(application)}
style={{ backgroundColor: '#ff4d4f', color: 'white', border: 'none' }}
>
拒绝申请
</Button>
<Button onClick={onClose}>关闭</Button>
</div>
)}
</div>
);
};

function CustomGroupApplicationInfoDemo() {
const applicationData = {
type: ContactItemType.GROUP_REQUEST,
data: {
applicant: 'user999',
applicantNick: '赵六',
groupID: 'group456',
groupName: '产品经理交流群',
applicationType: 0,
userID: 'user999',
note: '我想加入产品经理交流群,学习产品设计经验',
},
};

return (
<ContactInfo
contactItem={applicationData}
GroupApplicationInfoComponent={CustomGroupApplicationInfo}
onGroupApplicationAction={(action, application) => {
if (action === 'accept') {
console.log('同意群组申请:', application.groupName);
} else {
console.log('拒绝群组申请:', application.groupName);
}
}}
/>
);
}
效果如下图所示:





帮助和支持

本页内容是否解决了您的问题?

填写满意度调查问卷,共创更好文档体验。

文档反馈