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

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

@@ -14,13 +14,13 @@
 ## 核心概念
 
 在开始集成之前，您可能需要通过下表了解一下`RoomStore`中与预订房间相关的几个核心概念：
-| **核心概念** | **类型** | **核心职责与描述** |
+| <strong>核心概念</strong> | <strong>类型</strong> | <strong>核心职责与描述</strong> |
 | --- | --- | --- |
-| [RoomStatus](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/roomstatus) | `enum` | 代表当前房间的状态，包含：<br>- scheduled（预定状态）。<br>- running（进行中）。 |
-| [ScheduleRoomOptions](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/scheduleroomoptions) | `struct` | 代表预定房间的核心数据结构，包含：开始时间，结束时间，预定成员列表等。 |
-| [RoomState](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/roomstate) | `struct` | 代表房间状态管理的核心数据结构，负责维护用户的房间相关状态信息。<br>核心属性：<br>- `scheduledRoomList`存储了当前账号下所有预定的房间列表信息。<br>- `scheduledRoomListCursor` 则代表预定房间列表的分页游标。 |
-| [RoomEvent](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/roomevent) | `enum` | 代表房间动态的实时事件。其中包含预定房间相关的事件。 |
-| [RoomStore](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/roomstore) | `class` | 这是与房间全生命周期相关的核心类。通过它，您可以主动发起预定房间，获取预定房间列表等功能，并通过订阅其 `roomEventPublisher` 来接收与预定房间相关的实时动态事件。 |
+| <a href="https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/roomstatus">RoomStatus</a> | <code>enum</code> | 代表当前房间的状态，包含：<br>- scheduled（预定状态）。<br>- running（进行中）。 |
+| <a href="https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/scheduleroomoptions">ScheduleRoomOptions</a> | <code>struct</code> | 代表预定房间的核心数据结构，包含：开始时间，结束时间，预定成员列表等。 |
+| <a href="https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/roomstate">RoomState</a> | <code>struct</code> | 代表房间状态管理的核心数据结构，负责维护用户的房间相关状态信息。<br>核心属性：<br>- <code>scheduledRoomList</code>存储了当前账号下所有预定的房间列表信息。<br>- <code>scheduledRoomListCursor</code> 则代表预定房间列表的分页游标。 |
+| <a href="https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/roomevent">RoomEvent</a> | <code>enum</code> | 代表房间动态的实时事件。其中包含预定房间相关的事件。 |
+| <a href="https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/roomstore">RoomStore</a> | <code>class</code> | 这是与房间全生命周期相关的核心类。通过它，您可以主动发起预定房间，获取预定房间列表等功能，并通过订阅其 <code>roomEventPublisher</code> 来接收与预定房间相关的实时动态事件。 |
 
 ## 实现步骤
 
@@ -77,23 +77,23 @@ func scheduleRoom() {
 ##### scheduleRoom 接口参数详细说明
 | 参数名 | 类型 | 必填 | 说明 |
 | --- | --- | --- | --- |
-| `roomID` | `String` | 是 | - 字符串类型的房间唯一标识符。<br>- 限制长度为 0-48 字节。<br>- 建议仅包含数字、英文字母（区分大小写）、下划线（_）和连字符（-）。避免使用空格和中文字符。 |
-| `options` | `ScheduleRoomOptions` | 是 | - 创建房间配置对象。<br>- 详细用法请参考：ScheduleRoomOptions 结构体详细说明 |
-| `completion` | `CompletionClosure` | 否 | 操作完成回调，用于返回预定房间的结果。若预定失败则会返回错误码和错误信息。 |
+| <code>roomID</code> | <code>String</code> | 是 | - 字符串类型的房间唯一标识符。<br>- 限制长度为 0-48 字节。<br>- 建议仅包含数字、英文字母（区分大小写）、下划线（_）和连字符（-）。避免使用空格和中文字符。 |
+| <code>options</code> | <code>ScheduleRoomOptions</code> | 是 | - 创建房间配置对象。<br>- 详细用法请参考：ScheduleRoomOptions 结构体详细说明 |
+| <code>completion</code> | <code>CompletionClosure</code> | 否 | 操作完成回调，用于返回预定房间的结果。若预定失败则会返回错误码和错误信息。 |
 
 ##### ScheduleRoomOptions 结构体详细说明
 | 参数名 | 类型 | 必填 | 说明 |
 | --- | --- | --- | --- |
-| `roomName` | `String` | 否 | - 房间名称，可以不设置，默认为空字符串。<br>- 限制长度为 0-60 字节。<br>- 支持中英文、数字、特殊字符。 |
-| `password` | `String` | 否 | - 房间密码，空字符串 "" 通常表示该房间不设密码。<br>- 限制长度为 0-32 字节。<br>- 推荐使用 4-8 位纯数字，方便移动端输入。设置后，其他用户加入房间时需输入密码。建议不要存储明文敏感信息。 |
-| `scheduleStartTime` | `Int` | 是 | - 预定的房间开始时间（Unix 时间戳，单位：秒）。<br>- 取值必须大于当前时间。<br>- 推荐设置为未来的整分时间。例如：1736164800（代表 2025-01-06 20:00:00）。 |
-| `scheduleEndTime` | `Int` | 是 | - 预定的房间结束时间（Unix 时间戳，单位：秒）。<br>- 取值必须大于 `scheduleStartTime`。<br>- 建议根据预期时长设置。例如：`scheduleStartTime` + 3600（预定 1 小时时长的房间）。 |
-| `reminderSecondsBeforeStart` | `Int` | 否 | - 房间开始前的提醒时间（单位：秒）。用于系统触发开始提醒。<br>- 推荐设置为 300（5分钟）或 900（15分钟），用于在 App 端触发本地通知。 |
-| `scheduleAttendees` | `[String]` | 否 | - 预定参与者的用户 ID 列表，在预定房间时设置，系统将向这些用户发送预约邀请。<br>- 获取请参考获取指定预定房间的参与成员列表。 |
-| `isAllMicrophoneDisabled` | `Bool` | 否 | 是否全员禁止打开麦克风。开启后，除房主/管理员外，普通参与者默认禁止打开麦克风。<br>- true : 禁止<br>- false ：取消禁止 （默认值） |
-| `isAllCameraDisabled` | `Bool` | 否 | 是否全员禁止打开摄像头。开启后，除房主/管理员外，普通参与者默认禁止打开摄像头。<br>- true : 禁止<br>- false ：取消禁止（默认值） |
-| `isAllScreenShareDisabled` | `Bool` | 否 | 是否全员禁止发起屏幕共享。开启后，仅房主/管理员可进行屏幕共享。<br>- true : 禁止<br>- false ：取消禁止（默认值） |
-| `isAllMessageDisabled` | `Bool` | 否 | 是否全员禁止发送聊天消息（禁言）。开启后，普通参与者无法在房间内发送文字消息。<br>- true : 禁止<br>- false ：取消禁止（默认值） |
+| <code>roomName</code> | <code>String</code> | 否 | - 房间名称，可以不设置，默认为空字符串。<br>- 限制长度为 0-60 字节。<br>- 支持中英文、数字、特殊字符。 |
+| <code>password</code> | <code>String</code> | 否 | - 房间密码，空字符串 "" 通常表示该房间不设密码。<br>- 限制长度为 0-32 字节。<br>- 推荐使用 4-8 位纯数字，方便移动端输入。设置后，其他用户加入房间时需输入密码。建议不要存储明文敏感信息。 |
+| <code>scheduleStartTime</code> | <code>Int</code> | 是 | - 预定的房间开始时间（Unix 时间戳，单位：秒）。<br>- 取值必须大于当前时间。<br>- 推荐设置为未来的整分时间。例如：1736164800（代表 2025-01-06 20:00:00）。 |
+| <code>scheduleEndTime</code> | <code>Int</code> | 是 | - 预定的房间结束时间（Unix 时间戳，单位：秒）。<br>- 取值必须大于 <code>scheduleStartTime</code>。<br>- 建议根据预期时长设置。例如：<code>scheduleStartTime</code> + 3600（预定 1 小时时长的房间）。 |
+| <code>reminderSecondsBeforeStart</code> | <code>Int</code> | 否 | - 房间开始前的提醒时间（单位：秒）。用于系统触发开始提醒。<br>- 推荐设置为 300（5分钟）或 900（15分钟），用于在 App 端触发本地通知。 |
+| <code>scheduleAttendees</code> | <code>[String]</code> | 否 | - 预定参与者的用户 ID 列表，在预定房间时设置，系统将向这些用户发送预约邀请。<br>- 获取请参考获取指定预定房间的参与成员列表。 |
+| <code>isAllMicrophoneDisabled</code> | <code>Bool</code> | 否 | 是否全员禁止打开麦克风。开启后，除房主/管理员外，普通参与者默认禁止打开麦克风。<br>- true : 禁止<br>- false ：取消禁止 （默认值） |
+| <code>isAllCameraDisabled</code> | <code>Bool</code> | 否 | 是否全员禁止打开摄像头。开启后，除房主/管理员外，普通参与者默认禁止打开摄像头。<br>- true : 禁止<br>- false ：取消禁止（默认值） |
+| <code>isAllScreenShareDisabled</code> | <code>Bool</code> | 否 | 是否全员禁止发起屏幕共享。开启后，仅房主/管理员可进行屏幕共享。<br>- true : 禁止<br>- false ：取消禁止（默认值） |
+| <code>isAllMessageDisabled</code> | <code>Bool</code> | 否 | 是否全员禁止发送聊天消息（禁言）。开启后，普通参与者无法在房间内发送文字消息。<br>- true : 禁止<br>- false ：取消禁止（默认值） |
 
 #### **二、取消房间预定**
 
@@ -151,17 +151,17 @@ func updateScheduledRoom() {
 ##### updateScheduledRoom 接口参数详细说明
 | 参数名 | 类型 | 必填 | 说明 |
 | --- | --- | --- | --- |
-| `roomID` | `String` | 是 | - 字符串类型的房间唯一标识符。<br>- 限制长度为 0-48 字节。<br>- 建议仅包含数字、英文字母（区分大小写）、下划线（_）和连字符（-）。避免使用空格和中文字符。 |
-| `options` | `ScheduleRoomOptions` | 是 | - 预定房间配置对象。<br>- 详细用法请参考：ScheduleRoomOptions 结构体详细说明 |
-| `modifyFlag` | `ScheduleRoomOptions.ModifyFlag` | 是 | - 更新房间属性修改标志位。目前支持更新**房间名称**、**开始时间**、**结束时间。**<br>- 详细用法请参考：ScheduleRoomOptions.ModifyFlag 详细说明。 |
-| `completion` | `CompletionClosure` | 否 | 操作完成回调，用于返回更新预定房间的结果。若更新失败则会返回错误码和错误信息。 |
+| <code>roomID</code> | <code>String</code> | 是 | - 字符串类型的房间唯一标识符。<br>- 限制长度为 0-48 字节。<br>- 建议仅包含数字、英文字母（区分大小写）、下划线（_）和连字符（-）。避免使用空格和中文字符。 |
+| <code>options</code> | <code>ScheduleRoomOptions</code> | 是 | - 预定房间配置对象。<br>- 详细用法请参考：ScheduleRoomOptions 结构体详细说明 |
+| <code>modifyFlag</code> | <code>ScheduleRoomOptions.ModifyFlag</code> | 是 | - 更新房间属性修改标志位。目前支持更新<strong>房间名称</strong>、<strong>开始时间</strong>、<strong>结束时间。</strong><br>- 详细用法请参考：ScheduleRoomOptions.ModifyFlag 详细说明。 |
+| <code>completion</code> | <code>CompletionClosure</code> | 否 | 操作完成回调，用于返回更新预定房间的结果。若更新失败则会返回错误码和错误信息。 |
 
 **ScheduleRoomOptions.ModifyFlag 详细说明**
 | 参数名 | 类型 | 说明 |
 | --- | --- | --- |
-| `roomName` | `UInt` | - 修改预定房间名称时的标识位。<br>- 当修改`ScheduleRoomOptions`中的`roomName`后，需要同步设置`ModifyFlag`的<br>- `roomName`标识位。 |
-| `scheduleStartTime` | `UInt` | - 修改预定房间开始时间时的标识位。<br>- 当修改`ScheduleRoomOptions`中的`scheduleStartTime`后，需要同步设置`ModifyFlag`的`scheduleStartTime`标识位。 |
-| `scheduleEndTime` | `UInt` | - 修改预定房间结束时间时的标识位。<br>- 当修改`ScheduleRoomOptions`中的`scheduleEndTime`后，需要同步设置`ModifyFlag`的`scheduleEndTime`标识位。 |
+| <code>roomName</code> | <code>UInt</code> | - 修改预定房间名称时的标识位。<br>- 当修改<code>ScheduleRoomOptions</code>中的<code>roomName</code>后，需要同步设置<code>ModifyFlag</code>的<br>- <code>roomName</code>标识位。 |
+| <code>scheduleStartTime</code> | <code>UInt</code> | - 修改预定房间开始时间时的标识位。<br>- 当修改<code>ScheduleRoomOptions</code>中的<code>scheduleStartTime</code>后，需要同步设置<code>ModifyFlag</code>的<code>scheduleStartTime</code>标识位。 |
+| <code>scheduleEndTime</code> | <code>UInt</code> | - 修改预定房间结束时间时的标识位。<br>- 当修改<code>ScheduleRoomOptions</code>中的<code>scheduleEndTime</code>后，需要同步设置<code>ModifyFlag</code>的<code>scheduleEndTime</code>标识位。 |
 
 #### **四、添加、删除参与成员**
 
@@ -292,9 +292,9 @@ private func subscribeScheduledRoomListState() {
 ```
 
 ## API 文档
-| **Store/Component** | **功能描述** | **API文档** |
+| <strong>Store/Component</strong> | <strong>功能描述</strong> | <strong>API文档</strong> |
 | --- | --- | --- |
-| **RoomStore** | 房间全生命周期管理：创建并加入 / 加入 / 离开 / 结束房间 / 更新、获取房间信息 / 房间预定 / 呼叫房间外成员 / 监听房间内被动事件（例如房间解散，房间信息更新等）。 | [API 文档](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/roomstore) |
+| <strong>RoomStore</strong> | 房间全生命周期管理：创建并加入 / 加入 / 离开 / 结束房间 / 更新、获取房间信息 / 房间预定 / 呼叫房间外成员 / 监听房间内被动事件（例如房间解散，房间信息更新等）。 | <a href="https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/roomstore">API 文档</a> |
 
 ## 常见问题
 

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

@@ -25,6 +25,8 @@
 ### 步骤1：发起呼叫（邀请者）
 
 邀请者调用 [callUserToRoom](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#callUserToRoom) 接口发起邀请。请确保邀请者当前已在房间内（即 [currentRoom](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#currentRoom) 不为空），否则无法发起呼叫。
+
+【Vue3】
 ``` typescript
 import { useRoomState } from 'tuikit-atomicx-vue3/room';
 
@@ -54,9 +56,41 @@ const inviteUser = async () => {
 };
 ```
 
+【React】
+``` typescript
+import { useRoomState } from 'tuikit-atomicx-react/room';
+
+const { currentRoom, callUserToRoom } = useRoomState();
+
+const inviteUser = async () => {
+  // 会中呼叫必须关联一个已存在的 roomId，因此需先校验当前用户的进房状态
+  if (!currentRoom) {
+    console.warn('请先进入房间再发起邀请');
+    return;
+  }
+
+  try {
+    const resultMap = await callUserToRoom({
+      roomId: currentRoom.roomId, // 被邀请者将要加入的房间 ID
+      userIdList: ['user1', 'user2'],    // 目标用户 ID 数组，支持单人或多人
+      timeout: 60,                        // 邀请有效时长（秒），超时后双方会触发 onCallTimeout
+      // extensionInfo 可用于传递业务自定义数据，例如邀请类型、附加消息等
+      extensionInfo: JSON.stringify({ type: 'emergency', priority: 'high' })
+    });
+
+    // resultMap 返回每个 userId 对应的状态，例如 Success、AlreadyInRoom (已在房) 或 AlreadyInCalling (通话中)
+    console.log('邀请发送完成，详情状态映射:', resultMap);
+  } catch (error) {
+    console.error('呼叫请求发送失败，请检查网络或登录状态:', error);
+  }
+};
+```
+
 ### 步骤2：监听呼叫事件（被邀请者）
 
 被邀请者需要监听 `onCallReceived` 事件。建议在例如 `App.vue`等长驻组件中实现，以确保无论用户在哪个页面都能响应。
+
+【Vue3】
 ``` typescript
 import { ref, onMounted, onUnmounted } from 'vue';
 import { useRoomState, RoomEvent } from 'tuikit-atomicx-vue3/room';
@@ -136,30 +170,110 @@ onUnmounted(() => {
 });
 ```
 
+【React】
+``` typescript
+import { useState, useEffect } from 'react';
+import { useRoomState, RoomEvent } from 'tuikit-atomicx-react/room';
+
+const {
+  subscribeEvent,
+  unsubscribeEvent,
+  acceptCall,
+  rejectCall,
+  joinRoom,
+  currentRoom
+} = useRoomState();
+
+const [showInviteDialog, setShowInviteDialog] = useState(false); // 控制 UI 弹窗显隐
+const [currentCallInfo, setCurrentCallInfo] = useState(null);   // 缓存收到的邀请上下文
+
+const handleCallReceived = async ({ roomInfo, call, extensionInfo }) => {
+  // 冲突处理：如果用户当前已经在会议中，根据业务策略通常应直接拒绝新邀请，防止干扰
+  if (currentRoom?.roomId) {
+    await rejectCall({ roomId: roomInfo.roomId });
+    return;
+  }
+
+  // 记录邀请详情，用于在 UI 上展示邀请者名称或业务透传数据
+  setCurrentCallInfo({ roomInfo, call });
+  setShowInviteDialog(true);
+};
+
+// 接受邀请逻辑
+const onUserAccept = async () => {
+  if (!currentCallInfo) return;
+  const { roomId } = currentCallInfo.roomInfo;
+
+  try {
+    // 关键流程 A：响应信令。告知邀请者已接受，使其能更新 UI（例如显示"对方已接听"）
+    await acceptCall({ roomId });
+
+    // 关键流程 B：执行进房。只有调用 joinRoom 才会真正开启音视频推拉流链路
+    await joinRoom({ roomId });
+  } catch (error) {
+    console.error('接受呼叫后的进房操作失败:', error);
+  } finally {
+    closeDialog();
+  }
+};
+
+// 拒绝邀请逻辑
+const onUserReject = async () => {
+  if (currentCallInfo) {
+    // 告知邀请者已拒绝，邀请者会收到 onCallRejected 事件
+    await rejectCall({ roomId: currentCallInfo.roomInfo.roomId });
+  }
+  closeDialog();
+};
+
+const closeDialog = () => {
+  setShowInviteDialog(false);
+  setCurrentCallInfo(null);
+};
+
+// 事件全生命周期管理：确保在组件挂载时监听，销毁时移除，防止事件溢出
+useEffect(() => {
+  subscribeEvent(RoomEvent.onCallReceived, handleCallReceived);
+
+  // 监听导致邀请结束的各种异常/同步事件，确保 UI 弹窗能及时闭合
+  subscribeEvent(RoomEvent.onCallCancelled, closeDialog); // 邀请者取消了呼叫
+  subscribeEvent(RoomEvent.onCallTimeout, closeDialog);   // 呼叫超时未响应
+  subscribeEvent(RoomEvent.onCallHandledByOtherDevice, closeDialog); // 用户在其他设备已处理该呼叫
+
+  return () => {
+    // 移除所有监听器，避免在组件销毁后继续执行 handleCallReceived 导致内存泄漏或报错
+    unsubscribeEvent(RoomEvent.onCallReceived, handleCallReceived);
+    unsubscribeEvent(RoomEvent.onCallCancelled, closeDialog);
+    unsubscribeEvent(RoomEvent.onCallTimeout, closeDialog);
+    unsubscribeEvent(RoomEvent.onCallHandledByOtherDevice, closeDialog);
+  };
+}, []);
+```
+
 ## 实践教程：提升呼叫接通率
 
 为了在业务中获得更高的呼叫接通率，除了基础功能的实现外，建议参考以下策略优化用户体验：
 
-### 1. 增强呼叫感知（避免用户遗漏）
+### 增强呼叫感知（避免用户遗漏）
 
 由于 Web 端特性，浏览器静音或页面处于后台运行状态可能导致用户遗漏呼叫。
 - **视觉提醒**：利用 [Page Visibility API](https://developer.mozilla.org/en-US/docs/Web/API/Page_Visibility_API) 检测页面可见性状态。若页面处于后台，可通过循环修改 `document.title` 实现标题栏闪烁提示（例如：“【新邀请】UserA 邀请您入会...”），以吸引用户注意。
 
 - **听觉提醒**：在 `onCallReceived` 事件触发时播放高优先级的提示铃声。注意：需遵循浏览器的 [自动播放策略](https://developer.mozilla.org/zh-CN/docs/Web/Media/Guides/Autoplay)，大部分浏览器在缺乏用户交互（例如点击、触摸或按键）的情况下会限制音频自动播放。
 
-### 2. 丰富邀请上下文（提升接听意愿）
+### 丰富邀请上下文（提升接听意愿）
 
 缺乏明确意图的邀请容易被用户拒绝。建议充分利用 `extensionInfo` 字段传递关键业务信息，以提升用户的接听意愿。
 - **传递业务上下文**：利用 `extensionInfo` 透传如 `reason`（例如：“项目紧急评审”）、`level`（例如：“P0故障排查”）等业务字段，告知用户呼叫的紧迫性和重要性。
 
-### 3. 多通道触达兜底（确保消息可达）
+### 多通道触达兜底（确保消息可达）
 
 受限于 Web 端机制，浏览器进程结束将无法接收实时信令。建议采取以下替代方案以确保触达：
 - **浏览器系统通知**：引导用户授权 [Web Notification API](https://developer.mozilla.org/en-US/docs/Web/API/Notification)。只要浏览器进程未关闭（包括最小化或在后台标签页），即可触发操作系统级别的弹窗通知，有效提醒用户。
 
 - **多通道触达**：建议结合业务后端逻辑，在检测到用户不在线或超时未响应时，通过**短信**、**邮件**或**企业微信**等外部渠道发送入会链接，实现全方位触达。
 
-### 4. 智能重试机制（解决“接受邀请后进房失败”）
+### 智能重试机制（解决“接受邀请后进房失败”）
 
 在弱网或其他不稳定环境下，用户点击接受邀请后调用 `joinRoom` 可能会出现偶发性失败。
 - **自动重试**：建议在 `onUserAccept` 的异常处理逻辑（`catch`）中引入 2-3 次自动重试机制（推荐结合指数退避策略），以最大程度确保用户点击“接受”后能成功加入会议。
@@ -215,6 +329,7 @@ onUnmounted(() => {
 腾讯云在 GitHub 上提供了示例项目 [atomicx-vite-vue3-ts](https://github.com/Tencent-RTC/TUIRoomKit/tree/main/Web/example/atomicx-vite-vue3-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)|

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

@@ -19,6 +19,8 @@
 使用 [startCameraTest](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#startCameraTest) 方法启动摄像头测试。该方法仅用于本地预览，不会产生网络流量。
 
 **代码示例：**
+
+【Vue3】
 ``` typescript
 <template>
   <div class="preview-container">
@@ -115,11 +117,108 @@ const handleCameraChange = async (event: Event) => {
 </style>
 ```
 
+【React】
+``` typescript
+import React, { useEffect } from 'react';
+import {
+  useDeviceState,
+  DeviceStatus,
+  DeviceError,
+} from 'tuikit-atomicx-react/room';
+
+const CameraTest: React.FC = () => {
+  const {
+    isCameraTesting,
+    isCameraTestLoading,
+    cameraList,
+    currentCamera,
+    startCameraTest,
+    stopCameraTest,
+    getCameraList,
+    setCurrentCamera
+  } = useDeviceState();
+
+  useEffect(() => {
+    return () => {
+      if (isCameraTesting) {
+        stopCameraTest();
+      }
+    };
+  }, []);
+
+  const toggleCameraTest = async () => {
+    if (isCameraTesting) {
+      await stopCameraTest();
+    } else {
+      const previewElement = document.getElementById('camera-preview');
+      if (previewElement) {
+        await startCameraTest({ view: previewElement });
+      }
+    }
+  };
+
+  const handleCameraChange = async (event: React.ChangeEvent<HTMLSelectElement>) => {
+    const deviceId = event.target.value;
+    try {
+      await setCurrentCamera({ deviceId });
+    } catch (error) {
+      console.error('切换摄像头失败:', error);
+    }
+  };
+
+  return (
+    <div className="preview-container">
+      {/* 摄像头预览区域 */}
+      <div id="camera-preview" className="camera-preview">
+        {/* 加载状态 */}
+        {isCameraTestLoading && (
+          <div className="loading-overlay">
+            <div className="loading-spinner" />
+            <span>正在启动摄像头...</span>
+          </div>
+        )}
+      </div>
+
+      {/* 摄像头选择 */}
+      <div className="camera-selector">
+        <label>选择摄像头</label>
+        <select
+          value={currentCamera?.deviceId}
+          onChange={handleCameraChange}
+          disabled={isCameraTestLoading}
+        >
+          {cameraList.map(camera => (
+            <option key={camera.deviceId} value={camera.deviceId}>
+              {camera.deviceName}
+            </option>
+          ))}
+        </select>
+      </div>
+
+      {/* 控制按钮 */}
+      <div className="control-buttons">
+        <button onClick={getCameraList}>获取摄像头列表</button>
+        <button
+          onClick={toggleCameraTest}
+          disabled={isCameraTestLoading}
+        >
+          {isCameraTesting ? '停止预览' : '开始预览'}
+        </button>
+      </div>
+    </div>
+  );
+};
+
+export default CameraTest;
+```
+
 ### 步骤2：麦克风测试
 
 通过 [startMicrophoneTest](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#startMicrophoneTest) 启动麦克风测试，并利用 [testingMicVolume](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#testingMicVolume) 实现 UI 音量条的实时波动。
 
 **代码示例：**
+
+【Vue3】
 ``` typescript
 <template>
   <div class="microphone-test">
@@ -238,11 +337,127 @@ const handleMicrophoneChange = async (event: Event) => {
 </style>
 ```
 
+【React】
+``` typescript
+import React, { useMemo, useEffect } from 'react';
+import {
+  useDeviceState,
+  DeviceError,
+} from 'tuikit-atomicx-react/room';
+
+const MicrophoneTest: React.FC = () => {
+  const {
+    isMicrophoneTesting,
+    testingMicVolume,
+    microphoneList,
+    currentMicrophone,
+    startMicrophoneTest,
+    stopMicrophoneTest,
+    getMicrophoneList,
+    setCurrentMicrophone
+  } = useDeviceState();
+
+  // Volume bar style class
+  const volumeClass = useMemo(() => {
+    const volume = testingMicVolume;
+    if (volume === 0) return 'volume-zero';
+    if (volume < 30) return 'volume-low';
+    if (volume < 70) return 'volume-medium';
+    return 'volume-high';
+  }, [testingMicVolume]);
+
+  // Cleanup: stop test
+  useEffect(() => {
+    return () => {
+      if (isMicrophoneTesting) {
+        stopMicrophoneTest();
+      }
+    };
+  }, []);
+
+  // Toggle microphone test
+  const toggleMicrophoneTest = async () => {
+    if (isMicrophoneTesting) {
+      await stopMicrophoneTest();
+    } else {
+      try {
+        await startMicrophoneTest({ interval: 200 });
+      } catch (error) {
+        console.error('启动麦克风测试失败:', error);
+      }
+    }
+  };
+
+  // Switch microphone device
+  const handleMicrophoneChange = async (event: React.ChangeEvent<HTMLSelectElement>) => {
+    const deviceId = event.target.value;
+    try {
+      await setCurrentMicrophone({ deviceId });
+    } catch (error) {
+      console.error('切换麦克风失败:', error);
+    }
+  };
+
+  return (
+    <div className="microphone-test">
+      {/* 音量显示 */}
+      <div className="volume-display">
+        <div className="volume-label">麦克风音量</div>
+        <div className="volume-bar-container">
+          <div
+            className={`volume-bar ${volumeClass}`}
+            style={{ width: `${testingMicVolume}%` }}
+          />
+        </div>
+        <div className="volume-value">{testingMicVolume}</div>
+      </div>
+
+      {/* 麦克风选择 */}
+      <div className="microphone-selector">
+        <label>选择麦克风</label>
+        <select
+          value={currentMicrophone?.deviceId}
+          onChange={handleMicrophoneChange}
+          disabled={isMicrophoneTesting}
+        >
+          {microphoneList.map(mic => (
+            <option key={mic.deviceId} value={mic.deviceId}>
+              {mic.deviceName}
+            </option>
+          ))}
+        </select>
+      </div>
+
+      {/* 控制按钮 */}
+      <div className="control-buttons">
+        <button onClick={getMicrophoneList}>
+          获取设备
+        </button>
+        <button onClick={toggleMicrophoneTest}>
+          {isMicrophoneTesting ? '停止测试' : '开始测试'}
+        </button>
+      </div>
+
+      {/* 测试提示 */}
+      {isMicrophoneTesting && (
+        <div className="test-tip">
+          <span>请对着麦克风说话，查看音量变化</span>
+        </div>
+      )}
+    </div>
+  );
+};
+
+export default MicrophoneTest;
+```
+
 ### 步骤3：扬声器测试
 
 使用 [startSpeakerTest](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#startSpeakerTest) 方法播放一段指定的音频文件来确认扬声器是否工作正常。
 
 **代码示例：**
+
+【Vue3】
 ``` typescript
 <template>
   <div class="speaker-test">
@@ -342,10 +557,110 @@ const handleSpeakerChange = async (event: Event) => {
 </style>
 ```
 
+【React】
+``` typescript
+import React, { useEffect } from 'react';
+import { useDeviceState } from 'tuikit-atomicx-react/room';
+
+const SpeakerTest: React.FC = () => {
+  const {
+    isSpeakerTesting,
+    speakerList,
+    currentSpeaker,
+    startSpeakerTest,
+    stopSpeakerTest,
+    getSpeakerList,
+    setCurrentSpeaker,
+  } = useDeviceState();
+
+  // Test audio file path
+  // Note: This URL is for development testing only. In production, use your own audio file. Recommended: 3-5 second MP3 format.
+  const testAudioPath = 'https://web.sdk.qcloud.com/trtc/electron/download/resources/media/TestSpeaker.mp3';
+
+  // Cleanup: stop test
+  useEffect(() => {
+    return () => {
+      if (isSpeakerTesting) {
+        stopSpeakerTest();
+      }
+    };
+  }, []);
+
+  // Toggle speaker test
+  const toggleSpeakerTest = async () => {
+    if (isSpeakerTesting) {
+      await stopSpeakerTest();
+    } else {
+      try {
+        await startSpeakerTest({ filePath: testAudioPath });
+      } catch (error) {
+        console.error('启动扬声器测试失败:', error);
+      }
+    }
+  };
+
+  // Switch speaker device
+  const handleSpeakerChange = async (event: React.ChangeEvent<HTMLSelectElement>) => {
+    const deviceId = event.target.value;
+    try {
+      await setCurrentSpeaker({ deviceId });
+    } catch (error) {
+      console.error('切换扬声器失败:', error);
+    }
+  };
+
+  return (
+    <div className="speaker-test">
+      {/* 扬声器选择 */}
+      <div className="speaker-selector">
+        <label>选择扬声器</label>
+        <select
+          value={currentSpeaker?.deviceId}
+          onChange={handleSpeakerChange}
+          disabled={isSpeakerTesting}
+        >
+          {speakerList.map(speaker => (
+            <option key={speaker.deviceId} value={speaker.deviceId}>
+              {speaker.deviceName}
+            </option>
+          ))}
+        </select>
+      </div>
+
+      {/* 控制按钮 */}
+      <div className="control-buttons">
+        <button onClick={getSpeakerList}>获取扬声器列表</button>
+        <button
+          onClick={toggleSpeakerTest}
+          disabled={isSpeakerTesting}
+        >
+          {isSpeakerTesting ? '正在播放...' : '播放测试音频'}
+        </button>
+        {isSpeakerTesting && (
+          <button onClick={stopSpeakerTest}>
+            停止播放
+          </button>
+        )}
+      </div>
+
+      {/* 测试提示 */}
+      {isSpeakerTesting && (
+        <div className="test-tip">
+          <span>正在播放测试音频，请确认是否能听到声音</span>
+        </div>
+      )}
+    </div>
+  );
+};
+
+export default SpeakerTest;
+```
+
 ## API 文档
-| **State/Component** | **功能描述** | **API 文档** |
-| --- | --- | --- |
-| **useDeviceState** | 包含音视频设备状态，音视频设备列表及操作接口。 | [API 文档](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#module-DeviceState) |
+
+|**State/Component**|**功能描述**|**API 文档**|
+|---------|---------|---------|
+|**useDeviceState**|包含音视频设备状态，音视频设备列表及操作接口。|[API 文档](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#module-DeviceState)|
 
 ## 常见问题