@tencentcloud/sdk-mcp 1.3.8 → 1.4.0

package/resource/doc/roomkit/vue/integration.md

@@ -1,19 +1,18 @@
-TUIRoomKit 是腾讯云推出的音视频会议 UI 应用。本次升级引入了全新的 Atomicx 组件接入方案，开发者可以灵活组合这些原子化组件，以构建个性化的会议界面。
+TUIRoomKit 是腾讯云推出的音视频房间 UI 应用。本次升级引入了全新的原子化组件接入方案，开发者可以灵活组合这些原子化组件，以构建个性化的音视频房间界面。
 
-本文档将帮助您集成 TUIRoomKit (Atomicx 版本) 到现有的 Vue 3 项目中，同时介绍如何对 TUIRoomKit 的样式、布局及功能进行自定义修改。
+> **推荐使用更高效的 AI 集成助手**
+>
 
-> **说明：**
-> 
+> 我们为您提供了全新的 AI 集成方式，只需要描述您的需求，即可自动生成集成代码，大幅提升开发效率。
+>
 
-> TUIRoomKit (Atomicx 版本) 目前仅支持 PC 端 Vue3 项目，如果您的业务需要支持 Vue2.x 框架或 H5 平台，请参考 [旧版本 TUIRoomKit 快速接入](https://write.woa.com/document/196568527013543936)。
-> 
+> [点击这里，立即体验 AI 集成](https://cloud.tencent.com/document/product/647/127873)
+>
 
+本文档介绍如何将 TUIRoomKit 集成到现有的 Vue3 项目中，同时介绍如何对 TUIRoomKit 的样式、布局及功能进行自定义修改。
+- 桌面端多人会议
 
-![](https://write-document-release-1258344699.cos.ap-guangzhou.tencentcos.cn/100027337918/30581b7bd73111f0ab505254001c06ec.png)
-
-
-![](https://write-document-release-1258344699.cos.ap-guangzhou.tencentcos.cn/100027337918/31045da2d73111f097cb5254005ef0f7.png)
-
+- H5 多人会议
 
 ## 前提条件
 
@@ -24,7 +23,6 @@ TUIRoomKit 是腾讯云推出的音视频会议 UI 应用。本次升级引入
 
 - **SDKSecretKey**: 应用密钥，用于初始化配置文件的密钥信息。
 
-
 ### 环境准备
 - **Node.js**: ≥ 18.19.1 (推荐使用官方 LTS 版本)。
 
@@ -34,223 +32,75 @@ TUIRoomKit 是腾讯云推出的音视频会议 UI 应用。本次升级引入
 
 - **设备**：摄像头、麦克风、扬声器。
 
-
 ## 源码接入
 
 ### 步骤1：安装项目依赖
 
 在您的业务项目中安装以下依赖。
 
-
-
-
-【npm】
-``` bash
-npm install tuikit-atomicx-vue3 @tencentcloud/uikit-base-component-vue3 @tencentcloud/tuiroom-engine-js vue-router
-```
-
-
-【pnpm】
-``` bash
-pnpm install tuikit-atomicx-vue3 @tencentcloud/uikit-base-component-vue3 @tencentcloud/tuiroom-engine-js vue-router
-```
-
-
-【yarn】
-``` bash
-yarn add tuikit-atomicx-vue3 @tencentcloud/uikit-base-component-vue3 @tencentcloud/tuiroom-engine-js vue-router
-```
-
-### 步骤2：配置开发环境
-
-如果您的项目尚未支持 TypeScript 和 SCSS，请先安装相应的环境依赖。如果已安装，您可以略过此步骤。
-
-
-
-
 【npm】
 ``` bash
-npm install typescript sass -S -D
+npm install @tencentcloud/roomkit-web-vue3@latest tuikit-atomicx-vue3 @tencentcloud/uikit-base-component-vue3 @tencentcloud/universal-api
 ```
 
-
 【pnpm】
 ``` bash
-pnpm install typescript sass -S -D
+pnpm install @tencentcloud/roomkit-web-vue3@latest tuikit-atomicx-vue3 @tencentcloud/uikit-base-component-vue3 @tencentcloud/universal-api
 ```
 
-
 【yarn】
 ``` bash
-yarn add typescript sass -S -D
-```
-
-### 步骤3：拷贝核心源码文件
-
-克隆 TUIRoomKit 的 GitHub 仓库，并进入 PC 端 Vue3 示例目录。
-``` bash
-git clone https://github.com/Tencent-RTC/TUIRoomKit.git --depth=1
-cd TUIRoomKit/Web/example/atomicx-vite-vue3-ts
+yarn add @tencentcloud/roomkit-web-vue3@latest tuikit-atomicx-vue3 @tencentcloud/uikit-base-component-vue3 @tencentcloud/universal-api
 ```
 
-拷贝 `TUIRoomKit/Web/example/atomicx-vite-vue3-ts/src` 路径下核心源码文件到您的业务项目中。
-
-> **注意：**
-> 
-
-> 拷贝源码文件时，请确保与您项目已有的文件夹进行合并，避免直接覆盖已有的同名文件夹。
-> 
-
-<table>
-<tr>
-<td rowspan="1" colSpan="1" >源路径 (示例项目)</td>
-
-<td rowspan="1" colSpan="1" >目标路径 (您的项目)</td>
-
-<td rowspan="1" colSpan="1" >说明</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >src/assets/</td>
-
-<td rowspan="1" colSpan="1" >src/assets/</td>
-
-<td rowspan="1" colSpan="1" >包含背景图、图标等静态资源。</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >src/components/</td>
-
-<td rowspan="1" colSpan="1" >src/components/</td>
-
-<td rowspan="1" colSpan="1" >包含 TUIRoomKit 所有原子 UI 组件</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >src/hooks/</td>
-
-<td rowspan="1" colSpan="1" >src/hooks/</td>
-
-<td rowspan="1" colSpan="1" >包含 TUIRoomKit 业务逻辑处理</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >src/i18n/</td>
-
-<td rowspan="1" colSpan="1" >src/i18n/</td>
-
-<td rowspan="1" colSpan="1" >包含多语言配置文件</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >src/utils/</td>
-
-<td rowspan="1" colSpan="1" >src/utils/</td>
-
-<td rowspan="1" colSpan="1" >包含通用工具函数</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >src/config/</td>
-
-<td rowspan="1" colSpan="1" >src/config/</td>
-
-<td rowspan="1" colSpan="1" >包含 `basic-info-config.js` 等应用配置信息（首次接入请重点关注此文件）</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >src/views/home.vue</td>
-
-<td rowspan="1" colSpan="1" >src/views/home.vue</td>
-
-<td rowspan="1" colSpan="1" >该页面包含了设备检测、房间创建/加入的入口功能</td>
-</tr>
-
-<tr>
-<td rowspan="1" colSpan="1" >src/views/room.vue</td>
-
-<td rowspan="1" colSpan="1" >src/views/room.vue</td>
-
-<td rowspan="1" colSpan="1" >该页面是 TUIRoomKit 的核心会议界面，集成了完整的头部、视频布局、控制栏和侧边面板</td>
-</tr>
-</table>
-
-
-### 步骤4：配置页面路由
-
-请配置您的 Vue Router，将 home.vue 映射到主页，将 room.vue 映射到会议室页面。
-
-> **注意：**
-> 
-> - 如果您的业务项目中已有 `src/router/index.ts` 文件，请将以下内容合并到已有代码中。
-> - 如果尚未配置路由，请新建 `src/router/index.ts` 文件并添加以下配置。
-
+### 步骤2：**引用 **TUIRoomKit** 组件**
 ``` typescript
-// src/router/index.ts 示例配置
-import { createRouter, createWebHistory } from 'vue-router';
-import Home from '../views/home.vue'; 
-import Room from '../views/room.vue';     
-
-const router = createRouter({
-  history: createWebHistory(),
-  routes: [
-    {
-      path: '/',
-      redirect: '/home',
-    },
-    {
-      path: '/home',
-      name: 'Home',
-      component: Home,
-    },
-    {
-      path: '/room',
-      name: 'Room',
-      component: Room,
-    },
-  ],
-});
+<template>
+  <ConferenceMainView v-if="isPC"></ConferenceMainView>
+  <ConferenceMainViewH5 v-else></ConferenceMainViewH5>
+</template>
+<script setup>
+import { ref } from 'vue';
+import { ConferenceMainView, ConferenceMainViewH5 } from '@tencentcloud/roomkit-web-vue3';
+import { getPlatform } from '@tencentcloud/universal-api';
+
+const isPC = ref(getPlatform() === 'pc');
+</script>
 
-export default router;
 ```
 
-### 步骤5：配置 App.vue 文件
-
-您需要将以下内容合并到您项目中的 App.vue 文件，以配置全局 UI 样式和用户登录逻辑：
-- 配置全局 `UIKitProvider`： 引入 `UIKitProvider` 组件，并设置默认主题和语言；
+### 步骤3：配置 App.vue 文件
 
-- 引入页面路由： 渲染 <router-view />；
+将以下内容合并到项目的 App.vue 文件中，以配置全局 UI 样式和用户登录逻辑：
+- 配置全局 `UIKitProvider`：引入 `UIKitProvider` 组件，并设置默认主题和语言；
 
-- 用户登录： 在 `onMounted` 钩子中执行 login 和 setSelfInfo；
+- 用户登录： 在 `onMounted` 钩子中执行 `login` 和 `setSelfInfo`；
 
    ``` typescript
    <template>
      <!-- Step 1: 配置全局 UIKitProvider -->
      <UIKitProvider theme="light" language="zh-CN">
-       <!-- Step 2: 引入页面路由 -->
-       <router-view />
+       <!-- 您包含 ConferenceMainView 的业务组件 -->
      </UIKitProvider>
    </template>
-    
-    <!-- 注意添加 lang="ts" 来启用 TypeScript 支持 -->
-   <script setup lang="ts">
+
+   <script setup>
    import { UIKitProvider } from '@tencentcloud/uikit-base-component-vue3';
    import { onMounted } from 'vue';
-   import { SDKAPPID, genTestUserSig } from './config/basic-info-config';
-   import { RoomEvent, useLoginState, useRoomModal } from 'tuikit-atomicx-vue3/room';
-   
-   // step 3: 用户登陆
+   import { useLoginState } from 'tuikit-atomicx-vue3/room';
+
+   // step 2: 用户登陆
    const { login, setSelfInfo } = useLoginState();
-   const { handleErrorWithModal } = useRoomModal();
-   const userId = `user_${Math.ceil(Math.random(0,1)*999)}`;
-   const userName = userId;
-   const userSig = genTestUserSig(userId);
+   const SDKAppID = 0;    // 注意：请替换为实时音视频控制台获取的 SDKAppID 信息
+   const userId = '填入您真实的 userId';    // 注意：请替换为真实的 userId
+   const userName = '填入您真实的 userName';  // 注意：请替换为真实的 userName
+   const userSig = '填入您真实的 userSig';    // 注意：生成临时 userSig 请参考 https://cloud.tencent.com/document/product/647/17275#console
    onMounted(async () => {
      try {
        await login({
          userId,
          userSig,
-         sdkAppId: SDKAPPID,
+         sdkAppId: SDKAppID,
        });
        await setSelfInfo({
          userName,
@@ -258,18 +108,17 @@ export default router;
        });
      } catch (error: any) {
        console.error('Login failed:', error);
-       handleErrorWithModal(error);
      }
    });
    </script>
-   
-   <!-- Step 4: 配置全局样式（此样式用来覆盖脚手架搭建的新项目的默认样式，可按需配置） -->
+
+   <!-- Step 3: 配置全局样式（此样式用来覆盖脚手架搭建的新项目的默认样式，可按需配置）-->
    <style>
    html, body {
      padding: 0 !important;
      margin: 0 !important;
    }
-   
+
    #app {
      width: 100% !important;
      height: 100% !important;
@@ -283,67 +132,61 @@ export default router;
    </style>
    ```
 
-### 步骤6：配置 src/main.ts 文件
+### 步骤4：发起新的会议
 
-将路由和多语言配置合并到您项目中的入口文件 src/main.ts 中：
+会议主持人可以通过调用 `conference.start`  接口来发起一场新的会议，其他参会者可以参见 步骤6 的描述，调用 `conference.join` 接口加入该会议。
 
 > **注意：**
-> 
+>
 
-> 如果您项目中的入口文件为 js 文件，请修改文件后缀为 src/main.ts。
-> 
+> 请参考步骤 3 在用户登录成功后调用 `conference.start `接口发起会议。
+>
 
 ``` typescript
-// Step 1: 配置页面路由
-import router from './router/index';
-const app = createApp(App);
-// --- 以下为新增代码 ----
-app.use(router);
-// --- 以上为新增代码 ----
-app.mount('#app');
-
-// Step 2: 配置多语言资源
-import { i18next } from '@tencentcloud/uikit-base-component-vue3';
-import { enResource, zhResource } from './i18n';
-export const addI18n = (lng: string, resource: any, deep = true, overwrite = false) => {
-  i18next.addResourceBundle(lng, 'translation', resource.translation, deep, overwrite);
-};
-addI18n('en-US', { translation: enResource }, true, true);
-addI18n('zh-CN', { translation: zhResource }, true, true);
+import { conference } from '@tencentcloud/roomkit-web-vue3';
+const startConference = async () => {
+  await conference.start({
+    roomId: '123456',   // 请替换为您真实的 roomId
+    options: {
+      roomName: '我的临时会议',
+    },
+  });
+}
+startConference();
 ```
 
-## 启动项目
-
-### 配置应用信息
-
-在您的项目目录中找到 `src/config/basic-info-config.js` 配置文件，并将您在腾讯云控制台获取的 `SDKAppID` 和 `SDKSecretKey` 填入对应的变量中。
-
-![](https://write-document-release-1258344699.cos.ap-guangzhou.tencentcos.cn/100027337918/2fc2dd3dd73111f091e252540044a08e.png)
+### 步骤5：进入已有会议
 
+参与者可以通过调用 `conference.join` 接口，填写对应的 roomId 参数，来加入由会议主持人在 步骤4 中发起的会议。
 
-> **警告：**
-> 
-> - 本文的 Demo 示例中通过在客户端代码中配置 `SDKSecretKey` 进行鉴权，但 `SDKSecretKey` 很容易被反编译逆向破解，一旦密钥泄露，攻击者就可以盗用您的腾讯云流量，因此该方法仅适合本地跑通 Demo 和功能调试。 
-> - 在正式的生产环境中，建议在您的服务端生成 UserSig，在需要 UserSig 时由您的 App 向业务服务器发起请求获取动态 UserSig 来进行鉴权。详见 [正式运行阶段如何计算 UserSig?](https://cloud.tencent.com/document/product/647/17275#formal)
-
-
-### 启动开发服务器
+> **注意：**
+>
 
+> 请参考步骤 3 在用户登录成功后调用 `conference.join `接口加入会议。
+>
 
+``` typescript
+import { conference } from '@tencentcloud/roomkit-web-vue3';
+const joinConference = async () => {
+  await conference.join({
+    roomId: '123456',   // 请替换为您真实的 roomId
+  });
+}
+joinConference();
+```
 
+## 启动项目
 
 【npm】
 ``` bash
 npm run dev
 ```
 
-
 【pnpm】
 ``` bash
 pnpm run dev
 ```
 
-
 【yarn】
 ``` bash
 yarn run dev
@@ -351,54 +194,66 @@ yarn run dev
 
 启动成功后，请在浏览器中打开调试地址（通常为 http://localhost:5173）访问应用。您将看到如下所示的会议界面：
 
-![](https://write-document-release-1258344699.cos.ap-guangzhou.tencentcos.cn/100027337918/312e7796d73111f091e252540044a08e.png)
-
-
-## UI 自定义
+## UI 快速自定义
 
 ### 主题及语言
 
 通过配置 App.vue 中 `UIKitProvider` 的入参，修改主题及语言的默认值。
-<table>
-<tr>
-<td rowspan="1" colSpan="1" >UIKitProvider 参数</td>
+| UIKitProvider 参数 | 可选值 | 默认值 |
+| --- | --- | --- |
+| theme | "light" \\| "dark" | "light" |
+| language | "zh-CN" \\| "en-US" | "en-US" |
+
+``` typescript
+<UIKitProvider theme="light" language="zh-CN">
+  <router-view />
+</UIKitProvider>
 
-<td rowspan="1" colSpan="1" >可选值</td>
+<script setup lang="ts">
+import { UIKitProvider } from '@tencentcloud/uikit-base-component-vue3';
+```
 
-<td rowspan="1" colSpan="1" >默认值</td>
-</tr>
+### 配置用户联系人列表
 
-<tr>
-<td rowspan="1" colSpan="1" >theme</td>
+TUIRoomKit 预定会议用户选择列表和会中呼叫用户选择列表默认展示用户关系链列表，批量导入用户关系链请参考以下步骤：
 
-<td rowspan="1" colSpan="1" >"light" \| "dark"</td>
+步骤1：使用 [账号管理 > 导入多个账号](https://cloud.tencent.com/document/product/269/4919) REST API 接口批量导入用户账号；
 
-<td rowspan="1" colSpan="1" >"light"</td>
-</tr>
+步骤2：使用 [好友管理 > 导入好友](https://cloud.tencent.com/document/product/269/8301) REST API 接口批量导入用户关系链；
 
-<tr>
-<td rowspan="1" colSpan="1" >language</td>
+## TUIRoomKit 界面定制
 
-<td rowspan="1" colSpan="1" >"zh-CN" \| "en-US"</td>
+### 源码导出
 
-<td rowspan="1" colSpan="1" >"en-US"</td>
-</tr>
-</table>
+【Vue3】
+1. 执行源码导出脚本，默认拷贝路径为 `./src/components/RoomKit`
+
+``` bash
+  node ./node_modules/@tencentcloud/roomkit-web-vue3/scripts/eject.js
+```
+2. 根据脚本提示确认是否要将 TUIRoomKit 源码拷贝到 `./src/components/RoomKit` 目录。如您需要自定义拷贝目录请输入 'y', 否则输入'n'。
+
+3. 源码导出后，在您指定的项目路径中会新增 TUIRoomKit 源码。此时，您需要手动将 ConferenceMainView 组件，ConferenceMainViewH5 组件的 conference 对象的引用从 npm 包地址更改为 TUIRoom 源码的相对路径地址。
 
 ``` typescript
-<UIKitProvider theme="light" language="zh-CN">
-  <router-view />
-</UIKitProvider>
- 
-<script setup lang="ts">
-import { UIKitProvider } from '@tencentcloud/uikit-base-component-vue3';
+- import { ConferenceMainView, conference } from '@tencentcloud/roomkit-web-vue3';
+// 替换引用路径为 TUIRoomKit 源码的真实路径
++ import { ConferenceMainView, ConferenceMainViewH5, conference } from './components/RoomKit/index.ts';
 ```
+4. 配置 ESLint 校验
 
-### 房间流布局
+如果您导出 TUIRoomKit 源码后运行项目出现 ESLint 报错，您可以在`.eslintignore`文件中添加 RoomKit 文件夹忽略 ESLint 检测。
+``` javascript
+// 请替换为 TUIRoomKit 源码真实路径
+src/components/RoomKit
+```
+
+### 自定义房间流布局
 
 TUIRoomKit 目前支持九宫格、侧边栏及顶部栏三种流布局，默认为九宫格布局。
 ``` typescript
-// src/views/room.vue
+// RoomKit/views/ConferenceMainView/index.vue
+import { RoomLayoutTemplate } from 'tuikit-atomicx-vue3/room';
 // 修改默认视频流布局为侧边栏布局
 const participantViewLayout = ref(RoomLayoutTemplate.SidebarLayout);
 function handleLayoutUpdate(layout: RoomLayoutTemplate) {
@@ -414,21 +269,7 @@ function handleLayoutUpdate(layout: RoomLayoutTemplate) {
 
 ### 自定义视频流挂件
 
-TUIRoomKit 默认视频流挂件如图所示，如您需要自定义视频流挂件请修改 `src/components/RoomLayoutView/ParticipantViewUI/ParticipantViewUI.vue` 组件。
-
-![](https://write-document-release-1258344699.cos.ap-guangzhou.tencentcos.cn/100027337918/2fab38f2d73111f0929b525400bf7822.png)
-
-
-### 配置用户联系人列表
-
-TUIRoomKit 预定会议用户选择列表和会中呼叫用户选择列表默认展示用户关系链列表，批量导入用户关系链请参考以下步骤：
-
-步骤1：使用 [账号管理 > 导入多个账号](https://cloud.tencent.com/document/product/269/4919) REST API 接口批量导入用户账号；
-
-步骤2：使用 [好友管理 > 导入好友](https://cloud.tencent.com/document/product/269/8301) REST API 接口批量导入用户关系链；
-
-![](https://write-document-release-1258344699.cos.ap-guangzhou.tencentcos.cn/100027337918/32637a07d73111f0ab505254001c06ec.png)
-
+TUIRoomKit 默认视频流挂件如图所示，如需自定义视频流挂件请修改 `RoomKit/components/RoomLayoutView/ParticipantViewUI/ParticipantViewUI.vue` 组件。
 
 ## 常见问题
 
@@ -439,10 +280,9 @@ TUIRoomKit 预定会议用户选择列表和会中呼叫用户选择列表默认
 
 - **相关资源：**更多关于 URL 域名及协议的限制详情，请参见 [URL 域名及协议限制说明](https://cloud.tencent.com/document/product/647/17249#URL-.E5.9F.9F.E5.90.8D.E5.8D.8F.E8.AE.AE.E9.99.90.E5.88.B6)。
 
-
 #### **TUIRoomKit 是否支持使用 iframe 集成?**
 
-支持。使用 iframe 集成 TUIRoomKit 时, 需要在 iframe 标签中配置 allow 属性以授予必要的浏览器权限（麦克风、摄像头、屏幕共享、全屏等），示例如下: 
+支持。使用 iframe 集成 TUIRoomKit 时, 需要在 iframe 标签中配置 allow 属性以授予必要的浏览器权限（麦克风、摄像头、屏幕共享、全屏等），示例如下:
 ``` typescript
 // 开启麦克风、摄像头、屏幕分享、全屏权限
 <iframe allow="microphone; camera; display-capture; display; fullscreen;">
@@ -458,7 +298,7 @@ import { useRoomEngine } from 'tuikit-atomicx-vue3/room';
 const { roomEngine } = useRoomEngine();
 
 TUIRoomEngine.once('ready', () => {
-  const trtcCloud = roomEngine.instance?.getTRTCCloud()；
+  const trtcCloud = roomEngine.instance?.getTRTCCloud();
   trtcCloud.callExperimentalAPI(JSON.stringify({
     api: 'setNetworkProxy',
     params: {
@@ -473,7 +313,3 @@ TUIRoomEngine.once('ready', () => {
   }));
 });
 ```
-
-## 联系我们
-
-如果您在接入或使用过程有任何疑问或者建议，欢迎 [联系我们](https://cloud.tencent.com/document/product/269/59590) 提交反馈。