tencent cloud

即时通信 IM

动态与公告
产品动态
公告
产品简介
产品概述
基本概念
应用场景
功能介绍
账号系统
用户资料与关系链
消息管理
群组相关
公众号系统
音视频通话 Call
使用限制
购买指南
计费概述
价格说明
购买指引
续费指引
停服说明
退费说明
开发指引
Demo 专区
开通服务
体验 Demo
快速跑通
下载中心
SDK & Demo 源码
更新日志
聊天互动(含 UI)
TUIKit 组件介绍
快速开始
全功能接入
单功能接入
AI 集成
构建基础界面
更多特性
定义外观
国际化界面语言
推送服务(Push)
服务概述
名词解释
开通服务
快速跑通
厂商通道
数据统计
排查工具
客户端 API
服务端 API
推送回调
高级功能
更新日志
错误码
常见问题
智能客服
功能概述
快速入门
集成指引
管理员操作手册
客服操作手册
更多实践
直播间搭建
AI 聊天机器人方案
超大娱乐协作社群
Discord 实现指南
游戏内集成 Chat 指南
类 WhatsApp Channel 搭建方案
发送红包
Chat 应对防火墙限制相关
无 UI 集成
快速开始
集成 SDK
初始化
登录登出
消息相关
会话相关
群组相关
社群话题
用户管理
离线推送
云端搜索
本地搜索
公众号
客户端 API
JavaScript
Android
iOS & macOS
Swift
Flutter
Electron
Unity
React Native
C 接口
C++
服务端 API
生成 UserSig
REST API
第三方回调
控制台指南
新版控制台介绍
创建并升级应用
基本配置
功能配置
账号管理
群组管理
公众号管理
回调配置
用量统计
资源包查看指南
实时监控
开发辅助工具
访问管理
高级功能
常见问题
uni-app 常见问题
购买相关问题
SDK 相关问题
账号鉴权相关问题
用户资料与关系链相关问题
消息相关问题
群组相关问题
直播群相关问题
昵称头像相关问题
协议与认证
服务等级协议
安全合规认证
IM 政策
隐私政策
数据隐私和安全协议
平滑迁移方案
平滑迁移完整版
平滑迁移简化版
错误码
联系我们

Android(Compose)

PDF
聚焦模式
字号
最后更新时间: 2026-03-03 14:18:05
TUIKit Compose 是基于 Chat 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 中正确设置相对路径即可。
Kotlin DSL (推荐)
Groovy DSL
// settings.gradle.kts
include(":atomicx")
project(":atomicx").projectDir = file("../TUIKit_Android_Compose/atomic-x")
// settings.gradle
include ':atomicx'
project(':atomicx').projectDir = new File(settingsDir, '../TUIKit_Android_Compose/atomic-x')
3. 在 app 模块的 build.gradle.kts/build.gradle 中添加下列依赖:
Kotlin DSL (推荐)
Groovy DSL
// app/build.gradle.kts
dependencies {
implementation(project(":atomicx"))
}
// app/build.gradle
dependencies {
api project(':atomicx')
}
注意:
使用本地集成方案时,如需升级时需要从 GitHub 获取最新的组件代码,覆盖您本地项目的 TUIKit Compose 目录。
当私有化修改和远端有冲突时,需要手动合并,处理冲突。

配置项目

1. 在 app 目录下找到 AndroidManifest.xml 文件,在 application 节点中添加 tools:replace="android:allowBackup",覆盖组件内的设置,使用自己的设置。
// app/src/main/AndroidManifest.xml
<application
android: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 中添加下列配置:
Kotlin DSL (推荐)
Groovy DSL
// app/build.gradle.kts
plugins {
// 添加 Compose 插件
alias(libs.plugins.kotlin.compose)
}
android {
// 开启 Compose
buildFeatures {
compose = true
}
}
// app/build.gradle
plugins {
// 添加 Compose 插件
id libs.plugins.kotlin.compose.get().pluginId
}
android {
// 开启 Compose
buildFeatures {
compose true
}
}
4. 配置混淆规则。
在您的 app/proguard-rules.pro 文件中添加以下混淆规则:
-keep class com.tencent.** { *; }
5. Android Studio 中点击 File > Sync Project with Gradle Files 集成组件。

接入步骤

步骤1:配置用户鉴权

Tencent RTC 控制台 根据 UserID 获取 UserSig 用于后续登录时的用户鉴权。


步骤2:用户登录

登录鉴权后才能正常使用组件的功能。您可以调用 login 接口,传入上文获取的 SDKAPPID、userSig 用于登录鉴权。可参考 chat/demo/app/src/main/java/io/trtc/tuikit/chat/login/LoginActivity.kt 文件里实现:
// 用户登录
LoginStore.shared.login(context, SDKAPPID, userID, userSig,
object : CompletionHandler {
override fun onSuccess() {
// 登录成功,可跳转聊天或会话页
}
override fun onFailure(code: Int, desc: String) {
// 登录失败,可弹框报错
}
})
警告:
在正式的生产环境中,请在您的服务端生成 UserSig,在需要 UserSig 时由您的 App 向业务服务器发起请求获取动态 UserSig 来进行鉴权。详见 服务端生成 UserSig

步骤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 事件。
核心示例代码如下所示:
@Composable
fun ConversationsPage(
onConversationClick: (ConversationInfo) -> Unit = {},
editContent: @Composable () -> Unit = {},
) {
val colors = LocalTheme.current.colors
Column(
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。
核心示例代码如下所示:
@Composable
fun ChatPage(
conversationID: String,
locateMessage: MessageInfo? = null,
onUserClick: (String) -> Unit,
onChatHeaderClick: (String) -> Unit,
onBackClick: () -> Unit,
) {
...

val avatarUrl = conversationState.value?.avatarURL
val displayName = conversationState.value?.title
val colors = LocalTheme.current.colors
Scaffold(
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 事件。
核心示例代码如下所示:
@Composable
fun ContactsPage(
onContactClick: (ContactInfo) -> Unit = {},
onGroupClick: (ContactInfo) -> Unit = {},
editContent: @Composable () -> Unit = {},
) {

val colors = LocalTheme.current.colors
Column(
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 之间交互逻辑。

常见问题

功能常见问题

登录失败,提示签名错误?

请检查 SDKAppID 和 UserSig 是否正确,UserSig 是否已过期。可以参考上文配置用户鉴权重新生成 UserSig。

联系我们

如果您在接入或使用过程中有任何疑问或者建议,欢迎 联系我们 提交反馈。


帮助和支持

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

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

文档反馈