Conversation Menu

Overview of Conversation Menu

Global IM UIKit provides a basic conversation menu. Users can display the conversation menu by right-clicking on a conversation in the conversation list.

tip

The above image is a reference design and not the default implementation of Global IM UIKit. Components such as the conversation list filter, extended function items in the top-right corner of the conversation UI, and some items in the menu need to be implemented by the application.

Each menu item has a unique ID, defined by the RCKitConversationMenuID enumeration.

Menu ID	Description
RCKitConversationMenuID.ADD_TOP	Pin Conversation
RCKitConversationMenuID.REMOVE_TOP	Unpin Conversation
RCKitConversationMenuID.MUTE	Mute Conversation
RCKitConversationMenuID.UNMUTE	Unmute Conversation
RCKitConversationMenuID.MARK_READ	Mark as Read, clicking this will clear the unread message count of the conversation
RCKitConversationMenuID.MARK_UNREAD	Mark as Unread
RCKitConversationMenuID.REMOVE	Delete Conversation; this function is only used to delete the local conversation display and has no effect on multi-device setups (e.g., mobile)

Global IM UIKit also uses this ID to query the multilingual configuration file to obtain the display text for the menu items. Therefore, you can modify the display text of the menu items by editing the multilingual entries.

// Get a copy of the multilingual entries
const entries = kitApp.cloneLanguageEntries('zh_CN');
// Modify the display text for the Pin Conversation menu item
entries[RCKitConversationMenuID.ADD_TOP] = 'Pin';
// Register the multilingual pack, note that this method only takes effect before kitApp.ready() is called
kitApp.registerLanguagePack('zh_CN', entries);

Customizing the Conversation Menu

You can obtain a copy of the existing conversation menu by using cloneConversationMenu, allowing you to extend or modify the existing menu.

const menu: IRCKitConversationMenuItem[] = kitApp.cloneConversationMenu();
// [{ id: 'conversation.menu.item.add_top', icon: ''}, ... ]

The conversation menu data is an array, where each element represents a menu item with the following data structure:

export interface IRCKitConversationMenuItem {
  /**
   * Menu ID, included by the SDK when dispatching click events, and also used to query the multilingual UI display text
   */
  id: string,
  /**
   * Menu icon
   */
  icon: string,
  /**
   * Conversation filter function, the menu item is only displayed when this function returns true;
   * @param conversation - The clicked conversation
   * @description This method is used to customize the menu display for different conversations; when this method is undefined, the SDK will display the menu item for all conversations by default
   */
  readonly filter?: (conversation: IRCKitCachedConversation) => boolean,
}

Since the conversation menu data is an array, you can modify the array data to achieve customization of the conversation menu, such as changing the display order, adding or deleting menu items, etc.

After modification, developers need to register the modified data with Global IM UIKit using the setConversationMenu method.

tip

setConversationMenu only takes effect before kitApp.ready() is called.

kitApp.setConversationMenu(menu);

tip

Since Global IM UIKit matches the multilingual UI display text based on the conversation menu ID, you need to add the corresponding UI display text in the multilingual pack when adding new conversation menu items.

// Get a copy of the conversation menu items
const menu = kitApp.cloneConversationMenu();
// Add a test menu item
menu.push({
  id: 'conversation.menu.item.test',
  icon: '', // The icon UI needs to be provided by the developer
  // Only display when clicking on a private conversation
  filter: (conversation) => conversation.conversationType === ConversationType.PRIVATE,
});
// Register the conversation menu
kitApp.setConversationMenu(menu);

// Add multilingual UI display text
let entries = kitApp.cloneLanguageEntries('zh_CN');
entries['conversation.menu.item.test'] = 'Test Menu';
kitApp.registerLanguagePack('zh_CN', entries);

entries = kitApp.cloneLanguageEntries('en_US');
entries['conversation.menu.item.test'] = 'Test Menu';
kitApp.registerLanguagePack('en_US', entries);

When a new message menu item is clicked, Global IM UIKit will dispatch the RCKitEvents.CONVERSATION_MENU_ITEM_CLICK event. You can listen to this event to implement custom menu click handling logic.

tip

For built-in menu items, Global IM UIKit will automatically handle click events; unless developers have specific business requirements, they should avoid calling evt.preventDefault() to block default behavior.

kitApp.addEventListener(RCKitEvents.CONVERSATION_MENU_ITEM_CLICK, (evt) => {
  const { id, conversation } = evt.data;
  switch (id) {
    case 'conversation.menu.item.test':
      // Handling logic
      break;
    default:
      // Note, do not call evt.preventDefault() to intercept click events for built-in menu items
      break;
  }
});