TUIKit 是一款基于腾讯云 IM SDK 和 UTS 原生渲染技术的 uni-app UI 组件库，流畅度远超传统 Webview 方案，提供了一系列通用的 UI 组件，涵盖会话、聊天、群组、音视频通话等核心功能。基于这些精心设计的 UI 组件，您可以快速构建优雅、可靠、可扩展的即时通讯应用。
核心的聊天页面我们使用了原生动画模块，对每一个关键结构单独处理位置计算，带来更加流畅的聊天体验。
关键概念
原生渲染：基于 UTS 技术直接编译为 Kotlin/Swift 原生代码，流畅度远超 Webview 方案。
开源免费：插件源码以 uni_modules 形式开放，UI 样式、交互逻辑均可直接修改，无需二次封装。配套 GitHub Demo 开箱即用。
前提条件
IDE： HBuilderX 版本 ≥ 4.66。
Vue 版本： Vue3。
支持平台： 仅支持打包为 Android / iOS App，不支持 H5 和小程序。
说明：
Vue2、H5 和小程序项目，如有需要请参考以下替代方案：
Vue2 打包 App。 可参考：chat-uikit-uniapp。
Vue3/Vue2 打包 H5。 可参考：chat-uikit-uniapp。
Vue3/Vue2 打包小程序。可参考：uni-app 完整版（Vue3/Vue2）。
接入过程中遇到任何卡点或有改进建议，欢迎通过 UniApp Atomicx 接入体验反馈 告诉我们，我们会及时跟进处理。
集成步骤
步骤1：创建项目
打开 HBuilderX，在菜单栏中选择 “文件 > 新建 > 项目”，创建一个名为
chat-example 的 uni-app 项目。
步骤2：安装 TUIKit 插件
步骤3：配置原生模块与 Android 权限
说明：
Camera 和 VideoPlayer 模块用于聊天中的拍照和视频播放功能。Android 权限用于录音、网络访问和文件存储。1. 模块配置。点击
manifest.json > 点击安卓/iOS模块配置 > 勾选 Camera&Gallery（相机和相册）和 VideoPlayer（视频播放）。如图所示：
2. 配置 Android 相关权限。点击
manifest.json> 点击安卓/iOS权限配置 > Android 云打包配置中配置如下权限。如图所示：<uses-permission android:name="android.permission.RECORD_AUDIO" /><uses-permission android:name="android.permission.INTERNET" /><uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
步骤4：集成 TUIKit
1. 拷贝 TUIKit 页面 && 静态资源：将
uni_modules/tuikit-atomic-x/quickstart/下的pages/*拷贝到项目 page 目录，static/*拷贝到项目 static 目录下。cp -r uni_modules/tuikit-atomic-x/quickstart/static/* static/ && cp -r uni_modules/tuikit-atomic-x/quickstart/pages/* pages/
xcopy /E /I /Y "uni_modules\\tuikit-atomic-x\\quickstart\\static\\*" "static\\" && xcopy /E /I /Y "uni_modules\\tuikit-atomic-x\\quickstart\\pages\\*" "pages\\"
2. 配置页面路由：替换
pages.json 内容，注册所需页面路由：{"pages": [{"path": "pages/login/login","style": {"navigationStyle": "custom"}},{"path": "pages/index/index","style": {"navigationStyle": "custom"}},{"path": "pages/scenes/chat/conversationList/conversationList","style": {"navigationStyle": "custom","backgroundColor": "#f5f5f5"}},{"path": "pages/scenes/chat/chat/index","style": {"navigationStyle": "custom","backgroundColor": "#f5f5f5","app-plus": {"titleNView": false}}},{"path": "pages/scenes/chat/chatSetting/index","style": {"navigationStyle": "custom","backgroundColor": "#f5f5f5"}},{"path": "pages/scenes/chat/groupManagement/index","style": {"navigationStyle": "custom"}},{"path": "pages/scenes/chat/groupMemberList/index","style": {"navigationStyle": "custom","backgroundColor": "#f5f5f5"}},{"path": "pages/scenes/chat/search/search","style": {"navigationStyle": "custom"}},{"path": "pages/scenes/chat/search/searchInConversation","style": {"navigationStyle": "custom"}},{"path": "pages/scenes/chat/userPicker/userPicker","style": {"navigationBarTitleText": "选人列表","navigationBarBackgroundColor": "#ffffff","navigationBarTextStyle": "black","backgroundColor": "#f5f5f5"}},{"path": "pages/scenes/chat/createGroup/createGroup","style": {"navigationBarTitleText": "创建群聊","navigationBarBackgroundColor": "#ffffff","navigationBarTextStyle": "black","backgroundColor": "#f5f5f5"}},{"path": "pages/scenes/chat/groupTypeInfo/groupTypeInfo","style": {"navigationBarTitleText": "选择群类型","navigationBarBackgroundColor": "#ffffff","navigationBarTextStyle": "black","backgroundColor": "#f5f5f5"}},{"path": "pages/scenes/chat/videoPlayer/videoPlayer","style": {"app-plus": {"titleNView": false,"screenOrientation": ["portrait-primary","landscape-primary","landscape-secondary"]}}},{"path": "pages/scenes/chat/contacts/contactList/index","style": {"navigationStyle": "custom","backgroundColor": "#f5f5f5"}},{"path": "pages/scenes/chat/contacts/contactInfo/index","style": {"navigationStyle": "custom","backgroundColor": "#f5f5f5"}},{"path": "pages/scenes/chat/contacts/addFriend/index","style": {"navigationStyle": "custom","backgroundColor": "#f5f5f5"}},{"path": "pages/scenes/chat/contacts/addGroup/index","style": {"navigationStyle": "custom","backgroundColor": "#f5f5f5"}},{"path": "pages/scenes/chat/contacts/contactList/friendApplicationList","style": {"navigationStyle": "custom","backgroundColor": "#f5f5f5"}},{"path": "pages/scenes/chat/contacts/contactList/groupApplicationList","style": {"navigationStyle": "custom","backgroundColor": "#f5f5f5"}},{"path": "pages/scenes/chat/contacts/contactList/groupList","style": {"navigationStyle": "custom","backgroundColor": "#f5f5f5"}},{"path": "pages/scenes/chat/contacts/contactList/blackList","style": {"navigationStyle": "custom","backgroundColor": "#f5f5f5"}},{"path": "pages/scenes/chat/contacts/applicationVerify/index","style": {"navigationStyle": "custom","backgroundColor": "#f5f5f5"}},{"path": "pages/scenes/chat/contacts/setRemark/index","style": {"navigationStyle": "custom","backgroundColor": "#f5f5f5"}}],"tabBar": {"color": "#999999","selectedColor": "#147AFF","borderStyle": "black","backgroundColor": "#ffffff","list": [{"pagePath": "pages/scenes/chat/conversationList/conversationList","text": "消息","iconPath": "static/tuikit/message.png","selectedIconPath": "static/tuikit/message-selected.png"},{"pagePath": "pages/scenes/chat/contacts/contactList/index","text": "通讯录","iconPath": "static/tuikit/relation.png","selectedIconPath": "static/tuikit/relation-selected.png"}]},"globalStyle": {"navigationBarTextStyle": "black","navigationBarTitleText": "腾讯云 IM","navigationBarBackgroundColor": "#EBF0F6","backgroundColor": "#F8F8F8"}}
说明：
如需调整页面路由，请同步修改页面和
uni_modules/tuikit-atomic-x/components 中路由跳转逻辑。运行和测试
1. 制作自定义基座。点击运行 > 运行到手机或模拟器 > 制作自定义调试基座：
说明：
首次制作自定义基座需要下载 Gradle 依赖，Android 通常需要 10～20 分钟，iOS 需要 5～10 分钟，请耐心等待，请勿中断。
2. 获取 SDKAppID、userID 和 userSig 并配置。
注意：
SDKAppID：在 即时通信 IM 控制台 > 应用管理 单击创建新应用，获取 SDKAppID。
说明：
SDKAppID 是腾讯云 IM 客户应用的唯一标识。我们建议每一个独立的 App 都申请一个新的 SDKAppID。不同 SDKAppID 之间的消息是天然隔离的，不能互通。
userID：单击 即时通信 IM 控制台 > 消息服务 Chat > 账号管理，切换至目标应用所在账号，您可以创建 2～3 个账号用于体验单聊、群聊的功能。
说明：
用户的唯一标识符，由您定义，只能包含大小写字母（a-z，A-Z）、数字（0-9）、下划线和连字符。
userSig：单击 即时通信 IM 控制台 > 开发工具 > UserSig生成校验，切换至目标应用所在账号，填写创建的 userID，即可生成 userSig。
说明：
用户登录即时通信 IM 的密码，其本质是对 UserID 等信息加密后得到的密文。
开发环境：快速跑通 Demo，可以通过 即时通信 IM 控制台 获取 UserSig。
生产环境：将 UserSig 的生成代码集成到您的服务端，并提供面向项目的接口， 正确的 UserSig 签发方式请参见 服务端生成 UserSig。
在
pages/login/login.vue 文件中的 login 函数，填入 SDKAppID、userID、 UserSig。// 登录login({sdkAppID: Number(sdkAppId.value), // SDKAppIDuserID: userId.value, // userIDuserSig: '', // UserSigsuccess: () => {uni.reLaunch({ url: '/pages/scenes/chat/conversationList/conversationList' })},fail: (code: number, msg: string) => {isLoading.value = falseuni.showToast({ title: msg || '登录失败', icon: 'none' })}})
3. 运行项目。点击运行 > 运行到手机或模拟器 > 运行到Android/iOS基座，使用上一步中制作的自定义基座运行到手机：
集成音视频通话（推荐）
1. 下载腾讯云音视频通话 UTS 插件。访问 DCloud 插件市场——【官方】腾讯云音视频通话插件 TencentCloud-Call 并导入该插件到自己的项目。
2. 全局注册 TUICallKit 插件。在根目录下的
main.js 中引入如下代码，用于把 $TUICallKit 和 $TUIStore 注册到全局变量中：import { TUICallKit } from "@/uni_modules/TencentCloud-Call/callkit/callServices/services/index";import { TUIStore } from "@/uni_modules/TencentCloud-Call/callkit/callServices/TUIStore/index";uni.$TUICallKit = TUICallKit;uni.$TUIStore = TUIStore;
3. 注册 TUICallKit 页面。在根目录下的
pages.json 中注册唤起通话页面。{"path": "uni_modules/TencentCloud-Call/callkit/callPage","style": {"navigationBarTitleText": "","navigationStyle": "custom"}}
常见问题
技术兼容性类
Q：该 TUIKit 插件是否支持编译到 H5 或微信小程序？
A：不支持。由于新版 TUIKit 基于 UTS (Uni-app Type Script) 插件架构开发，深度依赖 Android 和 iOS 的原生能力（如原生渲染引擎、本地数据库、音视频编解码），因此仅支持打包为 App (Android/iOS)。如果您需要 H5 或小程序版本，请使用腾讯云 IM 的 Web 或小程序专用 SDK。
Q：我的现有项目全是 .vue 页面（Webview 渲染），能直接集成吗？
A：可以混用，但需要注意页面模式。
nvue 页面和 vue 页面可以互相跳转，但是 vue 页面的子组件不建议是 nvue 组件。TUIKit 的 UI 组件是 nvue 组件，因此使用 TUIKit 所在的页面（Pages）必须也是 nvue 文件。
建议方案： 将聊天页、会话列表等 IM 相关核心页面配置为
nvue 页面。注意事项： 在
pages.json 中配置相关路由时，请确保样式渲染模式正确。现有项目的 .vue 页面可以通过路由跳转到 IM 的 nvue 页面，两者可以共存，但不能在同一个页面文件中混写。可以理解为 nvue 组件具有污染性，nvue 组件的父组件、父页面都要是 nvue 文件。参考信息：uni-app > 纯原生渲染模式。
Q：页面样式错乱、布局塌陷？
A：没有严格遵守 nvue 的 Flex 布局规范。
nvue 页面中：
1. 默认
flex-direction 是 column（纵向），而非 Web 的 row。2. 文本必须包裹在
<text> 组件中，不能直接写在 <div> 或 <view> 里。3. 不支持简写属性（例如
margin: 10px 20px），必须写全（margin-top, margin-left 等）。4. 更多参考信息：uni-app-nvue 开发与 vue 开发的常见区别。
集成与构建类
Q：运行报错 "uni is not defined" 或组件无法加载？
A：请检查是否制作并使用了自定义调试基座。
由于插件包含原生代码（Java/Objective-C），标准基座不包含这些原生库。
解决步骤： 请严格按照文档“运行和测试-步骤2”操作，在 HBuilderX 中点击 运行 > 运行到手机或模拟器 > 制作自定义调试基座。制作完成后，运行时请务必选择运行到 Android/iOS 基座，并勾选“使用自定义基座”。
Q：制作自定义基座时一直失败或卡顿怎么办？
A：这通常是本地原生编译环境（Gradle 或 CocoaPods）配置问题导致的。
Android： 请检查本地 JDK 版本是否兼容，以及网络是否能正常访问 Maven/Google 仓库。
iOS： 请确保已安装 CocoaPods 且版本更新，同时检查网络环境是否能访问 GitHub 或 CDN 库。
Q：如何移除 CallKit 功能？
如果您不需要集成 CallKit 功能，请在
pages/scenes/chat/chat/index.nvue 中给 MessageInput 组件传入 toolList 属性，如下所示：<template><MessageInputv-if="conversationID"ref="messageInputRef":conversationID="conversationID":toolList="customToolList"@height-change="onMessageInputHeightChange"/></template><script setup lang="ts">import MessageInput, { DEFAULT_TOOLS } from '@/uni_modules/tuikit-atomic-x/components/MessageInput/MessageInput.nvue';const customToolList = computed(() => DEFAULT_TOOLS.filter(tool => tool.id !== 'videoCall' && tool.id !== 'voiceCall'));</script>
