@tencentcloud/sdk-mcp 1.3.9 → 1.4.1

package/resource/doc/chatkit/react/components/conversation-actions.md

@@ -0,0 +1,174 @@
+`ConversationActions` 组件负责对于单条会话进行操作，默认支持会话删除、会话置顶/取消置顶、会话免打扰/取消免打扰功能。
+
+## 基础使用
+
+当在 `ConversationList` 使用 `ConversationActions` 时，您可以通过 `ConversationList` 顶层 `actionsConfig` 参数直接进行自定义，`actionsConfig` 支持对于默认会话操作功能开关、事件响应、新增自定义操作项、基础 UI 定制等。
+
+如您需要更高阶的定制，您可以通过 `ConversationActions` 自定义新的组件。
+
+### 使用 actionsConfig 基础定制
+``` typescript
+import { UIKitProvider, ConversationList } from "@tencentcloud/chat-uikit-react";
+import type { ConversationModel } from "@tencentcloud/chat-uikit-react";
+
+const App = () => {
+  return (
+    <UIKitProvider>
+      <ConversationList
+        actionsConfig={{
+          enablePin: false,
+          onConversationDelete: (conversation: ConversationModel) => { console.log('Delete conversation success'); },
+          customConversationActions: {
+            'custom-actions-1': {
+               label: 'custom-actions',
+               onClick: (conversation: ConversationModel) => { console.log(conversation); },
+             },
+          },
+      }}/>
+    </UIKitProvider>
+  );
+}
+```
+
+### 自定义 ConversationActions 组件
+``` typescript
+import { UIKitProvider, ConversationList, ConversationActions } from "@tencentcloud/chat-uikit-react";
+import type { ConversationActionsProps } from '@tencentcloud/chat-uikit-react';
+
+const CustomConversationActions = (props: ConversationActionsProps) => {
+  return <ConversationActions {...props} enableDelete={false} />;
+};
+
+const App = () => {
+  return (
+    <UIKitProvider>
+      <ConversationList
+        style={{ maxWidth: '300px', height: '600px' }}
+        ConversationActions={CustomConversationActions}
+      />
+    </UIKitProvider>
+  );
+}
+```
+
+## Props
+
+`ConversationActions` 组件的接口类型 `ConversationActionsProps` 基于 `ConversationActionsConfig` 接口进行扩展。
+| ##### **IConversationActionsProps** |  |  |  |
+| --- | --- | --- | --- |
+| **参数名** | **类型** | **默认值** | **说明** |
+| **conversation*****(Required)*** | `ConversationModel` | - | 必选参数，表示当前渲染会话操作对应的会话。 |
+| className | `String` | - | 自定义根元素的类名。 |
+| style | `React.CSSProperties` | - | 自定义根元素的样式。 |
+| ##### IConversationActionsConfig |  |  |  |
+| **参数名** | **类型** | **默认值** | **说明** |
+| enablePin | `Boolean` | `true` | 是否显示置顶功能按钮。 |
+| enableMute | `Boolean` | `true` | 是否显示免打扰功能按钮。 |
+| enableDelete | `Boolean` | `true` | 是否显示删除功能按钮。 |
+| onConversationPin | `(conversation: ConversationModel, e?: React.MouseEvent) => void` | - | 自定义置顶/取消置顶会话的行为。 |
+| onConversationMute | `(conversation: ConversationModel, e?: React.MouseEvent)`<br>`=> void` | - | 自定义免打扰/取消免打扰会话的行为。 |
+| onConversationDelete | `(conversation: ConversationModel, e?: React.MouseEvent) => void` | - | 自定义删除会话的行为。 |
+| customConversationActions | `Record<string, ``ConversationActionItem``>` | - | 自定义会话操作项。 |
+| PopupIcon | `ReactElement` | - | 自定义动作弹窗的图标。 |
+| PopupElements | `ReactElement[]` | - | 自定义动作弹窗的内容。 |
+| onClick | `(e: React.MouseEvent, key?: string, conversation?: ConversationModel) => void` | - | 点击动作项时的回调函数。 |
+
+## 自定义组件
+
+### 基础功能开关
+
+通过设置 `enablePin`, `enableDelete` 和 `enableMute` 参数，您可以灵活地控制 `ConversationActions` 中的会话置顶、会话免打扰和会话删除的显示。
+``` typescript
+<ConversationActions enablePin={false} />
+```
+``` typescript
+<ConversationActions enableDelete={false} />
+```
+``` typescript
+<ConversationActions enableMute={false} />
+```
+| `enablePin={false}` | `enableDelete={false}` | `enableMute={false} ` |
+| --- | --- | --- |
+|  |  |  |
+
+### 事件响应
+
+`ConversationActions` 组件默认支持会话删除、会话置顶/取消置顶、会话免打扰/取消免打扰功能，如已有功能的事件响应不符合您的需求，您可以自定义事件响应处理函数并进行覆盖; 除了支持对于功能事件响应的自定义外，您还可以通过 onClick 获取基础点击事件响应。
+``` typescript
+import { ConversationList, ConversationActions, Toast } from '@tencentcloud/chat-uikit-react';
+import type { ConversationActionsProps, ConversationModel } from '@tencentcloud/chat-uikit-react';
+
+const CustomConversationActions = (props: ConversationActionsProps) => {
+  return (
+    <ConversationActions
+      {...props}
+      onConversationDelete={(conversation: ConversationModel) => {
+        conversation.deleteConversation().then(() => {
+          Toast({ text: 'delete conversation successfully!', type: 'info' });
+        }).catch(() => {
+          Toast({ text: 'delete conversation failed!', type: 'error' });
+        });
+      }}
+    />
+  );
+};
+
+<ConversationList ConversationActions={CustomConversationActions} />
+```
+
+### customConversationActions
+
+`customConversationActions` 用于在 ConversationActions 上新增自定义操作项列表。
+| ##### ConversationActionItem |  |  |  |
+| --- | --- | --- | --- |
+| **参数名** | **类型** | **默认值** | **说明** |
+| enable | `Boolean` | `true` | 是否启用自定义操作项。 |
+| label | `String` | - | 自定义操作项的展示内容。 |
+| onClick | `(conversation: ConversationModel, e?: React.MouseEvent) => void` | - | 点击自定义操作项时的回调函数。 |
+
+以下是使用 `customConversationActions` 新增自定义操作项的示例：
+``` typescript
+import { ConversationList, ConversationActions } from '@tencentcloud/chat-uikit-react';
+import type { ConversationActionsProps, ConversationModel } from '@tencentcloud/chat-uikit-react';
+
+const CustomConversationActions = (props: ConversationActionsProps) => {
+  return (
+    <ConversationActions
+      {...props}
+      customConversationActions={{
+        'custom-actions-1': {
+           label: 'custom-actions',
+           onClick: (conversation: ConversationModel) => { console.log(conversation); },
+         },
+      }}
+    />
+  );
+};
+
+<ConversationList ConversationActions={CustomConversationActions} />
+```
+| **修改前** | **修改后** |
+| --- | --- |
+|  |  |
+
+### UI 界面定制
+
+您可以通过 `PopupIcon` 参数定制唤醒弹出按钮样式，通过 `PopupElements` 定制弹出内容。
+
+以下是在默认的 `ConversationActions` 组件的基础上进行二次开发，为其定制新的唤起按钮样式代码示例：
+``` typescript
+import { ConversationList, ConversationActions, ConversationActionsProps } from '@tencentcloud/chat-uikit-react';
+import type { ConversationActionsProps } from '@tencentcloud/chat-uikit-react';
+
+const CustomConversationActions = (props: ConversationActionsProps) => {
+  const customIcon = <div> 自定义 Icon </div>
+  return (
+    <ConversationActions {...props} PopupIcon={customIcon} />
+  );
+};
+
+<ConversationList ConversationActions={CustomConversationActions} />
+```
+| **修改前** | **修改后** |
+| --- | --- |
+|  |  |

package/resource/doc/chatkit/react/components/conversation-list.md

@@ -0,0 +1,333 @@
+## 组件概述
+
+`ConversationList` 组件主要负责会话列表功能，它包含了 Header 部分和 List 部分，具有搜索会话、创建会话、会话置顶、会话删除等功能。
+
+本文档将详细介绍该组件的基础使用，组件定制，自由组合以及组件的 props 参数列表。
+| **会话列表** | **会话操作** | **会话搜索** | **创建会话** |
+| --- | --- | --- | --- |
+|  |  |  |  |
+
+## 组件构成
+
+`ConversationList` 组件包含以下内容：
+- `ConversationSearch` - 会话搜索
+
+- `ConversationList UI` - 会话列表容器
+
+- `ConversationPreview` - 单条会话信息展示
+
+- `ConversationActions` - 单条会话操作
+
+## 基础使用
+
+`ConversationList` 组件没有任何必须属性，您可以通过以下代码使用 `ConversationList`。
+``` typescript
+import { UIKitProvider, ConversationList } from '@tencentcloud/chat-uikit-react';
+
+const App = () => {
+  return (
+    <UIKitProvider>
+      <ConversationList />
+    </UIKitProvider>
+  );
+};
+```
+
+## 自定义组件
+
+`ConversationList` 为用户自定义提供了丰富且多维度的 Props 接口，允许用户自定义功能、UI、模块等。
+
+`ConversationList` 组件提供了多个可替换的子组件，允许用户自定义 `Header`, `List`, `ConversationPreview`, `ConversationCreate`, `ConversationSearch`, `ConversationActions`, `Avatar`, `Placeholder` 等。同时，用户还可以利用默认子组件进行二次开发定制。
+
+### 基础功能开关
+
+通过设置 `enableSearch`, `enableCreate` 和 `enableActions` 参数，您可以灵活地控制 `ConversationList` 中的搜索会话、创建会话和会话操作功能的显示。
+``` typescript
+<ConversationList enableSearch={false} />
+```
+``` typescript
+<ConversationList enableCreate={false} />
+```
+``` typescript
+<ConversationList enableActions={false} />
+```
+| `enableSearch={false}` | `enableCreate={false}` | `enableActions={false}` |
+| --- | --- | --- |
+|  |  |  |
+
+### 数据筛选和排序
+
+ConversationList 组件提供了 `filterConversation` 和 `sortConversation` 属性，可以让您对会话列表数据进行筛选和排序。
+
+#### 筛选会话
+
+要筛选会话列表数据，您可以给 `filterConversation` 属性传递一个筛选函数。这个函数接收一个 ConversationModel 数组作为参数，然后应该返回一个新数组，只包含符合您筛选条件的会话。
+
+下面是一个使用 `filterConversation` 属性来只显示“包含未读消息”的会话的例子：
+``` typescript
+import { ConversationList } from '@tencentcloud/chat-uikit-react';
+import type { ConversationModel } from '@tencentcloud/chat-uikit-react';
+
+<ConversationList
+  filter={(conversationList: ConversationModel[]) =>
+    conversationList.filter(conversation => conversation.unreadCount > 0)}
+/>
+```
+
+#### 排序会话
+
+要排序会话列表数据，您可以给 `sortConversation` 属性传递一个排序函数。这个函数接收一个 ConversationModel 数组作为参数，然后应该返回一个新数组，按照您的排序标准对会话进行排序。
+
+下面是一个使用 `sortConversation` 属性来按照“最新消息时间倒序”排序会话列表的例子：
+``` typescript
+import { ConversationList } from '@tencentcloud/chat-uikit-react';
+import type { ConversationModel } from '@tencentcloud/chat-uikit-react';
+
+<ConversationList
+  sort={(conversationList: ConversationModel[]) =>
+    conversationList.sort(
+      (a, b) => (+(b?.lastMessage?.lastTime || 0)) - (+(a?.lastMessage?.lastTime || 0)),
+    )}
+/>
+```
+
+通过使用 `filter` 和 `sort` 属性，您可以根据您的需求有效地筛选和排序会话列表数据。
+
+### 自定义 actionsConfig
+
+利用 actionsConfig 对 ConversationActions 的基础功能进行控制。
+
+更多定制请详情参见 ConversationActions 章节。
+``` typescript
+import { ConversationList } from '@tencentcloud/chat-uikit-react';
+import type { ConversationModel } from '@tencentcloud/chat-uikit-react';
+
+<ConversationList
+  actionsConfig={{
+    enablePin: false,
+    onConversationDelete: (conversation: ConversationModel) => { console.log('Delete conversation success'); },
+    customConversationActions: {
+      'custom-actions-1': {
+        label: 'custom-actions',
+        onClick: (conversation: ConversationModel) => { console.log(conversation); },
+      },
+    },
+  }}
+/>
+```
+| `enablePin: false` | `enableDelete: false` | `enableMute: false` | `customConversationActions` |
+| --- | --- | --- | --- |
+|  |  |  |  |
+
+### 自定义 Placeholder
+
+您可以通过传入 `PlaceholderEmptyList`、`PlaceholderLoading` 以及 `PlaceholderLoadError` 来定制不同状态下的列表展示。
+
+以下是定制一个新的 `PlaceholderLoading` 示例：
+``` typescript
+import { ConversationList } from '@tencentcloud/chat-uikit-react';
+
+<ConversationList
+  PlaceholderEmptyList={<div>Empty List!!!</div>}
+/>
+```
+
+### 自定义 Header
+
+`ConversationListHeader` 负责 ConversationList Header 部分的渲染工作，作为包裹层渲染默认 `ConversationSearch` 与 `ConversationCreate` 。您可以通过传入 left、right 等属性进行自定义，同时，您也可以自定义整个组件。
+
+#### Props
+| **参数名** | **类型** | **默认值** | **说明** |
+| --- | --- | --- | --- |
+| children | `ReactNode` | - | 自定义会话列表头部中心组件。<br>在 `<ConversationList>` 中使用时，会默认传入 `<ConversationSearch>` 和 `<ConversationCreate>` 。 |
+| left | `ReactElement` | - | 自定义会话列表头部左侧组件。 |
+| right | `ReactElement` | - | 自定义会话列表头部右侧组件。 |
+| className | `String` | - | 指定根元素类的 CSS 自定义名称。 |
+| style | `React.CSSProperties` | - | 指定根元素样式的自定义样式。 |
+
+#### 基础定制
+
+以下是在 Header 组件右侧添加一个新的功能按钮示例。
+``` typescript
+import {
+  ConversationList,
+  ConversationListHeader,
+} from '@tencentcloud/chat-uikit-react';
+import type { ConversationListHeaderProps } from '@tencentcloud/chat-uikit-react';
+
+const CustomConversationListHeader = (props: ConversationListHeaderProps) => {
+    const CustomIcon = <div>自定义 Icon </div>;
+    return (
+      <ConversationListHeader {...props} right={CustomIcon} />
+    );
+};
+
+<ConversationList Header={CustomConversationListHeader} />
+```
+
+#### 高阶定制
+
+以下是实现一个简易的会话分组功能，按照全部会话、未读会话、单聊会话、群会话四个维度进行区分，通过点击不同分组按钮执行不同的筛选规则。
+| **修改前** | **修改后** |
+| --- | --- |
+|  |  |
+
+【React】
+``` typescript
+import { useState } from 'react';
+import TUIChatEngine from '@tencentcloud/chat-uikit-engine';
+import { ConversationList, UIKitProvider } from '@tencentcloud/chat-uikit-react';
+import type { ConversationListHeaderProps, ConversationModel } from '@tencentcloud/chat-uikit-react';
+
+const App = () => {
+  const [currentFilter, setCurrentFilter] = useState<string>('all');
+  const conversationGroupFilter: Record<string, (conversationList: ConversationModel[]) => ConversationModel[]> = {
+    all: (conversationList: ConversationModel[]) => conversationList,
+    unread: (conversationList: ConversationModel[]) => conversationList?.filter((item: ConversationModel) => item.unreadCount > 0),
+    c2c: (conversationList: ConversationModel[]) => conversationList?.filter((item: ConversationModel) => item.type === TUIChatEngine.TYPES.CONV_C2C),
+    group: (conversationList: ConversationModel[]) => conversationList?.filter((item: ConversationModel) => item.type === TUIChatEngine.TYPES.CONV_GROUP),
+  };
+
+  const CustomConversationListHeader = (props: IConversationListHeaderProps) => {
+    return (
+      <div className="conversation-group-wrapper">
+        <button className={currentFilter === 'all' ? 'btn-active' : 'btn-default'} onClick={() => setCurrentFilter('all')}>All</button>
+        <button className={currentFilter === 'unread' ? 'btn-active' : 'btn-default'} onClick={() => setCurrentFilter('unread')}>Unread</button>
+        <button className={currentFilter === 'c2c' ? 'btn-active' : 'btn-default'} onClick={() => setCurrentFilter('c2c')}>C2C</button>
+        <button className={currentFilter === 'group' ? 'btn-active' : 'btn-default'} onClick={() => setCurrentFilter('group')}>Group</button>
+      </div>
+    );
+  };
+
+  return (
+    <UIKitProvider>
+      <ConversationList
+        style={{ maxWidth: '300px', height: '600px' }}
+        Header={CustomConversationListHeader}
+        filter={conversationGroupFilter[currentFilter]}
+      />
+    </UIKitProvider>
+  );
+};
+```
+
+【CSS】
+``` scss
+.conversation-group-wrapper {
+  display: flex;
+  justify-content: space-around;
+  align-items: center;
+  margin: 10px;
+  font-size: 14px;
+  .btn-default{
+    display: flex;
+    padding: 5px 10px;
+    border: 1px solid #b3b3b4;
+    color: #3b3d43;
+    background-color: transparent;
+    border-radius: 2px;
+  }
+  .btn-active{
+    display: flex;
+    padding: 5px 10px;
+    border: 1px solid #1c66e5;
+    color: #1c66e5;
+    background-color: transparent;
+    border-radius: 2px;
+  }
+}
+```
+
+### 自定义 List
+
+`ConversationListContent` 负责 ConversationList 主列表部分的渲染工作。
+
+作为包裹层默认渲染 Context 中计算好的当前会话列表显示数据 `filteredAndSortedConversationList`。
+
+#### Props
+| **参数名** | **类型** | **默认值** | **说明** |
+| --- | --- | --- | --- |
+| children | `ReactNode` | - | 自定义会话列表内容区域组件。<br>在 `<ConversationList> `中使用时，会默认传入 `filteredAndSortedConversationList` 遍历的 `` 列表。 |
+| empty | `Boolean` | `false` | 空会话列表标识位, 在 `<ConversationList>` 中使用时，会判断`filteredAndSortedConversationList.length === 0` 并传入。 |
+| loading | `Boolean` | `false` | 会话列表加载中标识位，在 `<ConversationList>` 中使用时，使用 `useConversationList() `获取 `isLoading` 并传入。 |
+| error | `Boolean` | `false` | 会话列表加载错误标识位，在 `<ConversationList>` 中使用时，使用 `useConversationList() `获取 `isLoadError` 并传入。 |
+| PlaceholderEmptyList | `ReactNode` | `` | 自定义会话列表为空时的占位元素。 |
+| PlaceholderLoading | `ReactNode` | `` | 自定义会话列表加载中的占位元素。 |
+| PlaceholderLoadError | `ReactNode` | `` | 自定义会话列表加载错误时的占位元素。 |
+| className | `String` | - | 指定根元素类的 CSS 自定义名称。 |
+| style | `React.CSSProperties` | - | 指定根元素样式的自定义样式。 |
+
+#### 基础定制
+
+`List` 组件不同状态 UI 效果如下，在 `ConversationList` 内部已处理好每种状态的触发时机。
+
+同时，您可以通过自定义传入 `empty`、`loading`、`error` 来控制组件状态。
+``` typescript
+import { ConversationList, ConversationListContent } from '@tencentcloud/chat-uikit-react';
+import type { ConversationListContentProps } from '@tencentcloud/chat-uikit-react';
+
+const CustomConversationListContent = (props: ConversationListContentProps) => {
+    return <ConversationListContent {...props} loading={true} />;
+};
+
+<ConversationList  List={CustomConversationListContent} />
+```
+| `default` | `empty={true}` | `loading={true}` | `error={true}` |
+| --- | --- | --- | --- |
+|  |  |  |  |
+
+### 自定义 ConversationPreview
+
+详情请参见 ConversationPreview 章节。
+``` typescript
+<ConversationList ConversationPreview={CustomConversationPreview} />
+```
+
+### 自定义 ConversationActions
+
+详情请参见 ConversationActions 章节。
+``` typescript
+  <ConversationList ConversationActions={CustomConversationActions} />
+```
+
+### 自定义 ConversationSearch
+
+详情请参见 ConversationSearch 章节。
+``` typescript
+<ConversationList ConversationSearch={CustomConversationSearch} />
+```
+
+### 自定义 ConversationCreate
+``` typescript
+<ConversationList ConversationCreate={CustomConversationCreate} />
+```
+
+### 自定义 Avatar
+``` typescript
+<ConversationList Avatar={CustomAvatar} />
+```
+
+## APIs/Props
+| **参数名** | **类型** | **默认值** | **说明** |
+| --- | --- | --- | --- |
+| enableSearch | `Boolean` | `true` | 控制会话搜索功能是否显示。 |
+| enableCreate | `Boolean` | `true` | 控制创建会话功能是否显示。 |
+| enableActions | `Boolean` | `true` | 控制会话操作功能是否显示。 |
+| actionsConfig | `ConversationActionsConfig` | - | 用于自定义会话操作配置。 |
+| Header | `ReactElement` | `Header` | 自定义 Header 组件。 |
+| List | `ReactElement` | `List` | 自定义会话列表组件。 |
+| Preview | `ReactElement` | ConversationPreview | 自定义会话预览组件。 |
+| ConversationCreate | `ReactElement` | `ConversationCreate` | 自定义创建会话组件。 |
+| ConversationSearch | `ReactElement` | ConversationSearch | 自定义会话搜索组件。 |
+| ConversationActions | `ReactElement` | ConversationActions | 自定义会话操作组件。 |
+| Avatar | `ReactElement` | `Avatar` | 自定义头像组件。 |
+| PlaceholderEmptyList | `ReactNode` | `` | 自定义会话列表为空时的占位元素。 |
+| PlaceholderLoading | `ReactNode` | `` | 自定义会话列表加载中的占位元素。 |
+| PlaceholderLoadError | `ReactNode` | `` | 自定义会话列表加载错误时的占位元素。 |
+| filter | `(conversationList: ConversationModel[]) => ConversationModel[]` | - | 用于筛选会话列表的函数。 |
+| sort | `(conversationList: ConversationModel[]) => ConversationModel[]` | - | 用于排序会话列表的函数。 |
+| onConversationSelect | `(conversation: ConversationModel) => void;` | - | 点击会话后的回调函数，参数为所点击的会话对象。 |
+| onBeforeCreateConversation | `(params: CreateParams) => CreateParams;` | - | 创建会话前执行的自定义操作，参数为创建会话所需的参数。 |
+| onConversationCreate | `(conversation: ConversationModel)  => void;` | - | 会话创建后的回调函数，参数为创建的会话对象。 |
+| className | `String` | - | 指定根元素类的 CSS 自定义名称。 |
+| style | `React.CSSProperties` | - | 指定根元素样式的自定义样式。 |

package/resource/doc/chatkit/react/components/conversation-preview.md

@@ -0,0 +1,116 @@
+`ConversationPreview` 用于对于会话列表中单条会话内容进行预览，组件负责显示会话信息、未读计数以及提供会话操作功能。
+
+借助原子化的信息展示组件，您可以自由地设计和组合出您所期望的 `ConversationPreview` 布局。
+
+同时，您还可以通过 `onConversationSelect` 函数来自定义选中会话时的行为。
+
+### 基础使用
+
+您可以使用 `ConversationList` 的 `Preview` 属性来自定义会话列表中每个单独会话的预览项，如果没有指定 `Preview` 属性，系统将自动采用 `ConversationPreviewUI` 组件作为默认值。
+``` typescript
+import { ConversationList, ConversationPreviewUI } from '@tencentcloud/chat-uikit-react';
+import type { ConversationPreviewUIProps } from '@tencentcloud/chat-uikit-react';
+
+const CustomConversationPreview = (props: ConversationPreviewUIProps) => {
+  const { Title } = props;
+  return (
+    <ConversationPreviewUI {...props}>
+      {Title}
+      <div>Your custom preview UI</div>
+    </ConversationPreviewUI>
+  );
+};
+
+<ConversationList Preview={CustomConversationPreviewUI}></ConversationList>
+```
+
+### Props
+| **参数名** | **类型** | **默认值** | **说明** |
+| --- | --- | --- | --- |
+| **conversation*****(Required)*** | `ConversationModel` | - | 必选参数，标识当前渲染的会话列表项。 |
+| isSelected | `Boolean` | `false` | 控制会话列表项 UI 是否处于选中状态。 |
+| enableActions | `Boolean` | `true` | 控制会话操作功能是否显示。 |
+| actionsConfig | ConversationActionsConfig | - | 用于自定义会话操作配置。 |
+| highlightMatchString | `String` | - | 会话列表项 Title 高亮匹配关键词，常用于会话搜索结果高亮。 |
+| Title | `String \\| JSX.Element` | `ConversationPreviewTitle` | 渲染会话列表项标题区域。 |
+| LastMessageAbstract | `String \\| JSX.Element` | `ConversationPreviewAbstract` | 渲染会话列表项最新消息摘要区域。 |
+| LastMessageTimestamp | `String \\| JSX.Element` | `ConversationPreviewTimestamp` | 渲染会话列表项最新消息时间戳区域。 |
+| Unread | `String \\| JSX.Element` | `ConversationPreviewUnread` | 渲染会话列表项消息未读标识区域。 |
+| ConversationActions | `ReactElement` | `ConversationActions` | 渲染会话列表项会话操作区域。 |
+| Avatar | `ReactElement` | `Avatar` | 渲染会话列表项头像区域。 |
+| onConversationSelect | `(conversation: ConversationModel) => void;` | - | 指定在选择对话列表中的对话时接收回调的属性。 |
+| className | `String` | - | 指定根元素类的 CSS 自定义名称。 |
+| style | `React.CSSProperties` | - | 指定根元素样式的自定义样式。 |
+
+## 自定义案例
+
+### 类 Discord 风格
+
+Discord 是一个流行的聊天应用程序，类似于 Skype 或 Telegram。Discord 中的聊天内容如下图所示:
+
+通过对 `ConversationPreview` 布局、功能以及样式的定制，我们可以快速实现类 Discord 效果。
+
+【React】
+1. 定制 `ConversationListPreview`
+
+2. 切换主题到深色模式
+
+``` typescript
+import { UIKitProvider, ConversationList, ConversationPreviewUI } from '@tencentcloud/chat-uikit-react';
+import type { ConversationPreviewUIProps } from '@tencentcloud/chat-uikit-react';
+
+const CustomConversationPreview = (props: ConversationPreviewUIProps) => {
+  const { Title } = props;
+  return (
+    <ConversationPreviewUI {...props}>
+      <span> # </span>
+      <span>{Title}</span>
+    </ConversationPreviewUI>
+  );
+};
+
+const App = () => {
+    <UIKitProvider theme={'dark'}>
+      <ConversationList
+        style={{ maxWidth: '300px', height: '600px' }}
+        Preview={CustomConversationPreviewUI}
+       />
+      ...
+    </UIKitProvider>
+}
+```
+
+【CSS】
+``` scss
+.custom-preview-ui {
+  height: 34px;
+  border-radius: 6px;
+  padding: 10px;
+  margin: 0 10px;
+  .custom-preview-ui__tag {
+    margin-right: 10px;
+    font-size: 16px;
+    color: #b3b3b4;
+  }
+  .custom-preview-ui__title {
+    font-size: 14px;
+    color: #b3b3b4;
+  }
+  &.uikit-conversation-preview--active {
+    background-color: #3b3d43;
+    .custom-preview-ui__tag {
+      color: #ffffff;
+    }
+    .custom-preview-ui__title {
+      .uikit-conversation-preview__title {
+        color: #ffffff;
+      }
+    }
+  }
+}
+```
+
+`ConversationListPreview` 定制后效果如下：
+| **修改前** | **修改后** |
+| --- | --- |
+|  |  |

package/resource/doc/chatkit/react/components/conversation-search.md

@@ -0,0 +1,57 @@
+`ConversationSearch` 是使用的 Search 组件，支持用户、群组、消息的搜索功能。它集成了搜索框、高级搜索、搜索结果展示等功能。
+
+## 基础使用
+``` typescript
+import {
+   UIKitProvider,
+   ConversationList,
+   ConversationSearch,
+} from '@tencentcloud/chat-uikit-react';
+
+import type {
+   ConversationSearchProps,
+   SearchResultItem,
+} from '@tencentcloud/chat-uikit-react';
+
+const CustomConversationSearch = (props: ConversationSearchProps) => {
+  const onSelectResult = (data: SearchResultItem, type: ISearchType) => {
+    console.warn(`Select Search Result: ${JSON.stringify(data)}, type: ${type}`);
+  };
+  return (
+    <ConversationSearch {...props} onResultItemClick={onSelectResult} />
+  );
+};
+
+const App = () => {
+  return (
+    <UIKitProvider>
+      <ConversationList
+        style={{ maxWidth: '300px', height: '600px' }}
+        ConversationSearch={CustomConversationSearch}
+       />
+     </UIKitProvider>
+  );
+};
+```
+
+## Props
+| **参数名** | **类型** | **默认值** | **说明** |
+| --- | --- | --- | --- |
+| visible | `boolean` | `true` | 是否可见 |
+| Search | `ComponentType<SearchProps>` | - | 自定义搜索组件 |
+| variant | `VariantType` | `VariantType.MINI` | 搜索模式：`mini`(迷你)、`standard`(标准)、`embedded`(嵌入式) |
+| SearchBar | `React.ComponentType<SearchBarProps>` | `DefaultSearchBar` | 自定义搜索框组件 |
+| SearchResults | `React.ComponentType<SearchResultsProps>` | `DefaultSearchResults` | 自定义搜索结果组件 |
+| SearchAdvanced | `React.ComponentType<SearchAdvancedProps>` | `DefaultSearchAdvanced` | 自定义高级搜索组件 |
+| SearchResultsPresearch | `React.ComponentType` | - | 搜索前占位符组件 |
+| SearchResultsLoading | `React.ComponentType` | - | 加载中占位符组件 |
+| SearchResultsEmpty | `React.ComponentType` | - | 空结果占位符组件 |
+| SearchResultItem | `React.ComponentType<ResultItemProps>` | - | 自定义搜索结果项组件 |
+| debounceTime | `number` | `300` | 搜索防抖时间(毫秒) |
+| autoFocus | `boolean` | `false` | 是否自动聚焦搜索框 |
+| className | `string` | - | 自定义样式类名 |
+| style | `React.CSSProperties` | - | 自定义样式 |
+| onKeywordChange | `(keyword: string) => void` | - | 搜索关键词变化回调 |
+| onSearchComplete | `(results: Map<SearchType, SearchResult>) => void` | - | 搜索完成回调 |
+| onResultItemClick | `(data: SearchResultItem, type: SearchType) => void` | - | 搜索结果点击回调 |
+| onError | `(error: Error) => void` | - | 搜索错误回调 |