tencent cloud

Chat

문서Chat

Web & H5 （Vue）

포커스 모드
폰트 크기
마지막 업데이트 시간: 2025-05-08 14:57:46

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
vite
주의：
반드시 @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 프로젝트인 경우 무시하십시오.
vue2.7
vue2.6 및 이하
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-example
npm install
TUIKit 설치에 필요한 sass 환경 종속성:
npm i -D sass sass-loader

단계 2: TUIKit 컴포넌트 다운로드

npm 방식으로 TUIKit 컴포넌트를 다운로드하며, 후속 확장을 위해 TUIKit 컴포넌트를 당신 프로젝트의 src 디렉터리에 복사하시는 것을 권장합니다.
macOS 측
Windows 측
npm i @tencentcloud/chat-uikit-vue
mkdir -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의 표준 방식에 따라 컴포넌트를 등록하십시오.
vue3
vue2.7
vue2.6 및 이하
<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 plugin
  configureWebpack: {
    plugins: [
      ScriptSetup({
        /* options */
      }),
    ],
  },
  chainWebpack(config) {
    // disable type check and let `vue-tsc` handles it
    config.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: 프로젝트 시작

아래 명령을 실행하여 프로젝트를 시작합니다.
vue-cli
vite
npm run serve
npm run dev

부가항목: 언어 전환

Web & H5 측 Vue TUIKit에는 인터페이스 표시 언어로 중국어 간체, 영어 언어 패키지가 기본적으로 제공됩니다.
아래 방식을 통해 언어를 전환할 수 있으며, 더 많은 전환 방식은 글로벌 인터페이스 언어를 참조하십시오.
import { TUITranslateService } from "@tencentcloud/chat-uikit-engine";
// change language to chinese
TUITranslateService.changeLanguage("zh");
// change language to english
TUITranslateService.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 디렉터리를 삭제하시기 바랍니다.
259937368-f7c85dfe-b4bd-4c73-88d9-3a9f0d7797f2.png (1186×550)


2. js 프로젝트는 TUIKit 컴포넌트에 어떻게 액세스합니까?

TUIKit는 ts 환경에서만 실행 가능하며, 당신의 프로젝트 중에 있는 js 코드와 TUIKit 중의 ts 코드가 공존할 수 있도록 프로그레시브를 통해 typescript를 구성할 수 있습니다.
vue-cli
vite
vue-cli 비계를 통해 생성한 프로젝트 루트 디렉터리에서 다음을 실행합니다.
vue add typescript
그 다음 아래 구성에 따라 선택합니다(기존 js 코드와 TUIKit 중의 ts 코드를 동시에 지원할 수 있도록 부디 엄격히 아래 5개 옵션에 따라 구성하시기 바랍니다).
260706614-5e2fc00b-ace5-4843-bef6-c0e234225b5d.png (1514×360)

위의 단계를 완료한 후 프로젝트를 다시 실행하십시오!
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

260897345-1ba994d8-da51-4820-94e7-a7145b34750b.png (690×160)

위에서와 같은 오류 정보가 나타나는 원인은 sass 환경을 설치하지 않았기 때문입니다. 아래 명령을 실행하여 sass 환경을 설치하십시오.
npm i -D sass sass-loader@10.1.1

5. ESLint 기타 오류?

chat-uikit-vue를 src 디렉토리로 복사하여 취합할 때 로컬 프로젝트 코드 스타일과 일치하지 않음으로 인해 오류가 발생하면, 본 컴포넌트 디렉터리를 차단합니다. 예를 들어 프로젝트 루트 디렉토리에 .eslintignore 파일을 추가합니다.
# .eslintignore
src/TUIKit

6. vue/cli는 dev 모드에서 webpack 풀화면 overlay error 오류 정보 알림을 어떻게 끕니까?

프로젝트 루트 디렉토리의 vue.config.js에서 끌 수 있습니다.
webpack4
webpack3
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"


교류와 피드백

Telegram 기술 교류 그룹 또는 WhatsApp 교류 그룹에 가입하여 전문 앤지니어의 지원을 받아 당신의 문제를 해결할 수 있습니다.

관련 문서

Vue2 & Vue3 UIKit 관련:

chat-uikit-vue npm
Vue2 Demo 소스 코드 및 실행 예시
Vue3 Demo 소스 코드 및 실행 예시

Vue2 & Vue3 UIKit 논리계층: engine 관련

chat-uikit-engine npm 창고
chat-uikit-engine 인터페이스 문서


다음 주제: 제품 개요

도움말 및 지원

문제 해결에 도움이 되었나요?

피드백