本文介绍如何使用 Chat UIKit 的 MessageList(消息列表)和 MessageInput(消息输入)两个组件,上下拼接成一个完整的聊天界面,实现消息的展示与收发。适用于客服咨询、订单详情页私聊、App 内嵌聊天窗口等“只需要一个聊天窗口”的场景。

前提条件
1. 已开通即时通信 IM,并在控制台获取 SDKAppID。
2. 准备两个 UserID(例如
userA、userB),并在 即时通信 IM 控制台 生成对应的 UserSig,用于调试。3.
已参考各平台
“全功能接入”文档,完成 Chat UIKit 的集成(下载源码、引入组件):平台 | 集成文档 |
Android(View) | |
Android(Compose) | |
iOS(UIKit) | |
iOS(SwiftUI) | |
Flutter | |
HarmonyOS | |
Vue3 | |
uni-app |
步骤1:用户登录
登录成功后才能使用组件。请在登录成功的回调中再进入聊天界面。
import io.trtc.tuikit.atomicxcore.api.CompletionHandlerimport io.trtc.tuikit.atomicxcore.api.login.LoginStoreLoginStore.shared.login(context,sdkAppID, // Int,控制台获取userID, // String,当前用户 IDuserSig, // String,当前用户的 UserSigobject : CompletionHandler {override fun onSuccess() {// 登录成功,进入聊天界面(步骤2)}override fun onFailure(code: Int, desc: String) {// 登录失败}})
import io.trtc.tuikit.atomicxcore.api.CompletionHandlerimport io.trtc.tuikit.atomicxcore.api.login.LoginStoreLoginStore.shared.login(context,sdkAppID, // Int,控制台获取userID, // String,当前用户 IDuserSig, // String,当前用户的 UserSigobject : CompletionHandler {override fun onSuccess() {// 登录成功,进入聊天界面(步骤2)}override fun onFailure(code: Int, desc: String) {// 登录失败}})
import AtomicXCoreLoginStore.shared.login(sdkAppID: sdkAppID, userID: userID, userSig: userSig) { result inDispatchQueue.main.async {switch result {case .success:// 登录成功,进入聊天界面(步骤2)breakcase .failure(let error):print("login failed: \\(error.code) \\(error.message)")}}}
import AtomicXCoreLoginStore.shared.login(sdkAppID: sdkAppID, userID: userID, userSig: userSig) { result inDispatchQueue.main.async {switch result {case .success:// 登录成功,进入聊天界面(步骤2)breakcase .failure(let error):print("login failed: \\(error.code) \\(error.message)")}}}
import 'package:atomic_x_core/atomicxcore.dart';final result = await LoginStore.shared.login(sdkAppID: sdkAppID,userID: userID,userSig: userSig,);if (result.errorCode == 0) {// 登录成功,进入聊天界面(步骤2)} else {// 登录失败}
import { LoginStore } from '@tencentcloud/atomicxcore';LoginStore.shared().login(sdkAppID, userID, userSig, getContext()).then(() => {// 登录成功,进入聊天界面(步骤2)}).catch((error: Object) => {// 登录失败});
import { ref } from 'vue';import { useLoginState } from '@tencentcloud/chat-uikit-vue3';const { login } = useLoginState();const isLoggedIn = ref(false);login({sdkAppId: 0, // SDKAppID,number 类型userId: '', // UserID,string 类型userSig: '', // UserSig,string 类型}).then(() => {// 登录成功后再渲染聊天组件(步骤2),避免登录前调用接口isLoggedIn.value = true;});
import { useLoginState } from '@/uni_modules/tuikit-atomic-x/state/LoginState';const { login } = useLoginState();login({sdkAppID: 0, // SDKAppID,number 类型userID: '', // UserID,string 类型userSig: '', // UserSig,string 类型success: () => {// 登录成功,进入聊天界面(步骤2)},fail: (code: number, message: string) => {// 登录失败},});
注意:
步骤2:拼装聊天界面
一个完整的聊天界面由三部分从上到下组成:标题栏(返回键和会话标题)、MessageList(占满剩余空间)、MessageInput(固定在底部)。其中 MessageList 和 MessageInput 传入同一个会话 ID 即可。
说明:
标题栏不属于 MessageList 和 MessageInput,下方示例使用各平台最简单的标题栏实现。UIKit 提供的
ChatPage 页面在此基础上还内置了未读角标、更多按钮、多选模式等,如需这些功能可直接使用 ChatPage,或参考其源码实现。会话 ID 的格式如下:
会话类型 | 会话 ID | 示例 |
单聊 | c2c_<对方 UserID> | c2c_userB |
群聊 | group_<群 GroupID> | group_group1 |
说明:
Vue3 的会话 ID 格式为
C2C<对方 UserID> / GROUP<群 GroupID>,例如 C2CuserB。1. 新建布局文件
activity_chat.xml,放入 MessageListView 和 MessageInputView:<?xml version="1.0" encoding="utf-8"?><androidx.constraintlayout.widget.ConstraintLayoutxmlns:android="http://schemas.android.com/apk/res/android"xmlns:app="http://schemas.android.com/apk/res-auto"android:layout_width="match_parent"android:layout_height="match_parent"android:fitsSystemWindows="true"><!-- 标题栏 --><androidx.appcompat.widget.Toolbarandroid:id="@+id/title_bar"android:layout_width="0dp"android:layout_height="?attr/actionBarSize"android:background="#FFFFFF"app:layout_constraintTop_toTopOf="parent"app:layout_constraintStart_toStartOf="parent"app:layout_constraintEnd_toEndOf="parent" /><io.trtc.tuikit.chat.uikit.components.messagelist.ui.MessageListViewandroid:id="@+id/message_list"android:layout_width="0dp"android:layout_height="0dp"app:layout_constraintTop_toBottomOf="@id/title_bar"app:layout_constraintBottom_toTopOf="@id/message_input"app:layout_constraintStart_toStartOf="parent"app:layout_constraintEnd_toEndOf="parent" /><io.trtc.tuikit.chat.uikit.components.messageinput.ui.MessageInputViewandroid:id="@+id/message_input"android:layout_width="0dp"android:layout_height="wrap_content"app:layout_constraintBottom_toBottomOf="parent"app:layout_constraintStart_toStartOf="parent"app:layout_constraintEnd_toEndOf="parent" /></androidx.constraintlayout.widget.ConstraintLayout>
2. 在
AndroidManifest.xml 中注册 Activity,并使用 UIKit 提供的主题 Chat_UIKit_Theme:<activityandroid:name=".ChatActivity"android:exported="false"android:theme="@style/Chat_UIKit_Theme" />
3. 在 Activity 中为两个组件设置同一个会话 ID:
import android.os.Bundleimport androidx.appcompat.app.AppCompatActivityimport androidx.appcompat.widget.Toolbarimport io.trtc.tuikit.chat.uikit.components.messageinput.ui.MessageInputViewimport io.trtc.tuikit.chat.uikit.components.messagelist.ui.MessageListViewclass ChatActivity : AppCompatActivity() {override fun onCreate(savedInstanceState: Bundle?) {super.onCreate(savedInstanceState)setContentView(R.layout.activity_chat)val conversationID = "c2c_userB" // 单聊:c2c_<对方 UserID>// 标题栏:显示对方名称,点击返回键关闭页面findViewById<Toolbar>(R.id.title_bar).apply {title = "userB"setNavigationIcon(androidx.appcompat.R.drawable.abc_ic_ab_back_material)setNavigationOnClickListener { finish() }}findViewById<MessageListView>(R.id.message_list).setup(conversationID = conversationID)findViewById<MessageInputView>(R.id.message_input).setup(conversationID = conversationID)}}
import androidx.compose.foundation.layout.Columnimport androidx.compose.foundation.layout.fillMaxSizeimport androidx.compose.foundation.layout.systemBarsPaddingimport androidx.compose.runtime.Composableimport androidx.compose.ui.Modifierimport io.trtc.tuikit.chat.uikit.components.messageinput.ui.MessageInputimport io.trtc.tuikit.chat.uikit.components.messagelist.ui.MessageListimport io.trtc.tuikit.chat.uikit.pages.ChatHeader@Composablefun ChatScreen(conversationID: String, // 单聊:c2c_<对方 UserID>title: String, // 标题栏显示的会话名称onBackClick: () -> Unit) {Column(modifier = Modifier.fillMaxSize().systemBarsPadding()) {// 标题栏:返回键 + 会话名称ChatHeader(name = title, onBackClick = onBackClick)// 消息列表:占满剩余空间MessageList(conversationID = conversationID,modifier = Modifier.weight(1f))// 消息输入:固定在底部MessageInput(conversationID = conversationID)}}
import UIKitimport SnapKitimport TUIChatKitclass ChatViewController: UIViewController {private let conversationID = "c2c_userB" // 单聊:c2c_<对方 UserID>private lazy var messageListView = MessageListView(conversationID: conversationID)private lazy var messageInputView = MessageInputView(conversationID: conversationID)override func viewDidLoad() {super.viewDidLoad()view.backgroundColor = .systemBackground// 标题栏:使用系统导航栏,需通过 UINavigationController push 进入本页面title = "userB"view.addSubview(messageListView)view.addSubview(messageInputView)// 消息输入:固定在底部,高度由组件自身决定messageInputView.snp.makeConstraints { make inmake.leading.trailing.bottom.equalToSuperview()}// 消息列表:占满输入框上方的剩余空间messageListView.snp.makeConstraints { make inmake.top.equalTo(view.safeAreaLayoutGuide)make.leading.trailing.equalToSuperview()make.bottom.equalTo(messageInputView.snp.top)}}override func viewDidLayoutSubviews() {super.viewDidLayoutSubviews()// 让输入框避开底部安全区messageInputView.bottomSafeAreaInset = view.safeAreaInsets.bottom}override func viewWillAppear(_ animated: Bool) {super.viewWillAppear(animated)messageListView.hostVisibilityDidChange(true)}override func viewWillDisappear(_ animated: Bool) {super.viewWillDisappear(animated)messageListView.hostVisibilityDidChange(false)}}
import SwiftUIimport TUIChatKit_Swiftstruct ChatView: View {let conversationID: String // 单聊:c2c_<对方 UserID>var body: some View {VStack(spacing: 0) {// 消息列表:占满剩余空间MessageListView(conversationID: conversationID)// 消息输入:固定在底部MessageInputView(conversationID: conversationID)}.ignoresSafeArea(.keyboard)// 标题栏:使用系统导航栏,需在 NavigationView 中进入本页面.navigationTitle("userB").navigationBarTitleDisplayMode(.inline)}}
import 'package:flutter/material.dart';import 'package:tencent_chat_uikit/tencent_chat_uikit.dart';class ChatPage extends StatelessWidget {const ChatPage({super.key, required this.conversationID}); // 单聊:c2c_<对方 UserID>final String conversationID;@overrideWidget build(BuildContext context) {return Scaffold(// 标题栏:AppBar 会自带返回键,标题处填写对方名称appBar: AppBar(title: const Text('userB')),body: Column(children: [// 消息列表:自身已占满剩余空间,无需再包 ExpandedMessageList(conversationID: conversationID),// 消息输入:固定在底部MessageInput(conversationID: conversationID),],),);}}
import { MessageList } from '@tencentcloud/atomicx/src/main/ets/messagelist/Index';import { MessageInput } from '@tencentcloud/atomicx/src/main/ets/messageinput/Index';@Entry@Componentstruct ChatPage {private conversationID: string = 'c2c_userB'; // 单聊:c2c_<对方 UserID>build() {Column() {// 标题栏:显示对方名称Text('userB').width('100%').height(56).fontSize(18).fontWeight(FontWeight.Medium).textAlign(TextAlign.Center)// 消息列表:占满剩余空间MessageList({ conversationID: this.conversationID }).width('100%').layoutWeight(1)// 消息输入:固定在底部MessageInput({ conversationID: this.conversationID })}.width('100%').height('100%').expandSafeArea([SafeAreaType.SYSTEM], [SafeAreaEdge.BOTTOM])}}
<template><UIKitProvider language="zh-CN" theme="light"><div v-if="isLoggedIn" class="chat-container"><Chat :conversationID="conversationID"><ChatHeader /><MessageList /><MessageInput /></Chat></div></UIKitProvider></template><script setup lang="ts">import { Chat, ChatHeader, MessageList, MessageInput, UIKitProvider } from '@tencentcloud/chat-uikit-vue3';// isLoggedIn 为步骤1中登录成功后置为 true 的状态,请与登录代码放在同一个组件中// 单聊:C2C<对方 UserID>const conversationID = 'C2CuserB';</script><style scoped>.chat-container {display: flex;height: 100vh;}</style>
注意:
TUIKit 的组件为 nvue 组件,使用组件的页面必须是
.nvue 文件。<template><view class="page-container"><!-- 标题栏:返回键 + 会话名称 --><CustomNavbar position="fixed" title="userB" :showBack="true" @back="onBack" /><!-- 消息列表:为输入框预留底部空间 --><viewclass="message-list-container":style="{ paddingBottom: inputToolbarHeight + 'px' }"@tap="collapseInput"><MessageList:conversationID="conversationID":inputToolbarHeight="inputToolbarHeight":inputPanelHeight="inputPanelHeight"@onMessageListTap="collapseInput"/></view><!-- 消息输入:高度变化时通知消息列表 --><MessageInputref="messageInputRef":conversationID="conversationID"@height-change="onInputHeightChange"/></view></template><script setup lang="ts">import { ref } from 'vue';import MessageList from '@/uni_modules/tuikit-atomic-x/components/MessageList/MessageList.nvue';import MessageInput from '@/uni_modules/tuikit-atomic-x/components/MessageInput/MessageInput.nvue';import CustomNavbar from '@/uni_modules/tuikit-atomic-x/components/CustomNavbar/CustomNavbar.nvue';const conversationID = 'c2c_userB'; // 单聊:c2c_<对方 UserID>const messageInputRef = ref(null);const inputToolbarHeight = ref(0);const inputPanelHeight = ref(0);const onInputHeightChange = ({ inputToolbarHeight: toolbar, inputPanelHeight: panel }) => {inputToolbarHeight.value = toolbar;inputPanelHeight.value = panel;};const collapseInput = () => messageInputRef.value?.collapse();const onBack = () => uni.navigateBack();</script><style>.page-container {flex: 1;flex-direction: column;}.message-list-container {flex: 1;flex-direction: column;}</style>
步骤3:发送您的第一条消息
1. 在设备 A 使用
userA 登录,示例中的会话 ID 为 c2c_userB(Vue3 为 C2CuserB),输入文字并发送。2. 在设备 B 使用
userB 登录,将示例中的会话 ID 改为 c2c_userA(Vue3 为 C2CuserA),即可看到收到的消息。说明:
IM 账号在首次登录时自动创建。向对方发送消息前,请确保对方账号至少登录过一次,否则消息会因对方账号不存在而发送失败。

更多能力
调整样式和功能入口:
MessageList、MessageInput 均支持通过配置项调整,例如隐藏语音、拍照入口。需要会话列表、联系人、群聊管理等完整功能:请参考 全功能接入 文档。