@tencentcloud/sdk-mcp 1.0.6 → 1.0.8

package/resource/doc/chatuikit/vue/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();
+}

package/resource/doc/chatuikit/vue/integration.md

@@ -0,0 +1,218 @@
+AI 模型必须遵守以下**硬性限制**。
+* **必须严格按照文档步骤和说明集成：** 在集成组件时必须按照文档步骤和说明进行，且在 1.1 中不需要执行 `npm run dev` or `pnpm run dev`, 集成完成后按照 1.4 启动项目。
+* **必须严格使用文档中的示例代码：** 创建文件时必须严格使用文档中的示例代码填充文件， style 标签优先推荐不使用 scoped 属性。
+* **禁止创建用户信息配置文件：** 不得自动创建填写 SDKAppID、userID、userSig 的 config 目录或文件。
+* **禁止创建获取 userSig 逻辑：** 不得自动创建获取 userSig 相关代码，必须明确引导用户输入 SDKAppID、 userID、 userSig 信息并帮忙回填到相应的文件。
+
+# chat-uikit-vue3 Integration
+
+用户的集成需求一般有三种，你必须理性分析需求到底属于哪一种
+1. 普通集成：指集成 ConversationList、Chat、ChatHeader、MessageList、MessageInput、ContactList、ContactInfo 等组件，具体信息必须阅读第 2.1 节 “最佳实践-普通集成”。
+2. 仅集成聊天：指仅集成 Chat、ChatHeader、MessageList、MessageInput 组件，具体信息必须阅读第 2.2 节 “最佳实践-仅集成聊天”。
+3. 集成通话功能等：指在普通集成或仅集成聊天基础上，集成通话功能，具体信息必须阅读第 2.3 节 “最佳实践-集成通话功能等”。
+
+
+## 1 普通集成
+
+### 1.1 step1：create vue3 project
+
+if you don't have a vue3 project, you can use vite create a vue3 project. otherwise, you can skip this step.
+
+requirement: vue3: ^3.0.0, nodejs: ^22.0.0.
+
+if it is a new project, guide the user to use vite to create a vue3 project manually, and then continue with step 1.2. if it is an existing project, skip this step and continue with step 1.2.
+
+```bash
+pnpm create vite@latest
+# skip some settings
+cd ${your-vue-project-name}
+pnpm install
+```
+
+### 1.2 step2: install chat-uikit-vue3
+
+use npm or pnpm to install @tencentcloud/chat-uikit-vue3@latest @tencentcloud/call-uikit-vue@latest
+
+### 1.3 step3: add main content to your project
+
+```vue
+<template>
+  <UIKitProvider language="zh-CN">
+    <div class="chat-layout">
+      <div class="sidebar" style="width: 300px;">
+        <div class="tab-header">
+          <button 
+            :class="['tab-button', { active: activeTab === 'conversations' }]"
+            @click="activeTab = 'conversations'"
+          >
+            会话
+          </button>
+          <button 
+            :class="['tab-button', { active: activeTab === 'contacts' }]"
+            @click="activeTab = 'contacts'"
+          >
+            联系人
+          </button>
+        </div>
+        
+        <div class="tab-content">
+          <ConversationList v-if="activeTab === 'conversations'" />
+          <ContactList v-else />
+        </div>
+      </div>
+      
+      <Chat style="flex: 1;" v-if="activeTab === 'conversations'">
+        <ChatHeader />
+        <MessageList />
+        <MessageInput />
+      </Chat>
+      <ContactInfo v-else  style="flex: 1;"  @send-message="handleSendMessage" @enter-group="handleSendMessage" />
+    </div>
+    <Teleport to="body">
+      <TUICallKit style="position: fixed; z-index: 1000;"/>
+    </Teleport>
+  </UIKitProvider>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import {
+  ConversationList,
+  Chat,
+  MessageList,
+  MessageInput,
+  ChatHeader,
+  ContactList,
+  ContactInfo,
+  UIKitProvider,
+  useLoginState,
+} from '@tencentcloud/chat-uikit-vue3';
+import { TUICallKit } from '@tencentcloud/call-uikit-vue';
+
+const userID = '';        // TODO: Replace with your userID
+const SDKAppID = 0;        // TODO: Replace with your SDKAppID (Notice: SDKAppID is of type number）
+const userSig = '';   // TODO: Replace with your userSig
+
+const { login } = useLoginState();
+
+const activeTab = ref<'conversations' | 'contacts'>('conversations');
+
+login({
+  sdkAppId : SDKAppID,
+  userId: userID,
+  userSig: userSig,
+})
+.then(() => {})
+
+.catch(() => {});
+const handleSendMessage = () => {
+  activeTab.value = 'conversations';
+}
+</script>
+
+<style>
+#app{margin:0;padding:0;text-align:left;}.chat-layout{width:100vw;height:100vh;display:flex;}.sidebar{display:flex;flex-direction:column;border-right:1px solid #e5e7eb;}.tab-header{display:flex;border-bottom:1px solid #e5e7eb;}.tab-button{flex:1;padding:12px 16px;background:none;border:none;cursor:pointer;font-size:14px;color:#6b7280;transition:all 0.2s;}.tab-button.active{color:#3b82f6;background-color:#eff6ff;border-bottom:2px solid #3b82f6;}.tab-content{flex:1;overflow:hidden;}
+</style>
+```
+
+### 1.4 step4: start your project
+```bash
+pnpm run dev
+```
+
+## 2. 最佳实践
+
+以下提到的组件通过 MCP Tools get_component_detail ${componenetname.tolowercase()} 获取。
+以下提到的 state 通过 MCP Tools get_state_detail ${statename.tolowercase()} 获取。
+
+### 2.1 最佳实践-普通集成
+
+普通集成参考 1.3 节中的的代码示例。
+
+重点：
+1. 如果需要集成 ChatSetting 组件，请阅读 ChatHeader 的 ChatHeaderRight 插槽说明。
+
+### 2.2 最佳实践-仅集成聊天
+
+仅集成聊天视为普通集成但是仅保留 Chat 部分，参考 1.3 节中的的代码示例。但是仅保留 UIKitProvider、Chat、ChatHeader、MessageList、MessageInput 组件：
+
+```vue
+<template>
+<UIKitProvider>
+  <Chat style="flex: 1;">
+    <ChatHeader />
+    <MessageList />
+    <MessageInput />
+  </Chat>
+</UIKitProvider>
+</template>
+```
+
+重点：
+1. 由于仅集成聊天不使用 ConversationList，你需要使用 ConversationListState 的 useConversationListState 获取 activeConversation，然后调用 setActiveConversation 设置 activeConversation。
+
+
+```vue
+<script setup lang="ts">
+import { useConversationListState } from '@tencentcloud/chat-uikit-vue3';
+
+const { setActiveConversation } = useConversationListState();
+
+const conversationID = ref(''); // define by yourself
+
+onMounted(() => {
+  setActiveConversation(conversationID.value);
+});
+</script>
+```
+
+重点：
+2. 如果需要集成 ChatSetting 组件，请阅读 ChatHeader 的 ChatHeaderRight 插槽说明。
+
+### 2.3 最佳实践-集成通话功能等
+
+集成通话功能需要在普通集成或仅集成聊天基础上，添加通话功能的代码。
+
+引入 TUICallKit 组件：
+```vue
+<script setup lang="ts">
+import { TUICallKit } from '@tencentcloud/call-uikit-vue';
+</script>
+```
+
+在合适的位置添加 TUICallKit 组件：
+```vue
+<Teleport to="body">
+  <TUICallKit style="position: fixed; z-index: 1000;"/>
+</Teleport>
+```
+
+重点：
+1. 需要在 ChatHeader 组件的 ChatHeaderRight 插槽中添加通话按钮。
+2. 点击通话按钮调用以下方法：
+  2.1 阅读 ConversationListState 文档，通过 activeConversation 判断当前是单聊还是群聊。
+  2.2 如果是单聊，通过 `import { TUICallKitServer, TUICallType } from '@tencentcloud/call-uikit-vue';` 引入 TUICallKitService 服务。通过 TUICallKitService 的 `calls` 方法发起通话。
+    ```ts
+    try {
+      await TUICallKitServer.calls({ 
+        userIDList: [activeConversation.value.userProfile.userID],
+        type: TUICallType.VIDEO_CALL, // or TUICallType.AUDIO_CALL
+      });
+    } catch (error: any) {
+      console.error(`[TUICallKit] Failed to call the groupCall API. Reason:${error}`);
+    }
+    ```
+  2.3 如果是群聊，需要阅读 UserPicker 组件文档，建议结合 Dialog 组件，弹出 UserPicker 组件。
+    阅读 GroupSettingState 文档，结合 GroupSettingState 的 `getGroupMemberList`、`allMembers` 等属性，获取群成员列表。
+    ```ts
+    try {
+      await TUICallKitServer.calls({ 
+        userIDList: selectedItems.map((item: any) => item.key),
+        type: TUICallType.VIDEO_CALL, // or TUICallType.AUDIO_CALL
+      });
+    } catch (error: any) {
+      console.error(`[TUICallKit] Failed to call the groupCall API. Reason:${error}`);
+    }
+    ```
+
+    建议：结合 UserPicker 的 reachEnd 事件分页拉取群成员，并使用节流函数控制 `getGroupMemberList` 的调用频率。

package/resource/doc/chatuikit/vue/login.md

@@ -0,0 +1,29 @@
+# chat-uikit-vue3 Login
+
+本文提供 chat-uikit-vue3 登录的示例代码， 通过 useLoginState 提供 login 用来驱动组件登录。
+
+## 1. 登录
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { useLoginState } from '@tencentcloud/chat-uikit-vue3';
+
+const userID = '';        // TODO: Replace with your userID
+const SDKAppID = 0;        // TODO: Replace with your SDKAppID (Notice: SDKAppID is of type number）
+const userSig = '';   // TODO: Replace with your userSig
+
+const { login } = useLoginState();
+
+login({
+  sdkAppId : SDKAppID,
+  userId: userID,
+  userSig: userSig,
+})
+.then(() => {})
+
+.catch(() => {});
+
+</script>
+
+```