问卷反馈
功能简介
TUIKit 是基于 IM SDK 的 UI 组件库,可通过 UI 组件快速实现聊天、会话、搜索、关系链、群组等功能。本文介绍如何快速集成 TUIKit 并实现核心功能。
界面效果图
会话列表页 | 聊天页 | 音视频通话 |
![]() | ![]() | ![]() |
功能速览
功能类别 | 支持功能 |
聊天消息 | 单聊、群聊;文本、表情、图片、语音、视频、文件、合并转发消息、流式消息。 |
消息输入 | 文字输入、表情选择、拍照、录音、相册选择器、文件选择器、长按录音、实时语音转文字、群内 @、自定义消息。 |
消息交互 | 复制、删除、撤回、转发、引用回复、多选、表情回应、已读回执、正在输入状态。 |
会话管理 | 会话列表、置顶、免打扰、删除会话、清空历史消息、标记已读或未读、显示未读消息数、消息摘要。 |
好友与群组 | 好友列表、好友申请、备注、删除好友、黑名单;群资料、公告、成员与管理员管理、禁言、群主转让、入群审批、退群、解散群。 |
搜索 | 好友搜索、群聊搜索、消息搜索、指定会话内消息搜索。 |
智能能力 | 文本消息翻译;语音转文字、实时语音转文字;语音转文本、流式文本消息朗读、连续消息朗读;AI 助手聊天。 |
音视频通话 | 单人及多人音频 / 视频聊天。 |
集成
TUIKit 以源码方式开放集成。它提供会话列表、聊天、联系人、搜索、群组等完整 UI 能力。
说明:
前提条件
Xcode:16.0 或以上版本(推荐 Xcode 16.x 系列)。
iOS:14.0 及以上真机或者模拟器。
CocoaPods:1.12.0 及以上版本(推荐 1.16.x)。如尚未安装,请参考 CocoaPods Getting Started 进行安装。
一个有效的 Chat 应用。参考 快速跑通 Demo > 开通服务。
方式1:AI 集成
在项目根目录执行
npx @tencent-rtc/trtc-agent-skills add --ide <您的 IDE>,将 trtc-agent-skills 安装到您本地 AI IDE 中(<您的 IDE> 可替换为 cursor、codebuddy、claude、codex,或使用 all 安装全部),辅助完成 TUIKit 集成。安装后,您可以直接向 AI 输入“集成 iOS TUIChatKit”、“新增自定义消息类型”、“切换明暗主题” 或“修改聊天气泡布局等需求。AI 将根据项目类型引导您完成 TUIKit 的接入、接口调用、UI 定制、源码修改及问题排查等。详情可参考 AI Coding Skills。方式2:手动集成
步骤1:下载源码
# 从 CNB 中克隆代码git clone https://cnb.cool/tencent/cloud/trtc/TUIKit_iOS.git# 从 GitHub 中克隆代码git clone https://github.com/Tencent-RTC/TUIKit_iOS.git
2. 将仓库根目录下的
chat、call 文件夹整体复制到您的工程根目录下。复制完成后的目录结构如下:YourApplication/├── source/ # 您的工程代码├── call/ # 音视频通话组件│ └── TUICallKit_Swift.podspec│ └── TUICallKit_Swift/├── chat/ # Chat 源码│ ├── demo/ # 示例工程│ ├── demo_mini/ # 最小示例工程│ └── uikit/ # TUIChatKit 组件库├── Podfile # 依赖配置文件├── YourApplication.xcworkspace # 您的项目文件
说明:
TUIKit_iOS 是包含多个产品的开源仓库,Chat 的 UI 源码位于
chat/ 目录下(chat/uikit 为 UIKit 组件库,chat/demo 为示例工程),其依赖的音视频通话组件 call/TUICallKit_Swift 位于仓库根目录。模块目录可放在工程任意位置,只需在 Podfile 中设置正确的相对路径即可。chat/demo 和 chat/demo_mini 均为示例工程,不需要一并引入您的业务工程,可保留作为接入参考。3. 在 Podfile 中引入对应模块(请按源码实际存放位置调整相对路径)并且执行
pod install:# 请使用您的真实项目名称替换 your_project_nametarget 'your_project_name' do# 补充如下内容 增加 TUIChatKit 和 TUICallKit_Swift 这两个依赖# 注意 path 的相对路径pod 'TUIChatKit', :path => 'chat/uikit/TUIChatKit.podspec'pod 'TUICallKit_Swift', :path => 'call/TUICallKit_Swift.podspec'end
步骤2:开通服务及配置鉴权
开通服务
配置鉴权
鉴权方式一:服务端生成 UserSig(用于生产环境)
鉴权方式二:客户端生成测试 UserSig(仅用于开发测试)
1. 在 IM 控制台获取应用的
sdkAppID 和 secretKey。

2. 复制 Demo 中的
GenerateTestUserSig.swift 文件(CNB / GitHub),并设置 sdkAppID 和 secretKey,调用该文件中的 genTestUserSig 方法,为指定 UserID 生成 UserSig,用于 用户登录。禁止:
此方式仅用于开发测试。禁止在生产环境中将应用密钥写入客户端源码或打包到 App 中,以免造成密钥泄露。生产环境请使用服务端生成 UserSig 的方式。
步骤3:功能接入
完成上述集成后,参考以下步骤即可搭建会话列表、聊天、联系人等核心界面。
说明:
您可以参考 chat/demo_mini 最小示例工程,了解 TUIChatKit 主要模块的接入方式。相比完整 Demo,该工程更精简,便于阅读和参考。您也可以安装 AI Coding Skills,通过 AI 辅助完成接入。
1. 用户登录
登录鉴权后才能正常使用组件的功能。调用
LoginStore(CNB 用法 / GitHub 用法) 的 login 接口,传入上文获取的 sdkAppID、userID、userSig 进行登录鉴权:import AtomicXCoreimport TUIChatKitimport UIKitfunc login() {let yourSdkAppID: Int32 = 1_000_000_000 // 替换为实际 SDKAppIDlet testUserID = "testUserID" // 替换为测试用户 IDlet userSig = "xxxxxxx" // 该用户对应的测试 UserSig,从步骤2的控制台获取LoginStore.shared.login(sdkAppID: yourSdkAppID, userID: testUserID, userSig: userSig) { [weak self] result inDispatchQueue.main.async {switch result {case .success:self?.showConversationList()case .failure(let error):print("login failed: \\(error.code) \\(error.message)")}}}}
2. 构建会话列表界面
登录成功后(用户登录),即可展示会话列表。创建
ConversationsPage(CNB / GitHub),并将其 push 到导航控制器。当用户点击某条会话时,ConversationsPage 会通过 onConversationClick 回调,把所选会话的信息传递给上层,您可以在该回调中创建并进入聊天页(构建聊天界面)。import AtomicXCoreimport TUIChatKitimport UIKitfunc showConversationList() {let conversationsPage = ConversationsPage(config: nil, // 会话操作配置,nil 使用默认配置onConversationClick: { [weak self] info in // 会话或搜索结果点击回调,返回 NavigationInfoself?.showChat(info.conversation, locateMessage: info.locateMessage)})navigationController?.setNavigationBarHidden(true, animated: false)navigationController?.pushViewController(conversationsPage, animated: true)}
3. 构建聊天界面
聊天页由
ChatPage(CNB / GitHub) 承载,负责消息的展示与收发。构造 ChatPage 时必须传入一个 ConversationInfo,用于指定要进入的会话。其中 conversationID 与 type 是必填的关键字段,title 用于聊天页导航栏标题的初始展示。import AtomicXCoreimport TUIChatKitimport UIKit// 单聊入口,例如 showC2CChat(userID: "test_user")func showC2CChat(userID: String, title: String? = nil) {var conversation = ConversationInfo(conversationID: ChatUtil.getC2CConversationID(userID))conversation.type = .c2cconversation.title = title ?? userIDshowChat(conversation)}// 群聊入口,例如 showGroupChat(groupID: "@TGS#xxxxxx")func showGroupChat(groupID: String, title: String? = nil) {var conversation = ConversationInfo(conversationID: ChatUtil.getGroupConversationID(groupID))conversation.type = .groupconversation.title = title ?? groupIDshowChat(conversation)}func showChat(_ conversation: ConversationInfo,locateMessage: MessageInfo? = nil,) {let chatPage = ChatPage(conversation: conversation, // 目标会话信息,指定单聊或群聊locateMessage: locateMessage, // 要定位的消息,nil 不指定定位消息messageListConfig: nil, // 消息列表配置,nil 使用页面默认配置(显示右侧头像)messageInputConfig: nil, // 输入配置,nil 使用默认配置isShowMoreButton: false, // 是否显示更多按钮,示例未接入设置页,因此隐藏showsNavigationBar: true, // 是否显示组件自绘导航栏,不控制系统导航栏onBack: { [weak self] in // 返回按钮回调,需要接入方执行导航返回self?.navigationController?.popViewController(animated: true)},onUserClick: nil, // 用户头像点击回调,参数为用户 ID,nil 不打开资料页onMoreClick: nil // 更多按钮点击回调,nil 不打开设置页)navigationController?.setNavigationBarHidden(true, animated: false)navigationController?.pushViewController(chatPage, animated: true)}
配置项 | 属性类型 | 说明 |
isShowLeftAvatar | Bool | 是否显示左侧消息头像。默认 true。 |
isShowRightAvatar | Bool | 是否显示右侧消息头像。配置对象默认 false;ChatPage 未传列表配置时为 true。 |
isShowTimeMessage | Bool | 是否显示消息列表中的时间标签。默认 true。 |
isSupportCopy | Bool | 是否提供复制菜单,适用于可复制的文本消息。默认 true。 |
isSupportRecall | Bool | 是否提供撤回菜单;仍需满足本人发送、发送成功及撤回时限等条件。默认 true。 |
isSupportForward | Bool | 是否提供转发菜单;仍需满足消息可转发条件。默认 true。 |
isSupportQuote | Bool | 是否启用引用回复菜单及引用内容展示。默认 true。 |
isSupportMultiSelect | Bool | 是否提供消息多选菜单。默认 true。 |
isSupportTranslate | Bool | 是否提供文本翻译菜单;具体显示还取决于消息状态和译文状态。默认 true |
配置项 | 属性类型 | 说明 |
isShowAudioRecorder | Bool | 是否显示录音入口,允许切换语音输入模式。默认 true。 |
isShowPhotoTaker | Bool | 是否显示更多面板中的拍照与录视频入口。默认 true。 |
isShowMore | Bool | 是否允许显示输入框的更多按钮。默认 true。 |
isShowVideoCall | Bool | 是否显示输入面板中的视频通话入口。默认 true。 |
isShowAudioCall | Bool | 是否显示输入面板中的语音通话入口。默认 true。 |
enableMention | Bool | 是否启用群聊中的 @ 提及。默认 true。 |
enableTyping | Bool | 是否启用单聊的正在输入状态;页面显示还需列表配置中的 enableTyping 开启。默认 true。 |
enableReadReceipt | Bool | 发送消息时请求已读回执。默认为 false。 |
actionCustomizer | 增删、替换或调整更多面板菜单。默认 nil,使用内置菜单。 |
注意:
在聊天界面使用 相册/录像/视频通话等需要声明对应的权限,请在 App 的 Info.plist 中声明如下权限:
<key>NSCameraUsageDescription</key><string>需要访问您的相机权限,开启后才能发送图片或视频</string><key>NSMicrophoneUsageDescription</key><string>需要访问您的麦克风权限,开启后才能发送语音</string><key>NSPhotoLibraryAddUsageDescription</key><string>需要访问您的相册权限,开启后保存图片或视频</string><key>NSPhotoLibraryUsageDescription</key><string>需要访问您的相册权限,开启后才能发送图片或视频</string>
4. 构建联系人界面
import AtomicXCoreimport TUIChatKitimport UIKitfunc showContacts() {let contactsPage = ContactsPage(config: nil, // 联系人列表配置,nil 使用默认配置onContactClick: { [weak self] contact in // 好友点击回调,返回 ContactInfoself?.showC2CChat(userID: contact.userID, title: contact.nickname)},onGroupClick: { [weak self] group in // 群点击回调,返回 GroupInfoself?.showGroupChat(groupID: group.groupID, title: group.groupName)})navigationController?.setNavigationBarHidden(true, animated: false)navigationController?.pushViewController(contactsPage, animated: true)}
5. 音视频通话
5.1. 登录成功后初始化通话引擎
LoginStore 登录只建立了消息通道,在登录成功后,通话引擎需单独初始化:import RTCRoomEngineimport TUICallKit_Swiftfunc initCallEngine(sdkAppID: Int32, userID: String, userSig: String) {TUICallEngine.createInstance().`init`(sdkAppID, userId: userID, userSig: userSig) {DispatchQueue.main.async {TUICallKit.createInstance().enableIncomingBanner(enable: true)// 初始化成功后,可使用聊天输入面板的通话入口或调用 startVideoCall(userID:)。}} fail: { code, message inprint("initCallEngine failed: \\(code), \\(message ?? "")")}}
5.2. 发起通话
import TUICallKit_Swiftfunc startVideoCall(userID: String) {TUICallKit.createInstance().calls(userIdList: [userID], // 被叫用户 ID 列表,传一个为单人呼叫,传多个为多人呼叫mediaType: .video, // .video 视频通话,.audio 语音通话params: nil, // 默认呼叫参数,关联已有 IM 群时需设置 CallParams.chatGroupIdcompletion: { result in // 发起呼叫的结果回调,不是通话结束回调if case .failure(let error) = result {print("startVideoCall failed: \\(error.code), \\(error.message)")}})}
调用后 TUICallKit 会自动弹出全屏通话界面(含呼叫等待、接通、挂断全流程 UI),无需自行实现。
5.3 隐藏聊天输入面板中的通话入口
import AtomicXCoreimport TUIChatKitfunc showChatWithoutCallEntries(_ conversation: ConversationInfo) {let inputConfig = ChatMessageInputConfig(isShowVideoCall: false, // 隐藏输入面板中的视频通话入口isShowAudioCall: false // 隐藏输入面板中的语音通话入口)showChat(conversation, messageInputConfig: inputConfig)}
说明:
本文所有示例代码均来自 demo_mini 示例工程。demo_mini 是一个面向 TUIChatKit 接入演示的最小化工程,代码简洁易懂,可直接编译运行,方便开发者快速参考与上手。
AI 助手:知识咨询与代码集成
在接入 IM SDK 过程中,您可以通过 MCP 使用 AI 助手,快速完成知识咨询、报错排查和 UIKit 集成代码生成。支持 Web/Android/iOS/Flutter/uni-app 等平台,答案基于官方文档。适用于查询 SDK API、UI 组件用法、服务端 API 与 IM 产品配置等场景,立即体验,提出您的第一个问题。
常见问题
音视频常见问题
TUICallKit 和自己集成的音视频库冲突了?
腾讯云的音视频库不能同时集成,可能存在符号冲突,可以按照下面的场景处理。
1. 如果您使用了
TXLiteAVSDK_TRTC 库,不会发生符号冲突。可直接在 Podfile 文件中添加依赖,pod 'TUICallKit_Swift'
2. 如果您使用了
TXLiteAVSDK_Professional 库,会产生符号冲突。您可在 Podfile 文件中添加依赖,pod 'TUICallKit_Swift/Professional'
3. 如果您使用了
TXLiteAVSDK_Enterprise 库,会产生符号冲突。建议升级到 TXLiteAVSDK_Professional 后使用 TUICallKit_Swift/Professional。通话邀请的超时时间默认是多久?
通话邀请的默认超时时间是 30 秒。
在邀请超时时间内,被邀请者如果离线再上线,能否立即收到邀请?
如果是单聊通话邀请,被邀请者离线再上线可以收到通话邀请,TUIKit 内部会自动唤起通话邀请界面。
如果是群聊通话邀请,被邀请者离线再上线后会自动拉取最近 30 秒内的邀请,TUIKit 会自动唤起群通话界面。
上架常见问题
上架 App Store 时打包失败,提示 Unsupported Architectures?
问题现象如下图,打包时提示 ImSDK_Plus.framework 中包含了 App Store 不支持的 x86_64 模拟器版本。该问题是由于 IMSDK 为了方便开发者调试,发布时会默认带上模拟器版本。


您可以按照下面的步骤,在打包时去掉模拟器版本:
1. 选中您工程的 Target,并点击 Build Phases 选项,在当前面板中添加 Run Script;

2. 在新增的 Run Script 中,添加如下脚本:
#!/bin/sh# Strip invalid architecturesstrip_invalid_archs() {binary="$1"echo "current binary ${binary}"# Get architectures for current filearchs="$(lipo -info "$binary" | rev | cut -d ':' -f1 | rev)"stripped=""for arch in $archs; doif ! [[ "${ARCHS}" == *"$arch"* ]]; thenif [ -f "$binary" ]; then# Strip non-valid architectures in-placelipo -remove "$arch" -output "$binary" "$binary" || exit 1stripped="$stripped $arch"fifidoneif [[ "$stripped" ]]; thenecho "Stripped $binary of architectures:$stripped"fi}APP_PATH="${TARGET_BUILD_DIR}/${WRAPPER_NAME}"# This script loops through the frameworks embedded in the application and# removes unused architectures.find "$APP_PATH" -name '*.framework' -type d | while read -r FRAMEWORKdoFRAMEWORK_EXECUTABLE_NAME=$(defaults read "$FRAMEWORK/Info.plist" CFBundleExecutable)FRAMEWORK_EXECUTABLE_PATH="$FRAMEWORK/$FRAMEWORK_EXECUTABLE_NAME"echo "Executable is $FRAMEWORK_EXECUTABLE_PATH"strip_invalid_archs "$FRAMEWORK_EXECUTABLE_PATH"done

Xcode 集成常见问题
[Xcodeproj] Unknown object version (60). (RuntimeError)

使用 Xcode 15 创建新工程来集成 TUIKit 时,输入 pod install 后,可能会遇到此问题,原因是使用了较旧版本的 CocoaPods ,此时有两种解决办法:
解决方式一: 修改 Xcode 工程的 Project Format 版本。

解决方式二: 升级本地的 CocoaPods 版本,升级方式本文不再赘述。
您可以在终端输入
pod --version 查看当前的 Pods 版本。-ld64链接器问题?
Assertion failed: (false && "compact unwind compressed function offset doesn't fit in 24 bits"), function operator(), file Layout.cpp,

或是使用 Xcode 15 集成 TUIRoom 时,因最新链接器导致 TUIRoomEngine 的符号冲突,都属于该问题。

解决方式是:修改链接器配置

Rosetta 模拟器问题?
使用苹果芯片(M1\\M2等系列芯片)时会遇到, 原因是包括 SDWebImage 在内的三方库,并未支持 xcframework,不过苹果依旧给出了适配办法,就是在模拟器上开启 Rosetta 设置, 一般情况下编译时会自动弹出 Rosetta 选项。

Xcode 15 开发者沙盒选项问题?
Sandbox: bash(xxx) deny(1) file-write-create

当您使用 Xcode 15 创建一个新工程时, 可能会因为此选项导致编译运行失败,建议您关闭此选项。

Xcode 16 不支持 Framework 开启 bitcode 问题?
解决方案1:升级 SDK
如果您使用的是包含 Bitcode 的旧版本 SDK(例如 TXIMSDK_iOS),建议您按照本文档的指引,将 SDK 升级至 TXIMSDK_Plus_iOS_XCFramework。
解决方式2: 修改 Podfile 配置
在您的 Podfile 末尾新增如下配置,重新 Pod install。
post_install do |installer|bitcode_strip_path = 'xcrun --find bitcode_strip'.chop!def strip_bitcode_from_framework(bitcode_strip_path, framework_relative_path)framework_path = File.join(Dir.pwd, framework_relative_path)command = "#{bitcode_strip_path} #{framework_path} -r -o #{framework_path}"puts "Stripping bitcode: #{command}"system(command)endframework_paths = ["/Pods/TXIMSDK_iOS/ImSDK.framework/ImSDK",]framework_paths.each do |framework_relative_path|strip_bitcode_from_framework(bitcode_strip_path, framework_relative_path)endend
CocoaPods 集成常见问题
若您执行 pod install,出现 Podfile.lock 和 插件依赖的版本不一致时,
此时请删除 Podfile.lock 文件, 并使用 pod repo update 更新本地代码仓库, 之后使用 pod update 重新更新即可。
其他常见问题
表情包的使用
为了尊重版权,IM Demo/TUIKit 工程中默认不包含大表情元素切图。正式上线商用前请您替换为自己设计或拥有版权的其他表情包。下图所示默认的小黄脸表情包版权归腾讯云所有,可有偿授权使用,如需获得授权,您可以通过升级至 IM 企业版套餐 免费使用该表情包。




