跳到主要内容

会话列表自定义

会话列表控制需要展示的会话类型​

SDK 会话列表默认仅支持单聊和群聊两种会话。

您可以通过 setSupportedTypes 传入对应的会话类型枚举来配置会话列表展示的会话类型，需要在会话列表展示前设置，最多可以支持 单聊、群聊、系统会话。

示例代码​

TypeScript
// 读取会话列表当前的配置
let config = RongIM.getInstance().conversationListService().getConversationListConfig()
// 设置会话列表仅展示单聊
config.setSupportedTypes([ConversationType.Private])
// 更新会话列表配置
RongIM.getInstance().conversationListService().setConversationListConfig(config)

会话列表组件自定义聚合展示​

您可以通过为 ConversationListComponent 组件设置 dataProcessor 参数，实现更灵活的会话列表数据源管理。

提示
  • 从 1.7.2 版本开始支持。
  • 一旦使用该参数，将会覆盖前述通过 setSupportedTypes 配置的会话类型展示方式。

示例代码​

TypeScript
// 仅展示单聊会话
ConversationListComponent({dataProcessor: {
  supportedTypes: [ConversationType.Private]
}})

// 仅展示群聊会话
ConversationListComponent({dataProcessor: {
  supportedTypes: [ConversationType.Group]
}})

// 自定义聚合（以获取未读数不为 0 的会话列表为例）
ConversationListComponent({dataProcessor: {
  onFetchConversationList: async (time: number) => {
    // 自定义请求会话列表数据
    const cons = new List<ConversationType>()
    cons.add(ConversationType.Group)
    cons.add(ConversationType.Private)

    const list: List<Conversation> = new List<Conversation>()

    const res = await IMEngine.getInstance().getUnreadConversations(cons)
    if (res.code === EngineError.Success && res.data && res.data.length > 0) {
      res.data.forEach(item => {
        list.add(item)
      })
      options.time = res.data.getLast().lastOperateTime
    }

    return list
  },
  // 设置会话数据过滤方法
  onConversationFilter: (item: Conversation) => {
    return item.unreadMessageCount > 0
  }
}})

会话列表增加长按事件​

您可以通过 addConversationItemLongClickActio 方法自行增加会话列表的长按事件:

示例代码​

TypeScript
private addConversationListLongClickAction() {
  let action: ItemLongClickAction<Conversation> = {
    // 显示标题
    obtainTitle: (context: Context, data: Conversation): string | Resource => {
      return "自定义长按事件";
    },
    // 长按 item 的点击事件
    onClick: (context: Context, data: Conversation) => {
      promptAction.showToast({ message: "会话列表自定义长按事件" })
    },
    // 过滤条件，true 代表需要显示，false 代表不会显示
    onFilter: (data: Conversation): boolean => {
      // 可以动态配置特定的 Conversation 才显示该长按 item
      return true;
    },
    actionId: 'Conversation_Custom' // 动作 Id，可自定义
  }

  RongIM.getInstance().conversationListService().addConversationItemLongClickAction(action);
}

会话列表头像圆角控制​

您可以通过 setConversationAvatarStyle 方法修改会话列表头像圆角，会话列表头像默认为矩形，可以修改为圆形，不支持动态切换矩形和圆形，必须在会话列表展示前设置:

示例代码​

TypeScript
// 读取会话列表当前的配置
let config = RongIM.getInstance().conversationListService().getConversationListConfig()
// 设置会话列表头像为圆角
config.setConversationAvatarStyle(AvatarStyle.Cycle)
// 更新会话列表配置
RongIM.getInstance().conversationListService().setConversationListConfig(config)

会话列表点击事件​

当您使用 ConversationListComponent 创建会话列表页面时，可以传入 onConversationItemClick 来处理点击事件。 SDK 默认未处理点击事件，如未设置 onConversationItemClick 则表现为点击无反应。

提示

从 1.4.3 版本开始， 支持通过 addConversationListEventListener 设置会话列表点击事件，见会话列表事件。 但需要注意，如果传入的 onConversationItemClick 不为空则不会再执行 ConversationListEventListener 的 onConversationClick 回调。

示例代码​

TypeScript
@Entry
@Component
export struct ChatListPage {

  build() {
    Column() {
      ConversationListComponent({
        // 实现会话列表的点击事件
        onConversationItemClick: this.onConversationItemClick
      }).layoutWeight(1)
    }.width('100%').height('100%')
  }
  
  private onConversationItemClick(conversation: Conversation, index: number): void {
    // let params = new Conversation()
    // params.conversationType = ConversationType.Private
    // params.targetId = "会话 Id"

    // 参数必须是 Conversation 对象，必须有有效的 conversationType targetId
    router.pushUrl({ url: "pages/ChatPage", params: conversation },);
  }
}

会话列表添加自定义空布局​

IMKit 的 会话列表组件-Component 支持在会话列表中添加空（Empty）视图，您只需在构造 ConversationListComponent 时传入 emptyComponent 即可。

示例代码​

TypeScript
@Entry
@Component
export struct ChatListPage {

  build() {
    Column() {
      ConversationListComponent({
        // 实现没有会话的空白页面
        emptyComponent: () => {
          this.emptyBuilder();
        }
      }).layoutWeight(1)
    }.width('100%').height('100%')
  }

  @Builder
  emptyBuilder() {
    Text(`空白页面`).width('95%').fontColor("#FF0000").padding(10)
  }
}

会话列表页面事件​

IMKit 提供了会话列表事件监听器 ConversationListEventListener，可监听保存草稿、会话清除未读数、删除会话、本端或者其他端修改会话的免打扰和置顶状态、点击会话、长按会话事件。

您需要使用 RongIM 的 addConversationListEventListener 与 removeConversationListEventListener 方法添加或移除监听器。 建议添加监听后，在合适的时机移除，避免内存泄露。如果在页面中监听，建议在aboutToAppear调用，在 aboutToDisappear 移除监听。

提示
  • 从 1.4.3 版本开始，增加 onConversationLongClick、onConversationClick 方法。

接口原型​

TypeScript
export interface ConversationListEventListener {
  /**
   * 当某个会话内产生保存草稿的行为时
   */
  onSaveDraft?: (identifier: ConversationIdentifier, content: string) => void;

  /**
   * 当某个会话清除未读数时
   */
  onClearedUnreadStatus?: (identifier: ConversationIdentifier) => void;

  /**
   * 当批量删除某些会话时
   */
  onRemoveConversation?: (identifierList: List<ConversationIdentifier>) => void;

  /**
   * 当其他端修改会话的免打扰和置顶状态时
   */
  onSyncConversationStatus?: (items: List<ConversationStatusInfo>) => void;

  /**
   * 当本端修改会话的置顶状态时
   */
  onConversationTopStatusChange?: (identifierList: List<ConversationIdentifier>, option: ISetConversationTopOption) => void;

  /**
   * 当本端修改会话的免打扰状态时
   */
  onConversationNotificationLevelChange?: (identifierList: List<ConversationIdentifier>, level: PushNotificationLevel) => void;
  
  /**
   * 长按会话列表中的 item 时执行。
   *
   * @param uiConversation 长按时的会话条目。
   * @warning 如果存在多个 Listener，只要有1个 Listener 实现了该方法且返回 true，SDK 则不再处理该事件。
   * @returns 是否处理该事件。实现该方法并且返回 true 代表 app 处理该点击事件，SDK 不再处理该点击事件。不实现该方法或者返回 false，代表由 SDK 处理点击事件。
   * @version 1.4.3
   */
  onConversationLongClick?: (uiConversation: BaseUiConversation) => boolean;
  /**
   * 点击会话列表中的 item 时执行。
   *
   * @param uiConversation 会话条目。
   * @warning 优先执行 ConversationListComponent 传入的 onConversationItemClick ，没传则执行此接口逻辑。
   * @warning 如果存在多个 Listener，只要有1个 Listener 实现了该方法且返回 true，SDK 则不再处理该事件。
   * @returns 是否处理该事件。实现该方法并且返回 true 代表 app 处理该点击事件，SDK 不再处理该点击事件。不实现该方法或者返回 false，代表由 SDK 处理点击事件。
   * @version 1.4.3
   */
  onConversationClick?: (uiConversation: BaseUiConversation) => boolean;
}

示例代码​

TypeScript
let service = RongIM.getInstance().conversationListService();
// 设置监听
service.addConversationListEventListener(conversationListEventListener)
// 移除监听
service.removeConversationListEventListener(conversationListEventListener)

自定义会话列表 Item 扩展组件​

您可以通过调用 setConversationItemComponentConfig 方法，为会话列表的每个 Item 组件灵活地添加自定义扩展内容。

提示

从 1.7.2 版本开始支持。

例如，若需为置顶的会话在右上角增加一个自定义图标，可参考以下示例代码：

TypeScript

@Builder
export function buildCustomConversationItemExtensionComponent(componentData: ConversationItemComponentData) {
  CustomConversationItemExtensionComponent({
    context: componentData.context,
    conversation: componentData.conversation,
  })
}

@Component
export struct CustomConversationItemExtensionComponent {
  @Prop context: Context;
  @Prop conversation: BaseUiConversation;

  build() {
    // 在会话右上角增加自定义置顶图标
    if (this.conversation.getConversation().isTop) {
      // 您需要将 “app.media.con_top” 替换为您应用中的图片资源
      Image($r('app.media.con_top')).width(12).height(12).objectFit(ImageFit.Contain)
        .alignRules({
          top: {anchor: '__container__', align: VerticalAlign.Top},
          right: {anchor: '__container__', align: HorizontalAlign.End}
        })
    }
  }
}

let ConversationItemComponent: ConversationItemComponentConfig = {
  identifier: ComponentIdentifier.ConversationItemExtensionComponent,
  component:wrapBuilder(buildCustomConversationItemExtensionComponent),
}
RongIM.getInstance().conversationListService().setConversationItemComponentConfig(ConversationItemComponent)
最后于 更新