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

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

@@ -1,369 +0,0 @@
-会中聊天功能允许会议内的成员通过文字、表情等形式进行实时互动。该功能基于 `tuikit-atomicx-vue3` 的 IM 组件能力实现，为用户提供便捷的即时通讯体验。
-
-## 适用场景
-- **在线研讨会：**主讲人进行视频演讲时，参会者可以通过文字提问或讨论。
-
-- **远程协作：**团队成员在沟通时，可发送文字、图片、文件等。
-
-- **直播教学：**学生可以在聊天区发送弹幕或问题，老师实时查看并解答，增强课堂互动性。
-
-## 前提条件
-
-在接入功能前，请确保满足以下条件：
-- **用户状态：**用户已经通过 useLoginState 完成登录鉴权，参考 接入概览，并已作为一个房间的房主或成员在房间内，参考 房间管理。
-
-- **环境依赖：**项目已正确安装并引入 `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 和交互逻辑，灵活度最高。
-
-   会中聊天
-
-## 方案一：使用 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 内部，否则将无法获取上下文依赖，导致样式异常。
->
-
-``` 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 文档
-| **State/Component** | **功能描述** | **API 文档** |
-| --- | --- | --- |
-| **useRoomState** | 房间状态管理（创建、加入、预约等） | [API 文档](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#module-RoomState) |
-| **useRoomParticipantState** | 房间参与者管理（成员列表、权限控制） | [API 文档](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#module-RoomParticipantState) |
-| **useConversationListState** | 会话列表管理 | [API 文档](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#module-ConversationListState) |
-| **useMessageListState** | 消息列表管理 | [API 文档](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#module-MessageListState) |
-| **useMessageInputState** | 消息输入管理 | [API 文档](https://web.sdk.qcloud.com/trtc/live/web/doc/zh/index.html#module-MessageInputState) |