@tencent-rtc/mcp 1.4.7 → 1.6.0

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

@@ -0,0 +1,350 @@
+## Overview
+
+`MessageList` is the core component of the chat UI. It renders the message list and provides rich interaction features. It supports message aggregation, auto-scroll, historical message loading, read receipts, and other advanced capabilities, making it suitable for highly customizable chat interfaces. The component handles scroll behavior, message loading logic, and grouped message display internally for a smooth browsing experience.
+
+## Features
+- **Message display**: Renders multiple message types (text, image, video, file, custom messages, and more).
+
+- **Message aggregation**: Automatically groups adjacent messages from the same sender based on a time interval.
+
+- **Smart scrolling**: Auto-scrolls to the bottom and supports manual scroll control.
+
+- **History loading**: Pull up to load more historical messages.
+
+- **Read receipts**: Supports displaying message read status.
+
+- **Message actions**: Supports actions such as recall and delete.
+
+- **Custom rendering**: Supports custom message components and time divider components.
+
+## Quick Start
+
+The following example shows the simplest way to use `MessageList`.
+``` typescript
+<template>
+  <UIKitProvider>
+    <Chat>
+      <MessageList />
+      <MessageInput />
+    </Chat>
+  </UIKitProvider>
+</template>
+
+<script lang="ts" setup>
+import { UIKitProvider, Chat, MessageList, MessageInput } from '@tencentcloud/chat-uikit-vue3';
+</script>
+
+```
+
+Usage notes:
+1. `MessageList` must be used inside `UIKitProvider` and the `Chat` container.
+
+2. `MessageList` is typically paired with `MessageInput`.
+
+## Props Quick Reference
+
+| Field | Type | Default | Description |
+|---------|---------|---------|---------|
+| alignment | 'left' \| 'right' \| 'two-sided' | 'two-sided' | Message alignment mode: left, right, or two-sided. |
+| enableReadReceipt | boolean | false | Whether to enable message read receipts. |
+| messageActionList | MessageAction[] | undefined | Custom message action list (e.g., recall, delete). |
+| messageAggregationTime | number | 300 (seconds) | Message aggregation interval in seconds. Messages from the same sender within this interval are grouped. Set to `0` to disable aggregation. |
+| filter | (message: MessageInfo) => boolean | undefined | Custom filter function to control which messages are displayed. |
+| enableReadReceipt | boolean | false | Whether to enable message read receipts. |
+| Message | Component | undefined | Custom component for rendering a single message. |
+| MessageTimeDivider | Component | undefined | Custom time divider component. |
+
+## Detailed Props
+
+### alignment
+- **Type**: `'left' | 'right' | 'two-sided'`
+
+- **Description**: Controls how messages are aligned in the list. `'left'` aligns all messages to the left; `'right'` aligns all messages to the right; `'two-sided'` right-aligns sent messages and left-aligns received messages. Default: `'two-sided'`.
+
+### messageAggregationTime
+- **Type**: `number`
+
+- **Description**: Time interval for message aggregation, in seconds. When the same sender sends multiple messages within this interval, they are grouped together. Set to `0` or a smaller value to disable aggregation and show each message independently. Default: `300` (5 minutes).
+
+### enableReadReceipt
+- **Type**: `boolean`
+
+- **Description**: Whether to enable message read receipts. When set to `true`, the component attempts to display read status for messages. Default: `false`.
+
+### messageActionList
+- **Type**: `MessageAction[]`
+
+- **Description**: Defines the custom action list available on messages, such as copy, recall, forward, and delete. Pass an array of `MessageAction` objects to customize behavior. Default: `undefined`; the component uses the default list from the `useMessageActions` hook.
+
+   The default order is: `['copy', 'recall', 'quote', 'forward', 'delete']`.
+
+   **MessageAction** type definition:
+
+   ``` typescript
+   import type { Component } from 'vue';
+   import type { MessageInfo } from '@tencentcloud/chat-uikit-vue3';
+
+   interface MessageAction {
+     /** Unique action identifier */
+     key: string;
+     /** Display label for the action */
+     label: string;
+     /** Icon component or icon name */
+     icon?: Component | string;
+     /** Callback when the action is clicked */
+     onClick?: (message: MessageInfo) => void;
+     /** Controls visibility; boolean or a function based on the message */
+     visible?: boolean | ((message: MessageInfo) => boolean);
+     /** Custom component that replaces the default label and icon */
+     component?: Component;
+     /** Custom CSS class name */
+     className?: string;
+     /** Custom inline styles */
+     style?: Record<string, any>;
+   }
+   ```
+
+   Use the `useMessageActions` hook to get the full message action list and customize it. The hook accepts an optional array of action keys (`string`) or full `MessageAction` objects. Passing a `string` array uses the default configuration for those actions; passing `MessageAction` objects merges and overrides the defaults.
+
+#### Example 1: Reorder message actions
+
+The following code moves the `forward` action to the first position.
+``` typescript
+<template>
+  <MessageList :messageActionList="actions" />
+</template>
+
+<script lang="ts" setup>
+import { MessageList, useMessageActions } from '@tencentcloud/chat-uikit-vue3';
+
+const actions = useMessageActions(['forward', 'copy', 'recall', 'quote', 'delete']);
+</script>
+```
+
+Result:
+
+#### Example 2: Show only selected message actions
+
+Show only `copy` and `recall`; hide all other actions.
+``` typescript
+<template>
+  <MessageList :messageActionList="actions" />
+</template>
+
+<script lang="ts" setup>
+import { MessageList, useMessageActions } from '@tencentcloud/chat-uikit-vue3';
+
+const actions = useMessageActions(['copy', 'recall']);
+</script>
+```
+
+Result:
+
+#### Example 3: Customize message action style and logic
+
+The following example customizes the forward action:
+1. Change the label to `'Forward ⚠️'`
+
+2. Change the color to orange
+
+3. Allow forwarding only for messages sent by others
+
+   ``` typescript
+   <template>
+     <MessageList :messageActionList="actions" />
+   </template>
+
+   <script lang="ts" setup>
+   import { MessageList, useMessageActions } from '@tencentcloud/chat-uikit-vue3';
+
+   const actions = useMessageActions(['copy', {
+     key: 'forward',
+     label: 'Forward ⚠️',
+     style: {
+       color: 'orange',
+     },
+     visible: (message) => message.isSentBySelf === false,
+   }, 'quote', 'recall', 'delete']);
+   </script>
+   ```
+
+   Result:
+
+#### Example 4: Add a custom message action
+
+Add a custom "Like" action that is visible only for messages sent by others, inserted after the "recall" action.
+``` typescript
+<template>
+  <MessageList :messageActionList="actions" />
+</template>
+
+<script lang="ts" setup>
+import { MessageList, useMessageActions } from '@tencentcloud/chat-uikit-vue3';
+
+const customLikeAction = {
+  key: 'like',
+  label: 'Like',
+  icon: '🩷',
+  visible: (message) => message.isSentBySelf === false,
+  onClick: (message) => {
+    console.log('like message:', message.msgID);
+    // Implement like logic here, e.g., call a backend API
+  },
+};
+
+const actions = useMessageActions(['forward', 'copy', 'recall', customLikeAction, 'quote', 'delete']);
+</script>
+```
+
+Result:
+
+### filter
+- **Type**: `((message: MessageInfo) => boolean) | undefined`
+
+- **Description**: A custom filter function applied before messages are rendered. It receives a `MessageInfo` object and returns a boolean. Return `true` to display the message; return `false` to hide it. Default: `undefined` (no extra filtering; the component still filters out messages where `isDeleted` is `true`).
+
+#### Example: Filter out text messages from bots
+
+This example shows how to use the `filter` prop to hide specific messages from certain users.
+``` typescript
+<template>
+  <MessageList :filter="customMessageFilter" />
+</template>
+
+<script lang="ts" setup>
+import { MessageList, MessageType } from '@tencentcloud/chat-uikit-vue3';
+import type { MessageInfo } from '@tencentcloud/chat-uikit-vue3';
+
+// Custom message filter function
+const customMessageFilter = (message: MessageInfo): boolean => {
+  if (
+    message.nick?.includes('_robot')
+    && message.messageType === MessageType.Text as any
+  ) {
+    return false;
+  }
+  return true;
+};
+</script>
+```
+
+### Message
+- **Type**: `Component | undefined`
+
+- **Description**: Custom component for rendering a single message in the list.
+
+   To fully control message appearance and internal logic, pass a Vue component to replace the default renderer. The custom component receives props such as `message`, `alignment`, and `messageActionList`. By default, the built-in `Message` component is used.
+
+   This example shows how to override the `Message` component to display avatar and nickname on your own messages (by default, sent messages do not show avatar or nickname).
+
+   ``` typescript
+   <template>
+     <MessageList :Message="MessageWithSelfAvatarAndNick" />
+   </template>
+
+   <script lang="ts" setup>
+   import { defineComponent, h } from 'vue';
+   import { MessageList, Message } from '@tencentcloud/chat-uikit-vue3';
+
+   const MessageWithSelfAvatarAndNick = defineComponent({
+     name: 'MessageWithSelfAvatar',
+     inheritAttrs: false,
+     setup(_, { attrs }) {
+       return () => h(Message as Component, {
+         ...attrs,
+         removeAvatar: false,
+         isHiddenMessageNick: false,
+       });
+     },
+   });
+   </script>
+   ```
+
+### MessageTimeDivider
+- **Type**: `Component | undefined`
+
+- **Description**: Custom component for rendering time dividers.
+
+   Pass a Vue component to replace the default time divider. The custom component receives props such as `currentMessage` (the message associated with the divider) and `previousMessage` (the previous message). Use these to control divider display logic and styling. By default, the built-in `MessageTimeDivider` component is used.
+
+   This example creates a custom time divider that labels business hours vs. off hours based on message timestamps.
+
+   ``` typescript
+   <template>
+     <MessageList :MessageTimeDivider="BusinessTimeDivider" />
+   </template>
+
+   <script lang="ts" setup>
+   import { defineComponent, h } from 'vue';
+   import { MessageList } from '@tencentcloud/chat-uikit-vue3';
+   import type { MessageInfo } from '@tencentcloud/chat-uikit-vue3';
+
+   const BusinessTimeDivider = defineComponent({
+     name: 'BusinessTimeDivider',
+     props: {
+       previousMessage: {
+         type: Object as PropType<MessageInfo | undefined>,
+         default: undefined,
+       },
+       currentMessage: {
+         type: Object as PropType<MessageInfo>,
+         required: true,
+       },
+     },
+     setup(props) {
+       return () => {
+         if (!props.previousMessage || !props.currentMessage) {
+           return null;
+         }
+
+         const currentTime = props.currentMessage.timestamp ?? new Date();
+         const previousTime = props.previousMessage.timestamp ?? new Date();
+         const shouldShow = currentTime.toDateString() !== previousTime.toDateString()
+           || currentTime.getTime() - previousTime.getTime() > 4 * 60 * 60 * 1000;
+
+         if (!shouldShow) {
+           return null;
+         }
+
+         const hour = currentTime.getHours();
+         const day = currentTime.getDay();
+         const isWorkingTime = day >= 1 && day <= 5 && hour >= 9 && hour <= 18;
+
+         return h('div', { class: 'message-props-demo__time-divider' }, [
+           h(
+             'span',
+             {
+               class: isWorkingTime
+                 ? 'message-props-demo__time-label message-props-demo__time-label--work'
+                 : 'message-props-demo__time-label message-props-demo__time-label--off',
+             },
+             isWorkingTime ? 'Business hours' : 'Off hours',
+           ),
+           currentTime.toLocaleString(),
+         ]);
+       };
+     },
+   });
+   </script>
+   ```
+
+## Related Documentation
+- Custom Components - UIKitProvider
+
+- Custom Components - ConversationList
+
+- Custom Components - Chat
+
+- Custom Components - MessageInput
+
+- Custom Components - ChatSetting
+
+- Custom Components - ContactList
+
+- Custom Components - Search
+
+- [chat-uikit-vue3 npm](https://www.npmjs.com/package/@tencentcloud/chat-uikit-vue3)
+
+- [GitHub Demo](https://github.com/Tencent-RTC/TUIKit_Vue3/tree/main/demos/rtcube-vite-vue3)
+
+## Community and Feedback

package/resource/{doc/chatkit/vue/components → knowledge/chat/preset/vue/features}/search.md

@@ -1,37 +1,38 @@
 ## Overview
 
-Search is a complete search solution that includes a comprehensive component set for search box, search results display, advanced search, and more. It's suitable for user, group, and message search scenarios in instant messaging, online meetings, online education, and more.
+Search is a complete search solution with a full set of components, including search bar, result display, advanced search, and more. It is suitable for user, group, and message search in instant messaging, online meeting, and online education scenarios.
 
 > **Note:**
 >
 
-> This feature is a value-added service that requires you to purchase the Cloud Search Plugin. Please click [Purchase](https://console.trtc.io/chat/plugin/TUICloudSearch).
+> This feature is a value-added service. You need to purchase the cloud search plugin. Click [Purchase](https://cloud.tencent.com/document/product/269/120945).
 >
 
 ## Search Modes
 | **Mini Mode (MINI)** | **Standard Mode (STANDARD)** | **Embedded Mode (EMBEDDED)** |
 | --- | --- | --- |
-| Suitable for sidebar or small containers<br>Displays limited number of results<br>Supports expanding to view more | Suitable for full-screen search interface<br>Complete feature display<br>Supports advanced search | Suitable for chat interface<br>Focuses on message search<br>Optimized layout |
+| Suitable for sidebars or small containers<br>Shows a limited number of results<br>Supports expand to view more | Suitable for full-screen search UI<br>Full feature set<br>Supports advanced search | Suitable for chat UI<br>Focused on message search<br>Optimized layout |
 
 ## Props
-| Property | Type | Default Value | Description |
-| --- | --- | --- | --- |
-| variant | VariantType | VariantType.MINI | Search mode: mini (Mini), standard (Standard), embedded (Embedded) |
-| SearchBar | Component<SearchBarProps> | DefaultSearchBar | Custom search bar component |
-| SearchResults | Component<SearchResultsProps> | DefaultSearchResults | Custom search results component |
-| SearchAdvanced | Component<SearchAdvancedProps> | DefaultSearchAdvanced | Custom advanced search component |
-| SearchResultsPresearch | Component | - | Pre-search placeholder component |
-| SearchResultsLoading | Component | - | Loading placeholder component |
-| SearchResultsEmpty | Component | - | Empty results placeholder component |
-| SearchResultItem | Component<ResultItemProps> | - | Custom search result item component |
-| debounceTime | number | 300 | Search debounce time (milliseconds) |
-| autoFocus | boolean | false | Whether to auto-focus search box |
-| className | string | - | Custom style class name |
-| style | CSSProperties | - | Custom styles |
-| onKeywordChange | (keyword: string) => void | - | Search keyword change callback |
-| onSearchComplete | (results: Map<SearchType, SearchResult>) => void | - | Search complete callback |
-| onResultItemClick | (data: SearchResultItem, type: SearchType) => void | - | Search result click callback |
-| onError | (error: Error) => void | - | Search error callback |
+
+|Prop Name|Type|Default Value|Description|
+|---------|---------|---------|---------|
+|variant|VariantType|VariantType.MINI|Search mode: mini, standard, embedded|
+|SearchBar|Component<SearchBarProps>|DefaultSearchBar|Custom search bar component|
+|SearchResults|Component<SearchResultsProps>|DefaultSearchResults|Custom search results component|
+|SearchAdvanced|Component<SearchAdvancedProps>|DefaultSearchAdvanced|Custom advanced search component|
+|SearchResultsPresearch|Component|-|Pre-search placeholder component|
+|SearchResultsLoading|Component|-|Loading placeholder component|
+|SearchResultsEmpty|Component|-|Empty result placeholder component|
+|SearchResultItem|Component<ResultItemProps>|-|Custom search result item component|
+|debounceTime|number|300|Search debounce time (ms)|
+|autoFocus|boolean|false|Whether to auto-focus the search box|
+|className|string|-|Custom CSS class name|
+|style|CSSProperties|-|Custom inline style|
+|onKeywordChange|(keyword: string) => void|-|Callback when the search keyword changes|
+|onSearchComplete|(results: Map<SearchType, SearchResult>) => void|-|Callback when search completes|
+|onResultItemClick|(data: SearchResultItem, type: SearchType) => void|-|Callback when a search result is clicked|
+|onError|(error: Error) => void|-|Search error callback|
 
 ## Basic Usage
 ``` typescript
@@ -51,7 +52,7 @@ import { Search, VariantType } from '@tencentcloud/chat-uikit-vue3';
 import type { SearchResultItemType, SearchType } from '@tencentcloud/chat-uikit-vue3';
 
 const handleResultClick = (data: SearchResultItemType, type: SearchType) => {
-  console.log('Search result clicked:', data, type);
+  console.log('Search result click:', data, type);
 };
 
 const handleKeywordChange = (keyword: string) => {
@@ -66,26 +67,27 @@ const handleError = (error: Error) => {
 
 ## Customization
 
-The `Search` component provides multiple replaceable child components, allowing users to customize `SearchBar`, `SearchResults`, `SearchAdvanced`, `SearchResultItem`, `SearchResultsPresearch`, `SearchResultsLoading`, `SearchResultsEmpty`, etc. Users can also utilize default child components for further customization.
+The `Search` component provides multiple replaceable subcomponents, allowing you to customize `SearchBar`, `SearchResults`, `SearchAdvanced`, `SearchResultItem`, `SearchResultsPresearch`, `SearchResultsLoading`, and `SearchResultsEmpty`. You can also extend the default subcomponents for further customization.
 
 【Custom SearchBar】
 
 **Props**
-| Property | Type | Default Value | Description |
-| --- | --- | --- | --- |
-| value | string | - | Search box value |
-| onChange | (e: Event) => void | - | Input change callback |
-| onKeyDown | (e: KeyboardEvent) => void | - | Keyboard event callback |
-| onClear | () => void | - | Clear callback |
-| placeholder | string | - | Placeholder text |
-| SearchIcon | Component | - | Custom search icon |
-| ClearIcon | Component | - | Custom clear icon |
-| className | string | - | Custom style class name |
-| style | CSSProperties | - | Custom styles |
-| onFocus | (e: FocusEvent) => void | - | Focus callback |
-| onBlur | (e: FocusEvent) => void | - | Blur callback |
-| autoFocus | boolean | false | Whether to auto-focus |
-| variant | VariantType | - | Search mode |
+
+|Prop Name|Type|Default Value|Description|
+|---------|---------|---------|---------|
+|value|string|-|Search box value|
+|onChange|(e: Event) => void|-|Input change callback|
+|onKeyDown|(e: KeyboardEvent) => void|-|Keyboard event callback|
+|onClear|() => void|-|Clear callback|
+|placeholder|string|-|Placeholder text|
+|SearchIcon|Component|-|Custom search icon|
+|ClearIcon|Component|-|Custom clear icon|
+|className|string|-|Custom CSS class name|
+|style|CSSProperties|-|Custom inline style|
+|onFocus|(e: FocusEvent) => void|-|Focus callback|
+|onBlur|(e: FocusEvent) => void|-|Blur callback|
+|autoFocus|boolean|false|Whether to auto-focus|
+|variant|VariantType|-|Search mode|
 
 **Example**
 ``` typescript
@@ -99,7 +101,7 @@ The `Search` component provides multiple replaceable child components, allowing
       <input
         type="text"
         :value="value"
-        :placeholder="placeholder || 'Enter keywords to start searching...'"
+        :placeholder="placeholder || 'Enter a keyword to start searching...'"
         @input="handleChange"
         class="enhanced-search-input"
       />
@@ -217,21 +219,22 @@ import CustomSearchBar from './CustomSearchBar.vue';
 【Custom SearchResults】
 
 **Props**
-| Property | Type | Default Value | Description |
-| --- | --- | --- | --- |
-| results | Map<SearchType, SearchResult> | - | Search result data |
-| isLoading | boolean | - | Whether loading |
-| error | Error \\| null | - | Error information |
-| keyword | string | - | Search keyword |
-| typeLabels | Record<SearchType, string> | - | Search type labels |
-| onLoadMore | (type: SearchType) => void | - | Load more callback |
-| onResultItemClick | (data: SearchResultItemType, type: SearchType) => void | - | Result item click callback |
-| SearchResultsLoading | Component | Loading | Custom loading component |
-| SearchResultsPresearch | Component | - | Pre-search placeholder component |
-| SearchResultsEmpty | Component | EmptyResult | Empty results placeholder component |
-| SearchResultItem | Component<ResultItemProps> | DefaultSearchResultsItem | Custom result item component |
-| variant | VariantType | VariantType.STANDARD | Display mode |
-| searchType | SearchType \\| 'all' | 'all' | Current search type |
+
+|Prop Name|Type|Default Value|Description|
+|---------|---------|---------|---------|
+|results|Map<SearchType, SearchResult>|-|Search result data|
+|isLoading|boolean|-|Whether loading is in progress|
+|error|Error \| null|-|Error information|
+|keyword|string|-|Search keyword|
+|typeLabels|Record<SearchType, string>|-|Search type labels|
+|onLoadMore|(type: SearchType) => void|-|Load more callback|
+|onResultItemClick|(data: SearchResultItemType, type: SearchType) => void|-|Result item click callback|
+|SearchResultsLoading|Component|Loading|Custom loading component|
+|SearchResultsPresearch|Component|-|Pre-search placeholder component|
+|SearchResultsEmpty|Component|EmptyResult|Empty result placeholder component|
+|SearchResultItem|Component<ResultItemProps>|DefaultSearchResultsItem|Custom result item component|
+|variant|VariantType|VariantType.STANDARD|Display mode|
+|searchType|SearchType \| 'all'|'all'|Current search type|
 
 **Example**
 ``` typescript
@@ -405,12 +408,13 @@ import CustomSearchResults from './CustomSearchResults.vue';
 【Custom SearchAdvanced】
 
 **Props**
-| Property | Type | Default Value | Description |
-| --- | --- | --- | --- |
-| variant | VariantType | - | Display mode |
-| searchType | SearchTabType | - | Current search type |
-| advancedParams | Map<SearchType, SearchParamsMap[SearchType]> | - | Advanced search parameters |
-| onAdvancedParamsChange | (type: SearchType, params: SearchParamsMap[SearchType]) => void | - | Parameter change callback |
+
+|Prop Name|Type|Default Value|Description|
+|---------|---------|---------|---------|
+|variant|VariantType|-|Display mode|
+|searchType|SearchTabType|-|Current search type|
+|advancedParams|Map<SearchType, SearchParamsMap[SearchType]>|-|Advanced search parameters|
+|onAdvancedParamsChange|(type: SearchType, params: SearchParamsMap[SearchType]) => void|-|Parameter change callback|
 
 **Example**
 ``` typescript
@@ -558,13 +562,14 @@ import CustomSearchAdvanced from './CustomSearchAdvanced.vue';
 【Custom SearchResultItem】
 
 **Props**
-| Property | Type | Default Value | Description |
-| --- | --- | --- | --- |
-| data | SearchResultItem | - | Search result data |
-| type | SearchType | - | Search result type |
-| keyword | string | - | Search keyword |
-| onClick | (data: SearchResultItem, type: SearchType) => void | - | Click callback |
-| className | string | - | Custom style class name |
+
+|Prop Name|Type|Default Value|Description|
+|---------|---------|---------|---------|
+|data|SearchResultItem|-|Search result data|
+|type|SearchType|-|Search result type|
+|keyword|string|-|Search keyword|
+|onClick|(data: SearchResultItem, type: SearchType) => void|-|Click callback|
+|className|string|-|Custom CSS class name|
 
 **Example**
 ``` java
@@ -717,11 +722,12 @@ import CustomSearchItem from './CustomSearchItem.vue';
 【Custom Placeholders】
 
 **Props**
-| Property | Type | Default Value | Description |
-| --- | --- | --- | --- |
-| SearchResultsPresearch | Component | - | Pre-search placeholder component |
-| SearchResultsLoading | Component | - | Loading placeholder component |
-| SearchResultsEmpty | Component | - | Empty results placeholder component |
+
+|Prop Name|Type|Default Value|Description|
+|---------|---------|---------|---------|
+|SearchResultsPresearch|Component|-|Pre-search placeholder component|
+|SearchResultsLoading|Component|-|Loading placeholder component|
+|SearchResultsEmpty|Component|-|Empty result placeholder component|
 
 **Example**
 ``` typescript
@@ -742,7 +748,7 @@ const PresearchComponent = defineComponent({
   setup() {
     return () => h('div', { class: 'presearch-placeholder' }, [
       h('div', { class: 'placeholder-icon' }, '🔍'),
-      h('div', { class: 'placeholder-text' }, 'Enter keywords to start searching')
+      h('div', { class: 'placeholder-text' }, 'Enter a keyword to start searching')
     ]);
   }
 });