帮你快速理解、总结文档立即下载

单聊天组件

最近更新时间:2026-11-12 11:09:11
我的收藏
本文介绍如何使用 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:用户登录

登录成功后才能使用组件。请在登录成功的回调中再进入聊天界面。
Android(View)
Android(Compose)
iOS(UIKit)
iOS(SwiftUI)
Flutter
HarmonyOS
Vue3
uni-app
import io.trtc.tuikit.atomicxcore.api.CompletionHandler
import io.trtc.tuikit.atomicxcore.api.login.LoginStore

LoginStore.shared.login(
context,
sdkAppID, // Int,控制台获取
userID, // String,当前用户 ID
userSig, // String,当前用户的 UserSig
object : CompletionHandler {
override fun onSuccess() {
// 登录成功,进入聊天界面(步骤2)
}

override fun onFailure(code: Int, desc: String) {
// 登录失败
}
}
)
import io.trtc.tuikit.atomicxcore.api.CompletionHandler
import io.trtc.tuikit.atomicxcore.api.login.LoginStore

LoginStore.shared.login(
context,
sdkAppID, // Int,控制台获取
userID, // String,当前用户 ID
userSig, // String,当前用户的 UserSig
object : CompletionHandler {
override fun onSuccess() {
// 登录成功,进入聊天界面(步骤2)
}

override fun onFailure(code: Int, desc: String) {
// 登录失败
}
}
)

import AtomicXCore

LoginStore.shared.login(sdkAppID: sdkAppID, userID: userID, userSig: userSig) { result in
DispatchQueue.main.async {
switch result {
case .success:
// 登录成功,进入聊天界面(步骤2)
break
case .failure(let error):
print("login failed: \\(error.code) \\(error.message)")
}
}
}
import AtomicXCore

LoginStore.shared.login(sdkAppID: sdkAppID, userID: userID, userSig: userSig) { result in
DispatchQueue.main.async {
switch result {
case .success:
// 登录成功,进入聊天界面(步骤2)
break
case .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) => {
// 登录失败
},
});
注意:
正式环境中,请在您的服务端生成 UserSig,由 App 向业务服务器请求获取,不要把 SDKSecretKey 写入客户端。详见 服务端生成 UserSig。

步骤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。
Android(View)
Android(Compose)
iOS(UIKit)
iOS(SwiftUI)
Flutter
HarmonyOS
Vue3
uni-app
1. 新建布局文件 activity_chat.xml,放入 MessageListView 和 MessageInputView:
<?xml version="1.0" encoding="utf-8"?>
<androidx.constraintlayout.widget.ConstraintLayout
xmlns: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.Toolbar
android: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.MessageListView
android: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.MessageInputView
android: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:
<activity
android:name=".ChatActivity"
android:exported="false"
android:theme="@style/Chat_UIKit_Theme" />
3. 在 Activity 中为两个组件设置同一个会话 ID:
import android.os.Bundle
import androidx.appcompat.app.AppCompatActivity
import androidx.appcompat.widget.Toolbar
import io.trtc.tuikit.chat.uikit.components.messageinput.ui.MessageInputView
import io.trtc.tuikit.chat.uikit.components.messagelist.ui.MessageListView

class 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.Column
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.systemBarsPadding
import androidx.compose.runtime.Composable
import androidx.compose.ui.Modifier
import io.trtc.tuikit.chat.uikit.components.messageinput.ui.MessageInput
import io.trtc.tuikit.chat.uikit.components.messagelist.ui.MessageList
import io.trtc.tuikit.chat.uikit.pages.ChatHeader

@Composable
fun 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 UIKit
import SnapKit
import TUIChatKit

class 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 in
make.leading.trailing.bottom.equalToSuperview()
}
// 消息列表:占满输入框上方的剩余空间
messageListView.snp.makeConstraints { make in
make.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 SwiftUI
import TUIChatKit_Swift

struct 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;

@override
Widget build(BuildContext context) {
return Scaffold(
// 标题栏:AppBar 会自带返回键,标题处填写对方名称
appBar: AppBar(title: const Text('userB')),
body: Column(
children: [
// 消息列表:自身已占满剩余空间,无需再包 Expanded
MessageList(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
@Component
struct 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" />

<!-- 消息列表:为输入框预留底部空间 -->
<view
class="message-list-container"
:style="{ paddingBottom: inputToolbarHeight + 'px' }"
@tap="collapseInput"
>
<MessageList
:conversationID="conversationID"
:inputToolbarHeight="inputToolbarHeight"
:inputPanelHeight="inputPanelHeight"
@onMessageListTap="collapseInput"
/>
</view>

<!-- 消息输入:高度变化时通知消息列表 -->
<MessageInput
ref="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 均支持通过配置项调整,例如隐藏语音、拍照入口。
需要会话列表、联系人、群聊管理等完整功能:请参考 全功能接入 文档。