Vue
TUIKit 주요 기능 소개
TUIKit는 주로 TUIChat, TUIConversation, TUIGroup, TUIContact, TUISearch의 몇몇 UI 서브 컴포넌트로 나누며, 각 UI 컴포넌트는 상이한 콘텐츠를 표시합니다.
개발 환경 요구사항
Vue (Vue2 & Vue3 지원됩니다. 아래에서 액세스할 때 매칭되는 Vue 액세스 가이드를 선택하여 액세스하십시오.)
TypeScript (js 프로젝트인 경우, js 프로젝트가 TUIKit 컴포넌트에 액세스하는 방법으로 이동하셔서 ts 프로그레시브 지원을 구성하십시오.)
sass (sass-loader 버전 ≤ 10.1.1)
node (node.js ≥ 16.0.0)
npm (node 버전과 매칭되는 버전)
TUIKit 소스 코드 통합( Web & H5 )
단계 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
주의:
Vite는 Node.js 18+, 20+ 버전이 필요합니다. 패킷 매니저에서 경고가 뜨는 경우 Node 버전을 업그레이드하십시오. 자세한 내용은 vite 공식 웹사이트를 참고하십시오.
vite 방식으로 프로젝트를 생성하는 경우 아래 그램의 옵션에 따라 Vue + TypeScript 를 구성합니다.
npm create vite@latest
그 다음 프로젝트 디렉터리로 전환합니다. 프로젝트 종속성 설치:
cd chat-examplenpm install
TUIKit 설치에 필요한 sass 환경 종속성:
npm i -D sass sass-loader
단계 2: TUIKit 컴포넌트 다운로드
npm 방식으로 TUIKit 컴포넌트를 다운로드하며, 후속 확장을 위해 TUIKit 컴포넌트를 당신 프로젝트의 src 디렉터리에 복사하시는 것을 권장합니다.
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: TUIKit 컴포넌트 가져오기
표시할 페이지에 TUIKit 컴포넌트를 가져오면 사용할 수 있습니다.
예: App.vue 페이지에서 아래 코드를 구현하면 채팅 인터페이스를 빠르게 구축할 수 있습니다(아래 예시 코드는 동시에 Web 측과 H5 측에서 지원됩니다).
주의:
아래 예시 코드에서는 setup 언어를 사용하였으며, 당신의 프로젝트에서 setup 언어를 사용하지 않은 경우 Vue3/Vue2의 표준 방식에 따라 컴포넌트를 등록하십시오.
<template><div id="app"><TUIKit :SDKAppID="YOUR_SDKAPPID" userID="YOUR_USERID" userSig="YOUR_USERSIG" /><TUICallKit class="callkit-container" :allowedMinimized="true" :allowedFullScreen="false" /></div></template><script lang="ts" setup>import { TUIKit } from './TUIKit';import { TUICallKit } from '@tencentcloud/call-uikit-vue';</script><style lang="scss"></style>
<template><div id="app"><TUIKit :SDKAppID="YOUR_SDKAPPID" userID="YOUR_USERID" userSig="YOUR_USERSIG" /><TUICallKit class="callkit-container" :allowedMinimized="true" :allowedFullScreen="false" /></div></template><script lang="ts" setup>import { TUIKit } from './TUIKit';import { TUICallKit } from '@tencentcloud/call-uikit-vue2';</script><style lang="scss"></style>
<template><div id="app"><TUIKit :SDKAppID="YOUR_SDKAPPID" userID="YOUR_USERID" userSig="YOUR_USERSIG" /><TUICallKit class="callkit-container" :allowedMinimized="true" :allowedFullScreen="false" /></div></template><script lang="ts" setup>import { TUIKit } from './TUIKit';import { TUICallKit } from '@tencentcloud/call-uikit-vue2.6';</script><style lang="scss"></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/mian.js
에 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"로 교체;
단계 4: SDKAppID, userID와 userSig 획득
<TUIKit>
의 관련 매개변수 SDKAppID, userID 및 해당 userSig을 설정합니다.SDKAppID
, Chat Console을 통해 Applications
에서 획득할 수 있습니다.
userID
위에서 생성한 Application,을 클릭하여 들어가면 왼쪽 사이드바에서
Chat
제품 입구를 볼 수 있으며, 클릭하여 들어갑니다.Chat 제품 서브페이지로 들어간 후
Users
를 클릭하여 사용자 관리 페이지로 들어갑니다.Create account
을 클릭하면 계정 정보 입력창이 뜹니다. 일반 회원인 경우, General
유형을 추천드립니다.더 나은 메시지 송수신 등 기능을 경험하기 위해 2개의 userID를 생성하는 것이 좋습니다.
userSig
, 콜솔에서 제공하는 개발 툴을 이용하여 실시간으로 생성할 수 있습니다. 개발 툴을 이용하시려면 Chat Console > Development Tools > UserSig Tools > Signature (UserSig) Generator 를 클릭하십시오.
단계 5: 프로젝트 시작
아래 명령을 실행하여 프로젝트를 시작합니다.
npm run serve
npm run dev
부가항목: 언어 전환
Web & H5 측
Vue TUIKit
에는 인터페이스 표시 언어로 중국어 간체, 영어 언어 패키지가 기본적으로 제공됩니다.import { TUITranslateService } from "@tencentcloud/chat-uikit-engine";// change language to chineseTUITranslateService.changeLanguage("zh");// change language to englishTUITranslateService.changeLanguage("en");
단계 6: 첫 번째 메시지 보내기
1. 프로젝트 시작 후 왼쪽 상단에 있는 1대1 채팅 시작을 클릭합니다.
2. 1대1 채팅 시작 팝업창에 들어갑니다. 단계 4에서 생성된 userID를 검색창에 입력하고 선택한 후 완료를 클릭합니다.
3. 입력창에 메시지를 입력한 후 발송을 클릭합니다.
Web 측 ‘첫 번째 메시지 보내기’의 구체적인 단계 예시:
H5 측 ‘첫 번째 메시지 보내기’의 구체적인 단계 예시:
단계 7: 첫 번째 전화 걸기
자주 받는 질문들
제품 서비스 관련 문제
1. 오디오/비디오 통화 능력 패키지 미활성화? 오디오/비디오 전화 걸기 실패?
오디오/비디오 통화 > 자주 받는 질문들을 클릭하여 솔루션을 확인하십시오.
2. UserSig란 무엇입니까? UserSig을 어떻게 생성합니까?
UserSig은 사용자 Chat에 로그인하기 위한 비밀번호로 본질적으로는 UserID 등 정보에 대한 암호화를 통해 얻은 암호문입니다.
UserSig 발급 방식은 UserSig의 컴퓨팅 코드를 당신의 서버 측에 통합하고 프로젝트 지향의 인터페이스를 제공하며, UserSig이 필요할 때 프로젝트에서 업무 서버로 요청을 개시하여 동적 UserSig을 획득하는 것입니다. 자세한 내용은 서버 측 UserSig 생성을 참고하시기 바랍니다.
주의:
여기서 예시된 코드는 클라이언트 코드에 SECRETKEY를 구성하여 UserSig을 획득하는 솔루션을 채택하였으며, 이 솔루션에서 SECRETKEY는 역컴파일에 의해 쉽게 해독되며, 암호키가 유출되면 공격자가 당신의 Tencent Cloud 트래픽을 도용할 수 있으므로, 이 방법은 로컬 실행 및 기능 디버깅에만 적용됩니다. 정확한 UserSig 발급 방식은 위의 내용을 참고하십시오.
액세스 오류 관련 문제
1. 실행 시 오류: "TypeError: Cannot read properties of undefined (reading "getFriendList")"
상기 단계에 따라 액세스한 후 실행 시 아래와 같은 오류가 발생하면, TUIKit의 종속성 유일성을 보장하여 TUIKit 다중 종속성으로 인한 문제를 피하기 위해 부디 TUIKit 디렉터리의 node_modules 디렉터리를 삭제하시기 바랍니다.
2. js 프로젝트는 TUIKit 컴포넌트에 어떻게 액세스합니까?
TUIKit는 ts 환경에서만 실행 가능하며, 당신의 프로젝트 중에 있는 js 코드와 TUIKit 중의 ts 코드가 공존할 수 있도록 프로그레시브를 통해 typescript를 구성할 수 있습니다.
vue-cli 비계를 통해 생성한 프로젝트 루트 디렉터리에서 다음을 실행합니다.
vue add typescript
그 다음 아래 구성에 따라 선택합니다(기존 js 코드와 TUIKit 중의 ts 코드를 동시에 지원할 수 있도록 부디 엄격히 아래 5개 옵션에 따라 구성하시기 바랍니다).
위의 단계를 완료한 후 프로젝트를 다시 실행하십시오!
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 기타 오류?
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 관련:
Vue2 & Vue3 UIKit 논리계층: engine 관련