@tencentcloud/sdk-mcp 1.3.0 → 1.3.2

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

@@ -0,0 +1,338 @@
+本篇文档将指导您使用 Atomicx 的核心视图组件 `RoomView` 实现实时音视频房间的视频画面渲染。通过配置布局模板和利用组件插槽，您可以快速实现视频布局的切换与个性化定制。
+
+`RoomView` 是 Atomicx 中负责视频画面渲染的主容器组件。它会自动处理视频流的订阅、渲染和释放，您只需关注其布局配置和 UI 增强。
+
+![](https://write-document-release-1258344699.cos.ap-guangzhou.tencentcos.cn/100027337918/c09ab2a6e07f11f0a5a25254007c27c5.png)
+
+
+## 核心能力
+
+`RoomView` 作为多人音视频房间的核心视图容器，内置了多项企业级音视频处理能力：
+- **智能性能管理**：支持视口内视频流懒加载，并能根据流区域尺寸，远端流数量自动进行高低清流切换，显著降低系统能耗与带宽占用。
+
+- **精细化排序策略**：系统根据角色（主持人优先）与媒体状态（音视频开启优先）自动调整画面顺序。
+
+- **交互式演讲者模式**：支持双击锁定主画面，并在侧边栏或顶部栏布局中支持收起非核心区域，聚焦演示内容。
+
+- **沉浸式视觉设计**：所有视频窗口强制保持 `16:9` 的标准比例，并配合交互显示的工具栏，提供无干扰的多人音视频房间体验。
+
+
+## 可定制范围
+
+`RoomView` 仅聚焦于底层视频流的播放，而将视图层的所有“表现权”交给了开发者。使用 `RoomView` 您可以自由定义：
+- **布局切换**：根据业务场景（例如演讲模式或讨论模式）实时变换布局。
+
+- **视频挂件 UI：**包含昵称标签、音量动态波形、角色徽章等。
+
+
+## **前提条件**
+- 用户已经通过 [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)。
+
+- 已在 `App.vue` 中配置全局 `UIKitProvider`，具体请参考 [配置 App.vue](https://cloud.tencent.com/document/product/647/81962#ce98ee15-b0cb-43af-81da-70f51231430e)。
+
+
+## 实现视频布局功能
+
+### 步骤1：引入并渲染基础布局
+
+在您的会议页面（例如 RoomLayoutView.vue）中引入 `RoomView` 及布局枚举 `RoomLayoutTemplate`。
+``` typescript
+<template>
+  <div class="room-container">
+    <RoomView />
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { RoomView } from 'tuikit-atomicx-vue3/room';
+</script>
+
+<style lang="scss">
+.room-container {
+ width: 100%;
+ height: 100%;
+}
+</style>
+```
+
+> **注意：**
+> 
+
+> `RoomView` 会自动占满父容器的高度和宽度，请确保其父容器具备明确的尺寸。
+> 
+
+
+### 步骤2：切换布局模式
+
+您可以根据业务逻辑（例如点击切换按钮）动态更新 `RoomView` 属性 `layoutTemplate` 的值。
+<table>
+<tr>
+<td rowspan="1" colSpan="1" >属性名</td>
+
+<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" >`layoutTemplate`</td>
+
+<td rowspan="1" colSpan="1" >`RoomLayoutTemplate`</td>
+
+<td rowspan="1" colSpan="1" >`RoomLayoutTemplate.GridLayout`</td>
+
+<td rowspan="1" colSpan="1" >视频流布局</td>
+</tr>
+</table>
+
+
+`RoomLayoutTemplate` 可选值解析：
+<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" >宫格布局</td>
+
+<td rowspan="1" colSpan="1" >`RoomLayoutTemplate.GridLayout`</td>
+
+<td rowspan="1" colSpan="1" >默认布局。所有参会者画面均匀排列，参会者超出 9 人时支持翻页。</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >侧边栏布局</td>
+
+<td rowspan="1" colSpan="1" >`RoomLayoutTemplate.SidebarLayout`</td>
+
+<td rowspan="1" colSpan="1" >主画面突出显示，其余参会者画面以侧边栏的形式排列，适用于演讲、报告等场景。</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >顶部栏布局</td>
+
+<td rowspan="1" colSpan="1" >`RoomLayoutTemplate.CinemaLayout`</td>
+
+<td rowspan="1" colSpan="1" >主画面突出显示，其余参会者画面以顶部栏的形式排列，适用于演讲、报告等场景。<br></td>
+</tr>
+</table>
+
+``` typescript
+<template>
+  <!-- 添加布局切换按钮 -->
+  <div class="layout-switcher">
+    <button @click="switchLayout(RoomLayoutTemplate.GridLayout)">宫格</button>
+    <button @click="switchLayout(RoomLayoutTemplate.SidebarLayout)">侧边栏</button>
+    <button @click="switchLayout(RoomLayoutTemplate.CinemaLayout)">顶部栏</button>
+  </div>
+  <div class="room-container">
+    <RoomView :layoutTemplate="currentLayout" />
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { RoomView, RoomLayoutTemplate } from 'tuikit-atomicx-vue3/room';
+// 默认使用宫格布局
+const currentLayout = ref(RoomLayoutTemplate.GridLayout);
+
+// 切换布局
+const switchLayout = (layout: RoomLayoutTemplate) => {
+  currentLayout.value = layout;
+};
+</script>
+
+<style lang="scss">
+.room-container {
+ width: 100%;
+ height: 100%;
+}
+</style>
+```
+
+### 步骤3：实现视频流挂件信息
+
+您可以通过使用 `participantViewUI` 插槽，为视频画面定制 UI 显示内容（例如设置昵称，添加自定义图标）。
+
+![](https://write-document-release-1258344699.cos.ap-guangzhou.tencentcos.cn/100027337918/3728c9fce00311f09bba52540044a08e.png)
+
+<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" >`participant`</td>
+
+<td rowspan="1" colSpan="1" >`RoomParticipant`</td>
+
+<td rowspan="1" colSpan="1" >当前视频流对应的参会者对象，包含用户的 `userId`、`userName`、`role` 等实时状态信息。</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >`streamType`</td>
+
+<td rowspan="1" colSpan="1" >`VideoStreamType`</td>
+
+<td rowspan="1" colSpan="1" >区分当前是摄像头流（Camera）还是屏幕分享流（Screen）</td>
+</tr>
+</table>
+
+
+#### 准备视觉资源
+
+为了提供完整的交互反馈，建议您提前准备以下图标：
+- 麦克风状态图标：区分开启、静音及动态音量条。
+
+- 身份标识图标：用于区分房主（Owner）、管理员（Admin）与普通成员。
+
+- 网络信号图标：展示实时的上/下行网络质量。
+   
+
+   > **特别说明：**
+   > 
+
+   > 我们在示例项目的 @tencentcloud/uikit-base-component-vue3 npm 包中提供了免版权的图标，您可以直接引入使用。
+   > 
+
+
+#### 实现代码示例
+1. 新增文件 `ParticipantViewUI.vue` 实现单个视频流挂件层 UI 渲染逻辑。
+
+   ``` typescript
+   <template>
+     <div class="stream-cover-container">
+       <div class="corner-user-info-container">
+         <div
+           v-if="showMasterIcon || showAdminIcon"
+           :class="{ 'master-icon': showMasterIcon, 'admin-icon': showAdminIcon }"
+         >
+           <IconUser />
+         </div>
+         <div v-if="!isScreenStream" :class="['audio-icon-container']">
+           <div class="audio-level-container">
+             <div class="audio-level" :style="audioLevelStyle" />
+           </div>
+           <IconMicOff v-if="!isMicrophoneOn" class="audio-icon" size="20" />
+           <IconMicOn v-else class="audio-icon" size="20" />
+         </div>
+         <span class="user-name" :title="displayName">
+           {{ displayName }}
+         </span>
+       </div>
+     </div>
+   </template>
+   
+   <script setup lang="ts">
+   import { computed, defineProps } from 'vue';
+   import {
+     IconUser,
+     IconMicOff,
+     IconMicOn,
+   } from '@tencentcloud/uikit-base-component-vue3';
+   import { RoomParticipantRole, DeviceStatus, VideoStreamType, useRoomParticipantState } from 'tuikit-atomicx-vue3/room';
+   import type { RoomParticipant } from 'tuikit-atomicx-vue3/room';
+   
+   interface Props {
+     participant: RoomParticipant;
+     streamType: VideoStreamType;
+   }
+   const props = defineProps<Props>();
+   
+   const { speakingUsers } = useRoomParticipantState();
+   const speakingAudioVolume = computed(() => speakingUsers.value.get(props.participant.userId) || 0);
+   const audioLevelStyle = computed(() => {
+     if (props.participant.microphoneStatus === DeviceStatus.Off || !speakingAudioVolume.value) {
+       return '';
+     }
+     return `height: ${speakingAudioVolume.value * 4}%`;
+   });
+   
+   const isMicrophoneOn = computed(() => props.participant.microphoneStatus === DeviceStatus.On);
+   const displayName = computed(() => props.participant.nameCard || props.participant.userName || props.participant.userId);
+   
+   const showMasterIcon = computed(() => {
+     const { role } = props.participant;
+     return role === RoomParticipantRole.Owner && props.streamType === VideoStreamType.Camera;
+   });
+   
+   const showAdminIcon = computed(() => {
+     const { role } = props.participant;
+     return (role === RoomParticipantRole.Admin && props.streamType === VideoStreamType.Camera);
+   });
+   </script>
+   
+   <style lang="scss" scoped>
+   .stream-cover-container {  position: absolute;  top: 0;  left: 0;  width: 100%;  height: 100%;  border-radius: 12px;  pointer-events: none;  .corner-user-info-container {    position: absolute;    bottom: 8px;    left: 8px;    display: flex;    align-content: center;    align-items: center;    box-sizing: border-box;    min-width: 118px;    max-width: calc(100% - 24px);    padding-right: 10px;    height: 32px;    overflow: hidden;    font-size: 14px;    color: var(--uikit-color-white-1);    border-radius: 16px;    background-color: var(--uikit-color-black-5);    .master-icon,    .admin-icon {      display: flex;      flex-shrink: 0;      align-items: center;      justify-content: center;      width: 32px;      height: 32px;      margin-left: 0;      border-radius: 50%;      background-color: var(--button-color-primary-default);    }    .admin-icon {      background-color: var(--text-color-warning);    }    .audio-icon-container {      margin-left: 4px;      position: relative;      width: 20px;      height: 20px;      flex-shrink: 0;      min-width: 20px;      &:first-child {        margin-left: 8px;      }      .audio-level-container {        position: absolute;        top: 2px;        left: 6px;        display: flex;        flex-flow: column-reverse wrap;        justify-content: space-between;        width: 8px;        height: 12px;        overflow: hidden;        border-radius: 4px;        .audio-level {          width: 100%;          background-color: var(--text-color-success);          transition: height 0.2s;        }      }      .audio-icon {        position: absolute;        top: 0;        left: 0;      }    }    .user-name {      margin-left: 4px;      overflow: hidden;      text-overflow: ellipsis;      white-space: nowrap;      min-width: 0;    }    .screen-icon {      flex-shrink: 0;      min-width: 0;      color: var(--uikit-color-white-1);      margin-left: 4px;      margin-right: 2px;    }    .screen-info {      margin-left: 4px;      font-size: 12px;      color: var(--uikit-color-white-1);      flex-shrink: 0;      min-width: 0;    }  }}
+   </style>
+   ```
+2. 配置 `RoomView` 插槽，在页面中渲染视频流挂件内容。
+
+   ``` typescript
+   <template>
+     <div class="room-container">
+       <RoomView :layout-template="currentLayout">
+         <template #participantViewUI="{ participant, streamType }">
+           <ParticipantViewUI :participant="participant" :stream-type="streamType" />
+         </template>
+       </RoomView>
+     </div>
+   </template>
+   
+   <script setup lang="ts">
+   import { ref } from 'vue';
+   import { RoomView, RoomLayoutTemplate } from 'tuikit-atomicx-vue3/room';
+   // 引入新增的 ParticipantViewUI.vue 文件
+   import ParticipantViewUI from './ParticipantViewUI.vue';
+   
+   // 默认使用宫格布局
+   const currentLayout = ref(RoomLayoutTemplate.GridLayout);
+   </script>
+   ```
+
+## 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>
+
+
+## 常见问题
+
+### **RoomView 是否包含屏幕分享流的渲染？**
+
+`RoomView` 内置远端屏幕分享流的渲染，对于本地屏幕共享您需要通过 `participantViewUI` 插槽完成本地屏幕分享的占位 UI。
+
+### RoomView 是否默认包含 UI 挂件？
+
+`RoomView` 内部无默认 UI 挂件，您可以参考 [RoomView 开源使用示例](https://github.com/Tencent-RTC/TUIRoomKit/tree/main/Web/example/atomicx-vite-vue3-ts/src/components/RoomLayoutView) 快速完成自定义 UI 挂件。
+
+### RoomView 提供的布局均不满足需求，是否可以提供更多的可选布局？
+
+`RoomView` 暂时支持宫格布局、侧边栏和顶部栏布局。如果您有定制需求请 [联系我们](https://cloud.tencent.com/document/product/647/19906)。

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

@@ -0,0 +1,349 @@
+预定房间功能允许用户提前规划会议时间、主题和入会密码。通过该功能，用户可以创建未来的会议计划，生成专属的会议号和入会链接，方便提前通知参会人员。
+
+## 适用场景
+- **企业定期会议：** 提前安排周会、月会，确保参会者提前收到通知。
+
+- **在线课堂排课：** 老师可以提前设置好一周的课程表。
+
+- **远程面试预约：** HR 为面试者和面试官预约特定的时间段。
+
+
+## 前提条件
+- **用户状态：** 用户已经通过 useLoginState 完成登录鉴权，参考 [接入概览](https://write.woa.com/document/197379797539790848)，处于**已登录**状态才能发起预定或查看预定列表。
+
+- **环境依赖：** 项目已引入 `tuikit-atomicx-vue3`。
+
+
+## 实现预定房间功能
+
+本功能提供两种集成方案，您可以根据业务需求选择最适合的一种：
+- **方案一（推荐）：** 使用 UI 组件快速集成。直接引入 `tuikit-atomicx-vue3` 提供的预定房间面板（[ScheduleRoomPanel](https://github.com/Tencent-RTC/TUIKit_Vue3/blob/main/packages/tuikit-atomicx-vue3/src/components/ScheduleRoomPanel/ScheduleRoomPanel.vue)）和预定房间列表组件（[ScheduledRoomList](https://github.com/Tencent-RTC/TUIKit_Vue3/blob/main/packages/tuikit-atomicx-vue3/src/components/ScheduleRoomPanel/ScheduledRoomList.vue)），开发成本最低。
+
+- **方案二（高级）：** 使用底层 API 自定义集成。基于 atomicx-core SDK API `useRoomState` 状态钩子自行实现 UI 和交互逻辑，灵活度最高。
+
+   ![](https://write-document-release-1258344699.cos.ap-guangzhou.tencentcos.cn/100027160512/87d4918de48011f0ab0f5254005ef0f7.png)
+
+
+## 方案一：使用 UI 组件快速集成
+
+`tuikit-atomicx-vue3` 提供了两个核心组件：
+- [**ScheduleRoomPanel**](https://github.com/Tencent-RTC/TUIKit_Vue3/blob/main/packages/tuikit-atomicx-vue3/src/components/ScheduleRoomPanel/ScheduleRoomPanel.vue)**：**预定会议的配置面板，包含时间选择、成员邀请等功能。
+
+- [**ScheduledRoomList**](https://github.com/Tencent-RTC/TUIKit_Vue3/blob/main/packages/tuikit-atomicx-vue3/src/components/ScheduleRoomPanel/ScheduledRoomList.vue)**：**展示当前用户的预定会议列表，支持点击入会、修改和取消预定。
+
+
+### 步骤1：引入组件
+``` typescript
+import { ScheduleRoomPanel, ScheduledRoomList } from 'tuikit-atomicx-vue3/room';
+```
+
+### 步骤2：使用组件
+
+在您的页面中，可以直接组合使用这两个组件。
+``` typescript
+<template>
+  <UIKitProvider theme="light" language="zh-CN">
+    <div class="schedule-container">
+      <!-- 预定按钮，点击后显示预定弹窗 -->
+      <button @click="showSchedulePanel = true">
+        预定会议
+      </button>
+
+      <!-- 预定列表组件 -->
+      <div class="list-container">
+        <!-- 监听 join-room 事件处理入会逻辑 -->
+        <ScheduledRoomList @join-room="handleJoinRoom" />
+      </div>
+
+      <!-- 预定面板弹窗 -->
+      <!-- 建议将其包裹在 Dialog 或 Modal 组件中 -->
+      <div v-if="showSchedulePanel" class="modal-mask">
+        <div class="modal-content">
+          <ScheduleRoomPanel
+            @confirm="handleScheduleConfirm"
+            @cancel="showSchedulePanel = false"
+          />
+        </div>
+      </div>
+    </div>
+  </UIKitProvider>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { UIKitProvider } from '@tencentcloud/uikit-base-component-vue3';
+import { ScheduleRoomPanel, ScheduledRoomList, useRoomState } from 'tuikit-atomicx-vue3/room';
+
+const { joinRoom } = useRoomState();
+
+const showSchedulePanel = ref(false);
+
+const handleScheduleConfirm = (roomId: string, options: Record<string, any>) => {
+  console.log('预定成功', roomId, options);
+  showSchedulePanel.value = false;
+  // 可选：显示邀请弹窗或复制链接
+};
+
+const handleJoinRoom = async (roomInfo: { roomId: string }) => {
+  console.log('点击入会', roomInfo.roomId);
+  await joinRoom(roomInfo.roomId); 
+};
+</script>
+
+<style scoped>
+.schedule-container{padding:24px;max-width:1000px;margin:0 auto;font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,'Helvetica Neue',Arial,sans-serif}button{background-color:#006eff;color:#fff;border:none;padding:10px 20px;border-radius:4px;cursor:pointer;font-size:14px;font-weight:500;transition:background-color .2s;margin-bottom:24px}button:hover{background-color:#0056cc}.list-container{background:#fff;border-radius:8px;box-shadow:0 2px 8px rgba(0,0,0,.05);padding:16px}.modal-mask{position:fixed;top:0;left:0;right:0;bottom:0;background-color:rgba(0,0,0,.4);backdrop-filter:blur(4px);display:flex;align-items:center;justify-content:center;z-index:1000}.modal-content{background-color:#fff;border-radius:8px;box-shadow:0 4px 16px rgba(0,0,0,.1);padding:24px;width:100%;max-width:480px}
+</style>
+```
+
+## 方案二：使用底层 API 自定义集成
+
+本节主要介绍如何通过 atomicx-core SDK API [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/100027160512/8dbc9bdedfae11f08304525400454e06.png)
+
+预定房间时序图
+
+
+### 步骤1：发起预定
+
+使用 [scheduleRoom](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#scheduleRoom) 方法创建一个新的预定会议。您需要指定会议的开始时间、结束时间以及房间名称等信息。
+``` typescript
+import { useRoomState } from 'tuikit-atomicx-vue3/room';
+
+const { scheduleRoom } = useRoomState();
+
+const createSchedule = async () => {
+  try {
+    // 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', // 可选：设置入会密码
+      isAllMicrophoneDisabled: false, // 可选：是否全体禁麦
+      isAllCameraDisabled: false,     // 可选：是否全体禁画
+    };
+
+    await scheduleRoom({ roomId, options });
+    console.log('预定成功', roomId);
+  } catch (error) {
+    console.error('预定失败', error);
+  }
+};
+```
+
+### 步骤2：获取预定列表
+
+使用 [getScheduledRoomList](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#getScheduledRoomList) 方法拉取当前用户的预定会议列表。列表数据会响应式更新到 [scheduledRoomList](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#scheduledRoomList) 状态中。
+``` typescript
+import { onMounted, watch } from 'vue';
+import { useRoomState } from 'tuikit-atomicx-vue3/room';
+
+const { 
+  scheduledRoomList,      // 响应式数据：预定会议列表
+  getScheduledRoomList    // 方法：拉取列表
+} = useRoomState();
+
+// 初始化加载列表
+onMounted(async () => {
+  // cursor 表示从哪里开始拉取数据，空字符串表示从头开始
+  // getScheduledRoomList 返回值包含新的 cursor
+  const { cursor } = await getScheduledRoomList({ cursor: '' }); 
+  // 如果 cursor 不为空，表示还有更多数据，可继续调用拉取
+});
+
+// 监听列表变化，实时更新 UI
+watch(scheduledRoomList, (list) => {
+  console.log('当前预定列表：', list);
+});
+```
+
+### 步骤3：修改预定
+
+如果需要调整已预定会议的时间或主题，可以使用 [updateScheduledRoom](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#updateScheduledRoom) 方法。
+``` typescript
+import { useRoomState } from 'tuikit-atomicx-vue3/room';
+
+const { updateScheduledRoom } = useRoomState();
+
+const updateRoom = async (roomId: string) => {
+  try {
+    const newStartTime = Math.floor(new Date().getTime() / 1000) + 7200; // 延后2小时
+    const options = {
+      roomName: '产品需求评审会（改期）',
+      scheduleStartTime: newStartTime,
+      scheduleEndTime: newStartTime + 1800,
+    };
+
+    await updateScheduledRoom({ roomId, options });
+    console.log('修改成功');
+  } catch (error) {
+    console.error('修改失败', error);
+  }
+};
+```
+
+### 步骤4：取消预定
+
+如果需要取消某个已预定的会议，可以调用 [cancelScheduledRoom](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#cancelScheduledRoom) 方法。
+``` typescript
+import { useRoomState } from 'tuikit-atomicx-vue3/room';
+
+const { cancelScheduledRoom } = useRoomState();
+
+const cancelRoom = async (roomId: string) => {
+  try {
+    await cancelScheduledRoom({ roomId });
+    console.log('取消成功');
+    // 取消成功后，scheduledRoomList 会自动更新，无需手动重新拉取
+  } catch (error) {
+    console.error('取消失败', error);
+  }
+};
+```
+
+### 步骤5：处理入会密码
+
+对于设置了密码的预定会议，在调用 [joinRoom](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#joinRoom) 接口入会时，需要捕获鉴权失败的错误，并引导用户输入密码。
+``` typescript
+import { useRoomState, TUIErrorCode } from 'tuikit-atomicx-vue3/room';
+
+const { joinRoom } = useRoomState();
+
+const enterRoom = async (roomId: string, password?: string) => {
+  try {
+    await joinRoom({ roomId, password });
+  } catch (error: any) {
+    // 捕获特定错误码，TUIErrorCode.ERR_NEED_PASSWORD (-2010)
+    if (error.code === TUIErrorCode.ERR_NEED_PASSWORD) {
+      console.log('该房间需要密码，请引导用户输入');
+      // 1. 弹出密码输入框
+      // 2. 获取用户输入的密码 inputPassword
+      // 3. 重新调用 enterRoom(roomId, inputPassword)
+    } else if (error.code === TUIErrorCode.ERR_WRONG_PASSWORD) {
+      console.error('密码错误，请重新输入');
+    } else {
+      console.error('入会失败', error);
+    }
+  }
+};
+```
+
+### 步骤6：监听预定事件
+
+除了被动响应数据变化，您还可以监听特定的预定事件来处理业务逻辑，例如在会议即将开始时弹出提醒。
+``` typescript
+import { onMounted, onUnmounted } from 'vue';
+import { useRoomState, RoomEvent } from 'tuikit-atomicx-vue3/room';
+
+const { subscribeEvent, unsubscribeEvent } = useRoomState();
+
+// 会议即将开始通知（默认为开始前5分钟）
+const handleRoomStartingSoon = (info: { roomInfo: any }) => {
+  console.log('会议即将开始：', info.roomInfo.roomName);
+  // 可在此处实现 Toast 提醒或系统通知
+};
+
+// 会议被取消通知
+const handleRoomCancelled = (info: { roomInfo: any; operateUser: any }) => {
+  console.log(`会议 ${info.roomInfo.roomName} 已被 ${info.operateUser.userName} 取消`);
+};
+
+// 收到新的会议邀请通知
+const handleRoomAdded = (info: { roomInfo: any }) => {
+  console.log('收到新的会议邀请：', info.roomInfo.roomName);
+};
+
+// 被移出会议通知
+const handleRemovedFromRoom = (info: { roomInfo: any; operateUser: any }) => {
+  console.log(`您已被 ${info.operateUser.userName} 移出会议 ${info.roomInfo.roomName}`);
+};
+
+onMounted(() => {
+  // 注册事件监听
+  subscribeEvent(RoomEvent.onScheduledRoomStartingSoon, handleRoomStartingSoon);
+  subscribeEvent(RoomEvent.onScheduledRoomCancelled, handleRoomCancelled);
+  subscribeEvent(RoomEvent.onAddedToScheduledRoom, handleRoomAdded);
+  subscribeEvent(RoomEvent.onRemovedFromScheduledRoom, handleRemovedFromRoom);
+});
+
+onUnmounted(() => {
+  // 移除事件监听
+  unsubscribeEvent(RoomEvent.onScheduledRoomStartingSoon, handleRoomStartingSoon);
+  unsubscribeEvent(RoomEvent.onScheduledRoomCancelled, handleRoomCancelled);
+  unsubscribeEvent(RoomEvent.onAddedToScheduledRoom, handleRoomAdded);
+  unsubscribeEvent(RoomEvent.onRemovedFromScheduledRoom, handleRemovedFromRoom);
+});
+```
+
+## 开发注意事项
+1. **时间戳单位**：SDK 中涉及的所有时间参数（例如 `scheduleStartTime`、`scheduleEndTime`）单位均为 **秒**，而非 JavaScript 中 `Date` 对象默认的毫秒。在传参前请务必执行 `/ 1000` 操作。
+
+2. **样式引入**：使用 UI 组件时，务必引入 `UIKitProvider`，否则组件样式将无法正常渲染。
+
+3. **RoomID 建议**：虽然 `scheduleRoom` 允许前端传入 `roomId`，但为了避免 ID 冲突，建议该 ID 由业务后端生成并保证全局唯一。
+
+4. **分页处理**：预定列表可能会很长，`getScheduledRoomList` 接口支持分页拉取。请关注返回值中的 `cursor` 字段，若不为空，则说明还有更多数据。
+
+
+## 常见问题
+1. **预定成功但列表不更新？**
+
+
+   请确认已登录且首屏调用过 `getScheduledRoomList`（例如 `cursor: ''`）。返回的 `cursor` 不为空需继续拉取；列表是响应式的，更新后 UI 会同步。
+
+2. `joinRoom`** 参数怎么传？**
+
+
+   推荐统一使用对象入参：`joinRoom({ roomId, password })`，避免直接传字符串导致类型不匹配或后续扩展受限。
+
+3. **时间戳用毫秒导致预约失败？**
+
+
+   所有时间相关参数必须是秒，`Date.now()` 需 `/ 1000`，否则会返回时间冲突错误。
+
+4. **房间设置了密码如何处理？**
+
+
+   捕获 `TUIErrorCode.ERR_NEED_PASSWORD` / `ERR_WRONG_PASSWORD`，弹出密码输入框，重新 `joinRoom({ roomId, password })`；错误多次后可提示联系房主重置。
+
+5. **roomId 冲突或重复？**
+
+
+   建议由后端生成全局唯一 roomId；如果前端生成，请在调度前检查冲突并做好重试策略。
+
+6. **分页怎么继续拉取？**
+
+
+   `getScheduledRoomList` 返回的 `cursor` 不为空时继续传入；为空表示已拉完。
+
+
+## **示例项目**
+
+腾讯云在 GitHub 上提供了示例项目 [atomicx-vite-vue3-ts](https://github.com/Tencent-RTC/TUIRoomKit/tree/main/Web/example/atomicx-vite-vue3-ts) ，您可以参考以实现完整的 RoomKit 功能。
+
+## 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" >**useRoomState**</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-RoomState)</td>
+</tr>
+</table>