tencent cloud

即时通信 IM

文档即时通信 IMDemo 专区快速跑通移动端uniapp

uniapp

Download
聚焦模式
字号
最后更新时间： 2026-04-28 11:58:12
chat-uikit-uniapp （vue2 /vue3）是基于腾讯云 Chat SDK 的一款 uniapp UI 组件库，它提供了一些通用的 UI 组件，包含会话、聊天、群组等功能。基于这些精心设计的 UI 组件，您可以快速构建优雅的、可靠的、可扩展的 Chat 应用。 chat-uikit-uniapp 界面效果如下图所示：


前提条件

环境准备

HBuilderX （HBuilderX 版本 >= 3.8.4.20230531）或者升级到新版本
Vue2 / Vue3
Sass（sass-loader 版本 ≤ 10.1.1）
Node.js v12 版本及以上
npm（版本请与 node 版本匹配）

操作步骤

步骤1：创建项目

打开 HBuilderX，在菜单栏中选择 “文件-新建-项目”，创建一个名为 chat-example 的 uni-app 项目。


步骤2：下载 TUIKit 组件

1. HBuilderX 不会默认创建 package.json 文件，因此您需要先创建 package.json 文件。请在项目根目录下执行以下命令：
npm init -y
2. 下载 TUIKit 并拷贝至源码中：
macOS 端
Windows 端
通过 NPM 方式下载 TUIKit 组件：
npm i @tencentcloud/chat-uikit-uniapp unplugin-vue2-script-setup
为了方便您后续的拓展，建议您将 TUIKit 组件复制到自己工程的 pages 目录下，请在自己的项目根目录下执行以下命令：
mkdir -p ./TUIKit && rsync -av --exclude={'node_modules','package.json','excluded-list.txt'} ./node_modules/@tencentcloud/chat-uikit-uniapp/ ./TUIKit
mkdir -p ./TUIKit/tui-customer-service-plugin && rsync -av ./node_modules/@tencentcloud/tui-customer-service-plugin/ ./TUIKit/tui-customer-service-plugin
通过 NPM 方式下载 TUIKit 组件：
npm i @tencentcloud/chat-uikit-uniapp unplugin-vue2-script-setup
为了方便您后续的拓展，建议您将 TUIKit 组件复制到自己工程的 pages 目录下，请在自己的项目根目录下执行以下命令：
xcopy .\\node_modules\\@tencentcloud\\chat-uikit-uniapp .\\TUIKit /i /e /exclude:.\\node_modules\\@tencentcloud\\chat-uikit-uniapp\\excluded-list.txt
xcopy .\\node_modules\\@tencentcloud\\tui-customer-service-plugin .\\TUIKit\\tui-customer-service-plugin /i /e

步骤3：引入 TUIKit 组件

1. 工程配置

manifest.json 文件
vue.config.js（Vue3 项目可忽略）
在 manifest.json 文件的源码视图中开启小程序分包 subPackages 和关闭 H5 treeShaking 选项。
// weixin miniProgram
"mp-weixin" : {
    "appid" : "",
    "optimization" : {
        "subPackages" : true
    }
},
// H5: close treeshaking to solve the problem of uni[methond]() is not a function 
"h5" : {
    "optimization" : {
        "treeShaking" : {
            "enable" : false
        }
    }
},
注意：
小程序默认使用分包集成，打包小程序时 manifest.json 不要配置 lazyCodeLoading 选项。
Vue2 项目必须在根目录下创建或修改 vue.config.js 。
const ScriptSetup = require('unplugin-vue2-script-setup/webpack').default;

module.exports = {
  parallel: false,
  configureWebpack: {
    plugins: [
      ScriptSetup({
        /* options */
      }),
    ],
  },
  chainWebpack(config) {
    // disable type check and let `vue-tsc` handles it
    config.plugins.delete('fork-ts-checker');
  },
};

2. 集成 TUIKit

请将以下内容复制到项目对应的文件中。
App.vue 文件
pages.json 文件
main.js（Vue3 项目可忽略）
<script lang="ts">
import { TUILogin } from '@tencentcloud/tui-core-lite';
import { TUIChatEngine } from '@tencentcloud/chat-uikit-engine-lite';

// #ifdef APP-PLUS || H5
import { TUIChatKit } from './TUIKit';
TUIChatKit.init();
// #endif

let vueVersion = 2;
// #ifdef VUE3
vueVersion = 3;
// #endif

// Required information
// You can get userSig from TencentCloud chat console for Testing TUIKit.
// Deploy production environment please get it from your server.
// View https://www.tencentcloud.com/document/product/269/32688?from_cn_redirect=1
uni.$SDKAppID = 0; // Your SDKAppID, is number type
uni.$userID = ''; // Your userID
uni.$userSig = ''; // Your userSig

export default {
  onLaunch: function () {
	TUILogin.login({
	  SDKAppID: uni.$SDKAppID,
	  userID: uni.$userID, 
	  userSig: uni.$userSig, 
	  framework: `vue${vueVersion}` // framework used vue2 / vue3
	})
    .then(() => {
      TUIChatEngine.isReady();
    })
    .catch(() => {});
  }
};
</script>
<style>
/* common css for page */
uni-page-body,html,body,page {
  width: 100% !important;
  height: 100% !important;
  overflow: hidden;
}
</style>
{
  "pages": [
    {
      "path": "pages/index/index" // 您的项目首页
    }
  ],
  "subPackages": [
    {
      "root": "TUIKit",
      "pages": [
        {
          "path": "components/TUIConversation/index",
          "style": {
            "navigationBarTitleText": "腾讯云 IM"
          }
        },
        {
          "path": "components/TUIChat/index",
          "style": {
            "navigationBarTitleText": "腾讯云 IM",
            "app-plus": {
              "softinputMode": "adjustResize",
              "titleNView": {
                "buttons": [
                  {
                    "type": "menu"
                  }
                ]
              }
            },
            "h5": {
              "titleNView": {
                "buttons": []
              }
            }
          }
        },
        // 集成 chat 组件，必须配置该路径: 视频播放
        {
          "path": "components/TUIChat/video-play",
          "style": {
            "navigationBarTitleText": "腾讯云 IM"
          }
        },
        {
          "path": "components/TUIChat/web-view",
          "style": {
            "navigationBarTitleText": "腾讯云 IM"
          }
        },
        {
          "path": "components/TUIContact/index",
          "style": {
            "navigationBarTitleText": "腾讯云 IM"
          }
        },
        {
          "path": "components/TUIGroup/index",
          "style": {
            "navigationBarTitleText": "腾讯云 IM"
          }
        },
        {
          "path": "components/TUISearch/index",
          "style": {
            "navigationBarTitleText": "聊天记录"
          }
        }
      ]
    }
  ],
  "preloadRule": {
    "pages/index/index": {
      "network": "all",
      "packages": ["TUIKit"]
    }
  },
  "globalStyle": {
    "navigationBarTextStyle": "black",
    "navigationBarTitleText": "uni-app",
    "navigationBarBackgroundColor": "#F8F8F8",
    "backgroundColor": "#F8F8F8"
  }
}
如果您是 Vue2 项目，请在 main.js 中引入组合式API，防止环境变量 isPC 等无法使用。
// #ifndef VUE3
import VueCompositionAPI from '@vue/composition-api';
Vue.use(VueCompositionAPI);
// #endif

3. 在项目主包首页中配置 TUIConversation 和 TUIContact 的入口

在 pages/index 文件夹下创建 index.vue 文件
<template>
  <div>
    <button @click="openConversationList">打开会话列表</button>
    <button @click="openContact">打开联系人</button>
  </div>
</template>
<script>
export default {
  methods: {
    // 打开会话列表
    openConversationList() {
      uni.navigateTo({ url: '/TUIKit/components/TUIConversation/index' });
    },
    // 打开联系人
    openContact() {
      uni.navigateTo({ url: '/TUIKit/components/TUIContact/index' });
    },
  },
};
</script>

步骤4：获取 SDKAppID、userID、userSig

获取 SDKAppID、userID、userSig 信息后填写到 App.vue 中对应的字段上。
uni.$SDKAppID = 0; // Your SDKAppID
uni.$userID = ''; // Your userID
uni.$userSig = ''; // Your userSig
获取 SDKAppID 并 创建两个测试用户账号
1. 在 即时通信 Chat 控制台中的应用管理页面下，可以看到您创建的应用，第二列即是 SDKAppID，然后单击操作中的查看密钥。网站会弹出查看密钥的对话框，然后单击显示密钥，即可查看密钥。
2. 点击控制台左侧的账号管理，如果您有多个应用，请注意切换至当前应用，然后在当前应用下单击新建账号，创建两个账号分别为 test-user1 和 test-user2 的账号，用于后续的互发消息。
3. userSig 信息，可单击 即时通信 IM 控制台 > 开发工具 > UserSig 工具，填写创建的 userID，即可生成 userSig。


运行和测试

步骤1：运行项目

1. 使用 HBuilderX 启动该项目，点击“运行-运行到小程序模拟器-微信开发者工具”。

2. 如果 HBuilderX 没有自动拉起微信开发者工具，请使用微信开发者工具手动打开编译后的项目。
使用微信开发者工具打开项目根目录下的 unpackage/dist/dev/mp-weixin 即可。
3. 打开项目后，在微信开发者工具 “详情-本地设置” 中勾选 “不校验合法域名、web-view（业务域名）、TLS版本以及 HTTPS 证书”。

步骤2：发送您的第一条消息

单击打开 TUIKit 会话，搜索用户 userID：test-user2，发送您的第一条消息。


更多高级特性

音视频通话 TUICallKit 插件

说明：
TUIKit 中默认没有集成 TUICallKit 音视频组件，TUICallKit 主要负责语音、视频通话。
如果您需要集成通话功能，可参考以下文档实现。
打包到 App 请参考： 音视频通话（客户端）
打包到小程序请参考：音视频通话（小程序）
打包到 H5 请参考官方：音视频通话（H5）
敬请期待。

TIMPush 离线推送插件

说明
TUIKit 中默认没有集成 TIMPush 离线推送插件。TIMPush 是腾讯云即时通信 Chat Push 插件。目前离线推送支持 Android 和 iOS 平台，设备有：华为、小米、OPPO、vivo、魅族 和 苹果手机。
如果您需要在 APP 中集成离线推送能力，请参见 uni-app 离线推送 实现。
敬请期待。

独立集成 TUIChat 组件

如果您按照本文步骤集成 TUIKit 后，需要单独使用 TUIChat 能力，按照以下示例代码用 uni.navigateTo 进行跳转即可。例如，如果您希望实现：点击对话按钮后直接打开与某特定 userID、groupID 的聊天页面，您可以给一个 button 按钮添加以下的 click 事件。
// 1v1 chat: conversationID = `C2C${userID}`
// group chat: conversationID = `GROUP${groupID}`
const conversationID = '';
uni.navigateTo({ url: `/TUIKit/components/TUIChat/index?conversationID=${conversationID}`});

常见问题

表情包的使用

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



更多问题请参见 uni-app 常见问题。

参考信息

TUIKit （vue2 / vue3）相关：
chat-uikit-uniapp (vue2/vue3) github 源码
chat-uikit-uniapp npm 快速接入
ChatEngine 相关：
ChatEngine API 手册

上一篇: Flutter下一篇: React Native

帮助和支持

本页内容是否解决了您的问题？

填写满意度调查问卷，共创更好文档体验。

文档反馈