@tencentcloud/sdk-mcp 1.3.1 → 1.3.2

package/resource/doc/roomkit/vue/features/screen-share.md

@@ -0,0 +1,333 @@
+本文档指导您如何使用 Atomicx 实现屏幕分享能力，并根据屏幕分享状态处理房间内交互。
+
+## 前提条件
+- 用户已经通过 [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)。
+
+- 若在 `iframe` 中集成，需在标签中声明权限。
+
+   ``` typescript
+   <iframe allow="display-capture; fullscreen;"></iframe>
+   ```
+
+## 实现屏幕分享功能
+
+### 步骤1：开始屏幕分享
+
+使用 [startScreenShare](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#startScreenShare) 方法开始屏幕分享。在 Web 环境下，您将看到浏览器的屏幕选择器，可以选择分享整个屏幕、应用窗口或浏览器标签页。
+
+![](https://write-document-release-1258344699.cos.ap-guangzhou.tencentcos.cn/100027337918/3233e9a6dbe911f0a38652540044a08e.png)
+
+``` typescript
+import { useDeviceState } from 'tuikit-atomicx-vue3/room';
+const { startScreenShare } = useDeviceState();
+
+// 尝试开始屏幕分享，并尝试分享系统音频
+const handleStartShare = async () => {
+  try {
+    await startScreenShare({ screenAudio: true });
+  } catch (error) {
+    // 处理用户拒绝或浏览器不支持等错误
+    console.error('开始屏幕分享失败:', error);
+  }
+};
+```
+
+### 步骤2：分享系统音频
+
+通过设置 `screenAudio: true` 参数，可以在屏幕分享时同时分享系统音频。这在分享视频、演示、音乐等包含音频内容时非常有用。
+
+![](https://write-document-release-1258344699.cos.ap-guangzhou.tencentcos.cn/100027337918/3e3557c9dbe911f0a4f35254007c27c5.png)
+
+``` typescript
+import { useDeviceState } from 'tuikit-atomicx-vue3/room';
+const { startScreenShare } = useDeviceState();
+
+// 开始屏幕分享并分享系统音频
+const handleStartScreenShareWithAudio = async () => {
+  try {
+    await startScreenShare({ screenAudio: true });
+    console.log('屏幕分享（含音频）已开始');
+  } catch (error) {
+    console.error('开始屏幕分享失败:', error);
+  }
+};
+```
+
+**浏览器兼容性说明：**
+<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" >Chrome 74+</td>
+
+<td rowspan="1" colSpan="1" >支持</td>
+
+<td rowspan="1" colSpan="1" >需要在选择器中勾选**分享音频**</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >Edge 79+</td>
+
+<td rowspan="1" colSpan="1" >支持</td>
+
+<td rowspan="1" colSpan="1" >基于 Chromium，体验同 Chrome</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >Firefox</td>
+
+<td rowspan="1" colSpan="1" >不支持</td>
+
+<td rowspan="1" colSpan="1" >暂不支持系统音频分享</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >Safari</td>
+
+<td rowspan="1" colSpan="1" >不支持</td>
+
+<td rowspan="1" colSpan="1" >暂不支持系统音频分享</td>
+</tr>
+</table>
+
+
+> **注意：**
+> 
+
+> 系统音频分享需要浏览器支持，且用户在屏幕选择器中勾选**分享音频**选项。如果浏览器不支持系统音频分享，`screenAudio` 参数会被忽略，但屏幕画面分享功能不受影响，可以正常使用。
+> 
+
+
+### 步骤3：停止屏幕分享
+
+用户可以通过以下几种方式停止屏幕分享：
+1. **调用 **[**stopScreenShare()**](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#stopScreenShare)** 接口**
+
+   ``` typescript
+   import { useDeviceState, DeviceStatus } from 'tuikit-atomicx-vue3/room';
+   const { screenStatus, stopScreenShare } = useDeviceState();
+   
+   // 停止屏幕分享
+   const handleStopScreenShare = async () => {
+     try {
+       await stopScreenShare();
+       console.log('屏幕分享已停止');
+     } catch (error) {
+       console.error('停止屏幕分享失败:', error);
+     }
+   };
+   ```
+2. **点击浏览器原生的"停止分享"按钮**
+
+   ![](https://write-document-release-1258344699.cos.ap-guangzhou.tencentcos.cn/100027337918/471f5332dbe911f0809c525400454e06.png)
+
+3. **关闭被分享的窗口或标签页**
+   
+
+   > **说明：**
+   > 
+
+   > 用户使用任意一种方式停止屏幕分享时，Atomicx 都会自动更新 [screenStatus](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#screenStatus) 的状态。
+   > 
+
+
+### 步骤4：权限控制与状态监听
+
+#### **设置屏幕分享权限**
+
+您可以通过 [useRoomParticipantState](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#module-RoomParticipantState) 提供的成员管理接口控制房间内的屏幕管理权限。
+``` typescript
+import { useRoomParticipantState, DeviceType } from 'tuikit-atomicx-vue3/room';
+const { disableAllDevices } = useRoomParticipantState();
+
+// 限制仅房主/管理员可以发起屏幕分享
+async function handleDisableAllScreen() {
+  await disableAllDevices({
+    deviceType: DeviceType.Screen,
+    disable: true,
+  });
+}
+
+// 允许房间内所有用户发起屏幕分享
+async function handleEnableAllScreen() {
+  await disableAllDevices({
+    deviceType: DeviceType.Screen,
+    disable: false,
+  });
+}
+```
+
+#### **自动布局切换**
+
+当检测到房间中有用户开始屏幕分享时，建议切换到侧边栏布局（`RoomLayoutTemplate.SidebarLayout`），将分享画面放大显示，其他参会者画面显示在侧边栏。
+``` typescript
+<template>
+  <div class="room-container">
+    <RoomView :layout-template="layoutTemplate">
+      <template #participantViewUI="{ participant, streamType }">
+        <ParticipantViewUI 
+          :participant="participant" 
+          :stream-type="streamType" 
+        />
+      </template>
+    </RoomView>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref, watch } from 'vue';
+import { 
+  RoomView, 
+  RoomLayoutTemplate,
+  useRoomParticipantState
+} from 'tuikit-atomicx-vue3/room';
+
+const layoutTemplate = ref(RoomLayoutTemplate.GridLayout);
+const { participantWithScreen } = useRoomParticipantState();
+
+// 监听屏幕分享状态，自动切换布局
+watch(participantWithScreen, (participant) => {
+  if (participant) {
+    // 有人分享屏幕，切换到侧边栏布局
+    layoutTemplate.value = RoomLayoutTemplate.SidebarLayout;
+  } else {
+    // 没有人分享屏幕，切换回网格布局
+    layoutTemplate.value = RoomLayoutTemplate.GridLayout;
+  }
+});
+</script>
+```
+
+#### **限制仅一人屏幕分享**
+
+在房间中应该只允许一个人分享屏幕，当有人正在分享时，禁用其他人的分享按钮：
+``` typescript
+<script setup>
+import { computed } from 'vue';
+import { useRoomParticipantState } from 'tuikit-atomicx-vue3/room';
+
+const { participantWithScreen, localParticipant } = useRoomParticipantState();
+
+const isOtherSharing = computed(() => {
+  const sharer = participantWithScreen.value;
+  if (!sharer) return false;
+  return sharer.userId !== localParticipant.value?.userId;
+});
+
+const canStartScreenShare = computed(() => {
+  return !isOtherSharing.value;
+});
+</script>
+
+// 在模板中使用
+<template>
+  <button :disabled="!canStartScreenShare" @click="handleStartShare">
+    开始屏幕分享
+  </button>
+<template>
+```
+
+### 步骤5：处理屏幕分享错误
+
+当屏幕分享发生错误时，根据错误信息提示用户做出相应的操作。
+
+**代码示例：**
+``` typescript
+import { useDeviceState, DeviceError } from 'tuikit-atomicx-vue3/room';
+import { TUIToast } from '@tencentcloud/uikit-base-component-vue3';
+
+const { startScreenShare } = useDeviceState();
+
+try {
+  await startScreenShare();
+} catch (error: any) {
+  let message = '';
+  switch (error.name) {
+    case 'NotReadableError':
+      message = '系统禁止当前浏览器访问屏幕内容，请启用屏幕分享权限。';
+      break;
+    case 'NotAllowedError':
+      if (error.message.includes('Permission denied by system')) {
+        message = '系统禁止当前浏览器访问屏幕内容，请启用屏幕分享权限。';
+      } else {
+        message = '用户取消屏幕分享';
+      }
+      break;
+    default:
+      message = '屏幕分享过程中发生未知错误，请重试。';
+      break;
+  }
+  TUIToast.warning({
+    message,
+  });
+}
+```
+
+## 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" >**useDeviceState**</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-DeviceState)</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>
+
+
+## 常见问题
+
+### 为什么系统音频分享不生效？
+- **平台限制：**音频分享目前仅在 Chrome、Edge 等现代浏览器上支持。
+
+- **操作细节：**用户必须在浏览器弹出的屏幕选择器中，手动选择**分享音频**。
+
+- **系统限制：**部分操作系统不支持分享特定**应用窗口**的音频，建议优先选择**整个屏幕**或**浏览器标签页**。
+
+
+### 如何感知用户通过点击浏览器的“停止分享”按钮后结束屏幕分享？
+
+Atomicx 会自动监听浏览器的停止分享事件，并更新 `screenStatus` 状态。您只需要监听 `screenStatus` 的变化即可：
+``` typescript
+watch(screenStatus, (newStatus, oldStatus) => {
+  if (oldStatus === DeviceStatus.On && newStatus === DeviceStatus.Off) {
+    console.log('用户已停止屏幕分享。');
+  }
+});
+```
+
+### 移动端浏览器是否支持屏幕分享？
+
+仅桌面端浏览器支持屏幕分享，移动端浏览器不支持屏幕分享能力。
+
+### 为什么用户开启屏幕分享音频后，其他参会者看到该用户的麦克风状态显示为“开启”？
+
+这是符合预期的系统行为，原因如下：
+
+**技术原理：**`microphoneStatus`表示当前设备是否正在对外传输音频信号。当开启屏幕分享并**勾选采集系统音频**时，Atomicx SDK 会启动一条音频传输通道。由于远端接收到的是连续的音频数据流，系统无法区分音频来源是物理麦克风还是系统播放声音，因此会将音频采集状态统一标识为 `DeviceStatus.On`。
+
+**隐私说明：**请放心，这并不代表您的麦克风已经在采集说话声音。 麦克风声音是否在推送仅和麦克风控制接口（ `openLocalMicrophone` 和 `unmuteLocalMicrophone` ）有关，与屏幕分享音频采集是独立的两个通道。即使屏幕分享音频正在传输，只要未调用麦克风相关接口，您的麦克风声音不会被采集和推送。

package/resource/doc/roomkit/vue/features/virtual-background.md

@@ -0,0 +1,281 @@
+虚拟背景功能允许用户在视频通话或直播中，将真实背景替换为自定义图片或进行模糊处理。通过该功能，用户可以有效保护隐私，隐藏杂乱的背景，或者通过特定背景展示企业形象。
+
+## 适用场景
+- **远程办公/会议：** 在家中或公共场所参会时，使用背景虚化或虚拟背景隐藏真实环境，保护个人隐私。
+
+- **在线教育：** 教师使用统一的教学背景，营造专业的课堂氛围。
+
+- **品牌展示：** 企业员工在对外会议中使用带有公司 Logo 的背景图，提升品牌形象。
+
+- **趣味互动：** 社交场景下，用户更换有趣的背景图片，增加互动乐趣。
+
+
+## 前提条件
+- **用户状态：** 用户已经通过 useLoginState 完成登录鉴权，参考 [接入概览](https://write.woa.com/document/197379797539790848)，处于**已登录**状态。
+
+- **环境依赖：** 项目已引入 `tuikit-atomicx-vue3`。
+
+- **设备要求：** 需要有可用的摄像头设备，并且用户已授权摄像头访问权限。如果用户拒绝授权，虚拟背景功能将无法使用。
+
+- **资源依赖：** 虚拟背景功能依赖 AI 模型文件，为保证浏览器可以正常加载和运行这些文件，您需要完成以下步骤。
+
+  - 将 `node_modules/trtc-sdk-v5/assets` 目录发布至 CDN 或者静态资源服务器中，详情可见 [SDK 文档](https://web.sdk.qcloud.com/trtc/webrtc/doc/zh-cn/tutorial-36-advanced-virtual-background.html)。
+
+  - 若选择 [方案一：使用 UI 组件快速集成](https://write.woa.com/#1362aad9-2836-4931-b947-2f0f7836d284)，在使用 [VirtualBackgroundPanel](https://github.com/Tencent-RTC/TUIKit_Vue3/tree/main/packages/tuikit-atomicx-vue3/src/components/VirtualBackgroundPanel) 组件时，需要通过 props 传入 `assetsPath` 静态资源地址。
+
+  - 若选择 [方案二：使用底层 API 自定义集成](https://write.woa.com/#b941dd3e-0f43-48af-8aa4-8818ab74a80e)，在使用 [initVirtualBackground](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#initVirtualBackground) 接口时，需要传入 `assetsPath` 静态资源地址。
+
+
+## 实现虚拟背景功能
+
+本功能提供两种集成方案，您可以根据业务需求选择最适合的一种：
+- **方案一（推荐）：** 使用 UI 组件快速集成。直接引入 `tuikit-atomicx-vue3` 提供的虚拟背景面板组件（[VirtualBackgroundPanel](https://github.com/Tencent-RTC/TUIKit_Vue3/tree/main/packages/tuikit-atomicx-vue3/src/components/VirtualBackgroundPanel)），将其嵌入到您的应用弹窗或侧边栏中，开发成本最低。
+
+- **方案二（高级）：** 使用底层 API 自定义集成。基于 atomicx-core SDK API [useVirtualBackgroundState](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#module-VirtualBackgroundState) 状态钩子自行实现 UI 和交互逻辑，灵活度最高。
+
+   ![虚拟背景](https://write-document-release-1258344699.cos.ap-guangzhou.tencentcos.cn/100027160512/1d881d05dee711f09143525400bf7822.png)
+
+   虚拟背景
+
+
+## 方案一：使用 UI 组件快速集成
+
+`tuikit-atomicx-vue3` 提供了核心设置面板组件：
+- [**VirtualBackgroundPanel**](https://github.com/Tencent-RTC/TUIKit_Vue3/tree/main/packages/tuikit-atomicx-vue3/src/components/VirtualBackgroundPanel)**：** 虚拟背景的配置面板，包含背景虚化、图片选择和预览功能。
+
+
+### 步骤1：引入组件
+``` typescript
+import { VirtualBackgroundPanel } from 'tuikit-atomicx-vue3/room';
+```
+
+### 步骤2：使用组件
+
+通常建议将 [VirtualBackgroundPanel](https://github.com/Tencent-RTC/TUIKit_Vue3/tree/main/packages/tuikit-atomicx-vue3/src/components/VirtualBackgroundPanel) 放置在一个弹窗（Dialog）或模态框（Modal）中，通过按钮点击触发显示。
+
+**以下示例展示了如何实现一个点击按钮弹出虚拟背景设置的完整交互：**
+
+> **注意：**
+> 
+> - 将 `node_modules/trtc-sdk-v5/assets` 目录发布至 CDN 或者静态资源服务器中，详情可见 [SDK 文档](https://web.sdk.qcloud.com/trtc/webrtc/doc/zh-cn/tutorial-36-advanced-virtual-background.html)。
+> - 在使用 [VirtualBackgroundPanel](https://github.com/Tencent-RTC/TUIKit_Vue3/tree/main/packages/tuikit-atomicx-vue3/src/components/VirtualBackgroundPanel) 组件时，通过 props 传入 `assetsPath` 静态资源地址。
+> - 所有 TUIKit 组件必须包裹在 [UIKitProvider](https://write.woa.com/document/197379797539790848) 内部，否则将无法获取上下文依赖，导致样式异常。
+
+``` typescript
+<template>
+  <UIKitProvider theme="light" language="zh-CN">
+    <div class="toolbar-container">
+      <!-- 1. 触发按钮 -->
+      <button @click="openSettings">设置虚拟背景</button>
+
+      <!-- 2. 设置弹窗 -->
+      <div v-if="showSettings" class="modal-mask">
+        <div class="modal-content">
+          <div class="modal-header">
+            <span>虚拟背景</span>
+            <button @click="showSettings = false">关闭</button>
+          </div>
+          
+          <div class="modal-body">
+            <!-- 3. 引入面板组件 -->
+            <!-- @close 事件：当用户点击面板内的关闭按钮（如有）时触发 -->
+            <VirtualBackgroundPanel assetsPath='https://xxxx/assets' @close="showSettings = false" />
+          </div>
+        </div>
+      </div>
+    </div>
+  </UIKitProvider>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { UIKitProvider } from '@tencentcloud/uikit-base-component-vue3';
+import { VirtualBackgroundPanel, useVirtualBackgroundState, useDeviceState } from 'tuikit-atomicx-vue3/room';
+
+const showSettings = ref(false);
+const { isSupported } = useVirtualBackgroundState();
+const { cameraList } = useDeviceState();
+
+const openSettings = () => {
+  // 1. 检查浏览器是否支持虚拟背景
+  if (!isSupported()) {
+    alert('当前浏览器不支持虚拟背景');
+    return;
+  }
+  
+  // 2. 检查是否有可用摄像头
+  if (cameraList.value.length === 0) {
+    alert('未检测到摄像头，无法设置虚拟背景');
+    return;
+  }
+
+  // 3. 打开设置面板
+  showSettings.value = true;
+};
+</script>
+
+<style scoped>
+.modal-mask{position:fixed;top:0;left:0;width:100%;height:100%;background:rgba(0,0,0,0.5);display:flex;justify-content:center;align-items:center;z-index:1000}.modal-content{background:white;width:600px;border-radius:8px;overflow:hidden}.modal-header{padding:16px;display:flex;justify-content:space-between;border-bottom:1px solid #eee}
+</style>
+```
+
+## 方案二：使用底层 API 自定义集成
+
+本节主要介绍如何通过 atomicx-core SDK API [**useVirtualBackgroundState**](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#module-VirtualBackgroundState) 接口来实现虚拟背景。
+
+### 步骤1：初始化与检测
+
+在调用虚拟背景功能前，必须先检查浏览器是否支持，并初始化资源路径。
+
+> **注意：**
+> 
+> - 将 node_modules/trtc-sdk-v5/assets 目录发布至 CDN 或者静态资源服务器中，详情可见 [SDK 文档](https://web.sdk.qcloud.com/trtc/webrtc/doc/zh-cn/tutorial-36-advanced-virtual-background.html)。
+> - 在使用 [initVirtualBackground](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#initVirtualBackground) 接口时，传入 assetsPath 静态资源地址。
+> - 虚拟背景功能依赖摄像头设备。可使用 [useDeviceState](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#module-DeviceState) 检查设备状态。
+> - [cameraList](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#cameraList)：当前可用的摄像头设备列表，如果列表为空，说明未检测到摄像头或摄像头权限被禁止。
+
+``` typescript
+import { onMounted } from 'vue';
+import { useVirtualBackgroundState } from 'tuikit-atomicx-vue3/room';
+
+const { isSupported, initVirtualBackground } = useVirtualBackgroundState();
+
+onMounted(async () => {
+  // 1. 检查浏览器兼容性
+  if (!isSupported()) {
+    console.warn('当前浏览器不支持虚拟背景');
+    return;
+  }
+
+  // 2. 初始化资源
+  try {
+    await initVirtualBackground({ assetsPath: './assets' });
+    console.log('虚拟背景初始化完成');
+  } catch (error) {
+    console.error('初始化失败', error);
+  }
+});
+```
+
+### 步骤2：设置预览
+
+在用户确认应用背景前，通常需要先预览效果。使用 [setVirtualBackground](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#setVirtualBackground) 方法可以设置预览效果，此时不会应用到远端可见的视频流中。
+
+> **说明：**
+> 
+
+> 调用 `setVirtualBackground` 仅在本地预览画面生效，远端用户不会看到虚拟背景效果，需调用 `saveVirtualBackground` 后才会同步到远端视频流。
+> 
+
+``` typescript
+import { useVirtualBackgroundState } from 'tuikit-atomicx-vue3/room';
+
+const { setVirtualBackground } = useVirtualBackgroundState();
+
+// 开启背景虚化预览
+const previewBlur = async () => {
+  await setVirtualBackground({
+    enable: true,
+    type: 'blur',
+    level: 0.5 // 虚化程度，可选
+  });
+};
+
+// 开启背景图片预览
+const previewImage = async (imageUrl: string) => {
+  await setVirtualBackground({
+    enable: true,
+    type: 'image',
+    source: imageUrl // 图片 URL，支持本地或网络路径
+  });
+};
+```
+
+### 步骤3：保存并生效
+
+用户确认预览效果满意后，调用 [saveVirtualBackground](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#saveVirtualBackground) 将配置真正应用到当前的视频流中，此时远端用户将看到效果。
+``` typescript
+import { useVirtualBackgroundState } from 'tuikit-atomicx-vue3/room';
+
+const { saveVirtualBackground } = useVirtualBackgroundState();
+
+const confirmSettings = async () => {
+  try {
+    await saveVirtualBackground();
+    console.log('虚拟背景已生效');
+  } catch (error) {
+    console.error('保存失败', error);
+  }
+};
+```
+
+### 步骤4：关闭虚拟背景
+
+如果需要关闭虚拟背景，恢复真实背景，可以将其 `enable` 属性设为 `false` 并保存。
+``` typescript
+import { useVirtualBackgroundState } from 'tuikit-atomicx-vue3/room';
+
+const { setVirtualBackground, saveVirtualBackground } = useVirtualBackgroundState();
+
+const disableVirtualBackground = async () => {
+  // 1. 设置为关闭状态
+  await setVirtualBackground({ enable: false });
+  // 2. 保存生效
+  await saveVirtualBackground();
+};
+```
+
+## 开发注意事项
+- **资源文件路径：**`initVirtualBackground` 中的 `assetsPath` 必须正确指向 AI 模型文件的目录。如果路径错误，会导致虚拟背景无法启动。请查阅 [SDK 文档](https://web.sdk.qcloud.com/trtc/webrtc/doc/zh-cn/tutorial-36-advanced-virtual-background.html) 获取资源文件包。
+
+- **性能消耗：** 开启虚拟背景会占用较高的 CPU 和 GPU 资源。在低端设备上可能会导致视频掉帧或发热，建议在检测到设备性能不足时提示用户关闭。
+
+- **浏览器兼容性：** 并非所有浏览器都支持虚拟背景（依赖 WebAssembly 和 SIMD 等特性）。务必在 UI 渲染前调用 `isSupported()` 进行检查。
+
+- **图片格式：** 自定义背景图片建议使用 `jpg` 或 `png` 格式，且分辨率不宜过大（建议 1920x1080 以内），以免影响加载速度和内存占用。
+
+
+## 常见问题
+
+### **在 Chrome 中运行 Demo 发现画面颠倒且卡顿？**
+
+虚拟背景插件使用 GPU 进行加速，您需要在浏览器设置中找到使用硬件加速模式并启用。可以将 `chrome://settings/system` 复制到浏览器地址栏，并且打开硬件加速模式。
+
+### **为什么开启虚拟背景后，电脑发热严重或风扇高速运转？**
+
+虚拟背景功能需要实时识别人物轮廓并进行图像处理，对 CPU 和 GPU 算力有一定要求。建议在无需使用时关闭该功能，或在低端设备上避免开启。
+
+### **初始化失败，报错 "assets load failed" 怎么办？**
+
+请检查 `initVirtualBackground` 中传入的 `assetsPath` 是否正确。确保该路径下包含必要的 AI 模型文件，且能够通过浏览器直接访问。如果是跨域资源，需要配置 CORS 策略。
+
+### **虚拟背景支持移动端浏览器吗？**
+
+由于移动端浏览器的性能限制和 WebAssembly 支持情况差异较大，体验可能不如桌面端稳定。建议优先在桌面端 Chrome（推荐 94+）、Edge 等主流浏览器中使用，并做好兼容性判断 `isSupported()`。
+
+### **本地开发时无法使用虚拟背景？**
+
+WebRTC 相关功能通常要求在 HTTPS 环境下运行，或者是 `localhost` / `127.0.0.1`。请确保您的开发环境满足安全上下文要求。
+
+## **示例项目**
+
+腾讯云在 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" >**useVirtualBackgroundState**</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-VirtualBackgroundState)</td>
+</tr>
+</table>