tencent cloud

即时通信 IM

文档即时通信 IM聊天互动（含 UI）全功能接入移动端Android（View）

Android（View）

Download
聚焦模式
字号
最后更新时间： 2026-07-06 11:25:24
TUIKit 是基于 Chat SDK 的一款 UI 组件库，可通过 UI 组件快速实现聊天、会话、搜索、关系链、群组等功能。本文介绍如何快速集成 TUIKit 并实现核心功能。

关键概念

TUIKit 提供了一套完整的即时通信 UI 组件，向下依赖 AtomicXCore 数据层，向上可构建各种功能性 Page。
Page 层：基于 TUIKit 组件封装的完整功能页面：ChatPageView、ContactsPageView、ConversationsPageView，您可以直接使用。
TUIKit（UI 组件层）：基于 AtomicXCore 构建的 View UI （非 Compose）组件，您可将其嵌套到自己已有的 App 页面中。
AtomicXCore（数据层）：提供数据管理和业务逻辑，包含各种 Store 和 Manager。

前提条件

Android Studio 2022.3.1 及之后的版本，JDK 17。
Android 6.0 及以上真机或模拟器。
工程需支持 Kotlin（TUIKit 使用 Kotlin 开发）。
minSdk >= 23 。
一个有效的腾讯云账号及 Chat 应用。可参考 开通服务 从控制台获取以下信息：
SDKAppID：App 在控制台获取的 Chat 应用的 ID，为应用的唯一标识
SDKSecretKey：应用的密钥

版本兼容性说明：

为确保构建环境稳定，请严格遵循官方兼容性要求进行配置：
Gradle、Android Gradle Plugin、JDK 与 Android Studio 的兼容性，请参阅 Android 官方文档：版本说明
Kotlin、Android Gradle Plugin 与 Gradle 的版本映射关系，请参阅 Kotlin 官方文档：Kotlin-Gradle 插件兼容性
我们建议您根据上述指南，选择与项目要求完全匹配的版本组合。

集成 TUIKit

下载源码

从 GitHub 仓库 Tencent-RTC/TUIKit_Android 下载源码。项目目录结构说明：
TUIKit_Android/
├── atomic_x/              # 基础 UI 组件库（Chat 依赖）
├── call/
│   └── tuicallkit-kt/     # 音视频通话组件（Chat 依赖）
└── chat/
    ├── demo/              # Chat View 版示例工程
    └── uikit/             # Chat View 版 UI 组件库

集成组件

1. 将仓库根目录下的 chat、atomic_x（以及可选的、用于音视频通话的 call）文件夹整体复制到您的工程根目录下。复制完成后的目录结构如下：
YourApplication/
├── app/                    # 您的应用模块
├── atomic_x/               # 基础 UI 组件库（必要）
├── call/                   # 音视频通话组件（可选）
│   └── tuicallkit-kt/
├── chat/                   # Chat 源码
│   ├── demo/               # 示例工程（可参考，非必需）
│   └── uikit/              # Chat UIKit 组件库（必要）
├── settings.gradle.kts
└── build.gradle.kts
2. 在 settings.gradle.kts 中引入对应模块（请按源码实际存放位置调整相对路径）：
Kotlin DSL
Groovy DSL
// settings.gradle.kts

// 引入 Chat UIKit 组件库（必要）
include(":uikit")
project(":uikit").projectDir = file("${settingsDir.path}/chat/uikit")

// 引入 AtomicX 基础 UI 组件库（必要）
include(":atomic_x")
project(":atomic_x").projectDir = file("${settingsDir.path}/atomic_x")

// 引入音视频通话组件（可选，集成音视频通话时需要）
include(":tuicallkit-kt")
project(":tuicallkit-kt").projectDir = file("${settingsDir.path}/call/tuicallkit-kt")
// settings.gradle

// 引入 Chat UIKit 组件库（必要）
include ':uikit'
project(':uikit').projectDir = new File(settingsDir, 'chat/uikit')

// 引入 AtomicX 基础 UI 组件库（必要）
include ':atomic_x'
project(':atomic_x').projectDir = new File(settingsDir, 'atomic_x')

// 引入音视频通话组件（可选，集成音视频通话时需要）
include ':tuicallkit-kt'
project(':tuicallkit-kt').projectDir = new File(settingsDir, 'call/tuicallkit-kt')
3. 在 app 模块的 build.gradle.kts 中添加依赖：
Kotlin DSL
Groovy DSL
// app/build.gradle.kts
dependencies {
    // TUIKit 组件库（必要）
    implementation(project(":uikit"))
    implementation(project(":atomic_x"))
    // 音视频通话（可选）
    implementation(project(":tuicallkit-kt"))
}
// app/build.gradle
dependencies {
    // TUIKit 组件库（必要）
    implementation project(':uikit')
    implementation project(':atomic_x')
    // 音视频通话（可选）
    implementation project(':tuicallkit-kt')
}

接入步骤

完成上述集成后，参考以下步骤，您仅需几行代码即可在项目中快速搭建会话列表、聊天、联系人等核心界面。

步骤1：配置用户鉴权

在 控制台 > 开发工具 > UserSig 工具 根据 UserID 获取 UserSig，用于后续登录时的用户鉴权。

说明：
更多 UserSig 相关操作，请参见 UserSig 生成&校验。

步骤2：用户登录

登录鉴权后才能正常使用组件的功能。调用 LoginStore 的 login 接口，传入上文获取的 sdkAppID、userID、userSig 进行登录鉴权：
import io.trtc.tuikit.atomicxcore.api.CompletionHandler
import io.trtc.tuikit.atomicxcore.api.login.LoginStore

LoginStore.shared.login(
    context,
    sdkAppID, // Int，控制台获取
    userID,   // String
    userSig,  // String，控制台或服务端生成
    object : CompletionHandler {
        override fun onSuccess() {
            // 登录成功，可跳转会话列表或聊天页
        }
        override fun onFailure(code: Int, desc: String) {
            // 登录失败，可弹框报错
        }
    }
)
注意：
在正式的生产环境中，建议在您的服务端生成 UserSig，在需要时由 App 向业务服务器发起请求获取动态 UserSig 进行鉴权。详见 服务端生成 UserSig。

步骤3：构建会话列表界面

会话列表只需创建 ConversationsPageView 并加入到您的布局即可。它会自动从本地读取最近会话，点击某个会话时通过 onConversationClick 回调返回该会话的 conversationID，您可据此跳转聊天界面。
import android.os.Bundle
import androidx.appcompat.app.AppCompatActivity
import io.trtc.tuikit.chat.uikit.pages.ConversationsPageView

class ConversationActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        val conversationsPage = ConversationsPageView(this)
        conversationsPage.setHeaderTitle("消息")

        // 点击会话回调，conversationID 已带 c2c_ / group_ 前缀
        conversationsPage.onConversationClick = { conversationID ->
            // 跳转到您的聊天界面，并将 conversationID 传入（可参考步骤4 的 ChatActivity）
        }
        // 可选：搜索、发起单聊、创建群聊等入口回调
        conversationsPage.onSearchClick = { /* 跳转搜索页 */ }
        conversationsPage.onStartChatClick = { /* 发起单聊 */ }
        conversationsPage.onCreateGroupClick = { /* 创建群聊 */ }

        // 将会话列表设置为页面内容
        setContentView(conversationsPage)
    }
}

步骤4：构建聊天界面

聊天界面使用 ChatPageView 展示和收发消息，通过 setup 传入 conversationID 即可。conversationID 的格式为：单聊 c2c_<对方 UserID>，群聊 group_<群 GroupID>。
import android.content.Context
import android.content.Intent
import android.os.Bundle
import androidx.appcompat.app.AppCompatActivity
import io.trtc.tuikit.chat.uikit.pages.ChatPageView

class ChatActivity : AppCompatActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        // 必须设置 Material Components 主题，否则 ChatPageView 运行时会 Crash
        setTheme(com.google.android.material.R.style.Theme_MaterialComponents_Light_NoActionBar)
        super.onCreate(savedInstanceState)

        // conversationID 格式：单聊 "c2c_<对方 UserID>"，群聊 "group_<群 GroupID>"
        val conversationID = intent.getStringExtra("conversationID") ?: return

        val chatPageView = ChatPageView(this)
        chatPageView.setup(conversationID = conversationID)
        setContentView(chatPageView)
    }

    companion object {
        fun start(context: Context, conversationID: String) {
            context.startActivity(Intent(context, ChatActivity::class.java).apply {
                putExtra("conversationID", conversationID)
            })
        }
    }
}
注意：
承载聊天页的 Activity 必须设置 Material Components 主题（如 setTheme(com.google.android.material.R.style.Theme_MaterialComponents_Light_NoActionBar)），否则 ChatPageView 内部使用的 Material 控件会因缺少对应主题属性，在运行时直接 Crash。
说明：示例工程（demo）中提供了基于 ChatPageView 封装好的聊天页 ChatActivity（带标题栏、未读角标、群事件处理等），可直接复用或参考其实现进行自定义：ChatActivity.start(context, conversationID)。

步骤5：构建联系人界面

联系人界面使用 ContactsPageView 展示好友列表、群组列表等，通过 setup 设置点击回调。点击联系人或群组时跳转对应聊天界面。
import android.os.Bundle
import androidx.appcompat.app.AppCompatActivity
import io.trtc.tuikit.chat.uikit.pages.ContactsPageView

class ContactActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        val contactsPage = ContactsPageView(this)
        contactsPage.setHeaderTitle("通讯录")
        contactsPage.setup(
            onContactClick = { contactInfo ->
                // 跳转到您的聊天界面，单聊会话 ID 为 "c2c_" + contactInfo.userID（可参考步骤4 的 ChatActivity）
            },
            onGroupClick = { contactInfo ->
                // 跳转到您的聊天界面，群聊会话 ID 为 "group_" + contactInfo.userID（可参考步骤4 的 ChatActivity）
            }
        )
        setContentView(contactsPage)
    }
}

步骤6：主题设置（可选）

TUIKit 通过 ThemeStore 支持设置主题色与浅色 / 深色主题切换。
import io.trtc.tuikit.atomicx.theme.Theme
import io.trtc.tuikit.atomicx.theme.ThemeStore

// 设置主题色
ThemeStore.shared(context).setPrimaryColor("#1C66E5")

// 切换浅色 / 深色主题
ThemeStore.shared(context).setTheme(Theme.lightTheme(context))
// ThemeStore.shared(context).setTheme(Theme.darkTheme(context))

其他常见问题

表情包的使用
为尊重表情设计版权，Chat Demo/TUIKit 工程中不包含大表情元素切图，正式上线商用前请您替换为自己设计或拥有版权的其他表情包。下图所示默认的小黄脸表情包版权归腾讯云所有，您可以通过升级至 Chat 专业版 Plus 和企业版 免费使用该表情包。




联系我们

如果您在接入或使用过程有任何疑问或者建议，欢迎 联系我们 提交反馈。
上一篇: Flutter下一篇: Android（Compose）

帮助和支持

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

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

文档反馈