@tencentcloud/sdk-mcp 1.4.7 → 1.6.0-beta.1

package/resource/{doc/roomkit/vue/features → knowledge/roomkit/core-sdk/vue}/schedule-room.md

@@ -1,39 +1,48 @@
 预定房间功能允许用户提前规划会议时间、主题和入会密码。通过该功能，用户可以创建未来的会议计划，生成专属的会议号和入会链接，方便提前通知参会人员。
 
 ## 适用场景
-- **企业定期会议：** 提前安排周会、月会，确保参会者提前收到通知。
+- **企业定期会议：**提前安排周会、月会，确保参会者提前收到通知。
 
-- **在线课堂排课：** 老师可以提前设置好一周的课程表。
+- **在线课堂排课：**老师可以提前设置好一周的课程表。
 
-- **远程面试预约：** HR 为面试者和面试官预约特定的时间段。
+- **远程面试预约：**HR 为面试者和面试官预约特定的时间段。
 
 ## 前提条件
-- **用户状态：** 用户已经通过 useLoginState 完成登录鉴权，参考 接入概览，处于**已登录**状态才能发起预定或查看预定列表。
+- **用户状态：**用户已经通过 useLoginState 完成登录鉴权，参考 接入概览，处于**已登录**状态才能发起预定或查看预定列表。
 
-- **环境依赖：** 项目已引入 `tuikit-atomicx-vue3`。
+- **环境依赖：**项目已引入 `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)），开发成本最低。
+- **方案一（推荐）：**使用 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 和交互逻辑，灵活度最高。
+- **方案二（高级）：**使用底层 API 自定义集成。基于 atomicx-core SDK API `useRoomState` 状态钩子自行实现 UI 和交互逻辑，灵活度最高。
 
 ## 方案一：使用 UI 组件快速集成
 
-`tuikit-atomicx-vue3` 提供了两个核心组件：
+`tuikit-atomicx-vue3` 及 `tuikit-atomicx-react`提供了两个核心组件：
 - [**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：引入组件
+
+【Vue3】
 ``` typescript
 import { ScheduleRoomPanel, ScheduledRoomList } from 'tuikit-atomicx-vue3/room';
 ```
 
+【React】
+``` typescript
+import { ScheduleRoomPanel, ScheduledRoomList } from 'tuikit-atomicx-react/room';
+```
+
 ### 步骤2：使用组件
 
 在您的页面中，可以直接组合使用这两个组件。
+
+【Vue3】
 ``` typescript
 <template>
   <UIKitProvider theme="light" language="zh-CN">
@@ -89,6 +98,59 @@ const handleJoinRoom = async (roomInfo: { roomId: string }) => {
 </style>
 ```
 
+【React】
+``` typescript
+import { useState } from 'react';
+import { UIKitProvider } from '@tencentcloud/uikit-base-component-react';
+import { ScheduleRoomPanel, ScheduledRoomList, useRoomState } from 'tuikit-atomicx-react/room';
+
+function ScheduleDemo() {
+  const { joinRoom } = useRoomState();
+  const [showSchedulePanel, setShowSchedulePanel] = useState(false);
+
+  const handleScheduleConfirm = (roomId: string, options: Record<string, any>) => {
+    console.log('预定成功', roomId, options);
+    setShowSchedulePanel(false);
+    // 可选：显示邀请弹窗或复制链接
+  };
+
+  const handleJoinRoom = async (roomInfo: { roomId: string }) => {
+    console.log('点击入会', roomInfo.roomId);
+    await joinRoom(roomInfo.roomId);
+  };
+
+  return (
+    <UIKitProvider theme="light" language="zh-CN">
+      <div className="schedule-container">
+        {/* 预定按钮，点击后显示预定弹窗 */}
+        <button onClick={() => setShowSchedulePanel(true)}>
+          预定会议
+        </button>
+
+        {/* 预定列表组件 */}
+        <div className="list-container">
+          {/* 监听 onJoinRoom 事件处理入会逻辑 */}
+          <ScheduledRoomList onJoinRoom={handleJoinRoom} />
+        </div>
+
+        {/* 预定面板弹窗 */}
+        {/* 建议将其包裹在 Dialog 或 Modal 组件中 */}
+        {showSchedulePanel && (
+          <div className="modal-mask">
+            <div className="modal-content">
+              <ScheduleRoomPanel
+                onConfirm={handleScheduleConfirm}
+                onCancel={() => setShowSchedulePanel(false)}
+              />
+            </div>
+          </div>
+        )}
+      </div>
+    </UIKitProvider>
+  );
+}
+```
+
 ## 方案二：使用底层 API 自定义集成
 
 本节主要介绍如何通过 atomicx-core SDK API [useRoomState](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#module-RoomState) 接口来实现预定房间的核心逻辑。
@@ -98,6 +160,8 @@ const handleJoinRoom = async (roomInfo: { roomId: string }) => {
 ### 步骤1：发起预定
 
 使用 [scheduleRoom](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#scheduleRoom) 方法创建一个新的预定会议。您需要指定会议的开始时间、结束时间以及房间名称等信息。
+
+【Vue3】
 ``` typescript
 import { useRoomState } from 'tuikit-atomicx-vue3/room';
 
@@ -130,9 +194,44 @@ const createSchedule = async () => {
 };
 ```
 
+【React】
+``` typescript
+import { useRoomState } from 'tuikit-atomicx-react/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) 状态中。
+
+【Vue3】
 ``` typescript
 import { onMounted, watch } from 'vue';
 import { useRoomState } from 'tuikit-atomicx-vue3/room';
@@ -156,9 +255,37 @@ watch(scheduledRoomList, (list) => {
 });
 ```
 
+【React】
+``` typescript
+import { useEffect } from 'react';
+import { useRoomState } from 'tuikit-atomicx-react/room';
+
+const {
+  scheduledRoomList,      // 预定会议列表
+  getScheduledRoomList    // 方法：拉取列表
+} = useRoomState();
+
+// 初始化加载列表
+useEffect(() => {
+  (async () => {
+    // cursor 表示从哪里开始拉取数据，空字符串表示从头开始
+    // getScheduledRoomList 返回值包含新的 cursor
+    const { cursor } = await getScheduledRoomList({ cursor: '' });
+    // 如果 cursor 不为空，表示还有更多数据，可继续调用拉取
+  })();
+}, []);
+
+// 监听列表变化，实时更新 UI
+useEffect(() => {
+  console.log('当前预定列表：', scheduledRoomList);
+}, [scheduledRoomList]);
+```
+
 ### 步骤3：修改预定
 
 如果需要调整已预定会议的时间或主题，可以使用 [updateScheduledRoom](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#updateScheduledRoom) 方法。
+
+【Vue3】
 ``` typescript
 import { useRoomState } from 'tuikit-atomicx-vue3/room';
 
@@ -181,9 +308,34 @@ const updateRoom = async (roomId: string) => {
 };
 ```
 
+【React】
+``` typescript
+import { useRoomState } from 'tuikit-atomicx-react/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) 方法。
+
+【Vue3】
 ``` typescript
 import { useRoomState } from 'tuikit-atomicx-vue3/room';
 
@@ -200,9 +352,28 @@ const cancelRoom = async (roomId: string) => {
 };
 ```
 
+【React】
+``` typescript
+import { useRoomState } from 'tuikit-atomicx-react/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) 接口入会时，需要捕获鉴权失败的错误，并引导用户输入密码。
+
+【Vue3】
 ``` typescript
 import { useRoomState, TUIErrorCode } from 'tuikit-atomicx-vue3/room';
 
@@ -227,9 +398,36 @@ const enterRoom = async (roomId: string, password?: string) => {
 };
 ```
 
+【React】
+``` typescript
+import { useRoomState, TUIErrorCode } from 'tuikit-atomicx-react/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：监听预定事件
 
 除了被动响应数据变化，您还可以监听特定的预定事件来处理业务逻辑，例如在会议即将开始时弹出提醒。
+
+【Vue3】
 ``` typescript
 import { onMounted, onUnmounted } from 'vue';
 import { useRoomState, RoomEvent } from 'tuikit-atomicx-vue3/room';
@@ -274,6 +472,50 @@ onUnmounted(() => {
 });
 ```
 
+【React】
+``` typescript
+import { useEffect } from 'react';
+import { useRoomState, RoomEvent } from 'tuikit-atomicx-react/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}`);
+};
+
+useEffect(() => {
+  // 注册事件监听
+  subscribeEvent(RoomEvent.onScheduledRoomStartingSoon, handleRoomStartingSoon);
+  subscribeEvent(RoomEvent.onScheduledRoomCancelled, handleRoomCancelled);
+  subscribeEvent(RoomEvent.onAddedToScheduledRoom, handleRoomAdded);
+  subscribeEvent(RoomEvent.onRemovedFromScheduledRoom, handleRemovedFromRoom);
+  return () => {
+    // 移除事件监听
+    unsubscribeEvent(RoomEvent.onScheduledRoomStartingSoon, handleRoomStartingSoon);
+    unsubscribeEvent(RoomEvent.onScheduledRoomCancelled, handleRoomCancelled);
+    unsubscribeEvent(RoomEvent.onAddedToScheduledRoom, handleRoomAdded);
+    unsubscribeEvent(RoomEvent.onRemovedFromScheduledRoom, handleRemovedFromRoom);
+  };
+}, []);
+```
+
 ## 开发注意事项
 1. **时间戳单位**：SDK 中涉及的所有时间参数（例如 `scheduleStartTime`、`scheduleEndTime`）单位均为 **秒**，而非 JavaScript 中 `Date` 对象默认的毫秒。在传参前请务必执行 `/ 1000` 操作。
 
@@ -288,7 +530,7 @@ onUnmounted(() => {
 
    请确认已登录且首屏调用过 `getScheduledRoomList`（例如 `cursor: ''`）。返回的 `cursor` 不为空需继续拉取；列表是响应式的，更新后 UI 会同步。
 
-2. `joinRoom`** 参数怎么传？**
+2. `joinRoom`**参数怎么传？**
 
    推荐统一使用对象入参：`joinRoom({ roomId, password })`，避免直接传字符串导致类型不匹配或后续扩展受限。
 
@@ -310,9 +552,10 @@ onUnmounted(() => {
 
 ## **示例项目**
 
-腾讯云在 GitHub 上提供了示例项目 [atomicx-vite-vue3-ts](https://github.com/Tencent-RTC/TUIRoomKit/tree/main/Web/example/atomicx-vite-vue3-ts) ，您可以参考以实现完整的 RoomKit 功能。
+腾讯云在 GitHub 上提供了示例项目 [vite-vue3-ts](https://github.com/Tencent-RTC/TUIRoomKit/tree/main/Web/example/vite-vue3-ts) 及 [vite-react-ts](https://github.com/Tencent-RTC/TUIRoomKit/tree/main/Web/example/vite-react-ts) ，您可以参考以实现完整的 RoomKit 功能。
 
 ## API 文档
-| **State/Component** | **功能描述** | **API 文档** |
-| --- | --- | --- |
-| **useRoomState** | 房间状态管理（创建、加入、预约等） | [API 文档](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#module-RoomState) |
+
+|**State/Component**|**功能描述**|**API 文档**|
+|---------|---------|---------|
+|**useRoomState**|房间状态管理（创建、加入、预约等）|[API 文档](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#module-RoomState)|