# ConversationCreate 组件自定义文档

## 概述

ConversationCreate 是一个会话创建组件，提供了创建私聊和群聊的完整交互流程。组件支持用户选择、群组详情设置、创建前预处理和创建后回调等功能。它包含一个可点击的创建按钮，点击后展开多步骤的创建向导，支持返回导航和状态管理。适用于各种即时通讯场景，为用户提供便捷的会话创建体验。

## Props 配置表格

| 字段 | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| visible | `boolean` | `true` | 是否显示会话创建组件 |
| className | `string` | - | 自定义样式类名 |
| style | `React.CSSProperties` | - | 自定义样式 |
| onBeforeCreateConversation | `(params: string \| CreateGroupParams) => string \| CreateGroupParams` | - | 创建会话前的预处理回调 |
| onConversationCreated | `(conversation: ConversationModel) => void` | - | 会话创建成功回调 |
| onChangeCreateModelVisible | `(visible: boolean) => void` | - | 创建模态框显示状态变化回调 |
| conversationList | `ConversationModel[]` | `[]` | 现有会话列表，用于避免重复创建 |

## Props 详解

### visible

type: `boolean`

visible 用于控制会话创建组件是否显示，默认值为 `true`。

### className

type: `string`

className 用于自定义组件的样式类名，默认值为 `-`。

### style

type: `React.CSSProperties`

style 用于自定义组件的内联样式，默认值为 `-`。

### onBeforeCreateConversation

type: `(params: string | CreateGroupParams) => string | CreateGroupParams`

onBeforeCreateConversation 用于在创建会话前对参数进行预处理或验证，默认值为 `-`。

#### Example1: 基础参数预处理

```tsx
import { ConversationCreate, ConversationModel } from 'tuikit-atomicx-react';
import { CreateGroupParams } from '@tencentcloud/chat-uikit-engine';

function ConversationCreateWithPreprocessing() {
  const handleBeforeCreate = (params: string | CreateGroupParams) => {
    if (typeof params === 'string') {
      // 私聊参数预处理
      console.log('创建私聊会话，用户ID:', params);
      
      // 可以在这里添加用户ID验证
      if (!params || params.trim() === '') {
        throw new Error('用户ID不能为空');
      }
      
      // 返回处理后的用户ID
      return params.trim();
    } else {
      // 群聊参数预处理
      console.log('创建群聊会话，参数:', params);
      
      // 设置默认群名称
      if (!params.name || params.name.trim() === '') {
        params.name = `群聊_${new Date().getTime()}`;
      }
      
      // 设置默认群介绍
      if (!params.introduction) {
        params.introduction = '欢迎加入群聊！';
      }
      
      // 返回处理后的参数
      return params;
    }
  };

  const handleConversationCreated = (conversation: ConversationModel) => {
    console.log('会话创建成功:', conversation.conversationID);
  };

  return (
    <ConversationCreate
      onBeforeCreateConversation={handleBeforeCreate}
      onConversationCreated={handleConversationCreated}
    />
  );
}
```

#### Example2: 权限验证和参数增强

```tsx
import { ConversationCreate, ConversationModel } from 'tuikit-atomicx-react';
import { CreateGroupParams } from '@tencentcloud/chat-uikit-engine';

function ConversationCreateWithValidation() {
  const handleBeforeCreate = async (params: string | CreateGroupParams) => {
    try {
      if (typeof params === 'string') {
        // 私聊权限验证
        const canCreatePrivateChat = await checkPrivateChatPermission(params);
        if (!canCreatePrivateChat) {
          throw new Error('您没有权限与此用户创建私聊');
        }
        
        // 检查是否已存在会话
        const existingConversation = await checkExistingConversation(params);
        if (existingConversation) {
          throw new Error('与此用户的会话已存在');
        }
        
        // 记录创建意图
        analytics.track('private_chat_create_attempt', {
          targetUserId: params,
          timestamp: Date.now()
        });
        
        return params;
      } else {
        // 群聊权限验证
        const canCreateGroup = await checkGroupCreatePermission();
        if (!canCreateGroup) {
          throw new Error('您没有权限创建群聊');
        }
        
        // 验证群成员数量
        if (params.memberList && params.memberList.length > 500) {
          throw new Error('群成员数量不能超过500人');
        }
        
        // 敏感词过滤
        if (params.name) {
          params.name = await filterSensitiveWords(params.name);
        }
        if (params.introduction) {
          params.introduction = await filterSensitiveWords(params.introduction);
        }
        
        // 添加创建者标识
        const enhancedParams: CreateGroupParams = {
          ...params,
          groupCustomField: [
            ...(params.groupCustomField || []),
            {
              key: 'creator_info',
              value: JSON.stringify({
                creatorId: getCurrentUserId(),
                createTime: Date.now(),
                createSource: 'conversation_create_component'
              })
            }
          ]
        };
        
        // 记录创建意图
        analytics.track('group_chat_create_attempt', {
          groupName: params.name,
          memberCount: params.memberList?.length || 0,
          timestamp: Date.now()
        });
        
        return enhancedParams;
      }
    } catch (error) {
      console.error('创建会话前验证失败:', error);
      showErrorToast(error.message);
      throw error;
    }
  };

  const handleConversationCreated = (conversation: ConversationModel) => {
    console.log('会话创建成功:', conversation.conversationID);
  };

  return (
    <ConversationCreate
      onBeforeCreateConversation={handleBeforeCreate}
      onConversationCreated={handleConversationCreated}
    />
  );
}
```

### onConversationCreated

type: `(conversation: ConversationModel) => void`

onConversationCreated 用于处理会话创建成功后的回调，默认值为 `-`。

#### Example1: 基础创建成功处理

```tsx
import { ConversationCreate, ConversationModel } from 'tuikit-atomicx-react';
import { useNavigate } from 'react-router-dom';

function ConversationCreateWithSuccessHandler() {
  const navigate = useNavigate();

  const handleConversationCreated = (conversation: ConversationModel) => {
    console.log('会话创建成功:', conversation.conversationID);
    
    // 显示成功提示
    showSuccessToast(`${conversation.type === 'GROUP' ? '群聊' : '私聊'}创建成功`);
    
    // 发送统计数据
    analytics.track('conversation_created', {
      conversationId: conversation.conversationID,
      conversationType: conversation.type,
      timestamp: Date.now()
    });
    
    // 自动跳转到新创建的会话
    navigate(`/chat/${conversation.conversationID}`);
  };

  return (
    <ConversationCreate
      onConversationCreated={handleConversationCreated}
    />
  );
}
```

#### Example2: 复杂的创建后处理

```tsx
import { ConversationCreate, ConversationModel } from 'tuikit-atomicx-react';
import { useState } from 'react';

function ConversationCreateWithAdvancedHandler() {
  const [recentlyCreated, setRecentlyCreated] = useState<ConversationModel[]>([]);

  const handleConversationCreated = async (conversation: ConversationModel) => {
    try {
      console.log('会话创建成功:', conversation.conversationID);
      
      // 添加到最近创建列表
      setRecentlyCreated(prev => [conversation, ...prev.slice(0, 4)]);
      
      // 根据会话类型执行不同的后处理
      if (conversation.type === 'GROUP') {
        await handleGroupCreated(conversation);
      } else {
        await handlePrivateChatCreated(conversation);
      }
      
      // 发送欢迎消息
      await sendWelcomeMessage(conversation.conversationID, conversation.type);
      
      // 更新用户创建统计
      await updateUserCreateStats(getCurrentUserId(), conversation.type);
      
      // 通知其他组件
      window.dispatchEvent(new CustomEvent('conversationCreated', {
        detail: conversation
      }));
      
      // 显示成功提示
      showSuccessToast('会话创建成功，已自动发送欢迎消息');
      
    } catch (error) {
      console.error('会话创建后处理失败:', error);
      showErrorToast('会话创建成功，但初始化失败');
    }
  };

  const handleGroupCreated = async (conversation: ConversationModel) => {
    // 群聊特有的后处理
    try {
      // 设置群公告
      await conversation.updateGroupProfile({
        notification: '欢迎大家加入群聊！请遵守群规，友好交流。'
      });
      
      // 如果是大群，设置群管理员
      if (conversation.memberCount > 50) {
        await setGroupAdmins(conversation.conversationID);
      }
      
      // 创建群聊统计记录
      await createGroupAnalytics(conversation.conversationID);
      
    } catch (error) {
      console.error('群聊后处理失败:', error);
    }
  };

  const handlePrivateChatCreated = async (conversation: ConversationModel) => {
    // 私聊特有的后处理
    try {
      // 添加好友关系（如果还不是好友）
      const isFriend = await checkFriendshipStatus(conversation.userProfile.userID);
      if (!isFriend) {
        await sendFriendRequest(conversation.userProfile.userID);
      }
      
      // 记录私聊创建
      await recordPrivateChatCreation(conversation.conversationID);
      
    } catch (error) {
      console.error('私聊后处理失败:', error);
    }
  };

  const sendWelcomeMessage = async (conversationID: string, type: string) => {
    const welcomeMessage = type === 'GROUP' 
      ? '群聊已创建，开始愉快的交流吧！' 
      : '私聊已建立，可以开始对话了！';
    
    await sendTextMessage(conversationID, welcomeMessage);
  };

  return (
    <div>
      <ConversationCreate
        onConversationCreated={handleConversationCreated}
      />
      
      {/* 最近创建的会话显示 */}
      {recentlyCreated.length > 0 && (
        <div className="recently-created-conversations">
          <h4>最近创建</h4>
          {recentlyCreated.map(conversation => (
            <div key={conversation.conversationID} className="recent-item">
              <span>{conversation.getShowName()}</span>
              <span className="create-time">
                {new Date(conversation.createTime * 1000).toLocaleString()}
              </span>
            </div>
          ))}
        </div>
      )}
    </div>
  );
}
```

### onChangeCreateModelVisible

type: `(visible: boolean) => void`

onChangeCreateModelVisible 用于监听创建模态框显示状态的变化，默认值为 `-`。

#### Example1: 基础状态监听

```tsx
import { ConversationCreate, ConversationModel } from 'tuikit-atomicx-react';
import { useState } from 'react';

function ConversationCreateWithVisibilityTracking() {
  const [isCreateModalOpen, setIsCreateModalOpen] = useState(false);

  const handleVisibilityChange = (visible: boolean) => {
    console.log('创建模态框状态变化:', visible);
    setIsCreateModalOpen(visible);
    
    // 发送状态变化统计
    analytics.track('create_modal_visibility_change', {
      visible,
      timestamp: Date.now()
    });
  };

  const handleConversationCreated = (conversation: ConversationModel) => {
    console.log('会话创建成功:', conversation.conversationID);
  };

  return (
    <div>
      <ConversationCreate
        onChangeCreateModelVisible={handleVisibilityChange}
        onConversationCreated={handleConversationCreated}
      />
      
      {/* 状态指示器 */}
      <div className="status-indicator">
        创建面板状态: {isCreateModalOpen ? '打开' : '关闭'}
      </div>
    </div>
  );
}
```

#### Example2: 复杂的状态管理和优化

```tsx
import { ConversationCreate, ConversationModel } from 'tuikit-atomicx-react';
import { useState, useEffect, useRef } from 'react';

function ConversationCreateWithAdvancedVisibility() {
  const [isCreateModalOpen, setIsCreateModalOpen] = useState(false);
  const [modalOpenTime, setModalOpenTime] = useState<number | null>(null);
  const [userInteractions, setUserInteractions] = useState<string[]>([]);
  const modalRef = useRef<HTMLDivElement>(null);

  const handleVisibilityChange = (visible: boolean) => {
    console.log('创建模态框状态变化:', visible);
    setIsCreateModalOpen(visible);
    
    if (visible) {
      // 模态框打开时的处理
      setModalOpenTime(Date.now());
      setUserInteractions([]);
      
      // 禁止背景滚动
      document.body.style.overflow = 'hidden';
      
      // 记录打开事件
      analytics.track('create_modal_opened', {
        timestamp: Date.now(),
        userAgent: navigator.userAgent
      });
      
    } else {
      // 模态框关闭时的处理
      const openDuration = modalOpenTime ? Date.now() - modalOpenTime : 0;
      
      // 恢复背景滚动
      document.body.style.overflow = 'auto';
      
      // 记录使用统计
      analytics.track('create_modal_closed', {
        duration: openDuration,
        interactions: userInteractions,
        interactionCount: userInteractions.length,
        timestamp: Date.now()
      });
      
      // 清理状态
      setModalOpenTime(null);
      setUserInteractions([]);
    }
  };

  const handleConversationCreated = (conversation: ConversationModel) => {
    console.log('会话创建成功:', conversation.conversationID);
    
    // 记录创建成功的交互
    setUserInteractions(prev => [...prev, 'conversation_created']);
  };

  // 监听用户交互
  useEffect(() => {
    const handleUserInteraction = (event: Event) => {
      if (isCreateModalOpen && modalRef.current?.contains(event.target as Node)) {
        const interactionType = event.type;
        setUserInteractions(prev => [...prev, interactionType]);
      }
    };

    if (isCreateModalOpen) {
      document.addEventListener('click', handleUserInteraction);
      document.addEventListener('keydown', handleUserInteraction);
    }

    return () => {
      document.removeEventListener('click', handleUserInteraction);
      document.removeEventListener('keydown', handleUserInteraction);
    };
  }, [isCreateModalOpen]);

  // 组件卸载时清理
  useEffect(() => {
    return () => {
      document.body.style.overflow = 'auto';
    };
  }, []);

  return (
    <div ref={modalRef}>
      <ConversationCreate
        onChangeCreateModelVisible={handleVisibilityChange}
        onConversationCreated={handleConversationCreated}
      />
      
      {/* 调试信息 */}
      {process.env.NODE_ENV === 'development' && (
        <div className="debug-info">
          <p>模态框状态: {isCreateModalOpen ? '打开' : '关闭'}</p>
          <p>打开时长: {modalOpenTime ? Math.floor((Date.now() - modalOpenTime) / 1000) : 0}秒</p>
          <p>交互次数: {userInteractions.length}</p>
        </div>
      )}
    </div>
  );
}
```

### conversationList

type: `ConversationModel[]`

conversationList 用于传入现有的会话列表，帮助组件避免创建重复的会话，默认值为 `[]`。

#### Example1: 基础重复检查

```tsx
import { ConversationCreate, ConversationModel } from 'tuikit-atomicx-react';
import { useState, useEffect } from 'react';

function ConversationCreateWithDuplicateCheck() {
  const [existingConversations, setExistingConversations] = useState<ConversationModel[]>([]);

  useEffect(() => {
    // 获取现有会话列表
    fetchConversationList().then(setExistingConversations);
  }, []);

  const handleConversationCreated = (conversation: ConversationModel) => {
    console.log('会话创建成功:', conversation.conversationID);
    
    // 更新本地会话列表
    setExistingConversations(prev => [conversation, ...prev]);
    
    showSuccessToast('会话创建成功');
  };

  return (
    <ConversationCreate
      conversationList={existingConversations}
      onConversationCreated={handleConversationCreated}
    />
  );
}
```

#### Example2: 智能会话推荐

```tsx
import { ConversationCreate, ConversationModel } from 'tuikit-atomicx-react';
import { useState, useEffect, useMemo } from 'react';

function ConversationCreateWithRecommendations() {
  const [existingConversations, setExistingConversations] = useState<ConversationModel[]>([]);
  const [userContacts, setUserContacts] = useState<any[]>([]);

  useEffect(() => {
    // 获取现有会话列表和用户联系人
    Promise.all([
      fetchConversationList(),
      fetchUserContacts()
    ]).then(([conversations, contacts]) => {
      setExistingConversations(conversations);
      setUserContacts(contacts);
    });
  }, []);

  // 计算推荐的联系人（排除已有会话的用户）
  const recommendedContacts = useMemo(() => {
    const existingUserIds = existingConversations
      .filter(conv => conv.type === 'C2C')
      .map(conv => conv.userProfile.userID);
    
    return userContacts
      .filter(contact => !existingUserIds.includes(contact.userID))
      .slice(0, 10); // 只显示前10个推荐
  }, [existingConversations, userContacts]);

  // 计算活跃群聊推荐
  const activeGroupRecommendations = useMemo(() => {
    return existingConversations
      .filter(conv => conv.type === 'GROUP')
      .filter(conv => {
        // 最近7天有消息的群聊
        const lastMessageTime = conv.lastMessage?.lastTime || 0;
        const sevenDaysAgo = Date.now() / 1000 - 7 * 24 * 60 * 60;
        return lastMessageTime > sevenDaysAgo;
      })
      .sort((a, b) => (b.lastMessage?.lastTime || 0) - (a.lastMessage?.lastTime || 0))
      .slice(0, 5);
  }, [existingConversations]);

  const handleConversationCreated = (conversation: ConversationModel) => {
    console.log('会话创建成功:', conversation.conversationID);
    
    // 更新本地会话列表
    setExistingConversations(prev => [conversation, ...prev]);
    
    // 记录创建统计
    analytics.track('conversation_created_with_context', {
      conversationId: conversation.conversationID,
      conversationType: conversation.type,
      totalExistingConversations: existingConversations.length,
      recommendedContactsCount: recommendedContacts.length,
      timestamp: Date.now()
    });
    
    showSuccessToast('会话创建成功');
  };

  return (
    <div>
      <ConversationCreate
        conversationList={existingConversations}
        onConversationCreated={handleConversationCreated}
      />
      
      {/* 推荐联系人 */}
      {recommendedContacts.length > 0 && (
        <div className="recommended-contacts">
          <h4>推荐联系人</h4>
          <div className="contact-list">
            {recommendedContacts.map(contact => (
              <div key={contact.userID} className="contact-item">
                <img src={contact.avatar} alt={contact.nick} />
                <span>{contact.nick}</span>
                <button 
                  onClick={() => createPrivateChat(contact.userID)}
                  className="quick-chat-btn"
                >
                  聊天
                </button>
              </div>
            ))}
          </div>
        </div>
      )}
      
      {/* 活跃群聊 */}
      {activeGroupRecommendations.length > 0 && (
        <div className="active-groups">
          <h4>活跃群聊</h4>
          <div className="group-list">
            {activeGroupRecommendations.map(group => (
              <div key={group.conversationID} className="group-item">
                <img src={group.getAvatar()} alt={group.getShowName()} />
                <div className="group-info">
                  <span className="group-name">{group.getShowName()}</span>
                  <span className="last-message">
                    {group.lastMessage?.messageForShow || '暂无消息'}
                  </span>
                </div>
                <span className="member-count">{group.memberCount}人</span>
              </div>
            ))}
          </div>
        </div>
      )}
    </div>
  );
}
```