@tencent-rtc/mcp 1.4.7 → 1.6.0

package/resource/knowledge/chat/preset/flutter/features/contact-list.md

@@ -0,0 +1,40 @@
+## Component Overview
+
+ContactList is a full-featured contact management component designed for chat applications. It enables users to view friend lists, process friend requests, manage group lists, and maintain blacklists. The component also provides a robust set of interactive webhook interfaces for custom event handling.
+| <strong>Contact List</strong> | <strong>Group List</strong> | <strong>Friend Request List</strong> |
+| --- | --- | --- |
+|  |  |  |
+
+## Component Integration
+
+The `ContactList` component is included in TUIKit Flutter. To use `ContactList`, integrate TUIKit Flutter into your application. For detailed integration steps, refer to the [TUIKit Flutter documentation](https://www.tencentcloud.com/document/product/1047/77489).
+
+## Component Structure
+
+`ContactList` serves as the main entry point for the contact list page. The following table describes the available webhook parameters for customizing click events:
+| Method | Parameter | Description |
+| --- | --- | --- |
+| <code>ContactList</code> | <code>onGroupClick: (ContactInfo contactInfo) {}</code> | Webhook triggered when a group is clicked. Optional. |
+| <code>onContactClick: (ContactInfo contactInfo) {}</code> | Webhook triggered when a contact is clicked. Optional. |  |
+
+The upper section of the `ContactList` displays navigation cells for subviews such as friend requests, group chat requests, group chat list, and blacklist. The lower section contains the contact list itself, as shown below:
+
+## Basic Usage
+- When you tap the entry cells for friend requests, group chat requests, group chat list, or blacklist in `ContactList`, navigation to the appropriate subview is handled automatically—no additional configuration is required.
+
+- When you tap a group in the group list or a contact in the contact list or blacklist, the corresponding webhook (`onGroupClick` or `onContactClick`) is triggered. Listen to these webhooks to implement custom navigation or behaviors.
+
+   For example, route navigation can be handled as shown below:
+
+   To display the contact list directly, initialize `ContactList` as shown below:
+
+   ``` swift
+   ContactList(
+     onGroupClick: (ContactInfo contactInfo) {
+       // Handle group click event
+     },
+     onContactClick: (ContactInfo contactInfo) {
+       // Handle contact click event
+     },
+   ),
+   ```

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

@@ -0,0 +1,129 @@
+## Component Overview
+
+ConversationList is a UI component that displays and manages user chat conversations. It provides a robust feature set for conversation listing—enabling users to view conversations and perform key actions directly from the list.
+| <strong>Conversation List</strong> | <strong>Conversation Actions</strong> |
+| --- | --- |
+|  |  |
+
+## Component Integration
+
+ConversationList is part of the TUIKit Flutter package. To add ConversationList to your project, integrate TUIKit Flutter following the [TUIKit Flutter documentation](https://www.tencentcloud.com/document/product/1047/77489).
+
+## Component Structure
+
+ConversationList exposes only its initialization method. All other internal logic is handled within the component itself.
+
+### Public Methods
+| Method Name | Parameters | Description |
+| --- | --- | --- |
+| <code>ConversationList</code> | <code>onConversationClick: (ConversationInfo conversation) {}</code> | Sets the callback for conversation cell clicks. |
+| <code>config: ConversationActionConfigProtocol</code> | Initializes the component and configures action menu items (optional). |  |
+| <code>customActions: List</code> | Initializes the component and defines custom action options (optional). |  |
+
+## Basic Usage
+
+Initialize ConversationList directly, providing an `onConversationClick` callback.
+
+|Parameter Name|Type|Description|
+|---------|---------|---------|
+|`onConversationClick`|`(ConversationInfo conversation) {}`|Callback that is invoked when a conversation cell is selected.|
+
+Sample code:
+``` java
+Expanded(
+  child: ConversationList(
+    onConversationClick: (conversation) {
+      // We recommend navigating to the chat page here
+    },
+  ),
+),
+```
+
+## Customization
+
+You can customize the actions available in the conversation list using the following methods.
+
+### Method 1: Hide Conversation Action Items Locally
+
+Provide a custom config when initializing ConversationList to control which menu items are visible:
+``` java
+Expanded(
+  child: ConversationList(
+    config: ChatConversationActionConfig(
+      isSupportDelete: true,
+      isSupportPin: true,
+      isSupportClearHistory: false
+    ),
+    onConversationClick: (conversation) {
+      // Navigate to chat page on conversation cell click
+    },
+  ),
+),
+```
+
+**Supported Action Toggles**
+
+|Action Type|Description|
+|---------|---------|
+|`isSupportDelete`|Enable or disable conversation deletion.|
+|`isSupportPin`|Enable or disable Pin Conversation.|
+|`isSupportClearHistory`|Enable or disable clearing chat history.|
+
+### Method 2: Add Custom Conversation Action Items Locally
+
+Pass `customActions` during initialization to append custom actions below the default options.
+
+|Parameter Name|Type|Description|
+|---------|---------|---------|
+|`customActions`|`List`|Custom actions shown in the conversation action menu.|
+
+Sample code:
+``` swift
+Expanded(
+  child: ConversationList(
+    customActions: [
+      ConversationCustomAction(
+        title: 'Share',
+        action: (conversation) {
+          print('Share conversation: ${conversation.title}');
+        })
+    ],
+  ),
+),
+```
+
+### Method 3: Configure Actions Globally
+
+Set global configuration via `AppBuilder`:
+``` swift
+// Configure at app startup; if omitted, the feature is not supported
+await AppBuilder.init();
+AppBuilder.getInstance().conversationListConfig = ConversationListConfig(
+    conversationActionList: [
+      AppBuilder.CONVERSATION_ACTION_DELETE,
+      AppBuilder.CONVERSATION_ACTION_PIN,
+      AppBuilder.CONVERSATION_ACTION_CLEAR_HISTORY
+    ],
+    // ... other required properties
+);
+
+// Then, initialize ConversationList. All ConversationList instances will inherit the above action configuration.
+Expanded(
+  child: ConversationList(
+    onConversationClick: (conversation) {
+      // You can navigate to the chat page here
+    },
+  ),
+),
+```
+
+> **Note：**
+>
+
+> Local configuration takes precedence over global configuration.
+>
+
+Below are examples of customization effects:
+| Conversation Actions (Default Options) | Conversation Actions (Delete Option Hidden) | Conversation Actions (Share Option Added) |
+| --- | --- | --- |
+|  |  |  |

package/resource/knowledge/chat/preset/flutter/features/language.md

@@ -0,0 +1,104 @@
+TUIKit Flutter includes built-in language packs for **Simplified Chinese, Traditional Chinese, English, Japanese, Korean, and Arabic**. These packs allow you to set the user interface language easily. With a simple configuration, you can enable dynamic language switching in your app.
+
+|Simplified Chinese|Traditional Chinese|English|Japanese|Korean|Arabic|
+|---------|---------|---------|---------|---------|---------|
+|||||||
+
+## Using Built-in Languages
+
+### Language Setup
+
+After integrating the component as described in [TUIKit Flutter](https://www.tencentcloud.com/document/product/1047/77489), you can enable internationalization using `LocaleProvider` and `AtomicLocalizations`. Wrap your app's main entry point with `MultiProvider`, and configure the language settings in `MaterialApp` as shown below. For a complete example, see the [demo](https://github.com/Tencent-RTC/TUIKit_Flutter/blob/main/chat/demo/lib/main.dart):
+``` javascript
+  @override
+  Widget build(BuildContext context) {
+    return ComponentTheme(
+      child: MultiProvider(
+        providers: [
+          // Language provider for dynamic language switching; notifies components when the language changes
+          ChangeNotifierProvider.value(value: LocaleProvider()),
+        ],
+        child: Builder(builder: (context) {
+          final themeState = BaseThemeProvider.of(context);
+          final isDarkMode = themeState.isDarkMode;
+          // Access the language provider
+          final localeProvider = Provider.of<LocaleProvider>(context);
+          return MaterialApp(
+            // ...... other configurations omitted
+            localizationsDelegates: const [
+              AtomicLocalizations.delegate,
+            // ...... you can add other localization delegates for additional components
+            ],
+            supportedLocales: AtomicLocalizations.supportedLocales, // Supported app languages
+            locale: localeProvider.locale, // Current language setting
+          );
+        }),
+      ),
+    );
+```
+
+### System Language Adaptation
+
+Once language configuration is complete, the plugin automatically matches the system language by default.
+
+### Real-time Language Switching
+
+`LocaleProvider` offers a `changeLanguage` method for switching languages at runtime. The selected language is cached locally, so your app will remember the user's choice after restart by reading the value from the `locale` field.
+
+For implementation details, refer to the [settings page demo](https://github.com/Tencent-RTC/TUIKit_Flutter/blob/main/chat/demo/lib/pages/settings_page.dart). To switch languages, obtain the `LocaleProvider` instance and call `changeLanguage`:
+``` javascript
+final localeProvider = Provider.of<LocaleProvider>(context, listen: false);
+// Switch to English
+localeProvider.changeLanguage('en');
+```
+
+After switching languages, the `State` subclass of a `StatefulWidget` will trigger the `didChangeDependencies` lifecycle method. In this method, initialize the `AtomicLocalizations` object and use the built-in localized entries.
+
+Example:
+``` javascript
+class ContactList extends StatefulWidget {
+  const ContactList({
+    super.key,
+  });
+
+  @override
+  State<ContactList> createState() => _ContactListState();
+}
+
+class _ContactListState extends State<ContactList> {
+  late AtomicLocalizations atomicLocale;
+  // Other code omitted
+
+  @override
+  void didChangeDependencies() {
+    super.didChangeDependencies();
+    // Initialize localization dynamically
+    atomicLocale = AtomicLocalizations.of(context);
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    // Display the addFriend label in the current language
+    return Text(atomicLocale.addFriend);
+  }
+}
+```
+
+## Custom Internationalization
+
+To add custom internationalization, integrate the tuikit_atomic_x component from source as described in [TUIKit Flutter](https://www.tencentcloud.com/document/product/1047/77489).
+
+### Adding Language Resource Files
+
+Localization entries are stored in `.arb` files in the [l10n](https://github.com/Tencent-RTC/TUIKit_Flutter/tree/main/atomic-x/lib/base_component/l10n) directory. To add a new language, create a new `.arb` file with the appropriate language code and translate all entries.
+- Create the file: Copy an existing language file and rename it to `l10n_xx.arb` (for example, Spanish: `l10n_es.arb`).
+
+- Translate the content: Update all entries in the new file with translations for your target language.
+
+   Next, run the `flutter gen-l10n` command in the component's root directory. This will update the localizations directory with your new language file.
+
+    Add logic in `locale_provider.dart` to cache Spanish locally, then call `changeLanguage('es')` to switch to Spanish.
+
+### Customizing Translations
+
+All language keys in the resource files under the l10n directory are consistent. You can modify or add translations as needed, then run the `flutter gen-l10n` command in the component's root directory to update the localization files.

package/resource/knowledge/chat/preset/flutter/features/message-input.md

@@ -0,0 +1,54 @@
+## Component Overview
+
+MessageInput is a message input component that enables users to create and send messages with a full range of editing options. It supports various message types, including text, images, videos, files, and voice messages. The component also includes features such as emoji selection and offers flexible styling and customization options.
+| <strong>Message Input Interface</strong> | <strong>Emoji Picker</strong> |
+| --- | --- |
+|  |  |
+
+## Component Integration
+
+MessageInput is part of TUIKit Flutter. To use MessageInput, integrate TUIKit Flutter into your project. For setup instructions, see [TUIKit Flutter documentation](https://www.tencentcloud.com/document/product/1047/77489).
+
+## Component Descriptions
+
+MessageInput is composed of a core input module and a style configuration protocol, allowing you to customize the input experience.
+
+### Initialization Parameters
+
+|Parameter Name|Type|Description|
+|---------|---------|---------|
+|`conversationID`|`String`|Conversation ID that identifies the current chat session.|
+|`config`|`MessageInputConfigProtocol`|Style configuration that controls which function buttons appear.|
+
+## Basic Usage
+
+Initialize the MessageInput component with a conversation ID:
+``` swift
+Column(
+  children: [
+    MessageInput(
+      conversationID: 'conversation_123',
+    ),
+  ],
+);
+```
+
+## Customization
+
+You can configure which feature buttons appear in the input bar:
+``` swift
+// Customize which feature buttons to show
+MessageInput(
+  conversationID: widget.conversation.conversationID,
+  config: ChatMessageInputConfig(
+    isShowAudioRecorder: false,  // Hide audio recording
+    isShowPhotoTaker: true,      // Show photo capture
+    isShowMore: true,            // Show more features
+  ),
+),
+```
+
+Examples of different configurations:
+| <strong>Default Input Box</strong> | <strong>Input Box with Audio Recording Hidden</strong> | <strong>Input Box with All Features Hidden</strong> |
+| --- | --- | --- |
+|  |  |  |

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

@@ -0,0 +1,158 @@
+## Component Overview
+
+MessageList is a Flutter component designed for displaying and managing chat messages. It supports a wide range of message types, including:
+- Text, image, video, voice, file, system notification, emoji messages, and more.
+
+- Message actions via long-press menus, such as copy, delete, recall, and custom actions.
+
+- Extensive customization: configure bubble color, corner radius, font, and add custom actions.
+
+| <strong>Chat Message List</strong> | <strong>Message Long-Press Menu</strong> |
+| --- | --- |
+|  |  |
+
+   MessageList is available as part of TUIKit Flutter. To integrate MessageList, add TUIKit Flutter to your project. For detailed setup instructions, refer to the [TUIKit Flutter documentation](https://www.tencentcloud.com/document/product/1047/77489).
+
+## Component Structure
+
+MessageList exposes only its initialization method; all other internal logic is fully encapsulated.
+
+### Public Methods
+| Method | Parameters | Description |
+| --- | --- | --- |
+| <code>MessageList</code> | <code>conversationID: String</code> | Initializes MessageList and sets the conversation ID.<br>- For C2C Chat, use the format <code>c2c_userID</code>.<br>- For group chat, use <code>group_groupID</code>. |
+| <code>config: MessageListConfigProtocol</code> | Initializes MessageList and applies the specified message list style. |  |
+| <code>customActions: List</code> | Initializes MessageList with custom long-press menu options. |  |
+| <code>locateMessage: MessageInfo?</code> | Initializes MessageList and scrolls to a specific message. Useful when navigating from search results to a specific message. |  |
+| <code>onUserClick: (String userID) {}</code> | Initializes MessageList and sets a handler for avatar click events. |  |
+
+## Basic Usage
+
+To initialize MessageList, provide a conversation ID. We recommend implementing `onUserClick` for avatar interactions.
+``` swift
+MessageList(
+  conversationID: 'conversation_123',
+  onUserClick: (String userID) {
+    // Handle avatar click event
+  },
+),
+```
+
+## Customization
+
+MessageList supports flexible style and action customization.
+
+### Custom Styles
+
+Implement `MessageListConfigProtocol` to define custom styles:
+``` swift
+class MyCustomConfig extends MessageListConfigProtocol {
+  @override
+  String get alignment => AppBuilder.MESSAGE_ALIGNMENT_TWO_SIDED;
+
+  @override
+  bool get isShowTimeMessage => true;
+
+  @override
+  bool get isShowLeftAvatar => true;
+
+  @override
+  bool get isShowLeftNickname => true;
+
+  @override
+  bool get isShowRightAvatar => true;
+
+  @override
+  bool get isShowRightNickname => true;
+
+  // ... other required properties
+}
+
+// Apply custom style
+MessageList(
+  conversationID: 'conversation_123',
+  config: MyCustomConfig(),
+);
+```
+
+**MessageListConfigProtocol Property Reference**
+| Property | Type | Description | Remarks |
+| --- | --- | --- | --- |
+| <code>alignment</code> | <code>String</code> | Message alignment | - <code>MessageAlignment.LEFT</code>：Left aligned.<br>- <code>MessageAlignment.RIGHT</code>：Right aligned.<br>- <code>MessageAlignment.TWO_SIDED</code>：Both sides aligned. |
+| <code>isShowTimeMessage</code> | <code>bool</code> | Show timestamp messages | Controls whether message timestamps are displayed. |
+| <code>isShowLeftAvatar</code> | <code>bool</code> | Show left avatar | Show sender's avatar for received messages. |
+| <code>isShowLeftNickname</code> | <code>bool</code> | Show left nickname | Show sender's nickname for received messages. |
+| <code>isShowRightAvatar</code> | <code>bool</code> | Show right avatar | Show your avatar for sent messages. |
+| <code>isShowRightNickname</code> | <code>bool</code> | Show right nickname | Show your nickname for sent messages. |
+| <code>isShowTimeInBubble</code> | <code>bool</code> | Show time inside bubble | Display timestamp inside the message bubble. |
+| <code>cellSpacing</code> | <code>double</code> | Message spacing | Set the space between adjacent messages. |
+| <code>isShowSystemMessage</code> | <code>bool</code> | Show system notification | Display system notification messages. |
+| <code>isShowUnsupportMessage</code> | <code>bool</code> | Show unsupported messages | Display messages of unsupported types. |
+| <code>horizontalPadding</code> | <code>double</code> | Horizontal padding | Set left and right padding for the message list. |
+| <code>avatarSpacing</code> | <code>double</code> | Avatar spacing | Set spacing between avatar and message content. |
+| <code>isSupportCopy</code> | <code>bool</code> | Enable copy action in menu | - true: Enable copy action<br>- false: Disable copy action |
+| <code>isSupportDelete</code> | <code>bool</code> | Enable delete action in menu | - true: Enable delete action<br>- false: Disable delete action |
+| <code>isSupportRecall</code> | <code>bool</code> | Enable recall action in menu | - true：Enable recall action<br>- false: Disable recall action |
+
+### Custom Actions
+
+You can customize the long-press menu actions using several approaches.
+
+#### Option A: Locally Hide or Show Action Items
+
+Set `isSupportCopy`, `isSupportDelete`, and `isSupportRecall` in the config to show or hide specific actions:
+``` swift
+MessageList(
+  conversationID: 'conversation_123',
+  config: ChatMessageListConfig(isSupportCopy: false),
+);
+```
+
+#### Option B: Locally Add Custom Action Items
+
+Pass custom actions to MessageList. These will be added below the default menu options:
+``` swift
+MessageList(
+  conversationID: 'conversation_123',
+  customActions: [
+    MessageCustomAction(
+      title: 'Share',
+      systemIconFallback: Icons.share,
+      action: (MessageInfo messageInfo) {
+        print('share message');
+      },
+    )
+  ],
+);
+```
+
+#### Option C: Configure Action Item Globally
+
+Configure menu actions globally using `AppBuilderConfig`:
+``` swift
+// Set global configuration at app startup
+await AppBuilder.init();
+AppBuilder.getInstance().messageListConfig = MessageListConfig(
+  messageActionList: [
+    AppBuilder.MESSAGE_ACTION_COPY,
+    AppBuilder.MESSAGE_ACTION_DELETE,
+    AppBuilder.MESSAGE_ACTION_RECALL,
+  ],
+  // other options
+);
+
+// All MessageList instances will inherit the global configuration
+MessageList(
+  conversationID: 'conversation_123',
+);
+```
+
+> **Note：**
+>
+
+>  Local configurations override global configuration settings.
+>
+
+| <strong>Message List Actions </strong><br><strong>(Default Options)</strong> | <strong>Message List Actions</strong><br><strong> (Copy Option Hidden)</strong> | <strong>Message List Actions </strong><br><strong>(Share Option Added)</strong> |
+| --- | --- | --- |
+|  |  |  |

package/resource/knowledge/chat/preset/flutter/features/search.md

@@ -0,0 +1,59 @@
+## Component Overview
+
+The Search component provides a full-featured search experience, including a search bar, results display, and seamless page navigation. It supports searching for users, groups, and messages, and offers extensive interactive Webhook integration for custom workflows.
+
+> **Note****：**
+>
+
+> Search is available in the Pro edition and Enterprise edition. To use Search function, you need to purchase either the Pro or Enterprise package. For details, see [Billing Information](https://trtc.io/document/67650).
+>
+
+| <strong>Search Entry</strong> | <strong>Search Results</strong> |
+| --- | --- |
+|  |  |
+
+## Component Integration
+
+Search is included in TUIKit Flutter. To use the Search component, integrate TUIKit Flutter into your project and complete the login flow. For detailed integration steps, refer to the [TUIKit Flutter](https://www.tencentcloud.com/document/product/1047/77489) documentation.
+
+## Component Descriptions
+
+`SearchBar` serves as the primary Widget for search and is typically placed at the top of your Scaffold body. Only the initialization method for the Search component is exposed; all internal logic is handled within `SearchBar`.
+
+|Method|Parameter|Description|
+|---------|---------|---------|
+|SearchBar|`onContactSelect: (`[FriendSearchInfo](https://pub.dev/documentation/atomic_x_core/latest/api_search_search_store/FriendSearchInfo-class.html)` selectedContact) {}`|Webhook triggered when a contact result is clicked; optional parameter.|
+|SearchBar|`onGroupSelect: (`[GroupSearchInfo](https://pub.dev/documentation/atomic_x_core/latest/api_search_search_store/GroupSearchInfo-class.html)` selectedGroup) {}`|Webhook triggered when a group result is clicked; optional parameter.|
+|SearchBar|`onConversationSelect: (`[MessageSearchResultItem](https://pub.dev/documentation/atomic_x_core/latest/api_search_search_store/MessageSearchResultItem-class.html)` selectedConversation) {}`|Webhook triggered when a conversation result is clicked; optional parameter.|
+|SearchBar|`onMessageSelect: (`[MessageInfo](https://pub.dev/documentation/atomic_x_core/latest/api_message_message_list_store/MessageInfo-class.html)` selectedMessage) {}`|Webhook triggered when a message result is clicked; optional parameter.|
+
+## Basic Usage
+
+`SearchBar` manages navigation for search results in two ways:
+- **Automatic Routing**: When users click the **More** button or a chat history item in the search results page, the component uses Flutter's Navigator to automatically handle page transitions.
+
+- **Custom Routing**: When a user selects a contact, group, conversation, or message, the corresponding Webhook (`onContactSelect`, `onGroupSelect`, `onConversationSelect`, or `onMessageSelect`) is triggered. Implement your custom navigation logic within these Webhooks (for example, routing to your own chat interface).
+
+   Example:
+
+   To initialize and use `SearchBar`, simply add it to your widget tree:
+
+   ``` java
+   SearchBar(
+     onContactSelect: (FriendSearchInfo selectedContact) {
+       // Handle contact selection
+     },
+
+     onGroupSelect: (GroupSearchInfo selectedGroup) {
+       // Handle group selection
+     },
+
+     onConversationSelect: (MessageSearchResultItem selectedConversation) {
+       // Handle conversation selection
+     },
+
+     onMessageSelect: (MessageInfo selectedMessage) {
+       // Handle message selection
+     },
+   ),
+   ```