From 1e5d3a825d6796afc070e3375ec653a9f1f3605e Mon Sep 17 00:00:00 2001 From: xinlxinli Date: Thu, 25 Jun 2026 20:49:42 +0800 Subject: [PATCH] =?UTF-8?q?=E3=80=90Web=E3=80=91update=20Web/vue3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- Web/example/vite-vue3-ts/package.json | 4 +- Web/roomkit/vue3/README.md | 379 ++++++++++++++++++ Web/roomkit/vue3/README.zh-CN.md | 368 +++++++++++++++++ .../components/RoomChatH5/RoomChat.vue | 7 +- Web/roomkit/vue3/package.json | 10 +- 5 files changed, 758 insertions(+), 10 deletions(-) create mode 100644 Web/roomkit/vue3/README.md create mode 100644 Web/roomkit/vue3/README.zh-CN.md diff --git a/Web/example/vite-vue3-ts/package.json b/Web/example/vite-vue3-ts/package.json index e68e1bd8..f0a6103b 100644 --- a/Web/example/vite-vue3-ts/package.json +++ b/Web/example/vite-vue3-ts/package.json @@ -9,10 +9,10 @@ "lint": "./node_modules/.bin/eslint ./src --no-error-on-unmatched-pattern" }, "dependencies": { - "@tencentcloud/roomkit-web-vue3": "6.0.0", + "@tencentcloud/roomkit-web-vue3": "6.0.1", "@tencentcloud/uikit-base-component-vue3": "1.4.4", "@tencentcloud/universal-api": "^2.4.0", - "tuikit-atomicx-vue3": "6.2.2", + "tuikit-atomicx-vue3": "6.2.6", "vue": "^3.2.25", "vue-router": "^4.0.14" }, diff --git a/Web/roomkit/vue3/README.md b/Web/roomkit/vue3/README.md new file mode 100644 index 00000000..e4e76668 --- /dev/null +++ b/Web/roomkit/vue3/README.md @@ -0,0 +1,379 @@ +# @tencentcloud/roomkit-web-vue3 + +TUIRoomKit is a UI solution for audio/video conferencing rooms provided by Tencent Cloud (Vue3 version). It offers two complete sets of UI view components — pre-conference and in-conference — covering both desktop and H5 mobile, along with a full conference lifecycle control API to help developers quickly integrate multi-party audio/video conferencing into existing Vue3 projects. + +--- + +## Overview + +### Pre-Conference View Components + +| Component | Description | +|-----------|-------------| +| `PreConferenceView` | Desktop pre-conference view (device check, meeting info confirmation) | +| `PreConferenceViewH5` | H5 mobile pre-conference view | + + + +### In-Conference View Components + +| Component | Description | +|-----------|-------------| +| `ConferenceMainView` | Desktop conference main view with full audio/video, chat, and member management | +| `ConferenceMainViewH5` | H5 mobile conference main view | + + + +### conference API + +The `conference` object provides core lifecycle control methods: + +| Method | Description | +|--------|-------------| +| `conference.login(options)` | SDK authentication | +| `conference.logout()` | SDK logout | +| `conference.setSelfInfo(options)` | Set current user display name and avatar | +| `conference.createAndJoinRoom(options)` | Create and join a room | +| `conference.joinRoom(options)` | Join an existing room | +| `conference.leaveRoom()` | Leave the room | +| `conference.endRoom()` | End the room (host only) | +| `conference.setFeatureConfig(options)` | Configure features (share link, video layout, etc.) | +| `conference.on(event, handler)` | Register a room event listener | +| `conference.off(event, handler)` | Remove a room event listener | + +### RoomEvent Reference + +| Event | Trigger | Recommended Handling | +|-------|---------|----------------------| +| `RoomEvent.ROOM_DISMISS` | Room ended, triggers for all participants | Return to home or meeting list | +| `RoomEvent.ROOM_LEAVE` | User clicks "Leave" in TUIRoomKit UI | Return to home or meeting list | +| `RoomEvent.ROOM_ERROR` | Join room failure or unhandled in-room error | Return to home or meeting list | +| `RoomEvent.KICKED_OUT` | Kicked out by host | Return to home or meeting list | +| `RoomEvent.KICKED_OFFLINE` | Same account logged in on another device | Redirect to login page | +| `RoomEvent.USER_SIG_EXPIRED` | UserSig expired | Redirect to login page | + +--- + +## Quick Integration + +### Prerequisites + +- Node.js ≥ 18.19.1 +- Vue ≥ 3.4.21 +- Modern browsers supporting [WebRTC APIs](https://trtc.io/document/41664?product=rtcengine&menulabel=core%20sdk&platform=web#supported-platforms) + +See [Activate the Service](https://trtc.io/document/59973?platform=web&product=conference) to obtain your `SDKAppID` and `SDKSecretKey`. + +--- + +### Step 1: Install Dependencies + +```bash +# npm +npm install @tencentcloud/roomkit-web-vue3 tuikit-atomicx-vue3 @tencentcloud/uikit-base-component-vue3 @tencentcloud/universal-api + +# pnpm +pnpm install @tencentcloud/roomkit-web-vue3 tuikit-atomicx-vue3 @tencentcloud/uikit-base-component-vue3 @tencentcloud/universal-api + +# yarn +yarn add @tencentcloud/roomkit-web-vue3 tuikit-atomicx-vue3 @tencentcloud/uikit-base-component-vue3 @tencentcloud/universal-api +``` + +--- + +### Step 2: Import TUIRoomKit Components + +```vue + + + +``` + +--- + +### Step 3: User Authentication + +Authentication is required to access all TUIRoomKit features. Call `conference.login` as soon as your user is authenticated. After login, call `conference.setSelfInfo` to set the user's display name and avatar, which appear in the participant video area and member list. + +```typescript +import { onMounted } from 'vue'; +import { conference } from '@tencentcloud/roomkit-web-vue3'; + +const SDKAppID = 0; // Replace with your SDKAppID +const userId = 'your_user_id'; +const userSig = 'your_dynamic_user_sig'; // Generate on your server in production +const userName = 'Display Name'; + +onMounted(async () => { + await conference.login({ sdkAppId: SDKAppID, userId, userSig }); + await conference.setSelfInfo({ + userName, + avatarUrl: 'https://your-avatar-url.com/image.png', + }); +}); +``` + +> **Note**: In production, generate UserSig on your server and fetch it dynamically on the client. See [How to calculate UserSig for production](https://trtc.io/document/35166?product=conference&menulabel=uikit&platform=web). + +**When authentication and Enter Room pages are on different routes**, monitor `loginUserInfo` to detect when login is complete: + +```typescript +import { watch } from 'vue'; +import { useLoginState } from 'tuikit-atomicx-vue3/room'; +import { conference } from '@tencentcloud/roomkit-web-vue3'; + +const { loginUserInfo } = useLoginState(); + +watch(() => loginUserInfo.value?.userId, async (userId) => { + if (userId) { + await conference.createAndJoinRoom({ roomId: '123456' }); + } +}, { immediate: true }); +``` + +--- + +### Step 4: Create a Room + +The **Room ID** must be generated and managed by your business system (globally unique). Choose the creation method that fits your scenario: + +**Scenario 1: Quick Meeting from Client** + +```typescript +import { conference } from '@tencentcloud/roomkit-web-vue3'; + +const startQuickMeeting = async () => { + const myRoomId = `room_${Date.now()}`; + await conference.createAndJoinRoom({ + roomId: myRoomId, + options: { roomName: 'My Quick Meeting' }, + }); +}; +``` + +**Scenario 2: Scheduled Meeting from Client** + +```typescript +import { useRoomState } from 'tuikit-atomicx-vue3/room'; + +const { scheduleRoom } = useRoomState(); + +const createSchedule = async () => { + const roomId = '123456'; + // Note: timestamp must be in seconds (divide Date.getTime() by 1000) + const startTime = Math.floor(Date.now() / 1000) + 3600; // starts in 1 hour + + await scheduleRoom({ + roomId, + options: { + roomName: 'Product Requirement Review', + scheduleStartTime: startTime, + scheduleEndTime: startTime + 1800, + scheduleAttendees: ['userA', 'userB'], + password: '123', + }, + }); +}; +``` + +**Scenario 3: Server-Side Room Creation** + +Your backend calls the [Server REST API to create a room](https://trtc.io/document/60707?product=conference&menulabel=uikit&platform=web). Suitable for government, healthcare, and large enterprise environments. + +--- + +### Step 5: Join a Room + +**Join by Room ID (room already exists)** + +```typescript +import { conference } from '@tencentcloud/roomkit-web-vue3'; + +await conference.joinRoom({ roomId: 'your-room-id' }); +``` + +**Peer-to-peer scenario (room existence unknown)** + +```typescript +// Both parties call the same API; SDK handles create-or-join internally +await conference.createAndJoinRoom({ + roomId: bizOrderId, + options: { roomName: `Business Communication: ${bizOrderId}` }, +}); +``` + +--- + +### Step 6: Leave or End a Room + +```typescript +import { conference } from '@tencentcloud/roomkit-web-vue3'; + +// Leave room (any participant) +await conference.leaveRoom(); + +// End room (host only) +await conference.endRoom(); +``` + +--- + +### Step 7: Listen to Room State + +TUIRoomKit handles audio/video cleanup and UI prompts internally, but route transitions must be managed by your application layer. Register listeners on mount and remove them on unmount. + +```vue + + + +``` + +--- + +## Advanced Configuration + +### Theme and Language + +Configure the global theme and language via `UIKitProvider` props: + +| Prop | Options | Default | +|------|---------|---------| +| `theme` | `"light"` \| `"dark"` | `"light"` | +| `language` | `"zh-CN"` \| `"en-US"` | `"en-US"` | + +### Customize Room Share Link + +```typescript +import { conference } from '@tencentcloud/roomkit-web-vue3'; + +// Call after createAndJoinRoom or joinRoom succeeds +conference.setFeatureConfig({ + shareLink: `https://your-domain.com/room?roomId=${roomId}`, +}); +``` + +### Configure Video Layout + +```typescript +import { conference } from '@tencentcloud/roomkit-web-vue3'; +import { RoomLayoutTemplate } from 'tuikit-atomicx-vue3/room'; + +// Sidebar layout +conference.setFeatureConfig({ layoutTemplate: RoomLayoutTemplate.SidebarLayout }); + +// Top bar layout +conference.setFeatureConfig({ layoutTemplate: RoomLayoutTemplate.CinemaLayout }); +``` + +### iframe Integration + +Configure the `allow` attribute to grant necessary browser permissions: + +```html + +``` + +### Intranet Proxy + +```typescript +import TUIRoomEngine from '@tencentcloud/tuiroom-engine-js'; +import { useRoomEngine } from 'tuikit-atomicx-vue3/room'; + +const { roomEngine } = useRoomEngine(); + +TUIRoomEngine.once('ready', () => { + const trtcCloud = roomEngine.instance?.getTRTCCloud(); + trtcCloud.callExperimentalAPI(JSON.stringify({ + api: 'setNetworkProxy', + params: { + websocketProxy: 'wss://proxy.example.com/ws/', + turnServer: [{ url: '14.3.3.3:3478', username: 'turn', credential: 'turn' }], + iceTransportPolicy: 'relay', + }, + })); +}); +``` + +For more details, see [Firewall Restrictions](https://trtc.io/document/59667?product=rtcengine&menulabel=core%20sdk&platform=web). + +--- + +## FAQs + +**Q: Does the meeting end immediately if the host closes the browser?** + +No. The meeting continues and other participants can interact as usual. The system reclaims resources 6 hours after the scheduled end time, provided the room is empty. Proactively call `conference.endRoom()` to release resources when the meeting is over. + +**Q: Can multiple devices use the same userId to join the same meeting?** + +No. If a second device joins with the same userId, the first device is forcibly logged out. Assign a unique userId to each device for multi-device support. + +**Q: Works locally but camera/microphone fails after deployment?** + +Browsers only allow media device access in secure contexts: `https://`, `localhost`, `file://`. Ensure your application is served over HTTPS with a valid certificate. See [URL domain and protocol restrictions](https://trtc.io/document/59733?product=rtcengine&menulabel=core%20sdk&platform=web#url-protocol-support). + +**Q: Can I export and modify the TUIRoomKit source code?** + +We recommend using the built-in customization APIs first, as exporting source code removes you from the standard npm upgrade path. If deep customization is truly necessary, run: + +```bash +node ./node_modules/@tencentcloud/roomkit-web-vue3/scripts/eject.js +``` + +After export, update the import paths: + +```typescript +- import { ConferenceMainView, ConferenceMainViewH5, conference } from '@tencentcloud/roomkit-web-vue3'; ++ import { ConferenceMainView, ConferenceMainViewH5, conference } from './components/RoomKit/index.ts'; +``` + +--- + +## Related Links + +- [Product Documentation](https://trtc.io/document/59973?platform=web&product=conference) +- [Full Integration Guide (with UI)](https://trtc.io/document/59973?platform=web&product=conference) +- [Server REST API](https://trtc.io/document/60707?product=conference&menulabel=uikit&platform=web) +- [Activate the Service](https://trtc.io/document/59973?platform=web&product=conference) +- [Contact Us](https://trtc.io/contact) diff --git a/Web/roomkit/vue3/README.zh-CN.md b/Web/roomkit/vue3/README.zh-CN.md new file mode 100644 index 00000000..7efdc3d1 --- /dev/null +++ b/Web/roomkit/vue3/README.zh-CN.md @@ -0,0 +1,368 @@ +# @tencentcloud/roomkit-web-vue3 + +腾讯云 TUIRoomKit 音视频房间 UI 组件库（Vue3 版本）。提供会前预检与会中两套完整的 UI 视图组件，覆盖桌面端与 H5 移动端，并配套完整的会议生命周期控制 API，帮助开发者快速将多人音视频会议能力集成到现有 Vue3 项目中。 + +--- + +## 能力概览 + +### 会前完整视图组件 + +| 组件 | 说明 | +|------|------| +| `PreConferenceView` | 桌面端会前预检视图（设备检测、会议信息确认） | +| `PreConferenceViewH5` | H5 移动端会前预检视图 | + + + +### 会中完整视图组件 + +| 组件 | 说明 | +|------|------| +| `ConferenceMainView` | 桌面端会议主视图，包含完整的音视频、聊天、成员管理等功能 | +| `ConferenceMainViewH5` | H5 移动端会议主视图 | + + + +### conference API + +`conference` 对象提供会议全生命周期的核心控制接口： + +| 方法 | 说明 | +|------|------| +| `conference.login(options)` | SDK 登录 | +| `conference.logout()` | SDK 登出 | +| `conference.setSelfInfo(options)` | 设置当前用户昵称和头像 | +| `conference.createAndJoinRoom(options)` | 创建并加入房间 | +| `conference.joinRoom(options)` | 加入已有房间 | +| `conference.leaveRoom()` | 离开房间 | +| `conference.endRoom()` | 解散房间（仅房主） | +| `conference.setFeatureConfig(options)` | 配置功能特性（分享链接、视频布局等） | +| `conference.on(event, handler)` | 注册房间事件监听 | +| `conference.off(event, handler)` | 取消房间事件监听 | + +### RoomEvent 事件列表 + +| 事件 | 触发时机 | +|------|---------| +| `RoomEvent.ROOM_DISMISS` | 房间被解散 | +| `RoomEvent.ROOM_LEAVE` | 用户点击离开按钮 | +| `RoomEvent.ROOM_ERROR` | 进房失败或房间内发生错误 | +| `RoomEvent.KICKED_OUT` | 被房主踢出房间 | +| `RoomEvent.KICKED_OFFLINE` | 同账号其他设备登录，当前设备被强制下线 | +| `RoomEvent.USER_SIG_EXPIRED` | UserSig 已过期 | + +--- + +## 快速接入 + +### 前提条件 + +- Node.js ≥ 18.19.1 +- Vue ≥ 3.4.21 +- 支持 [WebRTC APIs](https://cloud.tencent.com/document/product/647/17249#.E6.94.AF.E6.8C.81.E7.9A.84.E5.B9.B3.E5.8F.B0) 的现代浏览器 + +请参考 [开通服务](https://cloud.tencent.com/document/product/647/104842) 获取 `SDKAppID` 和 `SDKSecretKey`。 + +--- + +### 步骤1：安装依赖 + +```bash +# npm +npm install @tencentcloud/roomkit-web-vue3 tuikit-atomicx-vue3 @tencentcloud/uikit-base-component-vue3 @tencentcloud/universal-api + +# pnpm +pnpm install @tencentcloud/roomkit-web-vue3 tuikit-atomicx-vue3 @tencentcloud/uikit-base-component-vue3 @tencentcloud/universal-api + +# yarn +yarn add @tencentcloud/roomkit-web-vue3 tuikit-atomicx-vue3 @tencentcloud/uikit-base-component-vue3 @tencentcloud/universal-api +``` + +--- + +### 步骤2：引用会议组件 + +```vue + + + +``` + +--- + +### 步骤3：登录 + +```typescript +import { onMounted } from 'vue'; +import { conference } from '@tencentcloud/roomkit-web-vue3'; + +const SDKAppID = 0; // 替换为您的 SDKAppID +const userId = 'your_user_id'; +const userSig = 'your_dynamic_user_sig'; // 生产环境请从服务端动态获取 +const userName = '用户展示昵称'; + +onMounted(async () => { + await conference.login({ sdkAppId: SDKAppID, userId, userSig }); + await conference.setSelfInfo({ + userName, + avatarUrl: 'https://your-avatar-url.com/image.png', + }); +}); +``` + +> **注意**：生产环境请在服务端生成 UserSig，详见 [正式运行阶段如何计算 UserSig](https://cloud.tencent.com/document/product/647/17275#formal)。 + +**当登录页与进房页分属不同路由时**，可通过监听 `loginUserInfo` 判断登录状态： + +```typescript +import { watch } from 'vue'; +import { useLoginState } from 'tuikit-atomicx-vue3/room'; +import { conference } from '@tencentcloud/roomkit-web-vue3'; + +const { loginUserInfo } = useLoginState(); + +watch(() => loginUserInfo.value?.userId, async (userId) => { + if (userId) { + await conference.createAndJoinRoom({ roomId: '123456' }); + } +}, { immediate: true }); +``` + +--- + +### 步骤4：创建会议 + +根据业务场景选择合适的创建方式： + +**场景一：客户端快速发起会议** + +```typescript +import { conference } from '@tencentcloud/roomkit-web-vue3'; + +const startQuickMeeting = async () => { + const myRoomId = `room_${Date.now()}`; + await conference.createAndJoinRoom({ + roomId: myRoomId, + options: { roomName: '我的快速会议' }, + }); +}; +``` + +**场景二：客户端预约会议** + +```typescript +import { useRoomState } from 'tuikit-atomicx-vue3/room'; + +const { scheduleRoom } = useRoomState(); + +const createSchedule = async () => { + const roomId = '123456'; + const startTime = Math.floor(Date.now() / 1000) + 3600; // 1小时后，单位：秒 + + await scheduleRoom({ + roomId, + options: { + roomName: '产品需求评审会', + scheduleStartTime: startTime, + scheduleEndTime: startTime + 1800, + scheduleAttendees: ['userA', 'userB'], + password: '123', + }, + }); +}; +``` + +**场景三：服务端创建会议** + +调用腾讯云 [服务端 REST API 创建房间](https://cloud.tencent.com/document/product/647/104446)，适用于政务、医疗等强管控场景。 + +--- + +### 步骤5：加入会议 + +**已知 roomId 直接加入** + +```typescript +import { conference } from '@tencentcloud/roomkit-web-vue3'; + +await conference.joinRoom({ roomId: 'your-room-id' }); +``` + +**不确定房间是否存在（双向对等场景）** + +```typescript +// 双方统一调用，SDK 内部自动处理建房与进房逻辑 +await conference.createAndJoinRoom({ + roomId: bizOrderId, + options: { roomName: `业务沟通：${bizOrderId}` }, +}); +``` + +--- + +### 步骤6：离开与解散房间 + +```typescript +import { conference } from '@tencentcloud/roomkit-web-vue3'; + +// 离开房间（任意参会者） +await conference.leaveRoom(); + +// 解散房间（仅房主） +await conference.endRoom(); +``` + +--- + +### 步骤7：监听房间状态 + +```vue + + + +``` + +--- + +## 进阶配置 + +### 主题与语言 + +通过 `UIKitProvider` 的 props 配置全局主题和语言： + +| 参数 | 可选值 | 默认值 | +|------|--------|--------| +| `theme` | `"light"` \| `"dark"` | `"light"` | +| `language` | `"zh-CN"` \| `"en-US"` | `"en-US"` | + +更多自定义请参考 [UI 自定义 > 主题及语言](https://write.woa.com/document/202390358423633920)。 + +### 修改房间分享链接 + +```typescript +import { conference } from '@tencentcloud/roomkit-web-vue3'; + +conference.setFeatureConfig({ + shareLink: `https://your-domain.com/room?roomId=${roomId}`, +}); +``` + +### 设置视频布局 + +```typescript +import { conference } from '@tencentcloud/roomkit-web-vue3'; +import { RoomLayoutTemplate } from 'tuikit-atomicx-vue3/room'; + +// 侧边栏布局 +conference.setFeatureConfig({ layoutTemplate: RoomLayoutTemplate.SidebarLayout }); + +// 顶部栏布局 +conference.setFeatureConfig({ layoutTemplate: RoomLayoutTemplate.CinemaLayout }); +``` + +### iframe 集成 + +使用 iframe 集成时，需在标签中配置 `allow` 属性： + +```html + +``` + +### 内网代理 + +```typescript +import TUIRoomEngine from '@tencentcloud/tuiroom-engine-js'; +import { useRoomEngine } from 'tuikit-atomicx-vue3/room'; + +const { roomEngine } = useRoomEngine(); + +TUIRoomEngine.once('ready', () => { + const trtcCloud = roomEngine.instance?.getTRTCCloud(); + trtcCloud.callExperimentalAPI(JSON.stringify({ + api: 'setNetworkProxy', + params: { + websocketProxy: 'wss://proxy.example.com/ws/', + turnServer: [{ url: '14.3.3.3:3478', username: 'turn', credential: 'turn' }], + iceTransportPolicy: 'relay', + }, + })); +}); +``` + +--- + +## 常见问题 + +**Q：房主关闭网页后，会议会立即结束吗？** + +不会。房主离开后其他成员可继续使用会议功能。系统会在会议结束时间后 6 小时且房间内人数为 0 时自动回收资源。建议会议结束时主动调用 `conference.endRoom()` 销毁房间。 + +**Q：同一 userId 能否在多设备同时加入同一会议？** + +不支持。同一 userId 多端进房时，先进房的设备会被强制下线。如需多端同时参会，请为每个设备分配唯一的 userId。 + +**Q：部署到线上后无法采集摄像头或麦克风？** + +浏览器要求在安全环境（`https://`、`localhost`、`file://`）下才允许访问媒体设备。请确保您的应用部署在 HTTPS 协议下，并具备有效的安全证书。 + +**Q：是否可以直接修改底层源码？** + +我们非常不推荐导出源码，这会导致您脱离 npm 版本升级路径，需自行承担后续维护成本。如需导出，可执行： + +```bash +node ./node_modules/@tencentcloud/roomkit-web-vue3/scripts/eject.js +``` + +--- + +## 相关链接 + +- [产品文档](https://cloud.tencent.com/document/product/647/81962) +- [完整集成指南（含 UI）](https://write.woa.com/document/194132737030885376) +- [无 UI 集成指南](https://write.woa.com/document/197380092150673408) +- [UI 自定义](https://write.woa.com/document/202390358423633920) +- [视频布局及挂件自定义](https://write.woa.com/document/202273351084670976) +- [开通服务](https://cloud.tencent.com/document/product/647/104842) +- [联系我们](https://cloud.tencent.com/document/product/647/19906) diff --git a/Web/roomkit/vue3/RoomKit/components/RoomChatH5/RoomChat.vue b/Web/roomkit/vue3/RoomKit/components/RoomChatH5/RoomChat.vue index ee085eb2..1cc1a63b 100644 --- a/Web/roomkit/vue3/RoomKit/components/RoomChatH5/RoomChat.vue +++ b/Web/roomkit/vue3/RoomKit/components/RoomChatH5/RoomChat.vue @@ -9,13 +9,14 @@ :Message="CustomMessage" @click="handleMessageListClick" /> - @@ -25,12 +26,12 @@