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

iOS(UIKit)

最近更新时间:2026-11-16 15:45:31
本文档已由 AI 辅助审校
我的收藏

问卷反馈

花 30 秒,帮 iOS TUIKit 变得更好用!
正在接入、已经跑通、还是卡住了?都欢迎您填写 iOS TUIKit 接入体验问卷。
您的每一条卡点反馈和改进建议,官方都会及时跟进处理。

功能简介

TUIKit 是基于 IM SDK 的 UI 组件库,可通过 UI 组件快速实现聊天、会话、搜索、关系链、群组等功能。本文介绍如何快速集成 TUIKit 并实现核心功能。

界面效果图

会话列表页
聊天页
音视频通话






功能速览

功能类别
支持功能
聊天消息
单聊、群聊;文本、表情、图片、语音、视频、文件、合并转发消息、流式消息。
消息输入
文字输入、表情选择、拍照、录音、相册选择器、文件选择器、长按录音、实时语音转文字、群内 @、自定义消息。
消息交互
复制、删除、撤回、转发、引用回复、多选、表情回应、已读回执、正在输入状态。
会话管理
会话列表、置顶、免打扰、删除会话、清空历史消息、标记已读或未读、显示未读消息数、消息摘要。
好友与群组
好友列表、好友申请、备注、删除好友、黑名单;群资料、公告、成员与管理员管理、禁言、群主转让、入群审批、退群、解散群。
搜索
好友搜索、群聊搜索、消息搜索、指定会话内消息搜索。
智能能力
文本消息翻译;语音转文字、实时语音转文字;语音转文本、流式文本消息朗读、连续消息朗读;AI 助手聊天。
音视频通话
单人及多人音频 / 视频聊天。

集成

TUIKit 以源码方式开放集成。它提供会话列表、聊天、联系人、搜索、群组等完整 UI 能力。
说明:
IM 在 CNB 及 GitHub 上提供即时通信完整 Demo,5 分钟跑通聊天 + 音视频通话全功能。

前提条件

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:下载源码

1. 从 CNB 或者 GitHub 克隆 TUIKit iOS 源码:
# 从 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_name
target '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:开通服务及配置鉴权

开通服务
登录 即时通信 IM 控制台。在应用管理页面,单击创建新应用。参看快速跑通 Demo > 开通服务。
配置鉴权
鉴权方式一:服务端生成 UserSig(用于生产环境)
在生产环境中,请在业务服务端生成 UserSig,并由 App 在登录时向业务服务端请求获取。具体实现请参见 服务端生成 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 进行登录鉴权:
Swift
import AtomicXCore
import TUIChatKit
import UIKit

func login() {
let yourSdkAppID: Int32 = 1_000_000_000 // 替换为实际 SDKAppID
let testUserID = "testUserID" // 替换为测试用户 ID
let userSig = "xxxxxxx" // 该用户对应的测试 UserSig,从步骤2的控制台获取

LoginStore.shared.login(sdkAppID: yourSdkAppID, userID: testUserID, userSig: userSig) { [weak self] result in
DispatchQueue.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 回调,把所选会话的信息传递给上层,您可以在该回调中创建并进入聊天页(构建聊天界面)。
Swift
import AtomicXCore
import TUIChatKit
import UIKit

func showConversationList() {
let conversationsPage = ConversationsPage(
config: nil, // 会话操作配置,nil 使用默认配置
onConversationClick: { [weak self] info in // 会话或搜索结果点击回调,返回 NavigationInfo
self?.showChat(info.conversation, locateMessage: info.locateMessage)
}
)
navigationController?.setNavigationBarHidden(true, animated: false)
navigationController?.pushViewController(conversationsPage, animated: true)
}
会话配置: ConversationActionConfig(CNB / GitHub)
配置项
属性类型
说明
isSupportDelete
Bool
是否提供删除会话操作。默认 true
isSupportMute
Bool
是否提供消息免打扰操作。默认 true。
isSupportPin
Bool
是否提供置顶或取消置顶操作。默认 true。
isSupportMarkUnread
Bool
是否提供标记未读操作。默认 true。
isSupportClearHistory
Bool
是否提供清空聊天记录操作。默认 true。
actionCustomizer
ConversationActionCustomizer?(CNB / GitHub)
增删、替换或调整会话操作菜单。默认 nil,不额外定制菜单。
3. 构建聊天界面
聊天页由 ChatPage(CNB / GitHub) 承载,负责消息的展示与收发。构造 ChatPage 时必须传入一个 ConversationInfo,用于指定要进入的会话。其中 conversationID 与 type 是必填的关键字段,title 用于聊天页导航栏标题的初始展示。
Swift
import AtomicXCore
import TUIChatKit
import UIKit

// 单聊入口,例如 showC2CChat(userID: "test_user")
func showC2CChat(userID: String, title: String? = nil) {
var conversation = ConversationInfo(conversationID: ChatUtil.getC2CConversationID(userID))
conversation.type = .c2c
conversation.title = title ?? userID
showChat(conversation)
}

// 群聊入口,例如 showGroupChat(groupID: "@TGS#xxxxxx")
func showGroupChat(groupID: String, title: String? = nil) {
var conversation = ConversationInfo(conversationID: ChatUtil.getGroupConversationID(groupID))
conversation.type = .group
conversation.title = title ?? groupID
showChat(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)
}
消息列表配置
消息输入配置
ChatMessageListConfig 用于消息配置,部分配置如下表格,完整配置请参看 MessageListConfig.swift(CNB / GitHub)。
配置项
属性类型
说明
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
ChatMessageInputConfig 用于消息配置,部分配置如下表格,完整配置请参看 MessageInputConfig.swift(CNB / GitHub)。
配置项
属性类型
说明
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
MessageInputActionCustomizer?(CNB / GitHub)
增删、替换或调整更多面板菜单。默认 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. 构建联系人界面
联系人页由 ContactsPage(CNB / GitHub) 承载,展示按字母索引分组的好友列表,并提供群列表入口。
Swift
import AtomicXCore
import TUIChatKit
import UIKit

func showContacts() {
let contactsPage = ContactsPage(
config: nil, // 联系人列表配置,nil 使用默认配置
onContactClick: { [weak self] contact in // 好友点击回调,返回 ContactInfo
self?.showC2CChat(userID: contact.userID, title: contact.nickname)
},
onGroupClick: { [weak self] group in // 群点击回调,返回 GroupInfo
self?.showGroupChat(groupID: group.groupID, title: group.groupName)
}
)
navigationController?.setNavigationBarHidden(true, animated: false)
navigationController?.pushViewController(contactsPage, animated: true)
}
5. 音视频通话
音视频通话能力由 TUICallKit(CNB / GitHub)(TUICallKit_Swift 组件)提供(Podfile 中需添加 pod 'TUICallKit_Swift')。
开通音视频通话服务,请参考 开通音视频服务。
5.1. 登录成功后初始化通话引擎
LoginStore 登录只建立了消息通道,在登录成功后,通话引擎需单独初始化:
使用 TUICallEngine(CNB 用法 / GitHub 用法) 初始化通话引擎。
Swift

import RTCRoomEngine
import TUICallKit_Swift

func 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 in
print("initCallEngine failed: \\(code), \\(message ?? "")")
}
}

5.2. 发起通话
calls 的 params 使用可选的 CallParams(CNB / GitHub),用于设置呼叫扩展参数。
Swift
import TUICallKit_Swift

func startVideoCall(userID: String) {
TUICallKit.createInstance().calls(
userIdList: [userID], // 被叫用户 ID 列表,传一个为单人呼叫,传多个为多人呼叫
mediaType: .video, // .video 视频通话,.audio 语音通话
params: nil, // 默认呼叫参数,关联已有 IM 群时需设置 CallParams.chatGroupId
completion: { result in // 发起呼叫的结果回调,不是通话结束回调
if case .failure(let error) = result {
print("startVideoCall failed: \\(error.code), \\(error.message)")
}
}
)
}
调用后 TUICallKit 会自动弹出全屏通话界面(含呼叫等待、接通、挂断全流程 UI),无需自行实现。
5.3 隐藏聊天输入面板中的通话入口
ChatPage 默认集成了音视频通话功能,如果你不需要音视频通话功能。可以在 步骤 4 创建聊天界面 中关闭音视频通话开关,代码如下所示:
Swift
import AtomicXCore
import TUIChatKit

func 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 architectures
strip_invalid_archs() {
binary="$1"
echo "current binary ${binary}"
# Get architectures for current file
archs="$(lipo -info "$binary" | rev | cut -d ':' -f1 | rev)"
stripped=""
for arch in $archs; do
if ! [[ "${ARCHS}" == *"$arch"* ]]; then
if [ -f "$binary" ]; then
# Strip non-valid architectures in-place
lipo -remove "$arch" -output "$binary" "$binary" || exit 1
stripped="$stripped $arch"
fi
fi
done
if [[ "$stripped" ]]; then
echo "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 FRAMEWORK
do
FRAMEWORK_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 的符号冲突,都属于该问题。

解决方式是:修改链接器配置
在 Build Settings 中的 Other Linker Flags 中添加"-ld64",即可解决。点击查看参考资料。


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)
end
framework_paths = [
"/Pods/TXIMSDK_iOS/ImSDK.framework/ImSDK",
]
framework_paths.each do |framework_relative_path|
strip_bitcode_from_framework(bitcode_strip_path, framework_relative_path)
end
end

CocoaPods 集成常见问题

若您执行 pod install,出现 Podfile.lock 和 插件依赖的版本不一致时,
此时请删除 Podfile.lock 文件, 并使用 pod repo update 更新本地代码仓库, 之后使用 pod update 重新更新即可。

其他常见问题

表情包的使用

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




联系我们

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