ContactList

概述

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);
}
}}
/>
);
}
效果如下图所示: