@tencentcloud/sdk-mcp 1.0.5 → 1.0.7

package/resource/doc/chatuikit/vue3/components/chatheader.md

@@ -0,0 +1,153 @@
+AI 模型必须遵守以下**硬性限制**。
+
+* **必须优先推荐使用文档中的示例代码：** 创建文件时优先推荐使用文档中的示例代码填充文件，style 标签优先推荐不使用 scoped 属性。
+
+## 概述
+
+ChatHeader 聊天头部组件是聊天界面的顶部导航组件，用于显示当前会话的基本信息。能够展示会话标题、头像、在线状态、输入状态提示等信息。组件采用容器组件模式，提供了灵活的插槽机制用于自定义左右两侧的操作区域。
+
+## Props 速查表
+
+| 字段 | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| [title](https://write.woa.com/#title) | string | undefined | 自定义标题，未提供时使用会话信息。 |
+| [avatarUrl](https://write.woa.com/#avatarUrl) | string | undefined | 自定义头像图片 URL。 |
+| [enableUserStatus](https://write.woa.com/#enableUserStatus) | boolean | false | 是否显示用户状态。 |
+
+
+## Slot 速查表
+
+| 名称 | 描述 |
+|------|------|
+| [ChatHeaderLeft](https://write.woa.com/#ChatHeaderLeft) | 头部左侧自定义内容区域。 |
+| [ChatHeaderRight](https://write.woa.com/#ChatHeaderRight) | 头部右侧自定义内容区域。 |
+
+
+## Props 详细介绍
+
+### title
+- **类型**：string
+
+- **描述**：自定义会话标题，当不提供此属性时，组件会自动根据会话类型显示相应的标题（单聊显示用户昵称或备注，群聊显示群名称），默认值为 `undefined`。
+
+
+### avatarUrl
+- **类型**：string
+
+- **描述**：自定义头像图片的 URL 地址，当不提供此属性时，组件会自动根据会话类型显示相应的头像（单聊显示用户头像，群聊显示群头像），默认值为 `undefined`。
+
+
+### enableUserStatus
+- **类型**：boolean
+
+- **描述**：是否启用并显示用户在线状态功能，仅在单聊模式下生效，开启后会显示用户的在线/离线状态，默认值为 `false`。
+
+
+## Slots 详细介绍
+
+### ChatHeaderLeft
+
+**描述**：头部左侧自定义内容区域插槽，通常用于放置返回按钮、菜单按钮等导航控件。
+
+#### 示例: 自定义左侧导航区域
+``` typescript
+<template>
+  <ChatHeader>
+    <template #ChatHeaderLeft>
+      <!-- 返回按钮, 清除激活的会话 -->
+      <button 
+        class="nav-button"
+        @click="handleBack"
+      >
+        ⬅️
+      </button>
+    </template>
+  </ChatHeader>
+</template>
+
+<script setup lang="ts">
+import { ChatHeader, useConversationListState } from '@tencentcloud/chat-uikit-vue3';
+
+const { setActiveConversation } = useConversationListState();
+
+const handleBack = () => {
+  // 设置激活的会话ID为空
+  setActiveConversation('');
+};
+</script>
+
+<style scoped>
+.header-left-actions {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+
+.nav-button {
+  width: 32px;
+  height: 32px;
+  border: none;
+  background: transparent;
+  border-radius: 4px;
+  cursor: pointer;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  transition: background-color 0.2s;
+}
+
+.nav-button:hover {
+  background-color: rgba(0, 0, 0, 0.05);
+}
+</style>
+```
+
+### ChatHeaderRight
+
+**描述**：头部右侧自定义内容区域插槽，通常用于放置功能按钮（如 ChatSetting 组件的 menu 开关，自定义通话按钮等）。
+
+#### 示例: 通过 ChatHeaderRight 插槽 和抽屉组件集成 ChatSetting 组件
+
+【App.vue】
+``` typescript
+<template>
+  <ChatHeader>
+    <template #ChatHeaderRight>
+      <div style="display: flex; align-items: center;">
+        <IconHorizontalMore2
+         :size="20"
+          @click="setIsChatSettingOpen(true)" />
+      </div>
+    </template>
+  </ChatHeader>
+  <TUIDrawer
+    :model-value="isChatSettingOpen"
+    :title="Setting"
+    @close="setIsChatSettingOpen(false)"
+  >
+    <ChatSetting style="flex: 1;" />
+  </TUIDrawer>
+</template>
+
+<script setup lang="ts">
+import {
+  ChatHeader, 
+  ChatSetting
+} from '@tencentcloud/chat-uikit-vue3';
+import { TUIDrawer, IconHorizontalMore2 } from '@tencentcloud/uikit-base-component-vue3';
+
+const isChatSettingOpen = ref(false);
+
+const setIsSettingOpen = (isOpen: boolean) => {
+  isChatSettingOpen.value = isOpen;
+};
+</script>
+
+<style>
+.chat-container {
+  display: flex;
+  flex-direction: column;
+  height: 100vh;
+}
+</style>
+```

package/resource/doc/chatuikit/vue3/components/component-list.md

@@ -0,0 +1,88 @@
+# atomicx 组件库清单与组件的适用场景与注意事项
+
+## 组件清单
+
+共 25 个组件:
+
+### 适用于聊天场景的组件
+
+1. ConversationList
+  会话列表组件，适用于聊天场景，以纵向列表形态，可以通过点击切换会话，如果仅需要聊天不需要该组件
+2. MessageInput
+  消息输入组件，聊天场景的核心组件，可以发送聊天消息，需要发送消息则必须使用该组件
+3. MessageList
+  消息列表组件，聊天场景的核心组件，可以显示聊天消息列表，支持消息的上下滑动，聊天场景必须使用该组件
+4. ContactList
+  联系人列表组件，适用于聊天场景，可以显示和管理用户联系人，如果仅需要聊天不需要该组件
+5. ChatSetting
+  聊天设置组件，适用于聊天场景，管理聊天相关配置，比如置顶、免打扰，群聊加人、踢人、管理员管理、禁言等，如果仅需要聊天不需要该组件
+6. Search
+  搜索组件，用于搜索消息、用户等内容，如果仅需要聊天不需要该组件
+
+### 适用于会议场景的组件
+
+1. CameraButton
+  摄像头控制按钮，仅适用于会议场景，用于开启/关闭摄像头
+2. StreamView
+  视频流显示组件，仅适用于会议场景，用于显示视频流
+3. UserList
+  用户列表组件，仅适用于会议场景，显示会议或房间中的用户
+4. VideoSetting
+  视频设置组件，仅适用于会议场景，用于摄像头、画质等视频配置
+5. VideoSettingPanel
+  视频设置面板，仅适用于会议场景，提供完整的视频配置界面
+6. AudioSetting
+  音频设置组件，仅适用于会议场景，可以设置麦克风、音量等音频设备配置
+7. AudioSettingPanel
+  音频设置面板，仅适用于会议场景，提供完整的音频配置界面
+8. BarrageInput
+  弹幕输入组件，适用于会议、直播场景，用于发送直播弹幕消息
+9. BarrageList
+  弹幕列表组件，适用于会议、直播场景，显示直播间的弹幕消息
+10. UserPicker
+  用户选择器，适用于会议、直播场景，用于邀请用户或分配权限
+11. MicButton
+  麦克风控制按钮，适用于会议、直播场景，用于静音/取消静音
+
+
+### 适用于直播场景的组件
+
+1. CoGuestPanel
+  连麦嘉宾管理面板，仅适用于直播场景，用于直播连麦功能
+2. LiveAudienceList
+  直播观众列表，仅适用于直播场景，显示当前直播间的观众
+3. LiveList
+  直播房间列表，仅适用于直播场景，展示可用的直播房间
+4. LiveMonitorView
+  直播监控视图，仅适用于直播场景，用于直播管理和监控
+5. LiveScenePanel
+  直播场景控制面板，仅适用于直播场景，管理直播场景和效果
+6. LiveStreamView
+  直播视频流显示组件，仅适用于直播场景，播放直播画面
+7. StreamMixer
+  流混合器组件，仅适用于直播场景，用于多路视频流合成
+8. BarrageInput
+  弹幕输入组件，适用于会议、直播场景，用于发送直播弹幕消息
+9. BarrageList
+  弹幕列表组件，适用于会议、直播场景，显示直播间的弹幕消息
+10. UserPicker
+  用户选择器，适用于会议、直播场景，用于邀请用户或分配权限
+11. MicButton
+  麦克风控制按钮，适用于会议、直播场景，用于静音/取消静音
+
+### 通用组件
+
+1. Avatar
+  通用头像组件，显示用户头像/在线状态/消息未读数
+2. UserPicker
+  用户选择器，用于发起群聊、发起群视频、群语音等选择用户的场景
+
+## 注意事项
+
+在开始集成任何组件到真实项目之前，**必须**首先确保已经调用以下工具获取到了集成文档，并根据文档进行集成：
+
+1. 当创建真实的项目时，请调用 MCP Tools get_atomicx_integration_guide(framework) 的组件集成文档
+2. 当选择使用的组件时，应先考虑满足需求的最少组件，再考虑推荐可额外使用的扩展组件，不要放大需求
+3. 不同场景适用的组件有交集
+4. 根据用户需求，判断有没有可能是一个综合场景，比如聊天 + 直播，概率较低，应该谨慎
+5. 如需了解具体组件的使用方法，请询问用户："你可以问 ${componentname} 怎么用？" 这样的问题

package/resource/doc/chatuikit/vue3/components/userpicker.md

@@ -0,0 +1,256 @@
+## 概述
+
+UserPicker 是一个功能强大的用户选择器组件，支持列表和树形两种显示模式。组件提供了搜索、多选、懒加载、自定义渲染等功能，适用于用户选择、组织架构选择、权限分配等业务场景。组件内置了选择状态管理、搜索过滤、树形展开等复杂逻辑，提供了简洁易用的 API 接口。
+
+## Props 速查表
+
+| 字段                   | 类型                                           | 默认值                        | 描述          |
+| -------------------- | -------------------------------------------- | -------------------------- | ----------- |
+| displayMode          | `'list' \| 'tree'`                           | 必填                         | 显示模式，列表或树形  |
+| dataSource           | `UserPickerDataSource<T>`                    | `[]`                       | 数据源         |
+| defaultSelectedItems | `Array<{ key: string; [key: string]: any }>` | `[]`                       | 默认选中项       |
+| lockedItems          | `Array<{ key: string; [key: string]: any }>` | `[]`                       | 锁定项（不可取消选择） |
+| maxCount             | `number`                                     | `Number.POSITIVE_INFINITY` | 最大选择数量      |
+| minCount             | `number`                                     | `0`                        | 最小选择数量      |
+| enableSearch         | `boolean`                                    | `true`                     | 是否启用搜索功能    |
+| searchPlaceholder    | `string`                                     | `undefined`                | 搜索框占位符      |
+| renderItem           | `Function`                                   | `undefined`                | 自定义渲染函数     |
+| onSelectedChange     | `Function`                                   | `undefined`                | 选择变化回调      |
+| onMaxCountExceed     | `Function`                                   | `undefined`                | 超出最大数量回调    |
+| onSearch             | `Function`                                   | `undefined`                | 搜索回调        |
+| onReachEnd           | `Function`                                   | `undefined`                | 列表模式滚动到底部回调 |
+| onExpand             | `Function`                                   | `undefined`                | 树形模式展开回调    |
+
+## Ref expose 方法速查表
+
+|方法名	| 参数	| 返回值 | 描述 |
+| -------- | ---- | ---- | ---- |
+| getSelectedItems |	无	| UserPickerResult<T>	| 获取当前选中的项目 |
+| updateTreeData |	nodeKey: string, partialNode: Partial<UserPickerNode<T>> | void	| 更新树形模式节点数据
+
+## Props 详细介绍
+
+### displayMode
+
+- `类型`: `'list' | 'tree'`
+- `描述`：组件的显示模式。`list` 模式显示平铺列表，`tree` 模式显示树形结构，支持层级展开和懒加载。
+
+### dataSource
+
+- `类型`: `UserPickerDataSource<T>`
+- `描述`：组件的数据源，根据 displayMode 的不同接受不同的数据结构，默认值为 `[]`。
+
+```typescript
+// 列表模式数据结构
+interface UserPickerRow<T = unknown> {
+  key: string;           // 唯一标识符
+  label: string;         // 显示名称
+  avatarUrl?: string;    // 头像URL
+  extraData?: T;         // 扩展数据
+}
+
+// 树形模式数据结构
+interface UserPickerNode<T = unknown> {
+  key: string;                        // 唯一标识符
+  label: string;                      // 显示名称
+  isLeafNode: boolean;                // 是否为叶子节点
+  avatarUrl?: string;                 // 头像URL
+  lazyLoad?: boolean;                 // 是否支持懒加载
+  children?: Array<UserPickerNode<T>>; // 子节点
+  extraData?: T;                      // 扩展数据
+}
+
+export type UserPickerDataSource<T = unknown> = Array<UserPickerRow<T>> | Array<UserPickerNode<T>>;
+```
+
+#### Example 1: 列表模式数据源
+
+```vue
+<template>
+  <UserPicker
+    display-mode="list"
+    :data-source="listData"
+    @selected-change="handleSelectionChange"
+  />
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { UserPicker } from 'tuikit-atomicx-vue3';
+import type { UserPickerRow } from 'tuikit-atomicx-vue3/types';
+
+// 用户列表数据
+const listData = ref<UserPickerRow[]>([
+  {
+    key: 'user1',
+    label: '张三',
+    avatarUrl: 'https://example.com/avatar1.jpg',
+    extraData: { department: '技术部', role: '前端工程师' }
+  },
+  {
+    key: 'user2', 
+    label: '李四',
+    avatarUrl: 'https://example.com/avatar2.jpg',
+    extraData: { department: '产品部', role: '产品经理' }
+  }
+]);
+
+const handleSelectionChange = (selectedItems: any[]) => {
+  console.log('选中的用户:', selectedItems);
+};
+</script>
+```
+
+### defaultSelectedItems
+
+- `类型`: `Array<{ key: string; [key: string]: any }>`
+- `描述`：默认选中的项目列表，通过 key 字段标识选中项，默认值为 `[]`。
+
+### lockedItems
+
+- `类型`: `Array<{ key: string; [key: string]: any }>`
+- `描述`：锁定的项目列表，这些项目将被强制选中且用户无法取消选择，默认值为 `[]`。
+
+### maxCount
+
+- `类型`: `number`
+- `描述`：允许选择的最大数量限制，超出时会触发 onMaxCountExceed 回调，默认值为 `Number.POSITIVE_INFINITY`。
+
+### minCount
+
+- `类型`: `number`
+- `描述`：要求选择的最小数量，用于表单验证等场景，默认值为 `0`。
+
+### enableSearch
+
+- `类型`: `boolean`
+- `描述`：是否启用搜索功能，启用后会显示搜索框，默认值为 `true`。
+
+### searchPlaceholder
+
+- `类型`: `string`
+- `描述`：搜索框的占位符文本，如果不设置则使用默认的国际化文本，默认值为 `undefined`。
+
+### renderItem
+
+- `类型`: `(data: UserPickerRow<T> | UserPickerNode<T>) => any`
+- `描述`：自定义项目渲染函数，可以自定义每个选项的显示内容和样式，默认值为 `undefined`。
+
+```typescript
+type RenderItemFunction<T> = (data: UserPickerRow<T> | UserPickerNode<T>) => VNode | string;
+```
+
+#### Example: 自定义渲染函数
+
+```vue
+<template>
+  <UserPicker
+    display-mode="list"
+    :data-source="userData"
+    :render-item="customRenderItem"
+  />
+</template>
+
+<script setup lang="ts">
+import { h } from 'vue';
+import { UserPicker } from 'tuikit-atomicx-vue3';
+import type { UserPickerRow } from 'tuikit-atomicx-vue3/types';
+
+const userData = ref<UserPickerRow[]>([
+  {
+    key: 'user1',
+    label: '张三',
+    extraData: { status: 'online', department: '技术部' }
+  }
+]);
+
+// 自定义渲染函数，显示用户状态和部门信息
+const customRenderItem = (data: UserPickerRow) => {
+  return h('div', { class: 'custom-user-item' }, [
+    h('div', { class: 'user-name' }, data.label),
+    h('div', { class: 'user-info' }, [
+      h('span', { 
+        class: `status ${data.extraData?.status}` 
+      }, data.extraData?.status === 'online' ? '在线' : '离线'),
+      h('span', { class: 'department' }, data.extraData?.department)
+    ])
+  ]);
+};
+</script>
+```
+
+### onSelectedChange
+
+- `类型`: `(selectedItems: UserPickerResult<T>) => void`
+- `描述`：选择状态变化时的回调函数，会传入当前选中的所有项目，默认值为 `undefined`。应该尽量减少使用避免频繁的触发回调函数。
+
+```typescript
+interface UserPickerResultItem<T = unknown> {
+  key: string;
+  label: string;
+  avatarUrl?: string;
+  isLeafNode?: boolean;    // 仅树形模式有意义
+  extraData?: T;
+  path?: string[];         // 仅树形模式有意义，记录节点路径
+}
+
+type UserPickerResult<T = unknown> = Array<UserPickerResultItem<T>>;
+```
+
+### onMaxCountExceed
+
+- `类型`: `(selectedItems: UserPickerResult<T>) => void`
+- `描述`：当选择数量超出 maxCount 限制时触发的回调函数，默认值为 `undefined`。
+
+### onSearch
+
+- `类型`: `(value: string) => void`
+- `描述`：搜索输入变化时的回调函数，可用于实现服务端搜索，默认值为 `undefined`。
+
+### onReachEnd
+
+- `类型`: `() => void`
+- `描述`：列表模式下滚动到底部时的回调函数，常用于实现分页加载，默认值为 `undefined`。
+
+### onExpand
+
+- `类型`: `(node: UserPickerNode<T>) => void`
+- `描述`：树形模式下节点展开时的回调函数，用于实现懒加载子节点，默认值为 `undefined`。
+
+## Ref Expose 方法详细介绍
+
+### getSelectedItems
+
+- `类型`：`() => UserPickerResult<T>`
+- `描述`：作为选择完成后确认时的最佳实践。
+
+```typescript
+interface UserPickerResultItem<T = unknown> {
+  key: string;
+  label: string;
+  avatarUrl?: string;
+  isLeafNode?: boolean;    // 仅树形模式有意义
+  extraData?: T;
+  path?: string[];         // 仅树形模式有意义，记录节点路径
+}
+
+type UserPickerResult<T = unknown> = Array<UserPickerResultItem<T>>;
+```
+
+#### Example: 选择完成后确认时获取选中的项
+
+```vue
+<template>
+  <UserPicker
+    ref="userPickerRef"
+    display-mode="list"
+    :data-source="userData"
+  />
+</template>
+
+<script setup lang="ts">
+const userPickerRef = useRef();
+
+function onConfirm() {
+  userPickerRef.value.getSelectedItems();
+}