@tencentcloud/sdk-mcp 1.3.0 → 1.3.2

package/resource/doc/roomkit/vue/features/room-participant-state.md

@@ -0,0 +1,407 @@
+本篇文档将指导您如何管理房间内的参会者。Atomicx 提供了开箱即用的列表组件 `RoomParticipantList` 用于快速集成，并暴露了 [useRoomParticipantState](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#module-RoomParticipantState) Hook，方便您实现自定义的成员控制逻辑。
+
+## 功能介绍
+
+成员管理模块涵盖了房间内用户信息展示以及权限处理的全套能力：
+- **实时列表展示：**动态呈现房间内所有成员的昵称、角色、音视频状态及音量波动。
+
+- **权限控制：**支持房主或管理员执行踢人、全员禁言、转让房主等管理操作。
+
+- **分级管理：**支持对房主、管理员及普通成员实现差异化的权限策略。
+
+
+## 前提条件
+- 用户已经通过 [useLoginState](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#module-LoginState) 完成登录鉴权，请参考 [接入概览](https://write.woa.com/document/197379797539790848)。
+
+- 用户已经通过 [useRoomState](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#module-RoomState) 进入房间，请参考 [房间管理](https://write.woa.com/document/197379861957083136)。
+
+
+## 集成成员管理组件
+
+如果您需要快速构建成员列表界面，推荐直接使用 `RoomParticipantList` 组件。`RoomParticipantList` 是一个开箱即用的参会者列表组件，内置了完整的成员管理 UI 和交互。
+
+![](https://write-document-release-1258344699.cos.ap-guangzhou.tencentcos.cn/100027337918/9407bc54dbe911f0a4f35254007c27c5.png)
+
+
+集成 `RoomParticipantList` 组件示例代码：
+``` typescript
+<template>
+  <div class="room-page">
+    <!-- 参会者列表侧边栏 -->
+    <aside class="sidebar">
+      <div class="sidebar-header">
+        <span>参会者 ({{ currentRoom.participantCount }})</span>
+        <IconClose />
+      </div>
+
+      <!-- 参会者列表组件 -->
+      <RoomParticipantList />
+    </aside>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { IconClose } from '@tencentcloud/uikit-base-component-vue3';
+import { 
+  RoomView,
+  RoomParticipantList,
+  useRoomState,
+  useRoomParticipantState 
+} from 'tuikit-atomicx-vue3/room';
+
+const { currentRoom } = useRoomState();
+const { participantList } = useRoomParticipantState();
+</script>
+
+<style scope>
+.room-page {
+  width: 100vw;
+  height: 100vh;
+  min-width: 1150px;
+  display: flex;
+  flex-direction: row;
+  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+  position: relative;
+  overflow: hidden;
+}
+
+.sidebar {
+  position: absolute;
+  top: 0;
+  right: 0;
+  width: 400px;
+  height: 100%;
+  box-sizing: border-box;
+}
+
+.sidebar-header {
+  display: flex;
+  height: 60px;
+  justify-content: space-between;
+  align-items: center;
+  padding: 0px 20px;
+}
+</style>
+```
+
+> **说明：**
+> 
+> - `RoomParticipantList` 会自动占满父容器的高度和宽度，请确保其父容器具备明确的尺寸。
+> - 使用 `RoomParticipantList` 组件请确保在 `App.vue` 中配置全局 `UIKitProvider`，具体请参考 [配置 App.vue](https://cloud.tencent.com/document/product/647/81962#ce98ee15-b0cb-43af-81da-70f51231430e)。
+
+
+## 实现成员管理功能
+
+如果您需要自定义成员列表 UI 或在特定业务中触发管理行为，请使用 [useRoomParticipantState](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#module-RoomParticipantState)。
+
+### 步骤1：获取成员列表
+
+通过 [getParticipantList](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#getParticipantList) 获取响应式的成员数据 [participantList](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#participantList)。
+``` typescript
+import { useRoomState, useRoomParticipantState } from 'tuikit-atomicx-vue3/room';
+
+const { currentRoom } = useRoomState();
+const { participantList, participantListCursor, getParticipantList } = useRoomParticipantState();
+
+// 在进房成功之后获取房间内用户列表
+watch(() => currentRoom.value?.roomId, async () => {
+ await getParticipantList();
+})
+
+// 当列表滚动到底部时，加载更多用户
+const handleLoadMore = async () => {
+  if (participantListCursor.value) {
+    await getParticipantList({ cursor: participantListCursor.value });
+  }
+};
+```
+
+> **说明：**
+> 
+
+> `getParticipantList` 接口拉取成功的数据会自动维护在 `participantList` 中，UI 只需要渲染 `participantList` 的数据即可。
+> 
+
+
+### 步骤2：渲染参会者信息
+
+开发者可以使用  [participantList](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#participantList) 数据自定义渲染用户信息列表。
+``` typescript
+<template>
+  <div class="participant-list">
+    <div class="list-header">
+      <h3>参会者 ({{ participantList.length }})</h3>
+      <button @click="handleRefresh">
+        <IconRefresh />
+      </button>
+    </div>
+    <div class="list-content">
+      <div 
+        v-for="participant in participantList" 
+        :key="participant.userId"
+        class="participant-item"
+      >
+        <!-- 头像 -->
+        <Avatar 
+          :user-id="participant.userId" 
+          :avatar-url="participant.avatarUrl" 
+        />
+
+        <!-- 用户信息 -->
+        <div class="user-info">
+          <div class="user-name">
+            <span>{{ participant.userName }}</span>
+            <span v-if="participant.userId === localParticipant.userId" class="badge">我</span>
+            <span 
+              v-if="participant.role === RoomParticipantRole.Owner" 
+              class="role-badge owner"
+            >
+              房主
+            </span>
+            <span 
+              v-else-if="participant.role === RoomParticipantRole.Admin" 
+              class="role-badge admin"
+            >
+              管理员
+            </span>
+          </div>
+        </div>
+
+        <!-- 设备状态 -->
+        <div class="device-status">
+          <IconMicOn 
+            size="20"
+            v-if="participant.microphoneStatus === DeviceStatus.On" 
+            class="icon-on"
+          />
+          <IconMicOff size="20" v-else class="icon-off" />
+          <IconCameraOn
+            size="20"
+            v-if="participant.cameraStatus === DeviceStatus.On" 
+            class="icon-on"
+          />
+          <IconCameraOff size="20" v-else class="icon-off" />
+        </div>
+      </div>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { computed } from 'vue';
+import { IconRefresh, IconMicOn, IconMicOff, IconCameraOn, IconCameraOff } from '@tencentcloud/uikit-base-component-vue3';
+import { 
+  useRoomParticipantState,
+  Avatar,
+  RoomParticipantRole,
+  DeviceStatus
+} from 'tuikit-atomicx-vue3/room';
+
+const { 
+  localParticipant, 
+  participantList,
+  getParticipantList,
+  transferOwner
+} = useRoomParticipantState();
+
+const handleRefresh = async () => {
+  await getParticipantList({ cursor: '' });
+};
+</script>
+
+<style scoped>
+.participant-list {  display: flex;  flex-direction: column;  width: 400px;  height: 100%;  background-color: white;}.list-header {  display: flex;  align-items: center;  justify-content: space-between;  padding: 16px;  border-bottom: 1px solid #e0e0e0;}.list-header h3 {  margin: 0;  font-size: 16px;  font-weight: 600;}.list-content {  flex: 1;  overflow-y: auto;  padding: 8px;}.participant-item {  display: flex;  align-items: center;  gap: 12px;  padding: 12px;  border-radius: 8px;  transition: background-color 0.2s;}.participant-item:hover {  background-color: #f5f5f5;}.participant-item.is-local {  background-color: #e3f2fd;}.user-info {  flex: 1;  min-width: 0;}.user-name {  display: flex;  align-items: center;  gap: 6px;  font-size: 14px;  font-weight: 500;}.badge {  padding: 2px 6px;  background-color: #4caf50;  color: white;  border-radius: 3px;  font-size: 12px;}.role-badge {  padding: 2px 6px;  border-radius: 3px;  font-size: 12px;}.role-badge.owner {  background-color: #ff9800;  color: white;}.role-badge.admin {  background-color: #2196f3;  color: white;}.device-status {  display: flex;  gap: 8px;}.icon-on {  color: #4caf50;}.icon-off {  color: #999;}.action-button {  padding: 4px 8px;  background: transparent;  border: none;  cursor: pointer;  border-radius: 4px;  color: #666;}.action-button:hover {  background-color: #f0f0f0;}
+</style>
+```
+
+### 步骤3：设置用户自定义信息
+
+开发者可以使用 [updateParticipantMetaData](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#updateParticipantMetaData) 接口设置用户的自定义数据，用于**实现职务**、**购买状态**等能力。更新之后 `metaData` 信息将被维护在 `participantList` 对应用户的响应式数据中。
+``` typescript
+<template>
+  <div v-for="participant in participantList" :key="participant.userId">
+    <span>{{ participant.userName }}</span>
+    <span v-if="participant.metaData">
+      {{ JSON.parse(participant.metaData).level }}
+    </span>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { computed } from 'vue';
+import { IconRefresh, IconMicOn, IconMicOff, IconCameraOn, IconCameraOff } from '@tencentcloud/uikit-base-component-vue3';
+import { 
+  useRoomParticipantState,
+} from 'tuikit-atomicx-vue3/room';
+
+const { 
+  updateParticipantMetaData,
+} = useRoomParticipantState();
+
+await updateParticipantMetaData({
+ userId: '', // 指定用户 id
+ metaData: JSON.stringify({ level: 1 }),   // 业务自定义信息
+})
+</script>
+```
+
+### 步骤4：管理成员身份
+
+房主可以通过 [setAdmin](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#setAdmin) 接口变更用户角色为管理员, 通过 [revokeAdmin](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#revokeAdmin) 方法撤销用户管理员身份。
+``` typescript
+const { setAdmin, revokeAdmin } = useRoomParticipantState();
+
+// 将普通用户设置为管理员
+await setAdmin({ userId });
+
+// 将管理员设置为普通用户
+await revokeAdmin({ userId });
+```
+
+### 步骤5：管理成员媒体设备
+
+房主及管理员可以通过 [closeParticipantDevice](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#closeParticipantDevice) 接口远程控制其他成员的媒体设备，以维持会议环境的安静及有序。
+``` typescript
+import { useRoomParticipantState, DeviceType } from 'tuikit-atomicx-vue3/room';
+const { closeParticipantDevice } = useRoomParticipantState();
+
+// 强制关闭指定成员的麦克风
+async function handleCloseUserMicrophone(userId: string) {
+  await closeParticipantDevice({
+    userId,
+    deviceType: DeviceType.Microphone,
+  });
+}
+
+// 强制关闭指定成员的摄像头
+async function handleCloseUserCamera(userId: string) {
+  await closeParticipantDevice({
+    userId,
+    deviceType: DeviceType.Camera,
+  });
+}
+```
+
+### 步骤6：开启全局状态管理
+
+房主及管理员可通过 [disableAllDevices](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#disableAllDevices) 及 [disableAllMessages](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#disableAllMessages) 接口开启房间全局状态管理。
+
+#### **禁用房间内所有普通用户的媒体设备**
+``` typescript
+import { useRoomParticipantState, DeviceType } from 'tuikit-atomicx-vue3/room';
+const { closeParticipantDevice } = useRoomParticipantState();
+
+// 强制关闭所有普通成员的麦克风
+async function handleDisableAllMicrophone() {
+  await disableAllDevices({
+    deviceType: DeviceType.Microphone,
+    disable: true,
+  });
+}
+
+// 解除全员麦克风禁用
+async function handleEnableAllMicrophone() {
+  await disableAllDevices({
+    deviceType: DeviceType.Microphone,
+    disable: false,
+  });
+}
+
+// 强制关闭所有普通成员的摄像头
+async function handleDisableAllCamera() {
+  await disableAllDevices({
+    deviceType: DeviceType.Camera,
+    disable: true,
+  });
+}
+
+// 解除全员摄像头禁用
+async function handleEnableAllCamera() {
+  await disableAllDevices({
+    deviceType: DeviceType.Camera,
+    disable: false,
+  });
+}
+```
+
+#### **禁用房间内所有普通用户的会中聊天**
+``` typescript
+import { useRoomParticipantState, DeviceType } from 'tuikit-atomicx-vue3/room';
+const { disableAllMessages } = useRoomParticipantState();
+
+// 强制禁用所有普通成员的聊天能力
+async function handleDisableAllMessage() {
+  await disableAllMessages({
+    disable: true,
+  });
+}
+```
+
+### **步骤7：**监控成员发言状态
+
+通过 [speakingUsers](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#speakingUsers) 可以实时获取房间内正在说话的用户及其音量大小。
+``` typescript
+const { speakingUsers } = useRoomParticipantState();
+
+// 判断用户是否正在说话
+const isSpeaking = (userId: string) => speakingUsers.value.has(userId);
+// 获取用户实时音量 (0-100)
+const getVolume = (userId: string) => speakingUsers.value.get(userId) || 0;
+```
+
+### 步骤8：踢出房间内成员
+
+房主及管理员可以通过 [kickParticipant](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#kickParticipant) 接口将用户移出房间。
+``` typescript
+const { kickParticipant } = useRoomParticipantState();
+
+// 将用户踢出房间
+await kickParticipant({ userId });
+```
+
+### 步骤9：邀请其他人加入房间
+
+实际业务中，您可能需要向未进房的用户发起呼叫邀请。Atomicx 提供了完整的呼叫系统支持，请查看 [会中呼叫](https://write.woa.com/document/197380078005506048)。
+
+## API 文档
+<table>
+<tr>
+<td rowspan="1" colSpan="1" >**State/Component**</td>
+
+<td rowspan="1" colSpan="1" >**功能描述**</td>
+
+<td rowspan="1" colSpan="1" >**API 文档**</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >**useRoomParticipantState**</td>
+
+<td rowspan="1" colSpan="1" >包含房间内用户数据，用户管理接口。</td>
+
+<td rowspan="1" colSpan="1" >[API 文档](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#module-RoomParticipantState)</td>
+</tr>
+</table>
+
+
+## 开发建议
+
+**权限校验：**在 UI 层建议通过 `participant.role` 判断当前用户的操作权限，对不具备管理权限的用户隐藏**踢人**或**禁言**按钮。
+``` typescript
+<script setup>
+import { RoomParticipantRole } from 'tuikit-atomicx-vue3/room';
+
+const { localParticipant } = useRoomParticipantState();
+
+// 判断当前用户是否有管理权限
+const hasAdminPermission = computed(() => {
+  return localParticipant.value.role === RoomParticipantRole.Owner ||
+         localParticipant.value.role === RoomParticipantRole.Admin;
+});
+</script>
+
+// 在模板中使用
+<template>
+<button v-if="hasAdminPermission" @click="handleKick">踢出</button>
+<template>
+```

package/resource/doc/roomkit/vue/features/room-state.md

@@ -0,0 +1,291 @@
+本篇文档将详细指导您如何使用 Atomicx 的 [useRoomState](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#module-RoomState) 管理房间的完整生命周期，包括创建、加入、离开以及结束房间，以及处理关键的房间状态通知。以下时序图演示了房间从创建到销毁的主要流程。
+
+![](https://write-document-release-1258344699.cos.ap-guangzhou.tencentcos.cn/100027337918/b5d730a6dfdc11f08775525400bf7822.png)
+
+
+## 功能介绍
+
+[useRoomState](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#module-RoomState) 是 Atomicx 方案中负责房间管理的核心 Hook。它封装了复杂的底层信令流程，开发者可以通过简单的响应式数据和方法调用来驱动房间状态。
+- **创建与加入：**通过 [createAndJoinRoom](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#createAndJoinRoom) 方法创建并加入房间，或通过 [joinRoom](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#joinRoom) 方法加入已有房间。
+
+- **状态实时同步：**`useRoomState`Hook 内部维护 [currentRoom](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#currentRoom) 响应式数据，自动同步房间名称、模式及成员数等信息。
+
+- **权限分明的退出机制：**针对不同角色提供了清晰的操作边界。普通成员可以使用 [leaveRoom](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#leaveRoom) 退出；而房主（主持人）则拥有 [endRoom](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#endRoom) 权限，可以一键结束房间并销毁房间资源。
+
+
+## **前提条件**
+
+用户已经通过 [useLoginState](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#module-LoginState) 完成登录鉴权，请参考 [接入概览](https://write.woa.com/document/197379797539790848)。
+
+## 实现房间管理
+
+### 步骤1：导入 useRoomState
+``` typescript
+import { useRoomState } from 'tuikit-atomicx-vue3/room';
+
+const { 
+  createAndJoinRoom, 
+  joinRoom, 
+  leaveRoom, 
+  endRoom,
+  currentRoom 
+} = useRoomState();
+```
+
+### 步骤2：创建房间
+
+创建房间（房主）：使用 [createAndJoinRoom](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#createAndJoinRoom)，调用成功后该用户将自动获得房主权限。
+
+> **注意：**
+> 
+
+> 创建房间时指定的 roomId 建议由业务后台生成并下发，以确保房间 Id 在全局应用中的唯一性与稳定性。
+> 
+
+- **示例一：用户创建房间**
+
+   ``` typescript
+   import { useRoomState } from 'tuikit-atomicx-vue3/room';
+   const { createAndJoinRoom } = useRoomState();
+   
+   await createAndJoinRoom({
+     roomId: 'YOUR_ROOM_ID',    // 指定房间 Id，由业务后台生成
+   })
+   ```
+- **示例二：用户创建房间并指定房间名称**
+
+   ``` typescript
+   import { useRoomState } from 'tuikit-atomicx-vue3/room';
+   const { createAndJoinRoom } = useRoomState();
+   
+   await createAndJoinRoom({
+     roomId: 'YOUR_ROOM_ID',    // 指定房间 Id，由业务后台生成
+     options: {
+       roomName: '我的临时房间'
+     }
+   })
+   ```
+- **示例三：用户创建密码房间**
+
+   ``` typescript
+   import { useRoomState } from 'tuikit-atomicx-vue3/room';
+   const { createAndJoinRoom } = useRoomState();
+   
+   await createAndJoinRoom({
+     roomId: 'YOUR_ROOM_ID',    // 指定房间 Id，由业务后台生成
+     options: {
+       roomName: '我的临时房间',
+       password: '123456',
+     }
+   })
+   ```   
+
+   > **说明：**
+   > 
+
+   > 创建者在调用 [createAndJoinRoom](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#createAndJoinRoom) 时会自动加入房间，无需输入密码。
+   > 
+
+- **示例四：用户创建房间并配置成员管理信息**
+
+   ``` typescript
+   import { useRoomState } from 'tuikit-atomicx-vue3/room';
+   const { createAndJoinRoom } = useRoomState();
+   
+   await createAndJoinRoom({
+     roomId: 'YOUR_ROOM_ID',    // 指定房间 Id，由业务后台生成
+     options: {
+       roomName: '我的临时房间',
+       password: '123456',
+       isAllMicrophoneDisabled: true,   // 开启全员静音
+       isAllCameraDisabled: true,       // 开启全员静画
+       isAllScreenShareDisabled: true,  // 开启全员禁止屏幕共享
+       isAllMessageDisabled: true,      // 开启全员禁止发会中消息
+     }
+   })
+   ```   
+
+   > **说明：**
+   > 
+
+   > 成员管理配置信息仅对普通成员生效，房主和管理员不受限制。如需在房间创建后修改成员管理配置或单独管理成员权限，请参考 [成员管理](https://write.woa.com/document/197380064613830656)。
+   > 
+
+
+### 步骤3：用户加入已有房间
+
+登录用户可以调用 [joinRoom](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#joinRoom) 加入已有房间。Atomicx 仅支持用户同时加入一个房间。
+- **示例一：用户加入房间**
+
+   ``` typescript
+   import { useRoomState } from 'tuikit-atomicx-vue3/room';
+   const { joinRoom } = useRoomState();
+   
+   await joinRoom({
+     roomId: 'YOUR_ROOM_ID',    // 指定房间 Id，由业务后台生成
+   })
+   ```
+- **示例二：用户加入密码房间**
+
+   ``` typescript
+   import { useRoomState } from 'tuikit-atomicx-vue3/room';
+   const { joinRoom } = useRoomState();
+   
+   await joinRoom({
+     roomId: 'YOUR_ROOM_ID',    // 指定房间 Id，由业务后台生成
+     password: '123456',
+   })
+   ```
+
+### 步骤4：更新房间信息
+
+房主可以在创建房间后使用 [updateRoomInfo](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#updateRoomInfo) 更新房间名称和密码。
+``` typescript
+import { useRoomState } from 'tuikit-atomicx-vue3/room';
+const { updateRoomInfo } = useRoomState();
+
+await updateRoomInfo({
+  roomId: 'YOUR_ROOM_ID',    // 指定房间 Id，由业务后台生成
+  options: {
+     roomName: '新的房间名称',
+     password: '234567',
+  },
+})
+```
+
+> **说明：**
+> 
+
+> 房主必须在房间内才能调用 [updateRoomInfo](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#updateRoomInfo)。如果房主已离开房间，需要重新加入后才能更新房间信息。
+> 
+
+
+### 步骤5：离开房间
+
+房主及普通用户均可调用 [leaveRoom](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#leaveRoom) 接口离开房间，使用该接口的前提是用户已经通过 [createAndJoinRoom](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#createAndJoinRoom) 或者 [joinRoom](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#joinRoom) 接口加入房间。
+``` typescript
+import { useRoomState } from 'tuikit-atomicx-vue3/room';
+const { leaveRoom } = useRoomState();
+
+await leaveRoom();
+```
+
+### 步骤6：销毁房间
+
+仅房主可调用 [endRoom](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#endRoom) 接口销毁房间，使用该接口的前提是用户已经通过 [createAndJoinRoom](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#createAndJoinRoom) 创建房间或者已经获取房主身份。
+``` typescript
+import { useRoomState } from 'tuikit-atomicx-vue3/room';
+const { endRoom } = useRoomState();
+
+await endRoom();
+```
+
+> **说明：**
+> 
+> - 如果房主离开房间但未调用 [endRoom](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#endRoom)，房间将继续存在，直到满足自动回收条件（连续 6 小时无用户）。
+> - 房主可以通过 [transferOwner](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#transferOwner) 接口将房主身份转移给其他用户。
+
+
+### 步骤7：异常退出处理
+
+#### 处理房间被销毁事件
+
+普通用户可通过监听 `RoomEvent.onRoomEnded` 事件处理房间被销毁的业务交互。
+``` typescript
+import { useRoomState, RoomEvent } from 'tuikit-atomicx-vue3/room';
+import { TUIMessageBox } from '@tencentcloud/uikit-base-component-vue3';
+const { subscribeEvent, unsubscribeEvent } = useRoomState();
+
+function onRoomEnded() {
+  TUIMessageBox.alert({
+    title: '通知',
+    content: '房主已解散房间',
+  });
+}
+
+// 在组件加载时监听 RoomEvent
+subscribeEvent(RoomEvent.onRoomEnded, onRoomEnded);
+// 在组件销毁时取消监听 RoomEvent
+unsubscribeEvent(RoomEvent.onRoomEnded, onRoomEnded);
+```
+
+#### 处理用户被踢退房事件
+
+普通用户可通过监听 `RoomParticipantEvent.onKickedFromRoom` 事件处理用户被踢出房间的业务交互。
+``` typescript
+import { useRoomParticipantState, RoomParticipantEvent, KickedOutOfRoomReason } from 'tuikit-atomicx-vue3/room';
+import { TUIMessageBox } from '@tencentcloud/uikit-base-component-vue3';
+
+const { subscribeEvent, unsubscribeEvent } = useRoomParticipantState();
+
+function onKickedFromRoom({ reason }: { reason: KickedOutOfRoomReason; message: string }) {
+    let notice = '';
+    switch (reason) {
+      case KickedOutOfRoomReason.KickedByAdmin:
+        notice = '您已被房主移出房间';
+        break;
+      case KickedOutOfRoomReason.ReplacedByAnotherDevice:
+        notice = '您的账号已在其他设备登录';
+        break;
+      case KickedOutOfRoomReason.KickedByServer:
+        notice = '您已被服务器移出房间';
+        break;
+      case KickedOutOfRoomReason.ConnectionTimeout:
+        notice = '网络连接超时，正在退出房间';
+        break;
+      case KickedOutOfRoomReason.InvalidStatusOnReconnect:
+        notice = '房间已解散或您在离线期间已被移出';
+        break;
+      case KickedOutOfRoomReason.RoomLimitExceeded:
+        notice = '房间人数已达上限，无法加入';
+        break;
+      default:
+        notice = '您已被移出房间';
+        break;
+    }
+    TUIMessageBox.alert({
+      title: '通知',
+      content: notice,
+    });
+  }
+
+// 在组件加载时监听 RoomParticipantEvent
+subscribeEvent(RoomParticipantEvent.onKickedFromRoom, onKickedFromRoom);
+// 在组件销毁时取消监听 RoomParticipantEvent
+unsubscribeEvent(RoomParticipantEvent.onKickedFromRoom, onKickedFromRoom);
+```
+
+## 进阶实现
+
+当前文档介绍的是快速创建并立即加入一个房间，适用于即时多人音视频互通场景。
+
+但在现实商业场景中，我们往往需要提前规划：设置房间的主题、预定特定的开始与结束时间、并邀请参与者。参与者可以在多人音视频房间开始前收到提醒，并准时接入。
+
+Atomicx 提供了完整的预约房间能力，包括：
+- **预定房间：**提前设定多人房间时间与参与人名单。
+
+- **预约列表**：查看并管理自己名下的所有待开始的多人房间。
+
+- **入会提醒：**支持开始前的自动提醒逻辑。
+
+
+   如果您需要实现上述更复杂的商业多人音视频房间管理逻辑，请参考：[预定房间](https://write.woa.com/document/197380092150673408)。
+
+
+## 常见问题
+
+### 房间内已经没有用户但房间未被解散，房间是否会一直存在？
+
+房间内连续 6 小时无用户进入时，后台将尝试回收房间。
+
+### 房间内已经没有用户但房间未被解散，是否会产生费用消耗？
+
+没有用户但是未被解散的房间仅占用套餐群组数，不产生分钟数消耗和额外费用消耗。
+
+### 一个用户可以同时加入多个房间吗？
+
+Atomicx 提供的 `useRoomState` 为单例接口，仅支持用户同时加入一个房间。若您需要支持一个用户同时加入多个房间，欢迎 [联系我们](https://cloud.tencent.com/document/product/647/19906) 提交反馈。
+
+### 最多支持多少人同时加入房间？
+
+房间内用户数量上限和您的套餐包相关，具体请查看 [TUIRoomKit 套餐包说明](https://cloud.tencent.com/document/product/647/104842#function)。