@tencent-rtc/mcp 1.4.6 → 1.6.0-beta.1

package/resource/knowledge/chat/preset/vue/features/conversation-actions.md

@@ -0,0 +1,234 @@
+## Overview
+
+The `ConversationActions` component manages actions for a single conversation. By default, it supports delete, pin, mute (Do Not Disturb), and mark unread/read.
+
+## Basic Usage
+
+In `ConversationList`, customize conversation actions quickly via the `actionsConfig` prop.
+``` typescript
+<template>
+  <UIKitProvider>
+    <ConversationList :actions-config="actionsConfig" />
+  </UIKitProvider>
+</template>
+
+<script setup lang="ts">
+import { UIKitProvider, ConversationList } from '@tencentcloud/chat-uikit-vue3';
+import type { ConversationInfo } from '@tencentcloud/chat-uikit-vue3';
+
+const actionsConfig = {
+  enablePin: false,
+  onConversationDelete: (conversation: ConversationInfo) => {
+    console.log('Delete conversation success');
+  },
+  customConversationActions: {
+    'custom-actions-1': {
+      label: 'custom-actions',
+      onClick: (conversation: ConversationInfo) => {
+        console.log(conversation);
+      },
+    },
+  },
+};
+</script>
+```
+
+## Advanced Usage
+
+For deeper customization, replace the `ConversationActions` prop on `ConversationList` directly.
+``` typescript
+<template>
+  <UIKitProvider>
+    <ConversationList
+      :ConversationActions="CustomConversationActions"
+    />
+  </UIKitProvider>
+</template>
+
+<script setup lang="ts">
+import { defineComponent } from 'vue';
+import { UIKitProvider, ConversationList, ConversationActions } from '@tencentcloud/chat-uikit-vue3';
+type ConversationActionsProps = Parameters<typeof ConversationActions>[0];
+
+const CustomConversationActions = defineComponent({
+  name: 'CustomConversationActions',
+  setup(props: ConversationActionsProps) {
+    return () => h(ConversationActions, {
+      ...props,
+      enableDelete: false
+    });
+  }
+});
+</script>
+```
+
+## Props
+
+The `ConversationActionsProps` interface for `ConversationActions` extends `ConversationActionsConfig`.
+
+### ConversationActionsProps
+
+| Parameter | Type | Default | Description |
+|---------|---------|---------|---------|
+| conversation (Required) | ConversationInfo | - | Required. The conversation for which actions are rendered. |
+| className | string | - | Custom CSS class for the root element. |
+| style | CSSProperties | - | Custom inline styles for the root element. |
+
+### ConversationActionsConfig
+
+| Parameter | Type | Default | Description |
+|---------|---------|---------|---------|
+| enablePin | boolean | true | Whether to show the pin conversation button. |
+| enableMute | boolean | true | Whether to show the Do Not Disturb button. |
+| enableDelete | boolean | true | Whether to show the delete conversation button. |
+| enableMarkUnread | boolean | true | Whether to show the mark unread button. |
+| onMarkConversationUnread | (conversation: ConversationInfo, e?: Event) => void | - | Custom handler for marking a conversation unread/read. |
+| onConversationPin | (conversation: ConversationInfo, e?: Event) => void | - | Custom handler for pinning/unpinning a conversation. |
+| onConversationMute | (conversation: ConversationInfo, e?: Event) => void | - | Custom handler for enabling/disabling Do Not Disturb. |
+| onConversationDelete | (conversation: ConversationInfo, e?: Event) => void | - | Custom handler for deleting a conversation. |
+| customConversationActions | Record<string, ConversationActionItem> | - | Custom conversation action items. |
+| PopupIcon | any | - | Custom icon for the actions popup trigger. |
+| PopupElements | any[] | - | Custom content for the actions popup. |
+| onClick | (e: Event, key?: string, conversation?: ConversationInfo) => void | - | Callback when an action item is clicked. |
+| onClose | () => void | - | Callback when the actions popup is closed (H5 only). |
+
+### ConversationActionItem
+
+| Parameter | Type | Default | Description |
+|---------|---------|---------|---------|
+| enable | boolean | true | Whether the custom action item is enabled. |
+| label | string | - | Display label for the custom action item. |
+| onClick | (conversation: ConversationInfo, e?: Event) => void | - | Callback when the custom action item is clicked. |
+
+## Events
+
+| Event | Parameters | Description |
+|---------|---------|---------|
+| click | (e: Event, key?: string, conversation?: ConversationInfo) | Fired when an action item is clicked. |
+| close | () | Fired when the actions popup is closed. |
+| markConversationUnread | (conversation: ConversationInfo, e?: Event) | Fired when a conversation is marked unread/read. |
+| conversationPin | (conversation: ConversationInfo, e?: Event) | Fired when a conversation is pinned/unpinned. |
+| conversationMute | (conversation: ConversationInfo, e?: Event) | Fired when Do Not Disturb is enabled/disabled. |
+| conversationDelete | (conversation: ConversationInfo, e?: Event) | Fired when a conversation is deleted. |
+
+## Custom Components
+
+### Basic feature toggles
+
+Use `enablePin`, `enableDelete`, `enableMute`, and `enableMarkUnread` to control whether pin, mute, delete, and mark-unread actions are shown in `ConversationActions`.
+``` typescript
+<template>
+  <!-- Disable pin -->
+  <ConversationActions :enablePin="false" :conversation="conversation" />
+
+  <!-- Disable delete -->
+  <ConversationActions :enableDelete="false" :conversation="conversation" />
+
+  <!-- Disable mute -->
+  <ConversationActions :enableMute="false" :conversation="conversation" />
+
+  <!-- Disable mark unread -->
+  <ConversationActions :enableMarkUnread="false" :conversation="conversation" />
+</template>
+```
+| <code>enablePin: false</code> | <code>enableDelete: false</code> | <code>enableMute: false</code> | enableMarkUnread="false" |
+| --- | --- | --- | --- |
+|  |  |  |  |
+
+### Event handlers
+
+`ConversationActions` supports delete, pin/unpin, mute/unmute, and mark unread/read by default. Override the default handlers when you need custom behavior. You can also listen to `@click` for the base click event.
+``` typescript
+<template>
+  <ConversationList :conversation-actions="CustomConversationActions" />
+</template>
+
+<script setup lang="ts">
+import { defineComponent, h } from 'vue';
+import { ConversationActions, Toast } from '@tencentcloud/chat-uikit-vue3';
+import type { ConversationInfo } from '@tencentcloud/chat-uikit-vue3';
+type ConversationActionsProps = Parameters<typeof ConversationActions>[0];
+
+const CustomConversationActions = defineComponent({
+  name: 'CustomConversationActions',
+  setup(props: ConversationActionsProps) {
+    const handleConversationDelete = (conversation: ConversationInfo) => {
+      conversation.deleteConversation().then(() => {
+        console.log('delete conversation successfully!');
+      }).catch(() => {
+        console.log('delete conversation failed!');
+      });
+    };
+
+    return () => h(ConversationActions, {
+      ...props,
+      onConversationDelete: handleConversationDelete
+    });
+  }
+});
+</script>
+```
+
+### Custom actions
+
+`customConversationActions` adds custom action items to `ConversationActions`.
+
+**Example: Add a custom action item**
+``` typescript
+<template>
+  <ConversationList :ConversationActions="CustomConversationActions" />
+</template>
+
+<script setup lang="ts">
+import { defineComponent, h } from 'vue';
+import { ConversationActions } from '@tencentcloud/chat-uikit-vue3';
+import type { ConversationInfo } from '@tencentcloud/chat-uikit-vue3';
+type ConversationActionsProps = Parameters<typeof ConversationActions>[0];
+
+const CustomConversationActions = defineComponent({
+  name: 'CustomConversationActions',
+  setup(props: ConversationActionsProps) {
+    return () => h(ConversationActions, {
+      ...props,
+      customConversationActions: {
+        'custom-actions-1': {
+          label: 'custom-actions',
+          onClick: (conversation: ConversationInfo) => {
+            console.log(conversation);
+          },
+        },
+      }
+    });
+  }
+});
+</script>
+```
+
+### UI customization
+
+Use `PopupIcon` to customize the popup trigger button and `PopupElements` to customize popup content.
+
+**Example: Custom trigger button**
+``` typescript
+<template>
+  <ConversationList :ConversationActions="CustomConversationActions" />
+</template>
+
+<script setup lang="ts">
+import { defineComponent, h } from 'vue';
+import { ConversationActions } from '@tencentcloud/chat-uikit-vue3';
+type ConversationActionsProps = Parameters<typeof ConversationActions>[0];
+
+const CustomConversationActions = defineComponent({
+  name: 'CustomConversationActions',
+  setup(props: ConversationActionsProps) {
+    const customIcon = h('div', 'Custom Icon');
+
+    return () => h(ConversationActions, {
+      ...props,
+      PopupIcon: customIcon
+    });
+  }
+});
+</script>
+```

package/resource/knowledge/chat/preset/vue/features/conversation-list.md

@@ -0,0 +1,331 @@
+## Component Overview
+
+The `ConversationList` component renders the conversation list and supports search, creation, pinning, deletion, and other conversation actions.
+
+|**Conversation List**|**Conversation Actions**|**Create Conversation**|
+|---------|---------|---------|
+||||
+
+## Component Structure
+
+The `ConversationList` component includes the following:
+- **ConversationSearch**: Conversation search
+
+- **ConversationList UI**: Conversation list container
+
+- **ConversationPreview**: Single-conversation preview
+
+- **ConversationActions**: Per-conversation actions
+
+## Basic Usage
+
+The `ConversationList` component works without any required props.
+``` typescript
+<template>
+  <UIKitProvider>
+    <ConversationList />
+  </UIKitProvider>
+</template>
+<script setup lang="ts">
+import { UIKitProvider, ConversationList } from '@tencentcloud/chat-uikit-vue3';
+</script>
+```
+
+## Customization
+
+`ConversationList` exposes a rich, multi-dimensional props interface for customizing features, UI, modules, and more.
+
+You can replace multiple subcomponents in `ConversationList`, including **Header**, **List**, **ConversationPreview**, **ConversationCreate**, **ConversationSearch**, **ConversationActions**, **Avatar**, and **Placeholder**. You can also extend the default subcomponents for further customization.
+
+### Feature Toggles
+
+Use `enableSearch`, `enableCreate`, and `enableActions` to control whether conversation search, conversation creation, and conversation actions are shown in **ConversationList**.
+``` typescript
+<ConversationList :enableSearch="false" />
+```
+``` typescript
+<ConversationList :enableCreate="false" />
+```
+``` typescript
+<ConversationList :enableActions="false" />
+```
+| <code>enableSearch="false"</code> | <code>enableCreate="false"</code> | <code>enableActions="false"</code> |
+| --- | --- | --- |
+|  |  |  |
+
+### Data Filtering and Sorting
+
+The `ConversationList` component provides `filter` and `sort` props for filtering and sorting the conversation list.
+
+#### Filter Conversations
+
+To filter conversation list data, pass a filter function to the `filter` prop. The function receives a `ConversationModel` array and should return a new array containing only conversations that match your criteria.
+
+**Example: show only conversations with unread messages**
+``` typescript
+<template>
+  <UIKitProvider>
+    <ConversationList
+      :filter="(conversationList: ConversationInfo[]) =>
+        conversationList.filter(conversation => conversation.unreadCount > 0)" />
+  </UIKitProvider>
+</template>
+<script setup lang="ts">
+import { UIKitProvider, ConversationList } from '@tencentcloud/chat-uikit-vue3';
+import type { ConversationInfo } from '@tencentcloud/chat-uikit-vue3';
+</script>
+```
+
+#### Sort Conversations
+
+To sort conversation list data, pass a sort function to the `sort` prop. The function receives a `ConversationModel` array and should return a new array sorted according to your criteria.
+
+**Example: sort by latest message time in descending order**
+``` typescript
+<template>
+  <UIKitProvider>
+    <ConversationList
+      :sort="(conversationList: ConversationInfo[]) =>
+      (a, b) => {
+            const timeA = a.lastMessage?.timestamp?.getTime() || 0;
+            const timeB = b.lastMessage?.timestamp?.getTime() || 0;
+            return timeB - timeA;
+          },
+      "
+    />
+  </UIKitProvider>
+</template>
+<script setup lang="ts">
+import { UIKitProvider, ConversationList } from '@tencentcloud/chat-uikit-vue3';
+import type { ConversationInfo } from '@tencentcloud/chat-uikit-vue3';
+</script>
+```
+
+### Custom actionsConfig
+
+Use `actionsConfig` to customize the conversation action menu.
+``` typescript
+<template>
+  <UIKitProvider>
+    <ConversationList
+      :actionsConfig="{
+        enablePin: false,
+        onConversationDelete: (conversation: ConversationInfo) =>
+        { console.log('Delete conversation success'); },
+        customConversationActions: {
+          'custom-actions-1': {
+            label: 'custom-actions',
+            onClick: (conversation: ConversationInfo) => { console.log(conversation); },
+          },
+        },
+     }"/>
+  </UIKitProvider>
+</template>
+<script setup lang="ts">
+import { UIKitProvider, ConversationList } from '@tencentcloud/chat-uikit-vue3';
+import type { ConversationInfo } from '@tencentcloud/chat-uikit-vue3';
+</script>
+```
+| <code>enablePin: false</code> | <code>enableDelete: false</code> | <code>enableMute: false</code> | <code>customConversationActions</code> |
+| --- | --- | --- | --- |
+|  |  |  |  |
+
+### Custom Placeholder
+
+`ConversationList` supports custom placeholders for different states: empty list, loading, and load error.
+- `PlaceholderEmpty`: Shown when the list is empty.
+
+- `PlaceholderLoading`: Shown while loading.
+
+- `PlaceholderError`: Shown when loading fails.
+
+   **Example: custom empty-list placeholder**
+
+1. **Create a custom component** `MyEmptyPlaceholder.vue`
+
+   ``` typescript
+   <template>
+       <div>
+         Custom PlaceholderEmptyList
+       </div>
+   </template>
+   ```
+2. **Use it in** `ConversationList`**.**
+
+   ``` typescript
+   <template>
+     <UIKitProvider>
+       <ConversationList
+         :PlaceholderEmptyList="MyEmptyPlaceholder" />
+     </UIKitProvider>
+   </template>
+   <script setup lang="ts">
+   import { UIKitProvider, ConversationList } from '@tencentcloud/chat-uikit-vue3';
+   import MyEmptyPlaceholder from "./MyEmptyPlaceholder.vue";
+   </script>
+   ```
+
+### Custom Header
+
+**ConversationListHeader** renders the header section of `ConversationList`. By default, it wraps and renders `Search` and `ConversationCreate`. You can customize it by passing `left`, `right`, and other props, or replace the entire component.
+
+#### Props
+| **Prop Name** | **Type** | **Default** | **Description** |
+| --- | --- | --- | --- |
+| children | Component | - | Custom center component for the conversation list header.<br>By default, `<Search>` and `<ConversationCreate>` are passed in. |
+| left | Component | - | Custom left-side component for the conversation list header. |
+| right | Component | - | Custom right-side component for the conversation list header. |
+| className | String | - | Custom CSS class name for the root element. |
+| style | CSSProperties | - | Custom inline style for the root element. |
+
+##### Example: implement a simple conversation grouping feature
+
+Group conversations into All, Unread, One-to-one, and Group tabs. Clicking a tab applies the corresponding filter rule.
+
+【App.vue】
+``` typescript
+<template>
+  <UIKitProvider>
+    <ConversationList
+      :Header="CustomConversationListHeader"
+      :filter="conversationFilter"
+  </UIKitProvider>
+</template>
+<script setup lang="ts">
+import { UIKitProvider, ConversationList } from '@tencentcloud/chat-uikit-vue3';
+import type { ConversationInfo } from '@tencentcloud/chat-uikit-vue3';
+import CustomConversationListHeader from "./CustomConversationListHeader.vue";
+const conversationFilter = ref<((conversations: ConversationInfo[]) => ConversationModel[]) | undefined>(undefined);
+const handleFilterChange = (filter: (conversations: ConversationInfo[]) => ConversationModel[]) => {
+  conversationFilter.value = filter;
+};
+provide('setConversationFilter', handleFilterChange);
+</script>
+```
+
+【CustomConversationListHeader.vue】
+``` typescript
+<template>
+  <div class="customHeader">
+    <div class="filterTabs">
+      <button
+        v-for="(label, key) in filterLabels"
+        :key="key"
+        :class="[
+          'filterTab',
+          { ['active']: activeFilter === key }
+        ]"
+        @click="handleFilterClick(key as FilterType)"
+      >
+        {{ label }}
+      </button>
+    </div>
+  </div>
+</template>
+
+<script lang="ts" setup>
+import { ref, inject } from 'vue';
+import type { ConversationInfo } from '@tencentcloud/chat-uikit-vue3';
+
+type FilterType = 'All' | 'Unread' | 'C2C' | 'Group';
+
+interface Props {
+  children?: any;
+}
+
+defineProps<Props>();
+
+const activeFilter = ref<FilterType>('All');
+
+const filterLabels: Record<FilterType, string> = {
+  All: 'All',
+  Unread: 'Unread',
+  C2C: 'One-to-one',
+  Group: 'Group',
+};
+
+const conversationGroupFilter: Record<string, (conversationList: ConversationInfo[]) => ConversationModel[]> = {
+  All: (conversationList: ConversationInfo[]) => conversationList,
+  Unread: (conversationList: ConversationInfo[]) => conversationList?.filter((item: ConversationModel) => item.unreadCount > 0),
+  C2C: (conversationList: ConversationInfo[]) => conversationList?.filter((item: ConversationModel) => item.type === 'C2C'),
+  Group: (conversationList: ConversationInfo[]) => conversationList?.filter((item: ConversationModel) => item.type === 'GROUP'),
+};
+
+const setFilter = inject<(filter: any) => void>('setConversationFilter');
+
+const handleFilterClick = (filterType: FilterType) => {
+  activeFilter.value = filterType;
+  const filterFn = conversationGroupFilter[filterType];
+  setFilter?.(filterFn);
+};
+</script>
+
+<style lang="scss">
+.customHeader {
+  padding: 8px 16px;
+  border-bottom: 1px solid rgba(0, 0, 0, 0.08);
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+}
+
+.filterTabs {
+  display: flex;
+  gap: 4px;
+  align-items: center;
+}
+
+.filterTab {
+  position: relative;
+  display: flex;
+  align-items: center;
+  gap: 4px;
+  padding: 6px 12px;
+  border: 1px solid rgba(0, 0, 0, 0.1);
+  border-radius: 16px;
+  background: transparent;
+  cursor: pointer;
+  font-size: 12px;
+  font-weight: 400;
+  color: #3b3d43;
+  transition: all 0.2s ease;
+  outline: none;
+
+  &.active {
+    border: 1px solid #1c66e5;
+    color: #1c66e5;
+    font-weight: 500;
+  }
+}
+</style>
+
+```
+| **Before** | **After** |
+| --- | --- |
+|  |  |
+
+## Props
+
+|**Prop Name**|**Type**|**Default**|**Description**|
+|---------|---------|---------|---------|
+|enableSearch|Boolean|true|Controls whether conversation search is shown.|
+|enableCreate|Boolean|true|Controls whether conversation creation is shown.|
+|enableActions|Boolean|true|Controls whether conversation actions are shown.|
+|actionsConfig|ConversationActionsConfig|-|Custom conversation action configuration.|
+|Header|Component|Header|Custom Header component.|
+|List|Component|List|Custom conversation list component.|
+|Preview|Component|ConversationPreview|Custom conversation preview component.|
+|ConversationCreate|Component|ConversationCreate|Custom conversation creation component.|
+|ConversationSearch|Component|Search|Custom conversation search component.|
+|ConversationActions|Component|ConversationActions|Custom conversation actions component.|
+|Avatar|Component|Avatar|Custom avatar component.|
+|PlaceholderEmptyList|Component|<PlaceHolder type={PlaceHolderTypes.NO_CONVERSATIONS} />|Custom placeholder when the conversation list is empty.|
+|PlaceholderLoading|Component|<PlaceHolder type={PlaceHolderTypes.LOADING} />|Custom placeholder while the conversation list is loading.|
+|PlaceholderLoadError|Component|<PlaceHolder type={PlaceHolderTypes.WRONG} />|Custom placeholder when the conversation list fails to load.|
+|filter|(conversationList: ConversationInfo[]) => ConversationInfo[]|-|Function for filtering the conversation list.|
+|sort|(conversationList: ConversationModel[]) => ConversationModel[]|-|Function for sorting the conversation list.|
+|onConversationSelect|(conversation: ConversationInfo) => void;|-|Callback when a conversation is clicked. Receives the selected conversation.|
+|onBeforeCreateConversation|(params: CreateParams) => CreateParams;|-|Custom logic before creating a conversation. Receives the creation parameters.|
+|onConversationCreate|(conversation: ConversationInfo)  => void;|-|Callback after a conversation is created. Receives the created conversation.|
+|className|String|-|Custom CSS class name for the root element.|
+|style|CSSProperties|-|Custom inline style for the root element.|