@tencentcloud/sdk-mcp 1.3.1 → 1.3.2

package/resource/doc/roomkit/vue/features/free-beauty-panel.md

@@ -0,0 +1,238 @@
+基础美颜功能允许用户在视频通话或直播中，对人像进行磨皮、美白和红润处理。
+
+## 适用场景
+- **视频会议：** 弱化皮肤瑕疵，提亮肤色，使参会者看起来更加专业和精神。
+
+- **在线直播：** 主播通过美颜功能提升画面观感，吸引更多观众。
+
+- **在线教育：** 教师和学生保持整洁自然的形象，营造良好的课堂氛围。
+
+
+## 前提条件
+- **用户状态：** 用户已经通过 useLoginState 完成登录鉴权，参考 [接入概览](https://write.woa.com/document/197379797539790848)，处于 **已登录** 状态。
+
+- **环境依赖：** 项目已引入 `tuikit-atomicx-vue3`。
+
+- **设备要求：** 需要有可用的摄像头设备，并且用户已授权摄像头访问权限。如果用户拒绝授权，虚拟背景功能将无法使用。
+
+
+## 实现基础美颜功能
+
+本功能提供两种集成方案，您可以根据业务需求选择最适合的一种：
+- **方案一（推荐）：** 使用 UI 组件快速集成。直接引入 `tuikit-atomicx-vue3` 提供的美颜面板组件（[FreeBeautyPanel](https://github.com/Tencent-RTC/TUIKit_Vue3/tree/main/packages/tuikit-atomicx-vue3/src/components/FreeBeautyPanel)），将其嵌入到您的应用弹窗中，开发成本最低。
+
+- **方案二（高级）：** 使用底层 API 自定义集成。基于 atomicx-core SDK API [useFreeBeautyState](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#module-FreeBeautyState) 状态钩子自行实现 UI 和交互逻辑，灵活度最高。
+
+   ![](https://write-document-release-1258344699.cos.ap-guangzhou.tencentcos.cn/100027160512/70883e08df0d11f08304525400454e06.png)
+
+
+## 方案一：使用 UI 组件快速集成
+
+`tuikit-atomicx-vue3` 提供了核心美颜设置面板组件：
+- [**FreeBeautyPanel**](https://github.com/Tencent-RTC/TUIKit_Vue3/tree/main/packages/tuikit-atomicx-vue3/src/components/FreeBeautyPanel)**：** 基础美颜配置面板，包含磨皮、美白、红润的参数调节功能。
+
+
+### 步骤1：引入组件
+``` typescript
+import { FreeBeautyPanel } from 'tuikit-atomicx-vue3/room';
+```
+
+### 步骤2：使用组件
+
+通常建议将 `FreeBeautyPanel` 放置在一个弹窗（Dialog）或模态框（Modal）中，通过按钮点击触发显示。
+
+**以下示例展示了如何实现一个点击按钮弹出美颜设置的完整交互：**
+
+> **注意：**
+> 
+
+> 所有 TUIKit 组件必须包裹在 [UIKitProvider](https://write.woa.com/document/197379797539790848) 内部，否则将无法获取上下文依赖，导致样式异常。
+> 
+
+``` typescript
+<template>
+  <UIKitProvider theme="light" language="zh-CN">
+    <div class="toolbar-container">
+      <!-- 1. 触发按钮 -->
+      <button @click="openBeautySettings">设置美颜</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 事件：当用户点击面板内的关闭按钮（如有）时触发 -->
+            <FreeBeautyPanel @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 { FreeBeautyPanel, useDeviceState } from 'tuikit-atomicx-vue3/room';
+
+const showSettings = ref(false);
+const { cameraList } = useDeviceState();
+
+const openBeautySettings = () => {
+  // 1. 检查是否有可用摄像头
+  if (cameraList.value.length === 0) {
+    alert('未检测到摄像头，无法设置美颜');
+    return;
+  }
+
+  // 2. 打开设置面板
+  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; }
+.modal-body { padding: 16px; }
+</style>
+```
+
+该组件内部逻辑如下：
+- **显示面板：** 用户点击按钮后弹出包含 `FreeBeautyPanel` 的弹窗。
+
+- **调节参数：** 用户拖动面板内的滑块调节磨皮、美白、红润参数。
+
+- **实时预览：** 调节过程中会实时调用预览接口预览美颜效果。
+
+- **保存生效：** 关闭面板（触发 `@close` 事件）时自动保存当前设置，使其对远端生效。
+
+
+## 方案二：使用底层 API 自定义集成
+
+本节主要介绍如何通过 atomicx-core SDK API [useFreeBeautyState](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#module-FreeBeautyState) 接口来实现基础美颜。
+
+### 步骤1：设置预览
+
+在用户调节美颜参数（例如拖动滑块）时，使用 [setFreeBeauty](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#setFreeBeauty) 进行实时预览。此时效果仅本地可见，不会传输给远端用户。
+
+> **注意：**
+> 
+
+> 参数取值范围为 0-100。
+> 
+
+``` typescript
+import { useFreeBeautyState } from 'tuikit-atomicx-vue3/room';
+
+const { setFreeBeauty, beautyConfig } = useFreeBeautyState();
+
+// 示例：调节美颜参数
+const updatePreview = async (beauty: number, white: number, ruddy: number) => {
+  // beautyConfig 中的值会自动更新，这里演示如何手动设置预览
+  await setFreeBeauty({
+    beautyLevel: beauty,      // 磨皮 (0-100)
+    whitenessLevel: white,    // 美白 (0-100)
+    ruddinessLevel: ruddy     // 红润 (0-100)
+  });
+};
+```
+
+### 步骤2：保存并生效
+
+用户确认预览效果满意后，调用 [saveBeautySetting](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#saveBeautySetting) 将当前配置应用到视频流中。此时远端用户可以看到美颜效果。
+
+> **注意：**
+> 
+
+> 虚拟背景功能依赖摄像头设备。可使用 [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 { useFreeBeautyState } from 'tuikit-atomicx-vue3/room';
+
+const { saveBeautySetting } = useFreeBeautyState();
+
+const applyBeauty = async () => {
+  // 保存当前预览的设置，使其对远端生效
+  await saveBeautySetting();
+  console.log('美颜已生效');
+};
+```
+
+### 步骤3：关闭美颜效果
+
+若需关闭美颜，只需将所有参数设置为 0 并保存。
+``` typescript
+const closeBeauty = async () => {
+  // 1. 将所有参数设为 0 并预览
+  await setFreeBeauty({
+    beautyLevel: 0,
+    whitenessLevel: 0,
+    ruddinessLevel: 0
+  });
+  
+  // 2. 保存生效
+  await saveBeautySetting();
+};
+```
+
+## 开发注意事项
+- **参数范围：**`setFreeBeauty` 接收的参数（`beautyLevel`, `whitenessLevel`, `ruddinessLevel`）范围均为 0-100。
+
+- **预览与生效：** 为了提供更好的用户体验，美颜调节分为**“预览”**和**“生效”**两个阶段。`setFreeBeauty` 仅用于本地预览，必须调用 `saveBeautySetting` 才会正式调用 `trtcCloud.setBeautyStyle` 应用到推流中。
+
+- **设备依赖：** 美颜功能依赖于视频流，因此必须在摄像头开启的状态下才能看到效果。如果未检测到摄像头，建议禁用美颜入口。
+
+- **性能消耗：** 开启美颜会增加一定的 CPU 和 GPU 负载，建议在低端设备上引导用户适度使用。
+
+
+## 常见问题
+
+### **为什么调节美颜后远端看不到效果？**
+
+请确认是否调用了 `saveBeautySetting()`。`setFreeBeauty()` 仅用于本地预览，只有保存后才会应用到推流视频中。
+
+### **没有摄像头时能设置美颜吗？**
+
+不能。美颜功能是对视频流进行处理，如果没有采集到视频画面，美颜无法生效。建议在无摄像头时隐藏或禁用美颜入口。
+
+### **离开房间或关闭摄像头后，需要手动重置美颜吗？**
+
+不需要。`useFreeBeautyState` 内部已实现状态自动管理：
+- 摄像头切换： 关闭摄像头时美颜暂停，重新开启后会自动恢复上次保存的设置。
+
+- 进出房间： 退出房间时会自动重置所有美颜参数，无需开发者手动清理。
+
+
+## **示例项目**
+
+腾讯云在 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" >**useFreeBeautyState**</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-FreeBeautyState)</td>
+</tr>
+</table>

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

@@ -0,0 +1,427 @@
+会中聊天功能允许会议内的成员通过文字、表情等形式进行实时互动。该功能基于 `tuikit-atomicx-vue3` 的 IM 组件能力实现，为用户提供便捷的即时通讯体验。
+
+## 适用场景
+- **在线研讨会：**主讲人进行视频演讲时，参会者可以通过文字提问或讨论。
+
+- **远程协作：**团队成员在沟通时，可发送文字、图片、文件等。
+
+- **直播教学：**学生可以在聊天区发送弹幕或问题，老师实时查看并解答，增强课堂互动性。
+
+
+## 前提条件
+
+在接入功能前，请确保满足以下条件：
+- **用户状态：**用户已经通过 useLoginState 完成登录鉴权，参考 [接入概览](https://write.woa.com/document/197379797539790848)，并已作为一个房间的房主或成员在房间内，参考 [房间管理](https://write.woa.com/document/197379861957083136)。
+
+- **环境依赖：**项目已正确安装并引入 `tuikit-atomicx-vue3`。
+
+
+## 实现会中聊天功能
+
+本功能提供两种集成方案，您可以根据业务需求选择最适合的一种：
+- **方案一（推荐）：**使用 UI 组件快速集成。直接引入 `tuikit-atomicx-vue3` 提供的消息列表组件（[MessageList](https://github.com/Tencent-RTC/TUIKit_Vue3/tree/main/packages/tuikit-atomicx-vue3/src/components/MessageList)）和消息输入组件（[MessageInput](https://github.com/Tencent-RTC/TUIKit_Vue3/tree/main/packages/tuikit-atomicx-vue3/src/components/MessageInput)），开发成本最低。
+
+- **方案二（高级）：**使用底层 API 自定义集成。基于 atomicx-core SDK API [useMessageListState](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#module-MessageListState) 和 [useMessageInputState](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#module-MessageInputState) 状态钩子自行实现 UI 和交互逻辑，灵活度最高。
+
+   ![会中聊天](https://write-document-release-1258344699.cos.ap-guangzhou.tencentcos.cn/100027160512/8c740e5cdf1111f09143525400bf7822.png)
+
+   会中聊天
+
+
+## 方案一：使用 UI 组件快速集成
+
+`tuikit-atomicx-vue3` 提供了两个核心组件：
+- [**MessageList**](https://github.com/Tencent-RTC/TUIKit_Vue3/tree/main/packages/tuikit-atomicx-vue3/src/components/MessageList)**：** 消息列表组件，展示聊天记录，支持消息的复制、撤回、删除等操作。
+
+- [**MessageInput**](https://github.com/Tencent-RTC/TUIKit_Vue3/tree/main/packages/tuikit-atomicx-vue3/src/components/MessageInput)**：** 消息输入组件，支持文本、表情、图片、文件发送，并可根据禁言状态自动禁用。
+
+
+### 步骤1：数据初始化
+
+在用户加入房间成功后，需要调用 [setActiveConversation](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#setActiveConversation) 接口初始化聊天数据。建议监听 [currentRoom](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#currentRoom) 的变化来自动处理。
+
+> **说明：**
+> 
+> - `GROUP` 为固定前缀，`setActiveConversation` 参数必须为 ``GROUP${roomId}``，否则无法正常收发消息。
+> - `GROUP` 为 IM SDK 群组会话的固定前缀（参考 [IM 会话类型](https://web.sdk.qcloud.com/im/doc/zh-cn/Conversation.html)）。房间聊天基于 IM 群组实现，因此会话 ID 必须为 ``GROUP${roomId}`` 格式。
+
+``` typescript
+import { watch } from 'vue';
+import { useConversationListState } from 'tuikit-atomicx-vue3/chat';
+import { useRoomState } from 'tuikit-atomicx-vue3/room';
+
+const { currentRoom } = useRoomState();
+const { setActiveConversation } = useConversationListState();
+
+// 监听房间 ID 变化，自动切换到对应的 IM 群组会话
+watch(() => currentRoom.value?.roomId, (roomId) => {
+  if (roomId) {
+    // 关键步骤：设置当前活跃会话 ID，规则为 "GROUP" + 房间ID
+    setActiveConversation(`GROUP${roomId}`);
+  }
+}, { immediate: true });
+```
+
+### 步骤2： 使用组件
+
+在您的页面中，可以直接组合使用这两个组件。同时结合 [useRoomParticipantState](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#module-RoomParticipantState) 获取当前用户的禁言状态，控制输入框的可用性。
+
+> **注意：**
+> 
+
+> 所有 TUIKit 组件必须包裹在 [UIKitProvider](https://write.woa.com/document/197379797539790848) 内部，否则将无法获取上下文依赖，导致样式异常。
+> 
+
+``` typescript
+<template>
+  <UIKitProvider theme="light" language="zh-CN">
+    <div class="room-chat-container">
+      <!-- 消息列表组件 -->
+      <!-- messageActionList: 配置长按消息支持的操作，例如复制、撤回、删除 -->
+      <MessageList
+        class="message-list"
+        :messageActionList="['copy', 'recall', 'delete']"
+      />
+
+      <!-- 消息输入组件 -->
+      <!-- disabled: 当用户被禁言时禁用输入框 -->
+      <!-- hideSendButton: 可选，隐藏发送按钮，使用回车发送 -->
+      <MessageInput
+        class="message-input"
+        :placeholder="inputPlaceholder"
+        :disabled="isMessageDisabled"
+        hideSendButton
+      />
+    </div>
+  </UIKitProvider>
+</template>
+
+<script setup lang="ts">
+import { computed } from 'vue';
+import { UIKitProvider } from '@tencentcloud/uikit-base-component-vue3';
+import { MessageInput, MessageList } from 'tuikit-atomicx-vue3/chat';
+import { useRoomParticipantState } from 'tuikit-atomicx-vue3/room';
+
+const { localParticipant } = useRoomParticipantState();
+
+// 获取当前用户的禁言状态，isMessageDisabled 由房间后台实时同步，无需前端主动轮询，前端只需绑定该状态即可自动响应禁言变更。
+const isMessageDisabled = computed(() => localParticipant.value?.isMessageDisabled);
+
+// 根据状态动态显示占位符提示
+const inputPlaceholder = computed(() => 
+  isMessageDisabled.value ? '您已被禁言' : '请输入消息...'
+);
+</script>
+
+<style scoped>
+.room-chat-container{display:flex;flex-direction:column;height:100%;padding:8px;gap:8px}.message-list{flex:1;overflow:hidden}.message-input{flex-shrink:0;border:1px solid #e0e0e0;border-radius:8px}
+</style>
+```
+
+### 步骤3：处理未读消息计数（可选）
+
+如果聊天窗口平时是折叠或关闭状态，您需要通过监听 [messageList](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#messageList) 的变化来统计未读消息数，并在 UI 上（如聊天图标角标）进行提示。
+``` typescript
+import { ref, watch } from 'vue';
+import { useMessageListState } from 'tuikit-atomicx-vue3/chat';
+
+const { messageList } = useMessageListState();
+const unreadCount = ref(0);
+const isChatWindowOpen = ref(false); // 需根据您的业务逻辑维护此状态
+
+watch(() => messageList.value?.length, (newLength, oldLength) => {
+  // 如果是首次加载或数据为空，不进行计数
+  if (!newLength || newLength === 0) return;
+
+  // 仅当聊天窗口关闭且收到新消息时，增加未读计数
+  if (!isChatWindowOpen.value && newLength > (oldLength || 0)) {
+    unreadCount.value += (newLength - (oldLength || 0));
+  }
+});
+
+// 当用户打开聊天窗口时，清空未读计数
+const openChatWindow = () => {
+  isChatWindowOpen.value = true;
+  unreadCount.value = 0;
+};
+```
+
+## 方案二：使用底层 API 自定义集成
+
+本节主要介绍如何通过 atomicx-core SDK API [useMessageListState](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#module-MessageListState) 和 [useMessageInputState](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#module-MessageInputState) 接口来实现自定义的聊天界面。
+
+> **注意：**
+> 
+
+> `MessageInputState` 默认支持与 `@tiptap/vue-3` 编辑器集成。如果您仅需要简单的文本输入框（例如 `<input>` 或 `<textarea>`），请**忽略**`setEditorInstance`、`setContent` 等与编辑器实例绑定的 API，直接使用 `updateRawValue` 和 `sendMessage` 即可。
+> 
+
+
+#### 步骤1：数据初始化
+
+在用户加入房间成功后，需要调用 [setActiveConversation](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#setActiveConversation) 接口初始化聊天数据。建议监听 [currentRoom](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#currentRoom) 的变化来自动处理。
+
+> **说明：**
+> 
+> - `GROUP` 为固定前缀，`setActiveConversation` 参数必须为 ``GROUP${roomId}``，否则无法正常收发消息。
+> - 在房间切换或退房时，建议重置或清空活跃会话，避免消息错发至错误会话。
+
+``` typescript
+import { watch } from 'vue';
+import { useConversationListState } from 'tuikit-atomicx-vue3/chat';
+import { useRoomState } from 'tuikit-atomicx-vue3/room';
+
+const { currentRoom } = useRoomState();
+const { setActiveConversation } = useConversationListState();
+
+// 监听房间 ID 变化，自动切换到对应的 IM 群组会话
+watch(() => currentRoom.value?.roomId, (roomId) => {
+  if (roomId) {
+    // 关键步骤：设置当前活跃会话 ID，规则为 "GROUP" + 房间ID
+    setActiveConversation(`GROUP${roomId}`);
+  }
+}, { immediate: true });
+```
+
+#### 步骤2：获取消息列表
+
+使用 [useMessageListState](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#module-MessageListState) 获取当前会话的消息列表。`messageList` 是响应式数据，会自动更新新收到的消息。
+``` typescript
+import { useMessageListState } from 'tuikit-atomicx-vue3/chat';
+
+const { 
+  messageList,      // 响应式消息列表
+  loadMoreOlderMessage, // 加载更多历史消息方法
+  hasMoreOlderMessage,   // 是否还有更多历史消息
+} = useMessageListState();
+
+// 示例：渲染消息列表
+// <div v-for="msg in messageList" :key="msg.ID">
+//   {{ msg.payload.text }}
+// </div>
+```
+
+#### 步骤3：发送消息
+
+使用 [useMessageInputState](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#module-MessageInputState) 管理输入框内容并发送消息。
+``` typescript
+import { useMessageInputState } from 'tuikit-atomicx-vue3/chat';
+
+const { 
+  inputRawValue,  // 响应式数据：当前输入内容
+  updateRawValue, // 方法：更新输入内容（会自动触发"对方正在输入"状态）
+  sendMessage     // 方法：发送消息
+} = useMessageInputState();
+
+const handleSend = async () => {
+  // 校验非空
+  if (!inputRawValue.value) return;
+  
+  try {
+    // 1. 发送消息
+    // 方式 A：发送当前 inputRawValue 的内容
+    await sendMessage();
+    
+    // 方式 B：直接发送指定文本（不依赖 inputRawValue）
+    // await sendMessage('Hello World');
+
+    console.log('发送成功');
+    
+    // 2. 发送成功后清空输入框
+    // 关键点：非富文本模式下，务必使用 updateRawValue('') 清空
+    // 请勿使用 setContent('')，该方法仅在绑定了 editor 实例后生效
+    updateRawValue('');
+  } catch (error) {
+    console.error('发送失败', error);
+  }
+};
+
+// 示例：绑定原生输入框
+// <input 
+//   :value="inputRawValue" 
+//   @input="(e) => updateRawValue(e.target.value)" 
+//   @keyup.enter="handleSend" 
+// />
+```
+
+#### 步骤4：加载历史消息
+
+通过 [loadMoreOlderMessage](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#module-MessageListState) 方法分页拉取历史消息。通常在滚动到列表顶部时触发。
+
+> **注意：**
+> 
+
+> 在加载历史消息后，通常需要手动调整滚动条位置，以保持当前浏览视角不发生跳变。
+> 
+
+``` typescript
+import { useMessageListState } from 'tuikit-atomicx-vue3/chat';
+
+const { 
+  hasMoreOlderMessage,
+  loadMoreOlderMessage
+} = useMessageListState();
+
+const loadHistory = async () => {
+  if (hasMoreOlderMessage.value) {
+    // 记录加载前的滚动高度
+    // const previousHeight = scrollContainer.value.scrollHeight;
+    
+    await loadMoreOlderMessage();
+    
+    // DOM 更新后恢复滚动位置
+    // nextTick(() => {
+    //   const currentHeight = scrollContainer.value.scrollHeight;
+    //   scrollContainer.value.scrollTop += (currentHeight - previousHeight);
+    // });
+  }
+};
+```
+
+#### 步骤5：高级功能（已读回执）
+
+如果您需要已读回执功能，可以使用 [setEnableReadReceipt](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#setEnableReadReceipt)。
+``` typescript
+const { 
+  setEnableReadReceipt, // 开启/关闭已读回执
+} = useMessageListState();
+
+// 开启已读回执
+setEnableReadReceipt(true);
+```
+
+## 开发注意事项
+- **禁言状态同步**
+
+
+   `localParticipant.isMessageDisabled` 是由房间管理员控制的。当管理员开启“全员禁言”或单独禁言某用户时，该属性会自动更新。请务必将此属性绑定到输入框的 `disabled` 状态上，以在前端层面限制用户发言。
+
+- **会话切换时机**
+
+
+   确保 `setActiveConversation` 在进房成功后且 `roomId` 有值时调用。如果在进房前调用，可能会因为 SDK 尚未初始化完毕或未登录而失败。
+
+- **容器布局要求（重要）**
+
+
+   消息列表组件内部处理了滚动逻辑，因此**父容器必须有固定的高度**（例如 `height: 100%` 或具体像素值）并设置 `overflow: hidden`，否则会导致列表无限拉长、无法滚动。
+
+- **消息类型处理**
+
+
+   `messageList` 中包含多种类型的消息（文本、图片、文件等），自定义渲染时需根据 `msg.type` 进行区分处理。
+
+- **输入状态管理**
+
+
+   使用 `updateRawValue` 更新输入内容会自动触发 "对方正在输入" 的状态通知（如果支持）。如果仅使用 `inputRawValue.value = 'xxx'` 可能不会触发该状态。
+
+- **历史消息滚动维持**
+
+
+   在自定义开发中，调用 `loadMoreOlderMessage` 加载历史消息后，DOM 高度会增加。为了防止视图跳动，需要在加载前记录 `scrollHeight`，加载后（`nextTick`）计算高度差并调整 `scrollTop`。
+
+- **新消息滚动策略**
+
+
+   建议实现“智能滚动”逻辑：当用户位于列表底部时，收到新消息自动滚动到底部；当用户正在浏览历史消息时，保持当前位置不动，并显示“有新消息”的提示气泡。
+
+- **会话 ID 格式要求**
+
+
+   调用 `setActiveConversation` 时，必须使用 ``GROUP${roomId}`` 格式（GROUP 为固定前缀）。这是 IM SDK 群组会话的标准格式，不可自定义或省略前缀，否则无法正常收发消息。
+
+
+## 常见问题
+
+**切到群组会话失败或消息列表无内容？**
+
+确保已登录并进房成功后再调用 `setActiveConversation('GROUP' + roomId)`；未登录或 roomId 为空会导致失败。
+
+**消息收不到或列表空白？**
+
+检查当前活跃会话是否正确（`GROUP` 前缀 + roomId），以及网络/鉴权是否正常；必要时重新设置活跃会话 `setActiveConversation` 刷新。
+
+**未读计数不清零？**
+
+需要手动维护未读计数逻辑。打开聊天窗口时，或收到新消息但窗口关闭时进行计数更新。
+
+**被禁言仍能点击发送？**
+
+请确保前端 UI 根据 `isMessageDisabled` 状态禁用了发送按钮和输入框。虽然服务端也会拦截，但前端禁用体验更好。
+
+**自定义头像/昵称展示？**
+
+可通过 `MessageList` 插槽或自定义 Message 组件，优先显示房间内的 `nameCard`，并自定义头像样式等。
+
+**自定义方案如何发送图片或文件？**
+
+`sendMessage` 方法支持传入 `InputContent[]` 数组。您可以构造包含 `type: 'image'` 或 `type: 'file'` 以及对应 `file` 对象的数组来实现富媒体消息发送。
+``` typescript
+import { useMessageInputState } from 'tuikit-atomicx-vue3/chat';
+
+const { sendMessage } = useMessageInputState();
+
+// 示例：发送图片
+// const file = ...; // 从 input type="file" 获取的 File 对象
+await sendMessage([{ type: 'image', file }]);
+```
+
+**如何修改 UI 组件的默认样式？**
+
+`tuikit-atomicx-vue3` 的组件类名通常保持稳定。您可以使用 CSS 深度选择器（例如 Vue 的 `:deep()`）来覆盖默认样式。例如 `.message-list :deep(.tui-message-bubble) { background-color: #f0f0f0; }`。
+
+## **示例项目**
+
+腾讯云在 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>
+
+<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>
+
+<tr>
+<td rowspan="1" colSpan="1" >**useConversationListState**</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-ConversationListState)</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >**useMessageListState**</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-MessageListState)</td>
+</tr>
+
+<tr>
+<td rowspan="1" colSpan="1" >**useMessageInputState**</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-MessageInputState)</td>
+</tr>
+</table>