概述
ContactList 是一个高度可配置的联系人列表组件。该组件支持好友列表、群组列表、黑名单和申请管理，提供分组折叠、搜索过滤、自定义渲染等核心功能，适用于即时通讯、社交应用等场景的联系人管理界面。
ContactList Props
字段 | 类型 | 默认值 | 描述 |
activeContactItem | ContactGroupItem | undefined | undefined | 当前激活的联系人项 |
enableSearch | boolean | true | 是否启用搜索功能 |
groupConfig | Partial<Record<ContactItemType, CustomGroupConfig>> | {} | 自定义分组配置 |
searchPlaceholder | string | 'Search contacts' | 搜索框占位符文本 |
emptyText | string | 'No contacts' | 空状态提示文本 |
ContactItem | Component | undefined | ContactListItem | 自定义联系人项组件 |
ContactSearchComponent | Component | undefined | ContactSearch | 自定义搜索组件 |
GroupHeader | Component | undefined | 默认分组头 | 自定义分组头部组件 |
PlaceholderEmptyList | Component | undefined | 默认空状态 | 自定义空状态组件 |
onContactItemClick | (item: ContactGroupItem) => void | undefined | 联系人项点击事件 |
onFriendApplicationAction | (action: 'accept' | 'refuse', application: FriendApplication) => void | undefined | 好友申请操作事件 |
onGroupApplicationAction | (action: 'accept' | 'refuse', application: GroupApplication) => void | undefined | 群组申请操作事件 |
ContactList Events
事件名 | 参数 | 描述 |
contact-item-click | (item: ContactGroupItem) | 联系人项点击事件 |
friend-application-action | (action: 'accept' | 'refuse', application: FriendApplication) | 好友申请操作事件 |
group-application-action | (action: 'accept' | 'refuse', application: GroupApplication) | 群组申请操作事件 |
ContactInfo Props
字段 | 类型 | 默认值 | 描述 |
contactItem | ContactGroupItem | undefined | undefined | 当前显示的联系人项 |
showActions | boolean | true | 是否显示操作按钮 |
PlaceholderEmpty | Component | undefined | undefined | 空状态占位组件 |
FriendInfoComponent | Component | FriendInfo | 好友信息组件 |
GroupInfoComponent | Component | GroupInfo | 群组信息组件 |
BlacklistInfoComponent | Component | BlacklistInfo | 黑名单信息组件 |
FriendApplicationInfoComponent | Component | FriendApplicationInfo | 好友申请信息组件 |
GroupApplicationInfoComponent | Component | GroupApplicationInfo | 群组申请信息组件 |
SearchGroupInfoComponent | Component | SearchGroupInfo | 搜索群组信息组件 |
SearchUserInfoComponent | Component | SearchUserInfo | 搜索用户信息组件 |
ContactInfo Events
事件名 | 参数 | 描述 |
close | - | 关闭信息面板事件 |
sendMessage | (friend: Friend) | 发送消息事件 |
deleteFriend | (friend: Friend) | 删除好友事件 |
addToBlacklist | (friend: Friend) | 添加到黑名单事件 |
removeFromBlacklist | (profile: UserProfile) | 从黑名单移除事件 |
updateFriendRemark | (friend: Friend) | 更新好友备注事件 |
enterGroup | (group: GroupModel) | 进入群组事件 |
leaveGroup | (group: GroupModel) | 退出群组事件 |
dismissGroup | (group: GroupModel) | 解散群组事件 |
friendApplicationAction | (action: 'accept' | 'refuse', application: FriendApplication) | 好友申请操作事件 |
groupApplicationAction | (action: 'accept' | 'refuse', application: GroupApplication) | 群组申请操作事件 |
addFriend | (user: UserProfile, wording: string) | 添加好友事件 |
joinGroup | (group: GroupModel, note: string) | 加入群组事件 |
基础用法
<template><div class="contact-container"><ContactList /><ContactInfo /></div></template><script setup lang="ts">import { ContactList, ContactInfo } from '@tencentcloud/chat-uikit-vue3';</script><style scoped>.contact-container {display: flex;height: 100vh;}</style>
自定义
自定义联系列表搜索功能开关
通过设置
enableSearch 参数，您可以灵活地控制 ContactList 中的搜索好友群组功能的显示。<template><ContactList :enableSearch="false" /></template>
enableSearch="true" | enableSearch="false" |
 |  |
自定义联系列表联系人分组配置
groupConfig 用于自定义分组配置，包括标题、显示顺序、隐藏分组等。<template><ContactList :groupConfig="customGroupConfig" /></template><script setup lang="ts">import { ContactList } from '@tencentcloud/chat-uikit-vue3';import { ContactItemType } from '@tencentcloud/chat-uikit-vue3';const customGroupConfig = {[ContactItemType.FRIEND]: {title: '我的朋友们',order: 1,},[ContactItemType.GROUP]: {title: '群聊列表',order: 2,},[ContactItemType.BLACK]: {hidden: true,},[ContactItemType.FRIEND_REQUEST]: {title: '好友请求',order: 0,}};</script>
修改前 | 修改后 |
|  |
自定义联系列表子项
您可以通过传入自定义的
ContactItem 组件来完全控制联系人列表项的渲染。<template><div class="custom-contact-item" @click="handleClick"><label>自定义联系人</label><span v-if="props.contactItem.type === ContactItemType.FRIEND">{{ props.contactItem.data.nick }}</span><span v-if="props.contactItem.type === ContactItemType.GROUP">{{ props.contactItem.data.name }}</span></div></template><script setup lang="ts">import { ContactItemType } from '@tencentcloud/chat-uikit-vue3';const props = defineProps<{contactItem: any;}>();const emit = defineEmits<{click: [type: ContactItemType, item: any];}>();const handleClick = () => {emit('click', props.contactItem.type, props.contactItem.data);};</script><style scoped>.custom-contact-item {display: flex;align-items: center;gap: 10px;padding: 10px 20px;border-bottom: 1px solid #eee;}</style>
<template><ContactList :ContactItem="CustomContactItem" /></template><script setup lang="ts">import { ContactList } from '@tencentcloud/chat-uikit-vue3';import CustomContactItem from './CustomContactItem.vue';</script>
修改前 | 修改后 |
 |  |
自定义联系人详情操作按钮开关
通过设置
showActions 参数，您可以控制联系人详情页面中操作按钮的显示。<template><ContactInfo:showActions="false"/></template>
修改前 | 修改后 |
 |  |
自定义联系人详情空状态
当没有选中任何联系人时，您可以自定义显示的空状态组件。
<template><div>自定义空状态</div></template>
<template><ContactInfo:PlaceholderEmpty="CustomEmpty"/></template><script setup lang="ts">import { ContactList } from '@tencentcloud/chat-uikit-vue3';import CustomEmpty from './CustomEmpty.vue';</script>
自定义好友详情组件
您可以为不同类型的联系人自定义详情显示组件。
<template><div class="custom-contact-info"><label>自定义好友详情</label><div class="friend-info"><imgclass="avatar":src="friend.avatar"alt=""><span>{{ friend.nick }}</span></div></div></template><script setup lang="ts">import type { Friend } from '@tencentcloud/chat-uikit-vue3';defineProps<{friend: Friend;}>();</script><style scoped>.custom-contact-info {display: flex;flex-direction: column;gap: 10px;padding: 20px;}.friend-info {display: flex;justify-content: space-between;align-items: center;gap: 10px;}.avatar {width: 60px;height: 60px;border-radius: 50%}</style>
<template><ContactInfo:FriendInfoComponent="CustomFriendInfo"/></template><script setup lang="ts">import { defineComponent, h } from 'vue';import type { FriendInfoProps, GroupInfoProps } from '@tencentcloud/chat-uikit-vue3';import CustomFriendInfo from './CustomFriendInfo.vue';</script>
修改前 | 修改后 |
 |  |
