tencent cloud

即时通信 IM

文档即时通信 IM聊天互动（含 UI）单功能接入会话列表Android（Compose）

Android（Compose）

下载
聚焦模式
字号
最后更新时间： 2026-10-21 12:05:40

组件概述

ConversationList 是一个基于 Jetpack Compose 构建的会话列表组件，主要用于展示和管理用户的聊天会话。该组件提供了完整的会话列表功能，包括会话展示、长按会话弹出操作菜单等核心能力。
会话列表
会话操作



组件集成

ConversationList 是属于 TUIKit Compose 的一个组件，集成 TUIKit Compose 即可获取并使用 ConversationList，集成方法请参考文档 TUIKit Compose 里的集成步骤。

组件构成

ConversationList 组件对外仅暴露了会话列表的初始化方法，其他逻辑均封装在 ConversationList 中。

对外方法

方法名
参数
描述
ConversationList
modifier: Modifier
Jetpack Compose 中用来设置组件的样式、布局、行为和外观。
config: ConversationActionConfigProtocol
会话操作菜单配置，选填。默认值为 ChatConversationActionConfig()，可设置默认操作项是否展示，也可通过 customizeActions 编辑操作项。
conversationListViewModelFactory: ConversationListViewModelFactory
创建组件内部 ConversationListViewModel 的工厂类。通常情况下，您无需手动创建，组件已提供默认实现。
customActions: List<ConversationCustomAction>
自定义会话操作项，追加在操作菜单的末尾，选填。
onConversationClick: (ConversationInfo) -> Unit
设置会话点击回调，选填。

基础用法

ConversationList 组件可直接初始化使用，所有参数均有默认值，通常只需传入 onConversationClick 回调。
参数名
类型
描述
onConversationClick
(ConversationInfo) -> Unit
会话点击回调，当用户点击某个会话 cell 时触发。回调参数 ConversationInfo 中的 conversationID 可用于进入对应的聊天页面。
示例代码如下：
import io.trtc.tuikit.chat.uikit.components.conversationlist.ui.ConversationList

Box(
    modifier = Modifier
        .fillMaxSize()
        .systemBarsPadding()
) {
    ConversationList(onConversationClick = { conversation ->
        // 这里建议导航到聊天页面，conversation.conversationID 为会话 ID
    })
}

自定义组件

您可以自定义长按会话 cell 后弹出的操作菜单。默认操作项从上到下依次为：标为已读（或标为未读）、消息免打扰（或取消免打扰）、置顶（或取消置顶）、清空聊天记录、删除聊天，其中“清空聊天记录”和“删除聊天”点击后会先弹出确认框。自定义方法如下。

方式 1. 隐藏会话操作项

初始化 ConversationList 时设置 config，指定当前会话列表展示哪些默认操作项。
import io.trtc.tuikit.chat.uikit.components.conversationlist.config.ChatConversationActionConfig
import io.trtc.tuikit.chat.uikit.components.conversationlist.ui.ConversationList

ConversationList(
    config = ChatConversationActionConfig(
        isSupportMarkUnread = true,    // 展示“标为已读/标为未读”
        isSupportMute = true,          // 展示“消息免打扰/取消免打扰”
        isSupportPin = true,           // 展示“置顶/取消置顶”
        isSupportClearHistory = true,  // 展示“清空聊天记录”
        isSupportDelete = false        // 不展示“删除聊天”
    ),
    onConversationClick = { conversation ->
        // 点击会话 cell 跳转
    }
)
目前支持的菜单项开关操作
操作类型
对应操作项 ID
描述
isSupportMarkUnread
ConversationActionIDs.MARK_UNREAD
是否展示“标为已读/标为未读”。会话有未读消息或被标记为未读时显示“标为已读”，否则显示“标为未读”。
isSupportMute
ConversationActionIDs.MUTE
是否展示“消息免打扰/取消免打扰”。
isSupportPin
ConversationActionIDs.PIN
是否展示“置顶/取消置顶”。
isSupportClearHistory
ConversationActionIDs.CLEAR_HISTORY
是否展示“清空聊天记录”，点击后会先弹出确认框。
isSupportDelete
ConversationActionIDs.DELETE
是否展示“删除聊天”，标题显示为红色，点击后会先弹出确认框。

方式 2. 增加会话操作项

初始化 ConversationList 时传入 customActions，ConversationList 内部会在默认操作项的末尾添加您增加的自定义选项：
参数名
类型
描述
customActions
List<ConversationCustomAction>
自定义会话操作，长按会话 cell 弹出操作菜单时展示。
ConversationCustomAction 的字段说明如下：
字段
类型
描述
ID
String
操作项的唯一标识，必填。
title
String
操作项标题，默认为空字符串。
titleResID
Int
操作项标题的字符串资源 ID，仅在 title 为空时使用。title 和 titleResID 均未设置的操作项不会展示。
dangerous
Boolean
是否为危险操作，为 true 时标题显示为红色，默认为 false。
action
(ConversationInfo) -> Unit
点击操作项时的回调，参数为当前长按的会话。
示例代码如下：
import io.trtc.tuikit.chat.uikit.components.conversationlist.model.ConversationCustomAction
import io.trtc.tuikit.chat.uikit.components.conversationlist.ui.ConversationList

ConversationList(
    customActions = listOf(
        ConversationCustomAction(
            ID = "custom.conversation.hide",
            title = "Hide",
            action = { conversation ->
                println("Hide conversation: ${conversation.title}")
            }
        )
    ),
    onConversationClick = { conversation ->
        // 处理点击事件
    }
)

方式 3. 编辑会话操作菜单

如需调整操作项的顺序、修改默认操作项的标题或行为，或者根据会话动态增删操作项，可以通过 ChatConversationActionConfig 的 customizeActions 编辑操作菜单。每次长按会话 cell 时，组件会先根据开关生成默认操作项，再执行 customizeActions 中的代码，最后在末尾追加 customActions 中的操作项。
在 customizeActions 中，可以通过 editorContext.conversation 获取当前长按的会话，通过 editorContext.androidContext 获取 Android Context，并调用以下方法编辑操作项：
方法
描述
add(item)
在末尾添加操作项。item 的 ID 为空白或与已有操作项重复时会抛出 IllegalArgumentException。
remove(ID)
移除指定 ID 的操作项，不存在时返回 false。
replace(ID) { item -> ... }
替换指定 ID 的操作项，不存在时返回 false。替换后的操作项必须保持 ID 不变，否则会抛出异常。
insertBefore(anchorID, item) / insertAfter(anchorID, item)
在锚点操作项之前或之后插入操作项。锚点不存在时返回 false，且不会插入。item 的 ID 规则与 add 相同。
moveBefore(ID, anchorID) / moveAfter(ID, anchorID)
将操作项移动到锚点操作项之前或之后，任意一个 ID 不存在时返回 false。
clear()
移除全部操作项。
items
当前操作项列表的只读快照。
示例代码如下：
import io.trtc.tuikit.atomicxcore.api.conversation.ConversationType
import io.trtc.tuikit.chat.uikit.components.conversationlist.config.ChatConversationActionConfig
import io.trtc.tuikit.chat.uikit.components.conversationlist.model.ConversationActionIDs
import io.trtc.tuikit.chat.uikit.components.conversationlist.model.ConversationCustomAction
import io.trtc.tuikit.chat.uikit.components.conversationlist.ui.ConversationList

val actionConfig = ChatConversationActionConfig().customizeActions {
    // 当前长按的会话
    val conversation = editorContext.conversation
    // 移除“清空聊天记录”
    remove(ConversationActionIDs.CLEAR_HISTORY)
    // 修改“删除聊天”的标题。ID 保持不变，点击后仍会先弹出确认框
    replace(ConversationActionIDs.DELETE) { action ->
        action.copy(title = "删除会话")
    }
    // 仅对群聊会话，在“删除会话”之前插入自定义操作项
    if (conversation.type == ConversationType.GROUP) {
        insertBefore(
            ConversationActionIDs.DELETE,
            ConversationCustomAction(
                ID = "custom.conversation.groupProfile",
                title = "查看群资料",
                action = { target ->
                    // 跳转到群资料页，target.conversationID 的格式为 group_groupID
                }
            )
        )
    }
}

ConversationList(
    config = actionConfig,
    onConversationClick = { conversation ->
        // 点击会话 cell 跳转
    }
)
注意：
ID 为 ConversationActionIDs.DELETE 或 ConversationActionIDs.CLEAR_HISTORY 的操作项（包括通过 replace 修改后的操作项），点击后都会先弹出确认框，用户确认后才执行 action。
自定义效果如下图所示：
会话操作（默认选项）
会话操作（隐藏删除选项）
会话操作（新增隐藏会话选项）



上一篇: Web & H5 （Vue）下一篇: iOS（SwiftUI）

帮助和支持

本页内容是否解决了您的问题？

填写满意度调查问卷，共创更好文档体验。

文档反馈

搜索
    请输入关键词搜索文档