Conversation List Page

The conversation list page in Global IM UIKit displays the most recent one-to-one chat, group chat, and system conversation sessions that the current user has participated in.

Conversation List Interface

To display the nickname and avatar in the conversation list, you need to set up a user information provider for Global IM UIKit. Global IM UIKit retrieves the necessary data for display through the user information provider. For more details, refer to User Information.

The conversation list, with conversation objects as its elements, displays the most recent conversation objects on the current user's device and serves as the main entry point for conversations. When a message is generated in Global IM UIKit's local message database, a conversation list is created and sorted in reverse chronological order. Global IM UIKit also supports left-swipe and right-swipe editing for conversation items, providing operations such as pinning, Do Not Disturb, and marking as read.

• Left-swipe editing: When a conversation item is swiped to the left, the Turn Notifications On/Off and Delete buttons are displayed.
• Right-swipe editing: When a conversation item is swiped to the right, the Pin/Unpin and Mark as Read/Unread buttons are displayed.

Navigation Bar

The RCChatListHeaderView component is a custom implementation of the system navigation bar UINavigationBar. By defining the title and left/right buttons, it assigns values to UINavigationBar when the ViewController is loaded. The title (RCBarTitleView) is a custom view that supports two labels: title and subtitle. The buttons (RCBarItem) support name, image, and custom view display. Click events for non-custom view buttons are thrown through Action.

Conversation List

The RCChatListView component uses UITableView to implement list display and supports setting a placeholder view through the emptyView property. In the conversation list, each conversation corresponds to a Cell. The display style of conversations is generally consistent, and RCChatCell is used to display them in the list. Custom conversation Cells can be registered.

Initialization

When developing based on Global IM UIKit, it is recommended to inherit and use the RCChatListViewController class to create a custom conversation list page. When troubleshooting or reproducing issues related to the conversation page, you can directly use the RCChatListViewController class.

Call the initialization method initWithChatType: of the RCChatListViewController class to build the conversation list page, setting the types of conversations to be included in the list. The conversation type is an Option type:

/// Conversation Type
typedef NS_OPTIONS(NSUInteger, RCChatType) {
    RCChatTypeSingle    = 1 << 0,   /// One-to-one chat
    RCChatTypeGroup     = 1 << 1,   /// Group chat
    RCChatTypeSystem    = 1 << 2,   /// System
};

Inherit RCChatListViewController to create a custom conversation list class DemoChatListViewController, and display the initialized instance through UINavigationController:

{
    // The display type of the conversation list, using one-to-one chat and group chat as examples
    RCChatType chatType = RCChatTypeSingle|RCChatTypeGroup;
    // Initialize the conversation list
    DemoChatListViewController *controller = [[DemoChatListViewController alloc] initWithChatType:chatType];
    // Must use UINavigationController for display
    [self.navigationController pushViewController:controller animated:YES];
    // If UINavigationController is not used externally, create one
    // UINavigationController *navigationController = [[UINavigationController alloc] initWithRootViewController:controller];
    // navigationController.modalPresentationStyle = UIModalPresentationOverFullScreen;
    // navigationController.modalTransitionStyle = UIModalTransitionStyleCoverVertical;
    // [self presentViewController:navigationController animated:YES completion:nil];
}

Important

The conversation list must have a navigation controller.

Conversation List View Controller Properties

Property	Description
viewModel	An RCChatListViewModel object that may manage and provide data for the view controller.
headerView	An RCChatListHeaderView object representing the navigation header of the view controller.
listView	An RCChatListView object representing the chat list in the view controller.
editBar	An RCChatListEditBar object displayed when the view controller is in edit mode.

Conversation List View Controller Methods

Method	Description
initWithChatType:	The initialization method of the view controller that accepts a RCChatType as a parameter.
reloadHeaderView	A method in the RCChatListViewController (Header) category used to update the header view. If a custom header view is set, this method must be called to refresh the interface.
reloadListView	A method in the RCChatListViewController (List) category used to update the list view. If a custom list view is set, this method must be called to refresh the interface.
editItems	A method in the RCChatListViewController (Edit) category that returns an array of RCChatListEditItem objects. This method can be overridden to implement custom edit operations.

Customizing the Navigation Bar

Global IM UIKit's RCChatListViewController uses the system navigation bar. RCChatListHeaderView inherits from RCBaseHeaderView, which has three properties:

• Left button array: NSMutableArray<RCBarItem *> *leftItems;
• Right button array: NSMutableArray<RCBarItem *> *rightItems;
• Title View: RCBarTitleView *titleView;

The conversation list page sets the system navigation bar based on these three properties of RCChatListHeaderView.

Modifying Navigation Bar Buttons

Navigation bar buttons are configured by RCBarItem, supporting three button types: text, image, and custom view. Click events are passed through RCBarItemAction. You can also mark buttons by setting RCBarItemTag. In RCChatListHeaderView, both leftItems and rightItems are mutable arrays, supporting add, delete, modify, and query operations. The leftItems array has a built-in multi-select button that can be directly accessed and modified.

- (void)viewDidLoad {
    [super viewDidLoad];
    // Add a text button
    RCBarItem *addTitleItem = [RCBarItem itemWithTitle:@"Add" image:nil action:^(RCBarItem * item) {
        // TODO add item did click
    }];
    [self.headerView.rightItems addObject:addTitleItem];
    [self reloadHeaderView];
}

Modifying the Navigation Bar Title

The navigation bar title is the titleView property in RCChatListHeaderView, supporting the display of a title and also used to show the connection status.

The default title text is Chats, which can be modified:

- (void)viewDidLoad {
    [super viewDidLoad];
    // Modify the title
    self.headerView.titleView.titleLabel.text = @"Chats";
}

Disabling Navigation Bar Status Display

The navigation bar status display is enabled by default and can be turned off before displaying the conversation list page:

// Set before initializing `RCChatListViewController`
[RCIMKitConfig shared].displayNetStatus = NO;

Customizing the Navigation Bar

You can create a subclass that inherits from RCChatListHeaderView and customize the navigation bar by overriding the getter/setter methods of the three properties.

- (void)viewDidLoad {
    [super viewDidLoad];
    // Custom headerView, DemoChatListHeaderView : RCChatListHeaderView
    DemoChatListHeaderView *headerView = [[DemoChatListHeaderView alloc] init];
    self.headerView = headerView;
    [self reloadHeaderView];
}

Customizing the Conversation List

The conversation list component displays all conversations in reverse chronological order, with pinned conversations sorted in reverse chronological order at the top.

tip

If the Multi-Device Message Synchronization feature is enabled in the Console, in scenarios such as logging in on a new device or reinstalling the app, the offline compensation mechanism can only retrieve the most recent (default offline compensation period is 1 day, maximum 7 days) one-to-one and group chat messages. Conversations older than this period cannot be retrieved through the offline compensation mechanism. Therefore, the conversation list after offline compensation may not match the conversation list on the original device or before uninstallation (you may feel that some conversations are missing).

Conversation List View Hierarchy

Listening to Search Bar Click Events

The search bar is displayed at the top of the conversation list by default. You can listen to search bar click events through the listView:didClickSearchBar: method in RCChatListViewDelegate.

/// Implement the delegate method in the RCChatListHeaderView subclass
- (void)listView:(RCChatListView *)listView didClickSearchBar:(RCChatListSearchBar *)searBar {
    // TODO display search View Controller
}

Customizing the Search Bar

RCChatListView provides support for setting the searchBar property. You can create a subclass that inherits from RCChatListSearchBar to fully customize the search bar.

- (void)viewDidLoad {
    [super viewDidLoad];
    // Custom search bar DemoChatListSearchBar : RCChatListSearchBar
    DemoChatListSearchBar *searchBar = [[DemoChatListSearchBar alloc] init];
    self.listView.searchBar = NO;
    [self.listView reloadSearchBar];
}

Hiding the Search Bar

RCChatListView provides a switch displaySearchBar to hide the search bar.

- (void)viewDidLoad {
    [super viewDidLoad];
    // Hide the search bar
    self.listView.displaySearchBar = NO;
    [self.listView reloadSearchBar];
}

Customizing Conversation Cells

In RCChatListView, data is displayed by UITableView, and each conversation corresponds to a Cell, which is RCChatCell.

Conversation Cell View Hierarchy

Modifying Conversation Cell Styles

Override the delegate method listView:didLoadCell:forChatModel: in the RCChatListViewDelegate in the RCChatListViewController subclass to set personalized styles.

- (void)listView:(RCChatListView *)listView didLoadCell:(UITableViewCell *)cell forChatModel:(RCChatModel *)chatModel {
    if ([cell isKindOfClass:[RCChatCell class]]) {
        RCChatCell *chatCell = (RCChatCell *)cell;
        chatCell.portraitView.style = RCPortraitStyleRectangle;
        chatCell.portraitView.imageView.layer.cornerRadius = 2;
    }
}

Customizing Conversation Cells

Use the replaceChatCellWithClass: method to replace RCChatCell with a custom Cell that inherits from RCChatCell.

- (void)viewDidLoad {
    [super viewDidLoad];
    // Custom conversation Cell, DemoChatCell: RCChatCell
    [self.listView replaceChatCellWithClass:[DemoChatCell class]];
    [self.listView reloadTableView];
}

Customizing Swipe Editing

Override the delegate method listView:cellSwipeItemsAtIndexPath:forDirection: in the RCChatListViewDataSource in the RCChatListViewController subclass to set custom swipe buttons.

- (NSArray<RCSwipeItem *> *)listView:(RCChatListView *)listView
           cellSwipeItemsAtIndexPath:(NSIndexPath *)indexPath
                        forDirection:(RCSwipeDirection)direction {
    RCChatModel *model = self.viewModel.chatModels[indexPath.row];
    NSArray *defaultItems = [super listView:listView cellSwipeItemsAtIndexPath:indexPath forDirection:direction];
    NSMutableArray<RCSwipeItem *> *items = [NSMutableArray array];
    // Here you can decide whether to retain the default buttons based on business needs
    [items addObjectsFromArray:defaultItems];
    __weak typeof(self) weakSelf = self;
    if (direction == RCSwipeDirectionLeft) {
        RCSwipeItem *item = [RCSwipeItem itemWithImage:CustomLeftImage
                                                 title:CustomLeftTitle
                                       backgroundColor:CustomLeftColor
                                                action:^{
            // TODO weakSelf
        }];
        [items addObject:item];
    } else {
        RCSwipeItem *item = [RCSwipeItem itemWithImage:CustomRightImage
                                                 title:CustomRightTitle
                                       backgroundColor:CustomRightColor
                                                action:^{
            // TODO weakSelf
        }];
        [items addObject:item];
    }
    return items;
}

Customizing the Empty View

RCChatListView provides an empty view emptyView for the conversation list (i.e., when there are no conversations to display). If you need to customize the empty view, assign it to emptyView.

- (void)viewDidLoad {
    [super viewDidLoad];

    // Custom placeholder empty view
    UIView *empty = [[UIView alloc] init];
    self.listView.emptyView = empty;
}

Customizing Multi-Select Mode

Refer to Multi-Select Mode in the Conversation List