适用场景
Web & H5 平台,独立集成私信聊天(1V1)或者群聊(Group),例如房产中介咨询、电商在线客服、保险远程定损等。
?
?
??
?
?开发环境要求
Vue ( 全面支持 Vue2 & Vue3 , 请您在下方接入时选择您所匹配的 Vue 版本接入指引进行接入)
TypeScript ( 如您是 js 项目, 请跳转至 常见问题-js渐进式接入ts 进行配置 ts 渐进式支持)
sass(sass-loader 版本 ≤ 10.1.1)
node(node.js ≥ 16.0.0)
npm(版本请与 node 版本匹配)
TUIKit 源码集成
步骤1:创建项目
TUIKit 支持使用 webpack 或 vite 创建项目工程,配置 Vue3 / Vue2 + TypeScript + sass。以下是几种项目工程搭建示例:
注意:
请您务必保证您的 @vue/cli 版本在 5.0.0 以上,您可使用以下示例代码升级您的 @vue/cli 版本至 v5.0.8。
使用 vue-cli 方式创建项目, 配置 Vue2 / Vue3 + TypeScript + sass。
如果您尚未安装 vue-cli 或者 vue-cli 版本低于 5.0.0 ,可以在 terminal 或 cmd 中采用如下方式进行安装:
npm install -g @vue/cli@5.0.8 sass sass-loader@10.1.1
通过 vue-cli 创建项目,并选择下图中所选配置项。
vue create chat-example
请务必保证按照如下配置选择:
?
创建完成后,切换到项目所在目录:cd chat-example
如果您是 vue2 项目,请根据您所使用的 Vue 版本进行以下相应的环境配置, vue3 项目请忽略。
npm i vue@2.7.9 vue-template-compiler@2.7.9
npm i @vue/composition-api unplugin-vue2-script-setup vue@2.6.14 vue-template-compiler@2.6.14
?
步骤2:下载 TUIKit 组件
npm i @tencentcloud/chat-uikit-vuemkdir -p ./src/TUIKit && rsync -av --exclude={'node_modules','package.json','excluded-list.txt'} ./node_modules/@tencentcloud/chat-uikit-vue/ ./src/TUIKit
npm i @tencentcloud/chat-uikit-vue
xcopy .\\node_modules\\@tencentcloud\\chat-uikit-vue .\\src\\TUIKit /i /e /exclude:.\\node_modules\\@tencentcloud\\chat-uikit-vue\\excluded-list.txt
成功后目录结构如图所示:
?
?
?步骤3:引入 TUIChat 组件
在
main.ts / main.js
中,引入 TUIKit,并注册到 Vue 项目实例中。import { createApp } from 'vue';import App from './App.vue';import { TUIComponents, TUIChatKit, genTestUserSig } from "./TUIKit";import { TUILogin } from "@tencentcloud/tui-core"; const app = createApp(App);?const SDKAppID = 0; // Your SDKAppIDconst secretKey = ""; //Your secretKeyconst userID = ""; // User ID?// TUIChatKit add TUIComponentsTUIChatKit.components(TUIComponents, app);// TUIChatKit initTUIChatKit.init();// TUICore loginTUILogin.login({SDKAppID,userID,// UserSig 是用户登录即时通信 IM 的密码,其本质是对 UserID 等信息加密后得到的密文。// 该方法仅适合本地跑通 Demo 和功能调试,详情请参见 /document/product/269/32688userSig: genTestUserSig({SDKAppID,secretKey,userID,}).userSig,// 如果您需要发送图片、语音、视频、文件等富媒体消息,请设置为 trueuseUploadPlugin: true,// 本地审核可识别、处理不安全、不适宜的内容,为您的产品体验和业务安全保驾护航// 此功能为增值服务,请参考:/document/product/269/79139// 如果您已购买内容审核服务,开启此功能请设置为 trueuseProfanityFilterPlugin: false,framework: "vue3",});?app.mount("#app");export { SDKAppID, secretKey };
import Vue from "vue";import App from "./App.vue";import { TUIComponents, TUIChatKit, genTestUserSig } from "./TUIKit";import { TUILogin } from "@tencentcloud/tui-core";?const SDKAppID = 0; // Your SDKAppIDconst secretKey = ""; //Your secretKeyconst userID = ""; // User ID?// TUIChatKit add TUIComponentsTUIChatKit.components(TUIComponents, Vue);// TUIChatKit initTUIChatKit.init();// TUICore loginTUILogin.login({SDKAppID,userID,// UserSig 是用户登录即时通信 IM 的密码,其本质是对 UserID 等信息加密后得到的密文。// 该方法仅适合本地跑通 Demo 和功能调试,详情请参见 /document/product/269/32688userSig: genTestUserSig({SDKAppID,secretKey,userID,}).userSig,// 如果您需要发送图片、语音、视频、文件等富媒体消息,请设置为 trueuseUploadPlugin: true,// 本地审核可识别、处理不安全、不适宜的内容,为您的产品体验和业务安全保驾护航// 此功能为增值服务,请参考:/document/product/269/79139// 如果您已购买内容审核服务,开启此功能请设置为 trueuseProfanityFilterPlugin: false,framework: "vue2",});Vue.config.productionTip = false;new Vue({render: (h) => h(App),}).$mount("#app");export { SDKAppID, secretKey };
步骤4: 获取 SDKAppID 、secretKey 与 userID
设置 main.ts / main.js 文件示例代码中的相关参数 SDKAppID、secretKey 以及 userID:
SDKAppID 和 secretKey 等信息,可通过 即时通信 IM 控制台 获取。
?
?
??
?
?userID 信息,可单击 即时通信 IM 控制台 > 账号管理,切换至目标应用所在账号,即可创建账号并获取 userID。
?
?
?步骤5:请填写 userID / groupID,打开会话进行聊天
说明:
conversationID:会话 ID。会话 ID 组成方式:
C2C${userID}(单聊)
GROUP${groupID}(群聊)
关于群聊:
通过调用 API createGroup 可获取 groupID。
如果是直播群, 需要通过调用 API joinGroup加入群,才可以进行聊天。
进入聊天
通过调用 API switchConversation,传入 conversationID 进入聊天页面。
在需要展示的页面,调用 TUIKit 的组件即可使用。
例如:在 App.vue 页面中,使用 TUIChat、TUICallKit 快速搭建聊天界面(以下示例代码同时支持 Web 端与 H5 端)。
<template><div :class="['TUIKit', isH5 && 'TUIKit-h5']"><div class="TUIKit-main-container"><divv-show="!isH5 || !currentConversationID":class="['navbar', isH5 && 'navbar-h5']"><div class="navbar-button" @click="openChat">打开 1v1 聊天</div><div class="navbar-button" @click="openGroupChat">打开群聊</div></div><TUIChat v-show="!isH5 || currentConversationID"><h1>欢迎使用腾讯云即时通信IM</h1></TUIChat><TUICallKitclass="callkit-container":allowedMinimized="true":allowedFullScreen="false"/></div></div></template><script setup lang="ts">import { ref } from "vue";import { TUIStore, StoreName, TUIConversationService } from "@tencentcloud/chat-uikit-engine";import { TUICallKit } from "@tencentcloud/call-uikit-vue";import { TUIChat } from "./TUIKit";import { isH5 } from "./TUIKit/utils/env";const currentConversationID = ref<string>("");const userID = "";const groupID = "";TUIStore.watch(StoreName.CONV, {currentConversationID: (id: string) => {currentConversationID.value = id;},});function openChat() {// 切换会话进入聊天TUIConversationService.switchConversation(`C2C${userID}`);}function openGroupChat() {// 切换会话进入聊天TUIConversationService.switchConversation(`GROUP${groupID}`);}</script><style scoped lang="scss">@import "./TUIKit/assets/styles/common.scss";@import "./TUIKit/assets/styles/sample.scss";.navbar {box-sizing: border-box;min-width: 285px;flex: 0 0 24%;border-right: 1px solid #f4f5f9;padding: 20px;.navbar-button {padding: 10px 40px;background-color: #006eff;color: #ffffff;font-size: 16px;margin-top: 65px;border-radius: 30px;text-align: center;cursor: pointer;}}.navbar-h5 {flex: 1;border-right: 1px solid #f4f5f9;.navbar-button {cursor: none;}}.chat {flex: 1;}</style>
在需要展示的页面,调用 TUIKit 的组件即可使用。
例如:在 App.vue 页面中,使用 TUIChat、TUICallKit 快速搭建聊天界面(以下示例代码同时支持 Web 端与 H5 端)。
<template><div :class="['TUIKit', isH5 && 'TUIKit-h5']"><div class="TUIKit-main-container"><divv-show="!isH5 || !currentConversationID":class="['navbar', isH5 && 'navbar-h5']"><div class="navbar-button" @click="openChat">打开 1v1 聊天</div><div class="navbar-button" @click="openGroupChat">打开群聊</div></div><TUIChat v-show="!isH5 || currentConversationID"><h1>欢迎使用腾讯云即时通信 IM </h1></TUIChat><TUICallKitclass="callkit-container":allowedMinimized="true":allowedFullScreen="false"/></div></div></template><script lang="ts">import Vue from "vue";import { TUIStore, StoreName, TUIConversationService } from "@tencentcloud/chat-uikit-engine";import { TUICallKit } from "@tencentcloud/call-uikit-vue2";import { TUIChat } from "./TUIKit";import { isH5 } from "./TUIKit/utils/env";export default Vue.extend({name: "App",components: {TUIChat,TUICallKit,},data() {return {isH5: isH5,currentConversationID: "",currentNavbar: "conversation",userID: "", // 请填写对端 userIDgroupID: "", // 请填写会话 groupID};},methods: {// 打开 1v1 聊天openChat() {// 切换会话进入聊天TUIConversationService.switchConversation(`C2C${this.userID}`);},// 打开群聊openGroupChat() {TUIConversationService.switchConversation(`GROUP${this.groupID}`);},},mounted: function () {TUIStore.watch(StoreName.CONV, {currentConversationID: (id: string) => {this.currentConversationID = id;},});},});</script><style scoped lang="scss">@import "./TUIKit/assets/styles/common.scss";@import "./TUIKit/assets/styles/sample.scss";.navbar {box-sizing: border-box;min-width: 285px;flex: 0 0 24%;border-right: 1px solid #f4f5f9;padding: 20px;.navbar-button {padding: 10px 40px;background-color: #006eff;color: #ffffff;font-size: 16px;margin-top: 65px;border-radius: 30px;text-align: center;cursor: pointer;}}.navbar-h5 {flex: 1;border-right: 1px solid #f4f5f9;.navbar-button {cursor: none;}}.chat {flex: 1;}</style>
1. 安装支持 composition-api 以及 script setup 的相关依赖,以及 vue2.6 相关依赖:
npm i @vue/composition-api unplugin-vue2-script-setup vue@2.6.14 vue-template-compiler@2.6.14
2. main.ts 中引入 VueCompositionAPI:
import VueCompositionAPI from "@vue/composition-api";Vue.use(VueCompositionAPI);
3. 在 vue.config.js 中增加,若没有该文件请新建:
const ScriptSetup = require("unplugin-vue2-script-setup/webpack").default;module.exports = {parallel: false, // disable thread-loader, which is not compactible with this pluginconfigureWebpack: {plugins: [ScriptSetup({/* options */}),],},chainWebpack(config) {// disable type check and let `vue-tsc` handles itconfig.plugins.delete("fork-ts-checker");},};
4. 在 src/TUIKit/adapter-vue.ts 文件最后, 替换导出源:
// 初始写法export * from "vue";// 替换为export * from "@vue/composition-api";
5. 在需要展示的页面,调用 TUIKit 的组件即可使用。
例如:在 App.vue 页面中,使用 TUIChat、TUICallKit 快速搭建聊天界面(以下示例代码同时支持 Web 端与 H5 端)。
<template><div :class="['TUIKit', isH5 && 'TUIKit-h5']"><div class="TUIKit-main-container"><divv-show="!isH5 || !currentConversationID":class="['navbar', isH5 && 'navbar-h5']"><div class="navbar-button" @click="openChat">打开 1v1 聊天</div><div class="navbar-button" @click="openGroupChat">打开群聊</div></div><TUIChat v-show="!isH5 || currentConversationID"><h1>欢迎使用腾讯云即时通信IM</h1></TUIChat><TUICallKitclass="callkit-container":allowedMinimized="true":allowedFullScreen="false"/></div></div></template><script lang="ts">import Vue from "vue";import { TUIStore, StoreName, TUIConversationService } from "@tencentcloud/chat-uikit-engine";import { TUICallKit } from "@tencentcloud/call-uikit-vue2.6";import { TUIChat } from "./TUIKit";import { isH5 } from "./TUIKit/utils/env";export default Vue.extend({name: "App",components: {TUIChat,TUICallKit,},data() {return {isH5: isH5,currentConversationID: "",currentNavbar: "conversation",userID: "", // 请填写对端 userIDgroupID: "", // 请填写会话 groupID};},methods: {// 打开 1v1 聊天openChat() {// 切换会话进入聊天TUIConversationService.switchConversation(`C2C${this.userID}`);},// 打开群聊openGroupChat() {TUIConversationService.switchConversation(`GROUP${this.groupID}`);},},mounted: function () {TUIStore.watch(StoreName.CONV, {currentConversationID: (id: string) => {this.currentConversationID = id;},});},});</script><style scoped lang="scss">@import "./TUIKit/assets/styles/common.scss";@import "./TUIKit/assets/styles/sample.scss";.navbar {box-sizing: border-box;min-width: 285px;flex: 0 0 24%;border-right: 1px solid #f4f5f9;padding: 20px;.navbar-button {padding: 10px 40px;background-color: #006eff;color: #ffffff;font-size: 16px;margin-top: 65px;border-radius: 30px;text-align: center;cursor: pointer;}}.navbar-h5 {flex: 1;border-right: 1px solid #f4f5f9;.navbar-button {cursor: none;}}.chat {flex: 1;}</style>
步骤6:启动项目
执行以下命令启动项目:
npm run serve
npm run dev
步骤7:发送您的第一条消息
?
?
??
?
?更多高级特性
客服插件
?
?
??
?
??
?
?常见问题
产品服务类问题
1. 音视频通话能力包未开通?音视频通话发起失败?
2. 如何开通消息云端搜索插件?
3. 如何开通在线客服插件?
4. 什么是 UserSig?如何生成 UserSig?
UserSig 是用户登录即时通信 IM 的密码,其本质是对 UserID 等信息加密后得到的密文。
UserSig 签发方式是将 UserSig 的计算代码集成到您的服务端,并提供面向项目的接口,在需要 UserSig 时由您的项目向业务服务器发起请求获取动态 UserSig。更多详情请参见 服务端生成 UserSig。
注意:
本文示例代码采用的获取 UserSig 的方案是在客户端代码中配置 SECRETKEY,该方法中 SECRETKEY 很容易被反编译逆向破解,一旦您的密钥泄露,攻击者就可以盗用您的腾讯云流量,因此该方法仅适合本地跑通功能调试。 正确的 UserSig 签发方式请参见上文。
接入报错类问题
1. 运行时报错:"TypeError: Cannot read properties of undefined (reading "getFriendList")"
若按照上述步骤接入后,运行时出现以下错误,请您务必删除 TUIKit 目录下的 node_modules 目录,以保证 TUIKit 的依赖唯一性,避免 TUIKit 多份依赖造成问题。
?
?
?2. js 工程如何接入 TUIKit 组件?
TUIKit 仅支持 ts 环境运行,您可以通过渐进式配置 typescript 来使您项目中已有的 js 代码 与 TUIKit 中 ts 代码共存。
请在您 vue-cli 脚手架创建的工程根目录执行:
vue add typescript
之后按照如下进行配置项进行选择(为了保证能同时支持原有 js 代码 与 TUIKit 中 ts 代码,请您务必严格按照以下五个选项进行配置)。
?
?完成以上步骤后,请重新运行项目!
请在您 vite 创建的工程根目录执行:
npm install -D typescript
3. 运行时报错:/chat-example/src/TUIKit/components/TUIChat /message-input/message-input-editor.vue .ts(8,23)TS1005: expected.
?
?
?出现以上报错信息,是因为您安装的 @vue/cli 版本过低导致,请您务必保证您的 @vue/cli 版本在 5.0.0 及以上。升级方式如下:
npm install -g @vue/cli@5.0.8
4. 运行时报错: Failed to resolve loader: sass-loader
?
?
?出现以上报错信息,是因为您未安装
sass
环境导致,请执行以下命令进行 sass
环境安装:npm i -D sass sass-loader@10.1.1
5. ESLint 报错:error 'withDefaults' is not defined no-undef? 'defineProps' is not defined no-undef? 以及 ESLint 其他报错?
?
?
?若 chat-uikit-vue 拷贝到 src 目录汇总与您本地项目代码风格不一致导致报错,可将本组件目录屏蔽,如在项目根目录增加 .eslintignore 文件:
# .eslintignoresrc/TUIKit
6. vue/cli 如何关闭 dev 模式下,webpack 全屏 overlay error 报错信息提示?
可以在您项目根目录的 vue.config.js 中进行关闭:
module.exports = defineConfig({...devServer: {client: {overlay: false,},},});
module.exports = {...devServer: {overlay: false,},};
7. 出现 Component name "XXXX" should always be multi-word 怎么办?
IM TUIKit web 所使用的 ESLint 版本为 v6.7.2 ,对于模块名的驼峰式格式并不进行严格校验。
如果您出现此问题,您可以在 .eslintrc.js 文件中进行如下配置:
module.exports = {...rules: {...'vue/multi-word-component-names': 'warn',},};
8. 出现 ERESOLVE unable to resolve dependency tree 怎么办?
npm install 的时候如果出现 ERESOLVE unable to resolve dependency tree ,表示依赖安装冲突,可采用以下方式进行安装:
npm install --legacy-peer-deps
9. 运行报错如下'vue packages version mismatch',如何解决?
// 如果您是 vue2.7 项目,请在您项目根目录执行npm i vue@2.7.9 vue-template-compiler@2.7.9// 如果您是 vue2.6 项目,请在您项目根目录执行npm i vue@2.6.14 vue-template-compiler@2.6.14
10. vite 项目 npm run build 之后 ts 报错?
?
?
?原因:package.json script 下 "build": "vue-tsc && vite build" 中的 vue-tsc 命令导致。
?
?
?解决方案: 删除 vue-tsc 即可。 "build": "vite build"。
?
?
?技术咨询
相关文档
Vue2 & Vue3 UIKit 相关:
?集成音视频通话?