tencent cloud

Feedback

ConversationList

Last updated: 2024-10-09 15:11:35
    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
    (conversationList: IConversationModel[]) => IConversationModel[]
    -
    Function for Filtering Conversation List.
    sort
    (conversationList: IConversationModel[]) => IConversationModel[]
    -
    Function for Sorting Conversation List.
    onConversationSelect
    (conversation: IConversationModel) => void;
    -
    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
    (conversation: IConversationModel) => void;
    -
    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":
    <ConversationList
    filter={(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":
    <ConversationList
    sort={(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

    Utilize actionsConfig to control the basic feature of ConversationActions.
    For more customization details, please refer to the ConversationActions chapter.
    <ConversationList
    actionsConfig={{
    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:
    <ConversationList
    PlaceholderEmptyList={<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
    
    
    
    
    
    
    
    
    
    
    React
    CSS
    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>
    <ConversationList
    style={{ 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

    For details, see the ConversationPreview chapter.
    <ConversationList ConversationPreview={CustomConversationPreview} />

    Custom ConversationActions

    For details, see the ConversationActions chapter.
    <ConversationList ConversationActions={CustomConversationActions} />

    Custom ConversationSearch

    For details, see the ConversationSearch chapter.
    <ConversationList ConversationSearch={CustomConversationSearch} />

    Custom ConversationCreate

    <ConversationList ConversationCreate={CustomConversationCreate} />

    Custom Avatar

    <ConversationList Avatar={CustomAvatar} />
    
    Contact Us

    Contact our sales team or business advisors to help your business.

    Technical Support

    Open a ticket if you're looking for further assistance. Our Ticket is 7x24 avaliable.

    7x24 Phone Support