TUIKit 是一款基于腾讯云 IM SDK 的 uni-app UI 组件库，提供了一系列通用的 UI 组件，涵盖会话、聊天、群组、音视频通话等核心功能。基于这些精心设计的 UI 组件，您可以快速构建优雅、可靠、可扩展的即时通讯应用。新版 TUIKit 采用 nvue 原生渲染引擎结合 UTS 插件的全新架构，相比于传统的 Webview 方案，为您带来更加流畅的体验。
核心的聊天页面我们使用了原生动画模块，对每一个关键结构单独处理位置计算，带来 uni-app 平台上更加流畅的聊天体验。
关键概念
UTS (Uni-app TypeScript)
Uni-app 的一种新技术，能将 TypeScript 直接编译为原生代码 (Kotlin/Swift)。本 SDK 基于此构建，因此无法运行在浏览器或小程序中，仅支持 Android 和 iOS App。
nvue (Native View)
一种基于原生渲染引擎的页面模式（类似 Weex/React Native），而非传统的 Webview。本 SDK 的 UI 组件强制依赖 nvue 以保证流畅度，请务必遵守 Flex 布局 规范，且不要使用 DOM API。
自定义调试基座 (Custom Debug Base)
包含 UTS 原生插件代码的专用调试包。由于标准 HBuilderX 运行基座不包含本 SDK 的原生库，您必须制作并运行自定义基座，否则会报错“组件未定义”。
uni_modules
Uni-app 的插件模块化规范。本 SDK 默认安装在此目录下，如果直接修改目录下的代码，后续可能造成升级困难。
前提条件
安装新版 HBuilderX 并且注册登录 DCloud 账号。
创建 uni-app 项目（Vue3 版本）。
一个有效的腾讯云账号及 Chat 应用。可参考 开通服务 从控制台获取以下信息：
SDKAppID：App 在控制台获取的 Chat 应用的 ID，为应用的唯一标识。
SDKSecretKey：应用的密钥。
集成步骤
步骤1：安装 UTS 插件
1. 进入 DCloud 插件市场搜索【官方】腾讯云实时音视频响应式 SDK。
2. 点击使用 HBuilderX 导入插件，并选择您的项目，插件将自动安装到
uni_modules 目录下。步骤2：配置 manifest.json
打开项目根目录的
manifest.json，添加以下模块和权限配置：1. 点击安卓/iOS模块配置 > Camera&Gallery（相机和相册）：勾选此项。
2. 点击安卓/iOS模块配置 > VideoPlayer（视频播放）：勾选此项。
3. 点击安卓/iOS权限配置，添加以下权限配置：
<uses-permission android:name="android.permission.RECORD_AUDIO" /><uses-permission android:name="android.permission.INTERNET" /><uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
说明：
Camera 和 VideoPlayer 模块用于聊天中的拍照和视频播放功能；Android 权限用于录音、网络访问和文件存储。步骤3：配置 pages.json
替换
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"}}
步骤4：拷贝 pages 页面和静态资源文件
1. 将插件目录中
uni_modules/tuikit-atomic-x/quickstart/pages/*下的示例页面拷贝到您的项目中的 pages目录下。（此步骤可能与 uni-app 初始文件产生冲突，可酌情替换）2. 将插件目录中
uni_modules/tuikit-atomic-x/quickstart/static/tuikit文件夹拷贝到您的项目根目录中的 static目录下。拷贝后，您根目录下的
pages/ 目录结构应该如下所示：根目录├── pages/│ ├── login/ # 登录页│ │ └── login.vue│ ├── index/ # 首页│ │ └── index.vue│ └── scenes/ # 场景页面│ └── chat/│ ├── conversationList/ # 会话列表│ ├── chat/ # 聊天页面│ ├── chatSetting/ # 聊天设置│ ├── groupManagement/ # 群管理│ ├── groupMemberList/ # 群成员列表│ ├── search/ # 搜索│ ├── userPicker/ # 选人组件│ ├── createGroup/ # 创建群聊│ ├── groupTypeInfo/ # 群类型选择│ ├── videoPlayer/ # 视频播放│ └── contact/ # 联系人相关└── static/└── tuikit/ # 静态资源
说明：
quickstart/ 目录下的页面仅供拷贝、参考使用，不是运行时的依赖，拷贝后即可从插件中删除，也可根据需要自由调整，但不建议修改 pages/scenes 下的目录结构和命名。步骤5：集成音视频通话（推荐）
1. 下载腾讯云音视频通话 UTS 插件
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"}}
运行和测试
接下来以安卓为例进行介绍：
步骤1：配置用户鉴权信息
在
pages/login/login.vue文件中的 login 函数，填入 UserSig。// 登录login({sdkAppID: Number(sdkAppId.value),userID: userId.value,userSig: '', // 填入这里success: () => {uni.reLaunch({ url: '/pages/index/index' })},fail: (_: number, msg: string) => {isLoading.value = falseuni.showToast({ title: msg || '登录失败', icon: 'none' })}})
说明：
步骤2：制作自定义基座
点击运行 > 运行到手机或模拟器 > 制作自定义调试基座：
步骤3：运行项目
1. 点击运行 > 运行到手机或模拟器 > 运行到Android/iOS基座，使用步骤二中制作的自定义基座运行到手机：
常见问题
技术兼容性类
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>
