tencent cloud

PrevNext

Feedback

search by keyword

Recent Pages

Documentation
Chat
    Documentation
    Download PDF

    ConversationList

    Last updated: 2024-09-29 16:55:59
    Download PDF
      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.

      Contact Us
      Technical Support

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

      Submit a Ticket
      7x24 Phone Support
      Copyright © 2013-2024 Tencent Cloud. All Rights Reserved.
      Privacy PolicyLegalCookie Policy