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

package/resource/knowledge/chat/preset/react/features/chat-setting.md

@@ -0,0 +1,123 @@
+## 组件概述
+
+ChatSetting 是一个聊天设置组件，它能根据当前激活的**会话类型**（单聊或群聊）自动渲染对应的设置界面。该组件通过统一的入口，无缝集成了 C2C（单聊） 和群聊两种模式的设置功能，为用户提供了流畅且一致的操作体验。
+
+核心功能：
+- 智能适配： 自动识别**会话类型**，并切换至相应的设置面板。
+
+- 状态驱动： 基于当前会话状态，动态更新设置内容。
+
+   > **注意：**
+   >
+
+   > 如果当前没有激活的会话则不会显示。
+   >
+
+## 快速使用
+``` typescript
+import { useState } from 'react';
+import {
+  ChatSetting,
+  Search,
+  useChatContext,
+  VariantType,
+} from '@tencentcloud/chat-uikit-react';
+import './styles.css';
+
+function ChatSidePanelsBasicDemo() {
+  const [isChatSettingShow, setIsChatSettingShow] = useState(false);
+  const [isSearchShow, setIsSearchShow] = useState(false);
+  const [targetID, setTargetID] = useState('');
+  const [conversationType, setConversationType] = useState<'C2C' | 'GROUP'>('C2C');
+  const { activeConversationID, setActiveConversation } = useChatContext();
+
+  const handleActivateConversation = () => {
+    const normalizedID = targetID.trim();
+    if (!normalizedID) {
+      return;
+    }
+    setActiveConversation(`${conversationType}${normalizedID}`);
+  };
+
+  return (
+    <div className="chat-side-panels-basic-demo">
+      <div className="chat-side-panels-basic-demo__header">
+        <h2>Chat Side Panels</h2>
+        <p>Activate a conversation, then open or close ChatSetting and Search.</p>
+      </div>
+
+      <div className="chat-side-panels-basic-demo__frame">
+        <div className="chat-side-panels-basic-demo__actions">
+          <input
+            onChange={event => setTargetID(event.target.value)}
+            placeholder="User ID or group ID"
+            value={targetID}
+          />
+          <select
+            onChange={event => setConversationType(event.target.value as 'C2C' | 'GROUP')}
+            value={conversationType}
+          >
+            <option value="C2C">C2C</option>
+            <option value="GROUP">GROUP</option>
+          </select>
+          <button onClick={handleActivateConversation} type="button">
+            Activate Conversation
+          </button>
+          <span className="chat-side-panels-basic-demo__active">
+            Active: {activeConversationID || 'None'}
+          </span>
+          <button
+            onClick={() => setIsChatSettingShow(show => !show)}
+            type="button"
+          >
+            {isChatSettingShow ? 'Hide Setting' : 'Show Setting'}
+          </button>
+          <button
+            onClick={() => setIsSearchShow(show => !show)}
+            type="button"
+          >
+            {isSearchShow ? 'Hide Search' : 'Show Search'}
+          </button>
+        </div>
+
+        {isChatSettingShow && (
+          <div className="chat-side-panels-basic-demo__panel">
+            <ChatSetting />
+          </div>
+        )}
+
+        {isSearchShow && (
+          <div className="chat-side-panels-basic-demo__panel">
+            <Search variant={VariantType.EMBEDDED} />
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
+```
+
+## 相关文档
+
+**官方文档**
+- 自定义组件 - UIKitProvider
+
+- 自定义组件 - ConversationList
+
+- 自定义组件 - MessageList
+
+- 自定义组件 - MessageInput
+
+- 自定义组件 - ContactList
+
+- 自定义组件 - Search
+
+   **NPM 包**
+
+- [chat-uikit-react npm](https://www.npmjs.com/package/@tencentcloud/chat-uikit-react)
+
+   **GitHub**
+
+- [GitHub Demo](https://github.com/TencentCloud/chat-uikit-react)
+
+## 交流与反馈

package/resource/{doc/chatkit/react/components → knowledge/chat/preset/react/features}/contact-list.md

@@ -1,51 +1,53 @@
 ## 概述
 
-ContactList 是一个高度可配置的联系人列表组件。该组件支持好友列表、群组列表、黑名单和申请管理，提供分组折叠、搜索过滤、自定义渲染等核心功能，适用于即时通讯、社交应用等场景的联系人管理界面。
+ContactList 是一个高度可配置的联系人列表组件。该组件支持好友列表、群组列表、黑名单和申请管理，提供分组折叠、搜索过滤、自定义渲染等核心功能，适用于即时通信、社交应用等场景的联系人管理界面。
 
 ## ContactList Props
-| 字段 | 类型 | 默认值 | 描述 |
-| --- | --- | --- | --- |
-| activeContactItem | ContactGroupItem \\| undefined | `undefined` | 当前激活的联系人项 |
-| enableSearch | boolean | `true` | 是否启用搜索功能 |
-| groupConfig | Partial<Record<ContactItemType, CustomGroupConfig>> | `{}` | 自定义分组配置 |
-| className | string | `undefined` | 自定义 CSS 类名 |
-| style | React.CSSProperties | `undefined` | 自定义内联样式 |
-| searchPlaceholder | string | `'Search contacts'` | 搜索框占位符文本 |
-| emptyText | string | `'No contacts'` | 空状态提示文本 |
-| ContactItem | React.ComponentType<ContactListItemProps> \\| undefined | `ContactListItem` | 自定义联系人项组件 |
-| ContactSearchComponent | React.ComponentType<ContactSearchProps> \\| undefined | `ContactSearch` | 自定义搜索组件 |
-| GroupHeader | React.ComponentType<{ data: ContactGroup }> \\| undefined | 默认分组头 | 自定义分组头部组件 |
-| PlaceholderEmptyList | React.ReactNode \\| undefined | 默认空状态 | 自定义空状态组件 |
-| onContactItemClick | (item: ContactGroupItem) => void | `undefined` | 联系人项点击事件 |
-| onFriendApplicationAction | (action: 'accept' \\| 'refuse', application: FriendApplication) => void | `undefined` | 好友申请操作事件 |
-| onGroupApplicationAction | (action: 'accept' \\| 'refuse', application: GroupApplication) => void | `undefined` | 群组申请操作事件 |
+
+|字段|类型|默认值|描述|
+|---------|---------|---------|---------|
+|activeContactItem|ContactGroupItem \| undefined|`undefined`|当前激活的联系人项|
+|enableSearch|boolean|`true`|是否启用搜索功能|
+|groupConfig|Partial<Record<ContactItemType, CustomGroupConfig>>|`{}`|自定义分组配置|
+|className|string|`undefined`|自定义 CSS 类名|
+|style|React.CSSProperties|`undefined`|自定义内联样式|
+|searchPlaceholder|string|`'Search contacts'`|搜索框占位符文本|
+|emptyText|string|`'No contacts'`|空状态提示文本|
+|ContactItem|React.ComponentType<ContactListItemProps> \| undefined|`ContactListItem`|自定义联系人项组件|
+|ContactSearchComponent|React.ComponentType<ContactSearchProps> \| undefined|`ContactSearch`|自定义搜索组件|
+|GroupHeader|React.ComponentType<{ data: ContactGroup }> \| undefined|默认分组头|自定义分组头部组件|
+|PlaceholderEmptyList|React.ReactNode \| undefined|默认空状态|自定义空状态组件|
+|onContactItemClick|(item: ContactGroupItem) => void|`undefined`|联系人项点击事件|
+|onFriendApplicationAction|(action: 'accept' \| 'refuse', application: FriendApplication) => void|`undefined`|好友申请操作事件|
+|onGroupApplicationAction|(action: 'accept' \| 'refuse', application: GroupApplication) => void|`undefined`|群组申请操作事件|
 
 ## ContactInfo props
-| 字段 | 类型 | 默认值 | 描述 |
-| --- | --- | --- | --- |
-| contactItem | ContactGroupItem \\| undefined | `undefined` | 当前显示的联系人项 |
-| showActions | boolean | `true` | 是否显示操作按钮 |
-| PlaceholderEmpty | React.ReactNode \\| undefined | `undefined` | 空状态占位组件 |
-| FriendInfoComponent | React.ComponentType<FriendInfoProps> | `FriendInfo` | 好友信息组件 |
-| GroupInfoComponent | React.ComponentType<GroupInfoProps> | `GroupInfo` | 群组信息组件 |
-| BlacklistInfoComponent | React.ComponentType<BlacklistInfoProps> | `BlacklistInfo` | 黑名单信息组件 |
-| FriendApplicationInfoComponent | React.ComponentType<FriendApplicationInfoProps> | `FriendApplicationInfo` | 好友申请信息组件 |
-| GroupApplicationInfoComponent | React.ComponentType<GroupApplicationInfoProps> | `GroupApplicationInfo` | 群组申请信息组件 |
-| SearchGroupInfoComponent | React.ComponentType<SearchGroupInfoProps> | `SearchGroupInfo` | 搜索群组信息组件 |
-| SearchUserInfoComponent | React.ComponentType<SearchUserInfoProps> | `SearchUserInfo` | 搜索用户信息组件 |
-| onClose | () => void | `undefined` | 关闭信息面板回调 |
-| onSendMessage | (friend: Friend) => void | `undefined` | 发送消息回调 |
-| onDeleteFriend | (friend: Friend) => void | `undefined` | 删除好友回调 |
-| onUpdateFriendRemark | (friend: Friend, remark: string) => void | `undefined` | 更新好友备注回调 |
-| onAddToBlacklist | (friend: Friend) => void | `undefined` | 添加到黑名单回调 |
-| onRemoveFromBlacklist | (profile: UserProfile) => void | `undefined` | 从黑名单移除回调 |
-| onEnterGroup | (group: GroupModel) => void | `undefined` | 进入群组回调 |
-| onLeaveGroup | (group: GroupModel) => void | `undefined` | 退出群组回调 |
-| onDismissGroup | (group: GroupModel) => void | `undefined` | 解散群组回调 |
-| onFriendApplicationAction | (action: 'accept' \\| 'refuse', application: FriendApplication) => void | `undefined` | 好友申请操作回调 |
-| onGroupApplicationAction | (action: 'accept' \\| 'refuse', application: GroupApplication) => void | `undefined` | 群组申请操作回调 |
-| onAddFriend | (user: UserProfile, wording: string) => void | `undefined` | 添加好友回调 |
-| onJoinGroup | (group: GroupModel, note: string) => void | `undefined` | 加入群组回调 |
+
+|字段|类型|默认值|描述|
+|---------|---------|---------|---------|
+|contactItem|ContactGroupItem \| undefined|`undefined`|当前显示的联系人项|
+|showActions|boolean|`true`|是否显示操作按钮|
+|PlaceholderEmpty|React.ReactNode \| undefined|`undefined`|空状态占位组件|
+|FriendInfoComponent|React.ComponentType<FriendInfoProps>|`FriendInfo`|好友信息组件|
+|GroupInfoComponent|React.ComponentType<GroupInfoProps>|`GroupInfo`|群组信息组件|
+|BlacklistInfoComponent|React.ComponentType<BlacklistInfoProps>|`BlacklistInfo`|黑名单信息组件|
+|FriendApplicationInfoComponent|React.ComponentType<FriendApplicationInfoProps>|`FriendApplicationInfo`|好友申请信息组件|
+|GroupApplicationInfoComponent|React.ComponentType<GroupApplicationInfoProps>|`GroupApplicationInfo`|群组申请信息组件|
+|SearchGroupInfoComponent|React.ComponentType<SearchGroupInfoProps>|`SearchGroupInfo`|搜索群组信息组件|
+|SearchUserInfoComponent|React.ComponentType<SearchUserInfoProps>|`SearchUserInfo`|搜索用户信息组件|
+|onClose|() => void|`undefined`|关闭信息面板回调|
+|onSendMessage|(friend: Friend) => void|`undefined`|发送消息回调|
+|onDeleteFriend|(friend: Friend) => void|`undefined`|删除好友回调|
+|onUpdateFriendRemark|(friend: Friend, remark: string) => void|`undefined`|更新好友备注回调|
+|onAddToBlacklist|(friend: Friend) => void|`undefined`|添加到黑名单回调|
+|onRemoveFromBlacklist|(profile: UserProfile) => void|`undefined`|从黑名单移除回调|
+|onEnterGroup|(group: GroupModel) => void|`undefined`|进入群组回调|
+|onLeaveGroup|(group: GroupModel) => void|`undefined`|退出群组回调|
+|onDismissGroup|(group: GroupModel) => void|`undefined`|解散群组回调|
+|onFriendApplicationAction|(action: 'accept' \| 'refuse', application: FriendApplication) => void|`undefined`|好友申请操作回调|
+|onGroupApplicationAction|(action: 'accept' \| 'refuse', application: GroupApplication) => void|`undefined`|群组申请操作回调|
+|onAddFriend|(user: UserProfile, wording: string) => void|`undefined`|添加好友回调|
+|onJoinGroup|(group: GroupModel, note: string) => void|`undefined`|加入群组回调|
 
 ## 基础使用
 ``` tsx
@@ -685,66 +687,216 @@ function CustomGroupApplicationInfoDemo() {
 
 效果如下图所示：
 
-## useContactListState
-
-ContactListState 是基于 Zustand 的关系链管理钩子，为 ContactLis 组件提供完整的数据管理能力。它支持好友列表、群组列表、黑名单和申请管理等功能关了。如果自定义组件能力不能支持您的业务，可以使用 ContactListState 实现您的需求。
-
-### 数据
-| 属性名 | 类型 | 说明 |
-| --- | --- | --- |
-| friendList | Friend[] | 好友列表 |
-| groupList | Group[] | 群组列表 |
-| blackList | UserProfile[] | 黑名单列表 |
-| friendApplicationUnreadCount | number | 未读好友申请数量 |
-| friendGroupList | FriendGroup[] | 好友分组列表 |
-| friendApplicationList | FriendApplication[] | 好友申请列表 |
-| groupApplicationList | GroupApplication[] | 群组申请列表 |
-
-### 操作方法
-| 属性名 | 类型 | 说明 |
-| --- | --- | --- |
-| addFriend | (options: AddFriendParams) => Promise | 添加好友 |
-| deleteFriend | (options: DeleteFriendParams) => Promise | 删除好友 |
-| setFriendRemark | (options: FriendRemarkParams) => Promise | 设置好友备注 |
-| markFriendApplicationAsRead | () => Promise | 标记好友申请为已读 |
-| acceptFriendApplication | (options: FriendApplicationParams) => Promise | 接受好友申请 |
-| refuseFriendApplication | (userID: string) => Promise | 拒绝好友申请 |
-| addToBlacklist | (userIDList: string[]) => Promise | 添加到黑名单 |
-| removeFromBlacklist | (userIDList: string[]) => Promise | 从黑名单移除 |
-| createFriendGroup | (options: FriendGroupParams) => Promise | 创建好友分组 |
-| deleteFriendGroup | (name: string) => Promise | 删除好友分组 |
-| addToFriendGroup | (options: FriendGroupParams) => Promise | 添加好友到分组 |
-| removeFromFriendGroup | (options: FriendGroupParams) => Promise | 从分组移除好友 |
-| renameFriendGroup | (options: RenameFriendGroupParams) => Promise | 重命名好友分组 |
-| joinGroup | (options: JoinGroupParams) => Promise | 申请加入群组 |
-| acceptGroupApplication | (options: GroupApplicationParams) => Promise | 接受群组申请 |
-| refuseGroupApplication | (options: GroupApplicationParams) => Promise | 拒绝群组申请 |
-
-## 使用示例
-``` typescript
-import { useContactListState } from '@tencentcloud/chat-uikit-react';
-const {
-    friendList,
-    groupList,
-    blackList,
-    friendApplicationUnreadCount,
-    friendGroupList,
-    friendApplicationList,
-    groupApplicationList,
-    addFriend,
-    deleteFriend,
-    setFriendRemark,
-    markFriendApplicationAsRead,
-    acceptFriendApplication,
-    refuseFriendApplication,
-    addToBlacklist,
-    removeFromBlacklist,
-    createFriendGroup,
-    deleteFriendGroup,
-    addToFriendGroup,
-    removeFromFriendGroup,
-    joinGroup,
-    acceptGroupApplication,
-    refuseGroupApplication,
-  } = useContactListState();
+## Contact Store
+
+ContactStore 提供完整的联系人相关的数据管理能力。它支持好友列表、群组列表、黑名单和申请管理等功能。如果自定义组件能力不能支持您的业务，可以使用 ContactStore 实现您的需求。
+
+### 属性
+
+|方法名|类型|说明|
+|---------|---------|---------|
+|friendList|ContactInfo[]|好友列表。每项包含用户 ID、昵称、头像、好友备注、在线状态、是否好友、是否在黑名单等信息。|
+|friendApplicationList|FriendApplicationInfo[]|好友申请列表。包含收到/发出的好友申请信息。|
+|friendApplicationUnreadCount|number|好友申请未读数量。|
+|blackList|ContactInfo[]|黑名单列表。每项同样使用 ContactInfo 数据结构，并标记 isInBlacklist: true。|
+
+### 方法
+
+|方法名|类型|说明|
+|---------|---------|---------|
+|loadFriends|() => Promise<void>|加载好友列表，并补充好友关系、黑名单状态和在线状态。|
+|addFriend|(params: AddFriendParams) => Promise<void>|添加好友。参数包含 userID、source、remark、addWording。|
+|deleteFriend|(userID: string) => Promise<void>|删除指定好友，并本地更新 friendList。|
+|setFriendRemark|(userID: string, remark: string) => Promise<void>|设置好友备注，并本地更新该好友的 friendRemark。|
+|getContactInfo|(userIDList: string[]) => Promise<ContactInfo[]>|批量获取用户资料，并结合当前好友列表、黑名单状态返回标准 ContactInfo。|
+|loadBlackList|() => Promise<void>|加载黑名单列表，并同步更新好友列表中的 isInBlacklist 状态。|
+|addToBlacklist|(userID: string) => Promise<void>|将指定用户加入黑名单，并本地更新 blackList 与 friendList。|
+|removeFromBlacklist|(userID: string) => Promise<void>|将指定用户移出黑名单，并本地更新 blackList 与 friendList。|
+|loadFriendApplications|() => Promise<void>|加载好友申请列表和未读申请数量。|
+|acceptFriendApplication|(info: FriendApplicationInfo) => Promise<void>|同意好友申请。状态更新依赖 SDK 事件同步。|
+|refuseFriendApplication|(info: FriendApplicationInfo) => Promise<void>|拒绝好友申请。状态更新依赖 SDK 事件同步。|
+|clearFriendApplicationUnreadCount|() => Promise<void>|标记好友申请为已读，并将本地未读数置为 0。|
+|destroy|() => void|注销事件监听、清理在线状态订阅和 Store 状态。通常由框架封装层管理。|
+
+### 使用示例
+
+该使用示例展示了如何使用 ContactStore 和 GroupStore 实现一个简单的联系人页面，包含好友列表和群聊列表。
+
+【index.tsx】
+``` tsx
+import { useEffect } from 'react';
+import {
+  ContactStore,
+  GroupStore,
+} from '@tencentcloud/chat-uikit-react';
+import './styles.css';
+
+function ContactStoreBasicDemo() {
+  const { friendList, loadFriends } = ContactStore();
+  const { joinedGroupList, loadJoinedGroups } = GroupStore();
+
+  useEffect(() => {
+    loadFriends();
+    loadJoinedGroups();
+  }, []);
+
+  return (
+    <div className="contact-store-basic-demo">
+      <div className="contact-store-basic-demo__header">
+        <h2>Contact Store Basic</h2>
+        <p>Simple friend and group list powered by ContactStore and GroupStore.</p>
+      </div>
+
+      <div className="contact-store-basic-demo__columns">
+        <section className="contact-store-basic-demo__panel">
+          <h3>Friends ({friendList.length})</h3>
+          {friendList.length > 0 ? (
+            <ul className="contact-store-basic-demo__list">
+              {friendList.map(friend => (
+                <li className="contact-store-basic-demo__item" key={friend.userID}>
+                  <span className="contact-store-basic-demo__avatar">
+                    {(friend.friendRemark || friend.nickname || friend.userID).slice(0, 1).toUpperCase()}
+                  </span>
+                  <span>
+                    <strong>{friend.friendRemark || friend.nickname || friend.userID}</strong>
+                    <small>{friend.userID}</small>
+                  </span>
+                </li>
+              ))}
+            </ul>
+          ) : (
+            <div className="contact-store-basic-demo__empty">No friends.</div>
+          )}
+        </section>
+
+        <section className="contact-store-basic-demo__panel">
+          <h3>Groups ({joinedGroupList.length})</h3>
+          {joinedGroupList.length > 0 ? (
+            <ul className="contact-store-basic-demo__list">
+              {joinedGroupList.map(group => (
+                <li className="contact-store-basic-demo__item" key={group.groupID}>
+                  <span className="contact-store-basic-demo__avatar">
+                    {(group.groupName || group.groupID).slice(0, 1).toUpperCase()}
+                  </span>
+                  <span>
+                    <strong>{group.groupName || group.groupID}</strong>
+                    <small>{group.groupID}</small>
+                  </span>
+                </li>
+              ))}
+            </ul>
+          ) : (
+            <div className="contact-store-basic-demo__empty">No groups.</div>
+          )}
+        </section>
+      </div>
+    </div>
+  );
+}
+```
+
+【index.css】
+``` java
+.contact-store-basic-demo {
+  display: flex;
+  height: 100%;
+  flex-direction: column;
+  gap: 20px;
+  padding: 24px;
+  overflow: hidden;
+}
+
+.contact-store-basic-demo__header h2 {
+  margin: 0 0 8px;
+  color: #111827;
+  font-size: 22px;
+}
+
+.contact-store-basic-demo__header p {
+  margin: 0;
+  color: #6b7280;
+  font-size: 14px;
+}
+
+.contact-store-basic-demo__columns {
+  display: grid;
+  min-height: 0;
+  flex: 1;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: 16px;
+}
+
+.contact-store-basic-demo__panel {
+  display: flex;
+  min-width: 0;
+  min-height: 0;
+  flex-direction: column;
+  overflow: hidden;
+  border: 1px solid #edf0f5;
+  border-radius: 12px;
+  background: #fff;
+}
+
+.contact-store-basic-demo__panel h3 {
+  margin: 0;
+  padding: 14px 16px;
+  border-bottom: 1px solid #edf0f5;
+  color: #111827;
+  font-size: 15px;
+}
+
+.contact-store-basic-demo__list {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  margin: 0;
+  padding: 12px;
+  overflow: auto;
+  list-style: none;
+}
+
+.contact-store-basic-demo__item {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  padding: 10px;
+  border-radius: 10px;
+  background: #f9fafb;
+}
+
+.contact-store-basic-demo__avatar {
+  display: inline-flex;
+  width: 32px;
+  height: 32px;
+  align-items: center;
+  justify-content: center;
+  border-radius: 50%;
+  background: #eef2ff;
+  color: #4f46e5;
+  font-size: 13px;
+  font-weight: 700;
+}
+
+.contact-store-basic-demo__item strong,
+.contact-store-basic-demo__item small {
+  display: block;
+}
+
+.contact-store-basic-demo__item strong {
+  color: #111827;
+  font-size: 14px;
+}
+
+.contact-store-basic-demo__item small {
+  margin-top: 2px;
+  color: #6b7280;
+  font-size: 12px;
+}
+
+.contact-store-basic-demo__empty {
+  padding: 24px;
+  color: #6b7280;
+  text-align: center;
+}
+
 ```