ConversationList
ConversationList
is mainly responsible for the conversation list feature. It includes the Header and List sections, offering features like conversation search, conversation creation, conversation pinning, and conversation deletion.This document will detail the basic usage of the component, customization, free combination, and the component's props parameter list.
Conversation List | Conversation Actions | Conversation Search | Create Conversation |
| | | |
Basic Usage
The ConversationList component has no required properties. You can use the ConversationList with the following code.
import { UIKitProvider, ConversationList } from '@tencentcloud/chat-uikit-react';const App = () => {return (<UIKitProvider><ConversationList /></UIKitProvider>);};
Props
Parameter Name | Type | Default Value | Indication |
enableSearch | Boolean | true | Control whether the conversation search feature is displayed. |
enableCreate | Boolean | true | Control whether the create conversation feature is displayed. |
enableActions | Boolean | true | Control whether the conversation operation feature is displayed. |
actionsConfig | - | Used for custom conversation operation configuration. | |
Header | ReactElement | Header | Custom Header Component. |
List | ReactElement | List | Custom Conversation List Component. |
Preview | ReactElement | Custom Conversation Preview Component. | |
ConversationCreate | ReactElement | ConversationCreate | Custom Conversation Creation Component. |
ConversationSearch | ReactElement | Custom Conversation Search Component. | |
ConversationActions | ReactElement | Custom Conversation Operation Component. | |
Avatar | ReactElement | Avatar | Custom Avatar Component. |
PlaceholderEmptyList | ReactNode | <PlaceHolder type={PlaceHolderTypes.NO_CONVERSATIONS} /> | Custom Placeholder Element for an Empty Conversation List. |
PlaceholderLoading | ReactNode | <PlaceHolder type={PlaceHolderTypes.LOADING} /> | Custom Placeholder Element for Loading Conversation List. |
PlaceholderLoadError | ReactNode | <PlaceHolder type={PlaceHolderTypes.WRONG} /> | Custom Placeholder Element for Conversation List Load Error. |
filter | - | Function for Filtering Conversation List. | |
sort | - | Function for Sorting Conversation List. | |
onConversationSelect | - | Callback function after clicking on a conversation, with the parameter being the clicked conversation object. | |
onBeforeCreateConversation | (params: CreateParams) => CreateParams; | - | Custom operation executed before conversation creation. Parameters are the required parameters for creating a conversation. |
onConversationCreate | - | Callback function after conversation creation, with the parameter being the created conversation object. | |
className | String | - | Specify the custom CSS name for the root element class. |
style | React.CSSProperties | - | Specify the custom style for the root element. |
Custom Component
ConversationList
provides users with rich and multi-dimensional props interfaces for custom features, UI, modules, etc.ConversationList
component offers multiple replaceable subcomponents, allowing users to customize Header
, List
, ConversationPreview
, ConversationCreate
, ConversationSearch
, ConversationActions
, Avatar
, Placeholder
, etc. Additionally, users can perform secondary development customization using the default subcomponents.Basic Feature Toggle
By setting the
enableSearch
, enableCreate
, and enableActions
parameters, you can flexibly control the display of search conversations, create conversations, and conversation actions features in the ConversationList
.<ConversationList enableSearch={false} />
<ConversationList enableCreate={false} />
<ConversationList enableActions={false} />
enableSearch={false} | enableCreate={false} | enableActions={false} |
| | |
Data filtering and sorting
The ConversationList component provides the
filterConversation
and sortConversation
properties, allowing you to filter and sort conversation list data.Filtering Conversations
To filter conversation list data, you can pass a filter function to the
filterConversation
property. This function receives an array of IConversationModel as a parameter and should return a new array containing only the conversations that meet your filter criteria.Here is an example using the
filterConversation
property to show only conversations with "unread messages":<ConversationListfilter={(conversationList: IConversationModel[]) =>conversationList.filter(conversation => conversation.unreadCount > 0)}/>
Sorting Conversations
To sort conversation list data, you can pass a sorting function to the
sortConversation
property. This function takes an IConversationModel array as a parameter and should return a new array, sorting the conversations according to your criteria.Here is an example of using the
sortConversation
property to sort the conversation list by "Latest News Time Descending":<ConversationListsort={(conversationList: IConversationModel[]) =>conversationList.sort((a, b) => (+(b?.lastMessage?.lastTime || 0)) - (+(a?.lastMessage?.lastTime || 0)),)}/>
By using the
filter
and sort
properties, you can effectively filter and sort conversation list data according to your needs.Using actionsConfig
<ConversationListactionsConfig={{enablePin: false,onConversationDelete: (conversation: IConversationModel) => { console.log('Delete conversation success'); },customConversationActions: {'custom-actions-1': {label: 'custom-actions',onClick: (conversation: IConversationModel) => { console.log(conversation); },},},}}/>
enablePin: false | enableDelete: false | enableMute: false | customConversationActions |
| | | |
Custom Placeholder
You can customize the list display for different states by passing
PlaceholderEmptyList
, PlaceholderLoading
, and PlaceholderLoadError
.Here is an example of customizing a new
PlaceholderLoading
:<ConversationListPlaceholderEmptyList={<div>Empty List!!!</div>}/>
Custom Header
ConversationListHeader
is responsible for rendering the ConversationList Header, wrapping the default ConversationSearch
and ConversationCreate
. You can customize it by passing properties like left or right, or you can customize the entire component.Props
Name | Type | Default | Description |
children | ReactNode | - | Custom Conversation List Header Center Component. When used in <ConversationList> , it will default to include <ConversationSearch> and <ConversationCreate> . |
left | ReactElement | - | Custom Conversation List Header Left Component. |
right | ReactElement | - | Custom Conversation List Header Right Component. |
className | String | - | Specify the custom CSS name for the root element class. |
style | React.CSSProperties | - | Specify the custom style for the root element. |
Basic customization
The following is an example of adding a new feature button on the right side of the Header component.
import { ConversationList, ConversationListHeader, Icon, IconTypes, IConversationListHeaderProps } from '@tencentcloud/chat-uikit-react';const CustomConversationListHeader = (props: IConversationListHeaderProps) => {const CustomIcon = <Icon type={IconTypes.ADD} onClick={() => { console.log('click'); }}></Icon>;return (<ConversationListHeader {...props} right={CustomIcon} />);};<ConversationList Header={CustomConversationListHeader} />
Advanced customization
The following is an implementation of a simple conversation grouping feature, differentiating by all conversations, unread conversations, single chat conversations, and group chat conversations. By clicking different grouping buttons, you can execute various filter rules.
before | after |
| |
import { useState } from 'react';import TUIChatEngine, { IConversationModel } from '@tencentcloud/chat-uikit-engine';import { ConversationList, IConversationListHeaderProps, UIKitProvider } from '@tencentcloud/chat-uikit-react';const App = () => {const [currentFilter, setCurrentFilter] = useState<string>('all');const conversationGroupFilter: Record<string, (conversationList: IConversationModel[]) => IConversationModel[]> = {all: (conversationList: IConversationModel[]) => conversationList,unread: (conversationList: IConversationModel[]) => conversationList?.filter((item: IConversationModel) => item.unreadCount > 0),c2c: (conversationList: IConversationModel[]) => conversationList?.filter((item: IConversationModel) => item.type === TUIChatEngine.TYPES.CONV_C2C),group: (conversationList: IConversationModel[]) => conversationList?.filter((item: IConversationModel) => 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><ConversationListstyle={{ maxWidth: '300px', height: '600px' }}Header={CustomConversationListHeader}filter={conversationGroupFilter[currentFilter]}/></UIKitProvider>);};
.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;}}
Custom List
ConversationListContent
is responsible for rendering the main list part of ConversationList.As a wrapper layer, it renders the display data of the current conversation list, which is calculated in the Context, by default
filteredAndSortedConversationList
.Props
Name | Type | Default | Description |
children | ReactNode | - | Custom Definition Conversation List Content Area Component. When used in <ConversationList> , it defaults to traversing the filteredAndSortedConversationList as <Preview> list. |
empty | Boolean | false | Empty conversation list identifier bit. When used in <ConversationList> , it checks if filteredAndSortedConversationList.length === 0 and passes it. |
loading | Boolean | false | The identifier bit for loading the conversation list. When used in <ConversationList> , use useConversationList() to get isLoading and pass it in. |
error | Boolean | false | The identifier bit for loading errors in the conversation list. When used in <ConversationList> , use useConversationList() to get isLoadError and pass it in. |
PlaceholderEmptyList | ReactNode | <PlaceHolder type={PlaceHolderTypes.NO_CONVERSATIONS} /> | Custom Placeholder Element for an Empty Conversation List. |
PlaceholderLoading | ReactNode | <PlaceHolder type={PlaceHolderTypes.LOADING} /> | Custom Placeholder Element for Loading Conversation List. |
PlaceholderLoadError | ReactNode | <PlaceHolder type={PlaceHolderTypes.WRONG} /> | Custom Placeholder Element for Conversation List Load Error. |
className | String | - | Specify the custom CSS name for the root element class. |
style | React.CSSProperties | - | Specify the custom style for the root element. |
Basic customization
List
component UI effects for different statuses are as follows. Each status's triggering moment is handled internally within ConversationList
.Similarly, you can control the component status through custom definition by passing in
empty
, loading
, error
.import { ConversationList, ConversationListContent, IConversationListContentProps } from '@tencentcloud/chat-uikit-react';const CustomConversationListContent = (props: IConversationListContentProps) => {return <ConversationListContent {...props} loading={true} />;};<ConversationList List={CustomConversationListContent} />
default | empty={true} | loading={true} | error={true} |
| | | |
Custom ConversationPreview
<ConversationList ConversationPreview={CustomConversationPreview} />
Custom ConversationActions
<ConversationList ConversationActions={CustomConversationActions} />
Custom ConversationSearch
<ConversationList ConversationSearch={CustomConversationSearch} />
Custom ConversationCreate
<ConversationList ConversationCreate={CustomConversationCreate} />
Custom Avatar
<ConversationList Avatar={CustomAvatar} />