## 概述

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) | 加入群组事件 |

## 基础用法
``` typescript
<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 中的搜索好友群组功能的显示。
``` typescript
<template>
  <ContactList :enableSearch="false" />
</template>
```
| enableSearch="true" | enableSearch="false" |
| --- | --- |
|  |  |

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

`groupConfig` 用于自定义分组配置，包括标题、显示顺序、隐藏分组等。
``` typescript
<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` 组件来完全控制联系人列表项的渲染。
``` typescript
<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>

```
``` typescript
<template>
  <ContactList :ContactItem="CustomContactItem" />
</template>

<script setup lang="ts">
import { ContactList } from '@tencentcloud/chat-uikit-vue3';
import CustomContactItem from './CustomContactItem.vue';
</script>
```
| 修改前 | 修改后 |
| --- | --- |
|  |  |

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

通过设置 `showActions` 参数，您可以控制联系人详情页面中操作按钮的显示。
``` typescript
<template>
  <ContactInfo
    :showActions="false"
  />
</template>
```
| 修改前 | 修改后 |
| --- | --- |
|  |  |

### 自定义联系人详情空状态

当没有选中任何联系人时，您可以自定义显示的空状态组件。
``` typescript
<template>
  <div>
    自定义空状态
  </div>
</template>
```
``` typescript
<template>
  <ContactInfo
    :PlaceholderEmpty="CustomEmpty"
  />
</template>

<script setup lang="ts">
import { ContactList } from '@tencentcloud/chat-uikit-vue3';
import CustomEmpty from './CustomEmpty.vue';
</script>
```

### 自定义好友详情组件

您可以为不同类型的联系人自定义详情显示组件。
``` typescript
<template>
  <div class="custom-contact-info">
    <label>自定义好友详情</label>
    <div class="friend-info">

      <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>

```
``` typescript
<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>
```
| 修改前 | 修改后 |
| --- | --- |
|  |  |