TUIKit Compose 是基于腾讯云 IM SDK 的一套 Jetpack Compose 组件库,提供了聊天、会话列表、联系人管理等即时通信功能的完整解决方案。本文介绍如何手动集成该组件并实现核心功能。
关键概念
TUIKit Compose 提供了一套完整的即时通信 UI 组件,向下依赖 AtomicXCore 数据层,向上可构建各种功能性 Page。
Page 层:基于 TUIKit Compose 组件封装的完整功能页面:ChatPage、ContactsPage、ConversationsPage,您可以直接使用。
TUIKit Compose(UI 组件层):基于 AtomicXCore 构建的 Jetpack Compose 组件,您可将其嵌套到自己已有的 App 页面中。
AtomicXCore(数据层):提供数据管理和业务逻辑,包含各种 Store 和 Manager。
前提条件
Android Studio Ladybug | 2024.2.1 及以上版本
Android 5.0 及以上系统版本
Gradle 8.9 及以上版本
Android Gradle Plugin 8.6 及以上版本
JDK 17 及以上版本
Kotlin 1.9.0 及以上版本
一个有效的腾讯云账号及 Chat 应用。可参考 开通服务 从控制台获取以下信息:
SDKAppID:App 在控制台获取的 Chat 应用的 ID,为应用的唯一标识
SDKSecretKey:应用的密钥
说明:
本项目目前仅支持手动集成,暂不支持通过 Maven 等包管理器集成。
为确保构建环境稳定,请严格遵循官方兼容性要求进行配置:
Gradle、Android Gradle Plugin、JDK 与 Android Studio 的兼容性,请参阅 Android 官方文档:版本说明。
Kotlin、Android Gradle Plugin 与 Gradle 的版本对应关系,请参阅 Kotlin 官方文档:Kotlin-Gradle 插件兼容性。
我们建议您根据上述指南,选择与项目要求完全匹配的版本组合。
集成并引入组件
下载源码
1. 从 GitHub 下载 TUIKit Compose 源码:
git clone https://github.com/Tencent-RTC/TUIKit_Android_Compose.git
项目目录结构说明:
atomic-x/├── src/main/│ ├── java/io/trtc/tuikit/atomicx/ # UI 组件源码(必需集成)│ ├── messagelist/ # 消息列表组件│ ├── messageinput/ # 消息输入组件│ ├── conversationlist/ # 会话列表组件│ ├── contactlist/ # 联系人列表组件│ ├── basecomponent/ # 基础组件│ └── ... # 其他 UI 组件│ # 资源文件(必需集成)│ ├── res/ # 公共资源│ ├── res-message-list/ # 消息列表组件资源│ ├── res-message-input/ # 消息输入组件资源│ ├── res-conversation-list/ # 会话列表组件资源│ └── ... # 其他组件资源chat/├── uikit/src/main/java/io/trtc/tuikit/chat/pages # Page 组件(参考实现)│ ├── ChatPage.kt│ ├── ContactsPage.kt│ └── ConversationsPage.kt└── demo/ # 示例应用(可选参考)
集成组件
1. 将组件目录完整复制到您的 Android 项目中,如下图所示,其中 ComposeDemo 是示例项目,TUIKit_Android_Compose 是从 GitHub 上下载的组件源码:

2. 在您的 settings.gradle.kts/settings.gradle 文件中添加 TUIKit Compose 组件:
说明:
TUIKit_Android_Compose 可以放在任何位置,只要在 settings.gradle 中正确设置相对路径即可。
// settings.gradle.ktsinclude(":atomicx")project(":atomicx").projectDir = file("../TUIKit_Android_Compose/atomic-x")
// settings.gradleinclude ':atomicx'project(':atomicx').projectDir = new File(settingsDir, '../TUIKit_Android_Compose/atomic-x')
3. 在 app 模块的 build.gradle.kts/build.gradle 中添加下列依赖:
// app/build.gradle.ktsdependencies {implementation(project(":atomicx"))}
// app/build.gradledependencies {api project(':atomicx')}
注意:
使用本地集成方案时,如需升级时需要从 GitHub 获取最新的组件代码,覆盖您本地项目的 TUIKit Compose 目录。
当私有化修改和远端有冲突时,需要手动合并,处理冲突。
配置项目
1. 在 app 目录下找到 AndroidManifest.xml 文件,在
application 节点中添加 tools:replace="android:allowBackup",覆盖组件内的设置,使用自己的设置。// app/src/main/AndroidManifest.xml<applicationandroid:name=".BaseApplication"android:allowBackup="false"android:icon="@drawable/app_ic_launcher"android:label="@string/app_name"android:largeHeap="true"android:theme="@style/AppTheme"tools:replace="android:allowBackup">
2. 配置依赖项。
在您的项目工程的 gradle/libs.versions.toml 文件中添加如下依赖项:
# gradle/libs.versions.toml[versions]agp = "8.13.0"kotlin = "2.0.21"coreKtx = "1.10.1"junit = "4.13.2"junitVersion = "1.1.5"espressoCore = "3.5.1"appcompat = "1.7.1"material = "1.13.0"runner = "1.0.2"espressoCoreVersion = "3.0.2"appcompatV7 = "28.0.0"tuicore = "8.6.7021"lifecycleRuntimeKtx = "2.8.7"ui = "1.8.0"foundation = "1.8.0"composeBom = "2024.09.00"activityCompose = "1.10.1"activity = "1.8.0"constraintlayout = "2.2.1"[libraries]androidx-core-ktx = { group = "androidx.core", name = "core-ktx", version.ref = "coreKtx" }junit = { group = "junit", name = "junit", version.ref = "junit" }androidx-junit = { group = "androidx.test.ext", name = "junit", version.ref = "junitVersion" }androidx-espresso-core = { group = "androidx.test.espresso", name = "espresso-core", version.ref = "espressoCore" }androidx-appcompat = { group = "androidx.appcompat", name = "appcompat", version.ref = "appcompat" }material = { group = "com.google.android.material", name = "material", version.ref = "material" }runner = { group = "com.android.support.test", name = "runner", version.ref = "runner" }espresso-core = { group = "com.android.support.test.espresso", name = "espresso-core", version.ref = "espressoCoreVersion" }appcompat-v7 = { group = "com.android.support", name = "appcompat-v7", version.ref = "appcompatV7" }androidx-lifecycle-viewmodel-compose = { module = "androidx.lifecycle:lifecycle-viewmodel-compose", version.ref = "lifecycleRuntimeKtx" }androidx-compose-bom = { group = "androidx.compose", name = "compose-bom", version.ref = "composeBom" }androidx-compose-foundation = { group = "androidx.compose.foundation", name = "foundation", version.ref = "foundation" }androidx-compose-ui = { group = "androidx.compose.ui", name = "ui", version.ref = "ui" }androidx-compose-ui-graphics = { group = "androidx.compose.ui", name = "ui-graphics" }androidx-ui-tooling = { group = "androidx.compose.ui", name = "ui-tooling" }androidx-compose-material3 = { group = "androidx.compose.material3", name = "material3" }androidx-activity-compose = { group = "androidx.activity", name = "activity-compose", version.ref = "activityCompose" }androidx-lifecycle-runtime-ktx = { group = "androidx.lifecycle", name = "lifecycle-runtime-ktx", version.ref = "lifecycleRuntimeKtx" }androidx-ui-tooling-preview = { group = "androidx.compose.ui", name = "ui-tooling-preview" }androidx-ui-test-manifest = { group = "androidx.compose.ui", name = "ui-test-manifest" }tuicore = { module = "com.tencent.liteav.tuikit:tuicore", version.ref = "tuicore" }com-tencent-mmkv = { group = "com.tencent", name = "mmkv", version = "1.3.14" }[plugins]android-application = { id = "com.android.application", version.ref = "agp" }kotlin-android = { id = "org.jetbrains.kotlin.android", version.ref = "kotlin" }android-library = { id = "com.android.library", version.ref = "agp" }kotlin-compose = { id = "org.jetbrains.kotlin.plugin.compose", version.ref = "kotlin" }
3. 开启 Compose 支持。
在 app 模块的 build.gradle.kts/build.gradle 中添加下列配置:
// app/build.gradle.ktsplugins {// 添加 Compose 插件alias(libs.plugins.kotlin.compose)}android {// 开启 ComposebuildFeatures {compose = true}}
// app/build.gradleplugins {// 添加 Compose 插件id libs.plugins.kotlin.compose.get().pluginId}android {// 开启 ComposebuildFeatures {compose true}}
4. 配置混淆规则。
在您的 app/proguard-rules.pro 文件中添加以下混淆规则:
-keep class com.tencent.** { *; }
5. Android Studio 中点击 File > Sync Project with Gradle Files 集成组件。
接入步骤
步骤1:配置用户鉴权

步骤2:用户登录
登录鉴权后才能正常使用组件的功能。您可以调用 login 接口,传入上文获取的 SDKAPPID、userSig 用于登录鉴权:
// 用户登录LoginStore.shared.login(context, SDKAPPID, userID, userSig,object : CompletionHandler {override fun onSuccess() {// 登录成功,可跳转聊天或会话页}override fun onFailure(code: Int, desc: String) {// 登录失败,可弹框报错}})
注意:
步骤3: 构建会话列表界面
您可以基于 TUIKit Compose 中的 ConversationList 组件,构建一个会话列表页面。ConversationList 内建的功能是:
展示用户的会话列表,包含单聊和群聊会话
支持用户操作单个会话:置顶、删除、清空会话消息等
您可以将 ConversationList 直接集成到现有的 App 页面中,也可以新构建一个完整的会话列表页,组装后的一种 UI 效果如下图所示:

将 ConversationList 封装为会话列表页,可参考
chat/uikit/src/main/java/io/trtc/tuikit/chat/pages/ConversationsPage.kt 文件里的实现,ConversationsPage 主要做了以下工作:1. 在 ConversationList 上方添加了 headerView。
2. 传递点击会话列表 cell 事件。
核心示例代码如下所示:
@Composablefun ConversationsPage(onConversationClick: (ConversationInfo) -> Unit = {},editContent: @Composable () -> Unit = {},) {val colors = LocalTheme.current.colorsColumn(modifier = Modifier.fillMaxSize().background(Colors.Transparent)) {PageHeader(stringResource(R.string.chat_uikit_chat)) {editContent()}Box(modifier = Modifier.fillMaxSize(), contentAlignment = Alignment.Center) {ConversationList(modifier = Modifier.navigationBarsPadding(), onConversationClick = onConversationClick)}}}
步骤4:构建聊天界面
您可以基于 TUIKit Compose 中的 MessageList、MessageInput 组件,构建一个聊天页面。
MessageList 内建的功能是:
展示单聊或群聊消息列表。
支持对单条消息操作:查看图片消息大图、播放视频或语音消息、复制文本消息、撤回消息、删除消息等。
MessageInput 内建的功能是:
支持用户组建并发送多种类型的消息:文本、表情、图片、语音、视频、文件等。
您可以将 MessageList 和 MessageInput 直接集成到现有的 App 页面中,也可以新构建一个完整的聊天页,组装后的一种 UI 效果如下图所示:

将 MessageList 和 MessageInput 组装为聊天页,可参考
chat/uikit/src/main/java/io/trtc/tuikit/chat/pages/ChatPage.kt 文件里的实现,ChatPage 主要做了以下工作:1. 在最上方添加了 headerView,展示会话的名称。
2. 按照移动端用户使用习惯,上下拼接 MessageList 和 MessageInput。
核心示例代码如下所示:
@Composablefun ChatPage(conversationID: String,locateMessage: MessageInfo? = null,onUserClick: (String) -> Unit,onChatHeaderClick: (String) -> Unit,onBackClick: () -> Unit,) {...val avatarUrl = conversationState.value?.avatarURLval displayName = conversationState.value?.titleval colors = LocalTheme.current.colorsScaffold(modifier = Modifier.background(color = colors.bgColorOperate).fillMaxSize().wrapContentHeight(), topBar = {Box(modifier = Modifier.background(color = colors.bgColorOperate).fillMaxWidth().statusBarsPadding()) {ChatHeader(avatarUrl = avatarUrl,name = displayName ?: "",onBackClick = onBackClick,onAvatarClick = {onChatHeaderClick(conversationID)})}},bottomBar = {Box(modifier = Modifier.fillMaxWidth().background(color = colors.bgColorOperate)) {MessageInput(modifier = Modifier.navigationBarsPadding(), conversationID = conversationID)}}) { padding ->Box(modifier = Modifier.padding(padding)) {MessageList(conversationID = conversationID, locateMessage = locateMessage) {onUserClick(it)}}}}
步骤5:构建联系人界面
您可以基于 TUIKit Compose 中的 ContactList 组件,构建一个联系人页面。ContactList 内建的功能是:
查看好友申请列表。
查看已加入的群列表。
处理群组邀请和申请。
管理黑名单列表。
查看好友。
您可以将 ContactList 直接集成到现有的 App 中,也可以新构建一个完整的联系人列表页,组装后的一种 UI 效果如下图所示:

将 ContactList 封装为联系人列表页,可参考
chat/uikit/src/main/java/io/trtc/tuikit/chat/pages/ContactsPage.kt 文件里的实现,ContactsPage 主要做了以下工作:1. 在 ContactList 上方添加了 headerView。
2. 传递点击联系人列表 cell 事件。
核心示例代码如下所示:
@Composablefun ContactsPage(onContactClick: (ContactInfo) -> Unit = {},onGroupClick: (ContactInfo) -> Unit = {},editContent: @Composable () -> Unit = {},) {val colors = LocalTheme.current.colorsColumn(modifier = Modifier.fillMaxSize().background(Colors.Transparent)) {PageHeader(stringResource(R.string.chat_uikit_contacts)) {editContent()}Box(modifier = Modifier.fillMaxSize().navigationBarsPadding(), contentAlignment = Alignment.Center) {ContactList(onGroupClick = onGroupClick, onContactClick = onContactClick)}}}
步骤6:完善界面间的跳转逻辑
ConversationsPage、ChatPage、ContactsPage 中暴露了一些用户点击事件,您可以自定义事件来实现页面间的交互:
Page | 回调 | 建议跳转逻辑 |
ConversationsPage | onConversationClick: (ConversationInfo) -> Unit | 点击会话列表中的会话时触发,建议跳转到聊天页面(ChatPage)。 |
ContactsPage | onContactClick: (ContactInfo) -> Unit | 点击联系人 cell 时触发,建议跳转用户信息页(C2CChatSetting)。 |
| onGroupClick: (ContactInfo) -> Unit | 点击群组 cell 时触发,建议跳转群聊页面(ChatPage)。 |
ChatPage | onUserClick: (String) -> Unit | 点击消息中的用户头像或昵称时触发,建议跳转用户信息页(C2CChatSetting)。 |
| onChatHeaderClick: (String) -> Unit | 点击导航栏中的头像时触发,建议跳转用户信息页(C2CChatSetting)或群聊信息页(GroupChatSetting) |
| onBackClick: () -> Unit | 点击返回按钮时触发,建议返回上一级页面。 |
chat/demo/app/src/main/java/io/trtc/tuikit/chat/MainActivity.kt 和 chat/demo/app/src/main/java/io/trtc/tuikit/chat/chat/ChatActivity.kt 作为上述 Page 的粘合层,实现了各个 Page 的回调事件,核心示例代码如下:
// chat/demo/app/src/main/java/io/trtc/tuikit/chat/MainActivity.kt// 点击会话列表 cell 跳转ConversationsPage(onConversationClick = {activity?.startActivity(Intent(activity, ChatActivity::class.java).apply {putExtra("conversationID", it.conversationID)})})// 点击联系人页面跳转ContactsPage(onGroupClick = {ChatSettingActivity.start(context, "", it.contactID, true)}, onContactClick = {ChatSettingActivity.start(context, it.contactID, "", true)})
// chat/demo/app/src/main/java/io/trtc/tuikit/chat/chat/ChatActivity.kt// 点击聊天页面跳转ChatPage(conversationID = conversationID,locateMessage = message,onUserClick = {handleChatSettingNavigation(it)}, onChatHeaderClick = {val userID = getUserID(conversationID)val groupID = getGroupID(conversationID)handleChatSettingNavigation(userID, groupID)}, onBackClick = { finish() })
您可以参考上述回调说明及参考代码,实现 Page 之间交互逻辑。
常见问题
功能常见问题
登录失败,提示签名错误
联系我们