@tencentcloud/sdk-mcp 1.7.4 → 1.7.6

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

@@ -7,524 +7,224 @@
 请参考 [开通服务](https://cloud.tencent.com/document/product/647/104842) 领取 TUIRoomKit 体验版或开通 TUIRoomKit 正式版，并在 [应用管理](https://console.cloud.tencent.com/trtc) 页面获取以下信息：
 - **SDKAppID：**应用标识，腾讯云基于 `SDKAppID` 完成计费统计。
 
-- **SDKSecretKey：**应用密钥，用于本地调试时生成 UserSig。
+- **SDKSecretKey：**应用密钥，仅用于本地调试时生成 UserSig，不可写入生产代码。
+
+- **UserSig：**登录凭证。须由业务服务端签发并下发，切勿在客户端硬编码 SDKSecretKey。本地调试可用 `genTestUserSig` 生成临时签名，不可用于生产，详见 [正式运行阶段如何计算 UserSig](https://cloud.tencent.com/document/product/647/17275#formal)。
 
 ### 环境准备
-- **Node.js：** ≥ 18.19.1 (推荐使用官方 LTS 版本)。
+- **Node.js：**≥ 18.19.1 (推荐使用官方 LTS 版本)。
 
 - **浏览器：**推荐使用最新版 Chrome，或其他支持 [WebRTC API](https://cloud.tencent.com/document/product/647/17249#.E6.94.AF.E6.8C.81.E7.9A.84.E5.B9.B3.E5.8F.B0) 的浏览器。
 
 - **媒体设备：**建议配备摄像头、麦克风和扬声器。缺少相应设备时仍可入会，但对应音视频能力不可用。
 
-### 准备 Vue3 项目
-
-若您尚未创建 Vue 3 项目，可先执行以下命令初始化；若已有 Vue 3 项目，可跳过本节。
-``` bash
-# 创建名为 roomkit-demo 的 Vue3 + TypeScript 项目
-npm create vite@5 roomkit-demo -- --template vue-ts
-# 进入项目目录
-cd roomkit-demo
-# 安装基础依赖
-npm install
-```
-
-## 快速接入
-
-完成前提条件后，按以下步骤在 Vue 3 项目中快速完成 TUIRoomKit 接入，并体验会中能力。
-
-### 步骤1：安装 SDK 依赖
-
-在您的业务项目中安装以下依赖。
+### 安装依赖
 
 【npm】
 ``` bash
+# 在已有 Vue 3 项目根目录执行；若需新建项目，可先运行 npm create vite@5 roomkit-demo -- --template vue-ts
 npm install @tencentcloud/roomkit-web-vue3 tuikit-atomicx-vue3 @tencentcloud/uikit-base-component-vue3 @tencentcloud/universal-api
 ```
 
 【pnpm】
 ``` bash
+# 在已有 Vue 3 项目根目录执行；若需新建项目，可先运行 pnpm create vite@5 roomkit-demo --template vue-ts
 pnpm install @tencentcloud/roomkit-web-vue3 tuikit-atomicx-vue3 @tencentcloud/uikit-base-component-vue3 @tencentcloud/universal-api
 ```
 
 【yarn】
 ``` bash
+# 在已有 Vue 3 项目根目录执行；若需新建项目，可先运行 yarn create vite@5 roomkit-demo --template vue-ts
 yarn add @tencentcloud/roomkit-web-vue3 tuikit-atomicx-vue3 @tencentcloud/uikit-base-component-vue3 @tencentcloud/universal-api
 ```
 
-### 步骤2：集成会中界面
+## 快速接入
 
-将以下示例代码复制至 `src/App.vue`，并根据控制台信息替换 `SDKAppID` 与 `SDKSecretKey`。
+### 发起会议
 
-> **注意**：
->
-> 快速接入示例采用客户端生成 UserSig 的方式，**仅可用于本地开发调试**。正式环境请改为由业务服务端生成 UserSig，详见 [正式运行阶段如何计算 UserSig](https://cloud.tencent.com/document/product/647/17275#formal)。
->
+**适用场景：**用户在客户端点击“快速会议”，需要立即创建房间并加入（如临时沟通、IM 聊天内发起会议）。
 
+**实现方式：**由客户端生成或向业务后台申请一个唯一的房间号，随后由发起人调用 `createAndJoin` 创建并直接进入该房间。
 ``` typescript
-<template>
-  <UIKitProvider theme="light" language="zh-CN">
-    <ConferenceMainView v-if="inRoom && isPC" />
-    <ConferenceMainViewH5 v-else-if="inRoom" />
-    <div v-else class="entry">
-      <TUIInput v-model="entry.userId" placeholder="请输入用户 ID" />
-      <TUIInput v-model="entry.userName" placeholder="请输入昵称, 非必填" />
-      <TUIInput v-model="entry.roomId" placeholder="请输入房间 ID, 如 room_123456" />
-      <TUIButton type="primary" :disabled="!entry.userId || !entry.roomId" @click="handleEnterRoom">进入会议</TUIButton>
-    </div>
-  </UIKitProvider>
-</template>
-
-<script setup lang="ts">
-import { ref, onMounted, onUnmounted } from 'vue';
-import { UIKitProvider, TUIInput, TUIButton, TUIToast } from '@tencentcloud/uikit-base-component-vue3';
-import { conference, ConferenceMainView, ConferenceMainViewH5, RoomEvent, genTestUserSig } from '@tencentcloud/roomkit-web-vue3';
-import { getPlatform } from '@tencentcloud/universal-api';
-
-const SDKAppID = 0; // 替换为您在开通服务阶段获取的 SDKAppID
-const SDKSecretKey = ''; // 替换为您在开通服务阶段获取的 SDKSecretKey
-
-const isPC = getPlatform() === 'pc';
-const inRoom = ref(false);
-const stored = JSON.parse(sessionStorage.getItem('tuiRoom-entry') || '{}');
-const entry = ref({ userId: stored.userId || '', userName: stored.userName || '', roomId: stored.roomId || '' });
-
-const handleEnterRoom = async () => {
-  sessionStorage.setItem('tuiRoom-entry', JSON.stringify(entry.value));
-  if (!SDKAppID || !SDKSecretKey) {
-    TUIToast.warning({ message: '请先在代码中配置 SDKAppID 和 SDKSecretKey' });
-    return;
-  }
-  try {
-    const { userSig } = genTestUserSig({ userId: entry.value.userId, sdkAppId: SDKAppID, secretKey: SDKSecretKey });
-    await conference.login({ sdkAppId: SDKAppID, userId: entry.value.userId, userSig });
-    await conference.setSelfInfo({ userName: entry.value.userName, avatarUrl: '' });
-    await conference.createAndJoinRoom({ roomId: entry.value.roomId, options: { roomName: `${entry.value.userName || entry.value.userId} 的会议` } });
-    inRoom.value = true;
-  } catch (error) {
-    console.error('进入会议失败:', error);
-  }
-};
-
-const handleLeave = () => { inRoom.value = false; };
+<script setup>
+import { RoomKit } from '@tencentcloud/roomkit-web-vue3';
 
-onMounted(() => {
-  conference.on(RoomEvent.ROOM_LEAVE, handleLeave);
-  conference.on(RoomEvent.ROOM_DISMISS, handleLeave);
-});
+// 房间不存在则创建并成为房主，已存在则直接加入
+const startQuickMeeting = async () => {
+  const room = RoomKit.getShareInstance({
+    sdkAppId: 0, // 控制台获取的 SDKAppID
+    userId: 'your_user_id', // 业务侧用户唯一标识
+    userSig: 'your_user_sig', // 由业务服务端签发并下发，切勿在客户端硬编码 SDKSecretKey
+  });
 
-onUnmounted(() => {
-  conference.off(RoomEvent.ROOM_LEAVE, handleLeave);
-  conference.off(RoomEvent.ROOM_DISMISS, handleLeave);
-});
+  const myRoomId = `room_${Date.now()}`; // 由业务生成，需保证全局唯一
+  await room.createAndJoin({ container: '#meeting', roomId: myRoomId });
+};
 </script>
 
+<template>
+  <button @click="startQuickMeeting">发起会议</button>
+  <!-- 会议界面的挂载节点，需在进会前完成渲染，并指定明确宽高 -->
+  <div id="meeting" style="width: 1080px; height: 640px"></div>
+</template>
 ```
 
-### 步骤3：启动并验证
-
-【npm】
-``` bash
-npm run dev
-```
-
-【pnpm】
-``` bash
-pnpm run dev
-```
-
-【yarn】
-``` bash
-yarn run dev
-```
-
-启动成功后，在浏览器访问本地调试地址（通常为 `http://localhost:5173`），填写用户 ID 与房间号，点击 **进入会议**，即可进入 TUIRoomKit 会中界面。
-
-**验证多人会议：**建议打开两个浏览器标签页，分别模拟不同用户进入同一房间，验证音视频互通与会中功能。操作步骤如下：
-
-**步骤1：**打开两个浏览器标签页，分别填写用户 ID `userA`、`userB` 及相同房间号 `room_123456`，点击 **进入会议**。`userA` 先进入时将自动创建房间并成为房主；`userB` 后进入时将作为参会者加入。
-
-**步骤2：**测试用户均进入会中界面后，可在成员列表中互相看到对方；开启摄像头、麦克风，确认能否看到彼此的画面并听到声音。
-
-**步骤3：**您还可以体验屏幕共享、聊天、成员管理等会中能力，确认多人场景下的基础功能正常。
-
-## 接入详解
-
-快速接入章节以一体化示例帮助您完成首次进房体验。若需将会议能力集成至实际业务，可按会议流程分步集成。本节依次介绍 SDK 依赖安装、TUIRoomKit 组件引用、登录鉴权、创建与加入会议、离开会议、监听会议状态等核心能力的用法。
-
-### 步骤1：安装 SDK 依赖
-
-在您的业务项目中安装 TUIRoomKit 及配套依赖包。
-
-【npm】
-``` bash
-npm install @tencentcloud/roomkit-web-vue3 tuikit-atomicx-vue3 @tencentcloud/uikit-base-component-vue3 @tencentcloud/universal-api
-```
-
-【pnpm】
-``` bash
-pnpm install @tencentcloud/roomkit-web-vue3 tuikit-atomicx-vue3 @tencentcloud/uikit-base-component-vue3 @tencentcloud/universal-api
-```
-
-【yarn】
-``` bash
-yarn add @tencentcloud/roomkit-web-vue3 tuikit-atomicx-vue3 @tencentcloud/uikit-base-component-vue3 @tencentcloud/universal-api
-```
-
-### 步骤2：引用 TUIRoomKit 组件
-
-TUIRoomKit 提供 Web 桌面端与 H5 移动端两套会中完整界面组件，均从 `@tencentcloud/roomkit-web-vue3` 导出。根据终端类型按需引用：
-- `ConferenceMainView`：面向 Web 桌面端，提供九宫格 / 侧边栏 / 顶部栏等视频布局，内置摄像头、麦克风、屏幕共享、成员管理、聊天、邀请入会等完整会中能力。
+### 预定会议
 
-- `ConferenceMainViewH5`：面向 H5 移动端，采用移动端专属布局与交互，支持摄像头、麦克风、成员列表、聊天等核心会中能力，适配手机浏览器场景。
+#### **场景一：客户端预订**
 
-   组件须包裹在 `UIKitProvider` 内，并通过 `getPlatform()` 区分 Web 与 H5 终端后按需渲染：
+**适用场景：**适用于需要在未来特定时间召开的会议（如团队周会、线上培训等）。用户可在客户端提前设定会议标题、时间及受邀参会成员。
 
-   ``` typescript
-   <template>
-     <UIKitProvider theme="light" language="zh-CN">
-       <ConferenceMainView v-if="isPC"></ConferenceMainView>
-       <ConferenceMainViewH5 v-else></ConferenceMainViewH5>
-     </UIKitProvider>
-   </template>
+**实现方式：**由客户端生成或向业务后台申请一个唯一的房间号，并配合会议时间等参数调用 scheduleRoom 接口提交预定。预定成功后，会议信息将同步至参与者的会议列表中。更多客户端预订会议能力请参考 [无 UI 集成 > 预订房间](https://cloud.tencent.com/document/product/647/126931)。
 
-   <script setup lang="ts">
-   import { ref } from 'vue';
-   import { UIKitProvider } from '@tencentcloud/uikit-base-component-vue3';
-   import { ConferenceMainView, ConferenceMainViewH5 } from '@tencentcloud/roomkit-web-vue3';
-   import { getPlatform } from '@tencentcloud/universal-api';
+#### **场景二：服务端预订**
 
-   const isPC = ref(getPlatform() === 'pc');
-   </script>
-   ```
+**适用场景：**会议排期完全由业务系统统一管理，不由客户端发起（如政务、医疗、大型企业 OA 等强管控场景）。
 
-### 步骤3：登录
+**实现方式：**由业务服务端调用 [服务端 REST API 创建房间](https://cloud.tencent.com/document/product/647/104446)，在 invitees 中指定受邀成员后，这些成员在客户端同样能拉取到该会议。
 
-本节介绍 TUIRoomKit 登录的实践教程。推荐在用户完成业务侧 Web 登录鉴权后，由业务服务端签发 UserSig 并下发至客户端，再依次调用 `conference.login` 与 `conference.setSelfInfo`，完成 TUIRoomKit 鉴权并配置会中展示信息。
-
-> **注意**：
->
-> UserSig 是 TUIRoomKit 登录的核心凭证。**生产环境**必须由业务服务端生成 UserSig，客户端在需要时向业务服务器请求获取，切勿在客户端硬编码 SDKSecretKey。**本地开发调试**时，可使用 `@tencentcloud/roomkit-web-vue3` 提供的 `genTestUserSig` 生成临时 UserSig，仅用于本地验证，不可用于生产环境。详见 [正式运行阶段如何计算 UserSig](https://cloud.tencent.com/document/product/647/17275#formal)。
->
+### 加入会议
 
+房间已经存在时调用 `join` 接口，参数中传入 `roomId`。
 ``` typescript
-import { onMounted } from 'vue';
-import { conference } from '@tencentcloud/roomkit-web-vue3';
-
-const SDKAppID = 0; // 控制台获取的 SDKAppID
-const userId = 'your_user_id'; // 业务侧用户唯一标识
-const userSig = 'your_user_sig'; // 由业务服务端签发并下发
-const userName = 'your_user_name';
-
-onMounted(async () => {
-  try {
-    await conference.login({ sdkAppId: SDKAppID, userId, userSig });
-    await conference.setSelfInfo({
-      userName,
-      avatarUrl: 'https://your-avatar-url.com/image.png',
-    });
-  } catch (error) {
-    console.error('TUIRoomKit 登录失败:', error);
-  }
-});
-```
+<script setup>
+import { RoomKit } from '@tencentcloud/roomkit-web-vue3';
 
-#### 登录与进房分属不同路由时，如何监听登录状态？
+const room = RoomKit.getShareInstance({
+  sdkAppId: 0, // 控制台获取的 SDKAppID
+  userId: 'your_user_id', // 业务侧用户唯一标识
+  userSig: 'your_user_sig', // 由业务服务端签发并下发，切勿在客户端硬编码 SDKSecretKey
+});
 
-若登录页与进房页为独立路由，进房页加载时 `conference.login` 可能尚未执行完毕。可通过 `watch` 监听 `loginUserInfo.value?.userId`：该字段非空时表示 TUIRoomKit 已完成登录，再执行进房逻辑。
-``` typescript
-import { watch } from 'vue';
-import { useLoginState } from 'tuikit-atomicx-vue3/room';
-import { conference } from '@tencentcloud/roomkit-web-vue3';
+const joinMeeting = async (sharedRoomId) => {
+  await room.join({ container: '#meeting', roomId: sharedRoomId });
+};
+</script>
 
-const { loginUserInfo } = useLoginState();
+<template>
+  <div id="meeting" style="width: 1080px; height: 640px"></div>
+</template>
 
-watch(() => loginUserInfo.value?.userId, async (userId) => {
-  if (userId) {
-    await conference.createAndJoinRoom({ roomId: '123456' });
-  }
-}, { immediate: true });
 ```
 
-### 步骤4：创建会议
+### 离开会议
 
-创建会议所需的**房间号（roomId）**是会议的核心标识，**由您的业务系统自行生成并维护（需保证全局唯一）**。请根据实际业务场景，选择以下创建方式：
+TUIRoomKit 已在界面上内置离开与解散房间功能，用户可直接点击 **离开房间** 或 **解散房间** 完成操作。
 
-#### 场景一：客户端发起快速会议
+如需在业务代码中主动触发离开或解散，可调用以下接口，接口执行完成即代表退出成功，**不会触发** `exited` **事件**。
 
-**适用场景：**用户在客户端点击“快速会议”，需要立即创建房间并加入（如临时沟通、IM 聊天内发起会议）。
+**场景一：主动离开房间**
 
-**实现方式：**由客户端生成或向业务后台申请一个唯一的房间号，随后由发起人调用 `conference.createAndJoinRoom` 创建并直接进入该房间。
+参与者和房主均可调用 `leave()` 离开会议，调用后不影响其他成员，房间继续存在。
 ``` typescript
-import { conference } from '@tencentcloud/roomkit-web-vue3';
+const room = RoomKit.getShareInstance({
+  sdkAppId: 0, // 控制台获取的 SDKAppID
+  userId: 'your_user_id', // 业务侧用户唯一标识
+  userSig: 'your_user_sig', // 由业务服务端签发并下发，切勿在客户端硬编码 SDKSecretKey
+});
 
-const startQuickMeeting = async () => {
-  // 1. 客户端生成一个唯一的 roomId
-  const myRoomId = `room_${Date.now()}`;
-
-  // 2. 建房并直接加入
-  await conference.createAndJoinRoom({
-    roomId: myRoomId,
-    options: {
-      roomName: '我的快速会议',
-    },
-  });
-};
+await room.leave();
 ```
 
-#### 场景二：客户端预约会议
+> **说明：**
+> 房主离开房间或关闭网页，不会自动解散房间，其他参会成员可继续正常使用 TUIRoomKit 能力，系统会在会议结束时间后 6 小时、且房间内人数为 0 时自动回收房间资源
+>
 
-**适用场景：**适用于需要在未来特定时间召开的会议（如团队周会、线上培训等）。用户可在客户端提前设定会议标题、时间及受邀参会成员。
+**场景二：主动解散房间**
 
-**实现方式**：由客户端生成或向业务后台申请一个唯一的房间号，并配合会议时间等参数调用 `scheduleRoom` 接口提交预定。预定成功后，会议信息将同步至参与者的会议列表中。更多客户端预订会议能力。
+房主调用 `end()` 后，房间内所有成员均会收到房间已解散的通知。传入 `roomId` 可解散指定房间，调用者无需身处该房间，适用于在会议列表中直接解散某一场会议。
 ``` typescript
-import { useRoomState } from 'tuikit-atomicx-vue3/room';
-
-const { scheduleRoom } = useRoomState();
-
-const createSchedule = async () => {
-  try {
-    // roomId 限制：字符串类型，必传参数，建议由业务后台生成保证 roomId 唯一性。
-    const roomId = '123456';
-
-    // 注意：时间戳单位必须为 **秒** (Date.getTime() 获取的是毫秒，需除以 1000)
-    const startTime = Math.floor(new Date().getTime() / 1000) + 3600; // 1小时后开始
-    const duration = 1800; // 30分钟
-
-    const options = {
-      roomName: '产品需求评审会',
-      scheduleStartTime: startTime, // 单位：秒
-      scheduleEndTime: startTime + duration, // 单位：秒
-      scheduleAttendees: ['userA', 'userB'], // 邀请参会成员ID列表
-      password: '123', // 可选：设置入会密码
-    };
-
-    await scheduleRoom({ roomId, options });
-  } catch (error) {
-    console.error('预定失败', error);
-  }
-};
-```
-
-#### 场景三：服务端创建会议
-
-**适用场景：**政务、医疗、大型企业 OA 等强管控场景。
+const room = RoomKit.getShareInstance({
+  sdkAppId: 0, // 控制台获取的 SDKAppID
+  userId: 'your_user_id', // 业务侧用户唯一标识
+  userSig: 'your_user_sig', // 由业务服务端签发并下发，切勿在客户端硬编码 SDKSecretKey
+});
 
-**实现方式：**会议的创建动作完全由您的业务服务端发起，调用腾讯云的 [服务端 REST API 创建房间](https://cloud.tencent.com/document/product/647/104446)。
-``` bash
-POST /v4/room_engine_http_srv/create_room
-{
-  "roomId": "your-room-id",
-  "roomName": "会议名称",
-  "startTime": 1710000000,
-  "endTime": 1710003600,
-  "invitees": ["userId1", "userId2"]
-}
+// 解散当前所在的会议
+await room.end();
 ```
 
-### 步骤5：加入会议
-
-参会成员加入房间时，请根据业务情况选择适合的加入房间的方式。
+### 事件监听
 
-#### 场景一：房间已存在，已知 roomId 直接加入
-
-**适用场景：**房间已经被发起人或服务端明确创建，参会人收到了发起人分享的房间号或者会议邀请链接。
-
-**实现方式：**参会人输入房间号，或通过邀请链接解析出 `roomId` 后，调用 `conference.joinRoom` 加入会议。
+房间可能因用户离开、被解散、被踢或登录态失效而结束。TUIRoomKit 会处理底层音视频资源与界面提示，**页面怎么走由业务接管**。通过 `on('exited')` 监听退出，在回调中恢复业务页面，该方法返回一个取消监听的函数。
 ``` typescript
-import { conference } from '@tencentcloud/roomkit-web-vue3';
-
-const joinExistingMeeting = async (sharedRoomId: string) => {
-  await conference.joinRoom({
-    roomId: sharedRoomId,
-  });
-};
-```
-
-#### 场景二：从房间列表加入会议
-
-**适用场景：**适用于已通过“客户端预约”或“服务端创建”的会议。用户可进入“会议列表”页面，查看自己预定或受邀参与的会议，并快速点击加入。
+import { onUnmounted } from 'vue';
+import { RoomKit, ExitReason } from '@tencentcloud/roomkit-web-vue3';
 
-**实现方式：**通过 `useRoomState` 提供的 `getScheduledRoomList` 接口拉取当前用户的预约会议列表并渲染至界面；用户点击目标会议后，获取对应 `roomId` 并调用 `conference.joinRoom` 进房。
-``` typescript
-<template>
-  <div>
-    <h3>我的预约会议</h3>
-    <ul v-if="roomList.length > 0">
-      <li v-for="room in roomList" :key="room.roomId" class="item">
-        <div class="info">
-          <b>{{ room.roomName || '未命名会议' }}</b>
-          <span>房间号: {{ room.roomId }}</span>
-        </div>
-        <button class="btn" @click="handleJoinRoom(room.roomId)">加入会议</button>
-      </li>
-    </ul>
-    <div v-else>暂无待参加的预约会议</div>
-  </div>
-</template>
+const room = RoomKit.getShareInstance({
+  sdkAppId: 0, // 控制台获取的 SDKAppID
+  userId: 'your_user_id',
+  userSig: 'your_user_sig', // 由业务服务端签发
+});
 
-<script setup lang="ts">
-import { ref, watch } from 'vue';
-import { conference } from '@tencentcloud/roomkit-web-vue3';
-import { useRoomState, useLoginState } from 'tuikit-atomicx-vue3/room';
-
-const { getScheduledRoomList } = useRoomState();
-const { loginUserInfo } = useLoginState();
-const roomList = ref<any[]>([]);
-
-// 1. 监听登录状态，确保鉴权就绪后再拉取会议列表
-watch(
-  () => loginUserInfo.value?.userId,
-  async (userId) => {
-    if (userId) {
-      try {
-        roomList.value = await getScheduledRoomList() || [];
-      } catch (error) {
-        console.error('获取预约会议列表失败:', error);
-      }
-    }
-  },
-  { immediate: true }
-);
-
-// 2. 点击加入房间
-const handleJoinRoom = async (roomId: string) => {
-  try {
-    await conference.joinRoom({ roomId });
-  } catch (error) {
-    console.error(`加入会议失败 (${roomId}):`, error);
+const offExited = room.on('exited', ({ roomId, reason }) => {
+  switch(reason) {
+    case ExitReason.KickedOffline:
+    case ExitReason.UserSigExpired:
+      backToLogin(); // 业务侧的登录逻辑
+      break;
+    default:
+      // 隐藏会议容器或返回上一页
+      return;
   }
-};
-</script>
+});
 
+onUnmounted(() => offExited()); // 组件销毁时取消监听
 ```
 
-#### 场景三：不确定房间是否已存在，需要直接进入
+`reason` 的取值及触发时机如下。
 
-**适用场景：**双向对等发起的场景（如在线问诊、1v1 视频客服）。无法预先确定房间是否已创建。
-
-**实现方式：**双方统一使用共知的业务单据号（如订单号）作为 `roomId`，并统一调用 `conference.createAndJoinRoom` 加入房间。
-``` typescript
-import { conference } from '@tencentcloud/roomkit-web-vue3';
-
-const enterDualMeeting = async (bizOrderId: string) => {
-  // 双方无需判断房间是否已经创建 SDK 内部自动处理建房与进房逻辑
-  await conference.createAndJoinRoom({
-    roomId: bizOrderId,
-    options: {
-      roomName: `业务沟通：${bizOrderId}`,
-    },
-  });
-};
-```
+|`reason`|触发时机|
+|---------|---------|
+|`ExitReason.RoomLeave`|用户点击界面上的「离开会议」按钮，或在密码输入框中点击取消|
+|`ExitReason.RoomDismiss`|会议被解散，对所有成员触发|
+|`ExitReason.KickedOut`|被房主踢出会议|
+|`ExitReason.RoomError`|会议界面已挂载后进房失败（如输入密码后进房失败），TUIRoomKit 会先给出错误提示。界面挂载前的失败不触发本事件：`join` 由 TUIRoomKit 弹出错误提示且 Promise resolve，`createAndJoin` 当场失败则抛出异常|
+|`ExitReason.KickedOffline`|同一账号在其他设备登录，当前设备被强制下线|
+|`ExitReason.UserSigExpired`|UserSig 已过期|
 
 > **说明：**
-> `conference.createAndJoinRoom` 内部封装了“房间不存在则创建并成为房主，已存在则加入并成为参会者”的逻辑，适用于双方对等发起的进房场景。
+> `KickedOffline` 与 `UserSigExpired` 属于登录态失效，即使用户当前不在会议中也会触发，此时 `roomId` 为空字符串。
 >
 
-### 步骤6：离开与解散房间
-
-TUIRoomKit 已在界面上内置离开与解散房间功能，用户可直接点击 **离开房间** 或 **解散房间** 完成操作。
-
-如需在业务代码中主动触发离开或解散，可调用以下接口。
-
-#### 场景一：主动离开房间
+## 界面定制
 
-参与者和房主均可调用 `leaveRoom()` 离开会议，调用后不影响其他成员，房间继续存在。
-``` typescript
-import { conference } from '@tencentcloud/roomkit-web-vue3';
-
-await conference.leaveRoom();
-```
+在完成基础集成后，您可以根据业务需求进一步定制会议界面。以下配置均通过会议实例调用，建议在进会前调用，避免界面加载后再变化。
 
-> **说明**：
->
-> 房主离开房间或关闭网页，不会自动解散房间，其他参会成员可继续正常使用 TUIRoomKit 能力，系统会在会议结束时间后 6 小时、且房间内人数为 0 时自动回收房间资源。
->
-
-#### 场景二：主动解散房间
-
-房主调用 `endRoom()` 后，房间内所有成员均会收到房间已解散的通知。
-``` typescript
-import { conference } from '@tencentcloud/roomkit-web-vue3';
-
-await conference.endRoom();
-```
-
-> **注意**：
->
-> `endRoom()` 必须由房主在成功进入房间后才能调用。非房主身份或在尚未进入房间的状态下调用会报错。
->
+### 配置主题及语言
 
-### 步骤7：监听房间状态
+会议界面默认使用浅色主题，界面语言跟随浏览器语言。用户可在会中通过内置的主题、语言按钮自行切换；如需隐藏这两个按钮。更多自定义主题及语言。
 
-在音视频会议场景中，房间状态可能因房主解散、账号在其他设备登录或网络异常等原因发生变化。
+### 调整工具栏按钮
 
-TUIRoomKit 会自动处理底层音视频资源释放与界面提示，但页面路由跳转需由业务层接管。建议您在会议组件 `onMounted` 时注册状态监听，并在 `onUnmounted` 时移除监听。
+会议界面的工具栏按钮默认全部展示。如需隐藏某些能力（如后台系统不需要主题切换、教育场景不开放屏幕共享），可调用 `setWidgetVisible`：
 ``` typescript
-<template>
-  <ConferenceMainView></ConferenceMainView>
-</template>
-
-<script setup lang="ts">
-import { ref, onMounted, onUnmounted } from 'vue';
-import { ConferenceMainView, conference, RoomEvent } from '@tencentcloud/roomkit-web-vue3';
+import { RoomKit, BuiltinWidget } from '@tencentcloud/roomkit-web-vue3';
 
-const backToHome = () => {};
-const backToLogin = () => {};
-
-onMounted(() => {
-  conference.on(RoomEvent.ROOM_DISMISS, backToHome);
-  conference.on(RoomEvent.ROOM_LEAVE, backToHome);
-  conference.on(RoomEvent.ROOM_ERROR, backToHome);
-  conference.on(RoomEvent.KICKED_OUT, backToHome);
-  conference.on(RoomEvent.KICKED_OFFLINE, backToLogin);
-  conference.on(RoomEvent.USER_SIG_EXPIRED, backToLogin);
+const room = RoomKit.getShareInstance({
+  sdkAppId: 0, // 控制台获取的 SDKAppID
+  userId: 'your_user_id',
+  userSig: 'your_user_sig', // 由业务服务端签发
 });
 
-onUnmounted(() => {
-  conference.off(RoomEvent.ROOM_DISMISS, backToHome);
-  conference.off(RoomEvent.ROOM_LEAVE, backToHome);
-  conference.off(RoomEvent.ROOM_ERROR, backToHome);
-  conference.off(RoomEvent.KICKED_OUT, backToHome);
-  conference.off(RoomEvent.KICKED_OFFLINE, backToLogin);
-  conference.off(RoomEvent.USER_SIG_EXPIRED, backToLogin);
+room.setWidgetVisible({
+  [BuiltinWidget.ScreenShareWidget]: false, // 隐藏屏幕共享
+  [BuiltinWidget.ThemeWidget]: false, // 隐藏主题切换
 });
-</script>
 ```
 
-|事件|触发时机|推荐处理|
-|---------|---------|---------|
-|`RoomEvent.ROOM_DISMISS`|房间被解散，对所有成员触发|返回首页或会议列表|
-|`RoomEvent.ROOM_LEAVE`|用户点击 TUIRoomKit 界面上的「离开」按钮|返回首页或会议列表|
-|`RoomEvent.ROOM_ERROR`|进房失败或房间内发生未处理的错误|返回首页或会议列表|
-|`RoomEvent.KICKED_OUT`|被房主踢出房间|返回首页或会议列表|
-|`RoomEvent.KICKED_OFFLINE`|同一账号在其他设备登录，当前设备被强制下线|跳转登录页|
-|`RoomEvent.USER_SIG_EXPIRED`|UserSig 已过期|跳转登录页|
-
-## 下一步
-
-在完成基础集成后，您可以根据业务需求进一步定制 UI 界面。
-
-### 配置主题及语言
-
-通过配置 `App.vue` 中 `UIKitProvider` 的入参，修改主题及语言的默认值。更多自定义主题及语言。
-| <code>UIKitProvider</code> 参数 | 可选值 | 默认值 |
-| --- | --- | --- |
-| theme | "light" \\| "dark" | "light" |
-| language | "zh-CN" \\| "en-US" | "en-US" |
-
+若需要在用户操作生效前插入业务校验（如开启摄像头前确认权限、共享屏幕前提示保密要求），可使用 `onWill` 拦截：
 ``` typescript
-<UIKitProvider theme="light" language="zh-CN">
-  <ConferenceMainView v-if="stage === 'room' && isPC" />
-  <ConferenceMainViewH5 v-else-if="stage === 'room'" />
-</UIKitProvider>
-
-<script setup lang="ts">
-import { UIKitProvider } from '@tencentcloud/uikit-base-component-vue3';
-import { ConferenceMainView, ConferenceMainViewH5 } from '@tencentcloud/roomkit-web-vue3';
-</script>
+import { InterceptorAction } from '@tencentcloud/roomkit-web-vue3';
+
+const offInterceptor = room.onWill(InterceptorAction.StartScreenShare, async (_action, proceed, abort) => {
+  const confirmed = await showYourOwnConfirmDialog();
+  confirmed ? proceed() : abort();
+});
 ```
 
+更多界面调整能力。
+
 ### 配置用户联系人列表
 
 TUIRoomKit 内置的邀请参会和预定会议选人组件，底层默认依赖腾讯云 IM 的用户关系链（好友列表）。如果您希望在这些组件中展示您企业内部的组织架构或好友列表，请先通过服务端 REST API 将您的业务联系人同步至腾讯云 IM 系统中：
@@ -536,28 +236,41 @@ TUIRoomKit 内置的邀请参会和预定会议选人组件，底层默认依赖
 
 TUIRoomKit 默认使用当前页面地址作为房间分享链接。
 
-如您需要修改链接地址，可调用 `conference.setFeatureConfig` 更新分享链接。
+如您需要修改链接地址，可调用 `setFeatureConfig` 更新分享链接。
 ``` typescript
-import { conference } from '@tencentcloud/roomkit-web-vue3';
+import { RoomKit } from '@tencentcloud/roomkit-web-vue3';
 
-// 在 conference.createAndJoinRoom / conference.joinRoom 成功之后立即调用，确保 roomId 已知
+const room = RoomKit.getShareInstance({
+  sdkAppId: 0, // 控制台获取的 SDKAppID
+  userId: 'your_user_id',
+  userSig: 'your_user_sig', // 由业务服务端签发
+});
+
+// 在 createAndJoin / join 成功之后立即调用，确保 roomId 已知
 const roomId = '123456';
-conference.setFeatureConfig({
+room.setFeatureConfig({
   shareLink: `https://your-domain.com/room?roomId=${roomId}`,
 });
 ```
 
 ### 设置视频布局及挂件
 
-TUIRoomKit 目前支持九宫格、侧边栏及顶部栏三种流布局，默认为九宫格布局，开发者可调用 `conference.setFeatureConfig` 修改默认视频布局。
+TUIRoomKit 目前支持九宫格、侧边栏及顶部栏三种流布局，默认为九宫格布局，开发者可调用 `setFeatureConfig` 修改默认视频布局。
 ``` typescript
+import { RoomKit } from '@tencentcloud/roomkit-web-vue3';
 import { RoomLayoutTemplate } from 'tuikit-atomicx-vue3/room';
 
+const room = RoomKit.getShareInstance({
+  sdkAppId: 0, // 控制台获取的 SDKAppID
+  userId: 'your_user_id',
+  userSig: 'your_user_sig', // 由业务服务端签发
+});
+
 // 方案一：修改默认视频流布局为侧边栏布局
-conference.setFeatureConfig({ layoutTemplate: RoomLayoutTemplate.SidebarLayout });
+room.setFeatureConfig({ layoutTemplate: RoomLayoutTemplate.SidebarLayout });
 
 // 方案二：修改默认视频流布局为顶部栏布局
-conference.setFeatureConfig({ layoutTemplate: RoomLayoutTemplate.CinemaLayout });
+room.setFeatureConfig({ layoutTemplate: RoomLayoutTemplate.CinemaLayout });
 ```
 
 TUIRoomKit 默认内置以下视频流挂件，如您需要自定义视频流挂件。
@@ -571,7 +284,7 @@ TUIRoomKit 默认内置以下视频流挂件，如您需要自定义视频流挂
 为节省资源，建议在会议实际结束时，通过以下任一方式主动销毁房间：
 - 界面操作：房主点击 TUIRoomKit 界面上的「解散房间」按钮；
 
-- 客户端 API：调用 `conference.endRoom()` 方法；
+- 客户端 API：调用 `room.end()` 方法；
 
 - 服务端 API：通过 REST API 进行远程销毁。
 
@@ -622,12 +335,12 @@ TUIRoomKit 已提供丰富的 UI 自定义能力，包括 主题及语言、界
 ```
 2. 根据脚本提示确认是否要将 TUIRoomKit 源码拷贝到 `./src/components/RoomKit` 目录。如您需要自定义拷贝目录请输入 'y', 否则输入'n'。
 
-3. 源码导出后，在您指定的项目路径中会新增 TUIRoomKit 源码。此时，您需要手动将 ConferenceMainView 组件，ConferenceMainViewH5 组件的 conference 对象的引用从 npm 包地址更改为 TUIRoom 源码的相对路径地址。
+3. 源码导出后，在您指定的项目路径中会新增 TUIRoomKit 源码。此时，您需要手动将 `RoomKit` 的引用从 npm 包地址更改为 TUIRoomKit 源码的相对路径地址。
 
 ``` typescript
-- import { ConferenceMainView, ConferenceMainViewH5, conference } from '@tencentcloud/roomkit-web-vue3';
+- import { RoomKit } from '@tencentcloud/roomkit-web-vue3';
 // 替换引用路径为 TUIRoomKit 源码的真实路径
-+ import { ConferenceMainView, ConferenceMainViewH5, conference } from './components/RoomKit/index.ts';
++ import { RoomKit } from './components/RoomKit/index.ts';
 ```
 4. 配置 ESLint 校验