TUIKit AtomicX React

✨ 特性

• 🎯 专业场景适配 - 深度适配在线会议、在线直播、在线教育等音视频场景
• 🚀 开箱即用 - 提供完整的聊天功能组件，快速集成到您的应用
• 💪 TypeScript 支持 - 完整的类型定义，提供优秀的开发体验
• 🎨 主题定制 - 支持深色/浅色主题，可自定义样式
• 🌍 国际化 - 内置多语言支持，轻松实现国际化
• 📱 响应式设计 - 完美适配桌面端和移动端
• ⚡ 高性能 - 基于 Zustand 状态管理，性能优异
• 🔧 灵活扩展 - 模块化设计，支持按需引入和自定义扩展
• 👥 联系人管理 - 完整的联系人列表组件，支持好友、群组、黑名单管理
• 🎛️ 状态管理 - 12+ 个专业状态管理 Hook，覆盖所有聊天场景
• 🔄 消息操作 - 支持消息转发、引用、撤回、复制等完整操作
• 📊 性能优化 - 虚拟滚动、消息聚合、防抖搜索等性能优化

📦 安装

# npm
npm install tuikit-atomicx-react

# yarn
yarn add tuikit-atomicx-react

# pnpm
pnpm add tuikit-atomicx-react

🚀 快速开始

基础使用

import React from 'react';
import { 
  Search, 
  ConversationList, 
  MessageList,
  MessageInput,
  VariantType 
} from 'tuikit-atomicx-react';
import 'tuikit-atomicx-react/dist/style.css';

function App() {
  return (
    <div className="chat-app">
      {/* 搜索组件 */}
      <Search variant={VariantType.STANDARD} />
      
      {/* 会话列表 */}
      <ConversationList />
      
      {/* 消息列表 */}
      <MessageList />
      
      {/* 消息输入框 */}
      <MessageInput />
    </div>
  );
}

export default App;

📚 核心组件

🔍 Search - 搜索组件

支持用户、群组、消息的全功能搜索组件。

import { Search, VariantType } from 'tuikit-atomicx-react';

<Search 
  variant={VariantType.STANDARD}  // 搜索模式：STANDARD | EMBEDDED | MINI
  onResultClick={(result) => console.log(result)}
  placeholder="搜索..."
/>

功能特性：

• ✅ 防抖搜索（300ms）
• ✅ 多类型搜索（用户/群组/消息）
• ✅ 高级搜索参数支持
• ✅ 分页加载更多
• ✅ 三种搜索模式（标准/嵌入/迷你）

💬 ConversationList - 会话列表

展示用户会话列表，支持会话管理功能。

import { ConversationList } from 'tuikit-atomicx-react';

<ConversationList 
  onConversationClick={(conversation) => console.log(conversation)}
  showUnreadCount={true}
  enableSwipeActions={true}
/>

📝 MessageList - 消息列表

展示聊天消息列表，支持多种消息类型。

import { MessageList } from 'tuikit-atomicx-react';

<MessageList 
  conversationID="conversation_id"
  onMessageClick={(message) => console.log(message)}
  enableVirtualScroll={true}
/>

✏️ MessageInput - 消息输入

基于 TipTap 的富文本消息输入组件。

import { MessageInput } from 'tuikit-atomicx-react';

<MessageInput 
  conversationID="conversation_id"
  onSendMessage={(message) => console.log(message)}
  enableRichText={true}
  placeholder="输入消息..."
/>

👤 Avatar - 头像组件

用户和群组头像展示组件。

import { Avatar } from 'tuikit-atomicx-react';

<Avatar 
  src="https://example.com/avatar.jpg"
  name="用户名"
  shape="circle"  // circle | square
/>

👥 UserPicker - 用户选择器

支持多选的用户选择组件。

import { UserPicker } from 'tuikit-atomicx-react';

<UserPicker 
  multiple={true}
  onSelectionChange={(users) => console.log(users)}
  excludeUserIDs={['user1', 'user2']}
/>

⚙️ ChatSetting - 聊天设置

群组和个人聊天设置组件。

import { ChatSetting } from 'tuikit-atomicx-react';

<ChatSetting 
  conversationID="conversation_id"
  type="group"  // group | private
  onSettingChange={(setting) => console.log(setting)}
/>

👥 ContactList - 联系人列表

高度可配置的联系人列表组件，支持好友列表、群组列表、黑名单和申请管理。

import { ContactList } from 'tuikit-atomicx-react';

<ContactList 
  enableSearch={true}
  showOnlineStatus={true}
  showContactInfo={true}
  enableMultiSelect={true}
  onContactClick={(item) => console.log('Contact clicked:', item)}
  onAddFriend={(userID) => console.log('Add friend:', userID)}
  onJoinGroup={(groupID) => console.log('Join group:', groupID)}
/>

功能特性：

• ✅ 好友列表管理 - 支持好友添加、删除、备注设置
• ✅ 群组列表管理 - 支持群组加入、退出、群组信息查看
• ✅ 黑名单管理 - 支持添加/移除黑名单
• ✅ 申请管理 - 支持好友申请、群组申请处理
• ✅ 搜索功能 - 支持联系人搜索和筛选
• ✅ 分组管理 - 支持好友分组创建和管理

🎣 状态管理 Hooks

🔍 useSearchState - 搜索状态管理

提供完整的搜索功能状态管理。

import { useSearchState, VariantType } from 'tuikit-atomicx-react';

const {
  // 状态
  keyword,                    // 当前搜索关键词
  results,                    // 搜索结果 Map<SearchType, SearchResult>
  isLoading,                  // 是否正在搜索
  error,                      // 搜索错误信息
  searchAdvancedParams,       // 高级搜索参数
  selectedSearchType,         // 当前选择的搜索类型 'all' | 'user' | 'group' | 'message'
  
  // 方法
  setKeyword,                 // 设置搜索关键词
  setSelectedType,            // 设置搜索类型
  loadMore,                   // 加载更多结果
  setSearchMessageAdvancedParams,    // 设置消息搜索高级参数
  setSearchUserAdvancedParams,       // 设置用户搜索高级参数
  setSearchGroupAdvancedParams,      // 设置群组搜索高级参数
} = useSearchState(VariantType.STANDARD);

// 使用示例
const handleSearch = (keyword: string) => {
  setKeyword(keyword);
};

const handleTypeChange = (type: 'all' | 'user' | 'group' | 'message') => {
  setSelectedType(type);
};

💬 useConversationListState - 会话列表状态管理

管理会话列表的状态和操作。

import { useConversationListState } from 'tuikit-atomicx-react';

const {
  // 状态
  conversationList,           // 会话列表
  activeConversation,         // 当前激活的会话
  totalUnRead,               // 总未读消息数
  netStatus,                 // 网络状态
  
  // 方法
  setActiveConversation,      // 设置激活会话
  markConversationUnread,     // 标记会话未读/已读
  pinConversation,           // 置顶/取消置顶会话
  deleteConversation,        // 删除会话
  muteConversation,          // 免打扰/取消免打扰
  setConversationDraft,      // 设置会话草稿
  createC2CConversation,     // 创建单聊会话
  createGroupConversation,   // 创建群聊会话
} = useConversationListState();

// 使用示例
const handleConversationClick = (conversationID: string) => {
  setActiveConversation(conversationID);
};

📝 useMessageListState - 消息列表状态管理

管理消息列表的状态和操作。

import { useMessageListState } from 'tuikit-atomicx-react';

const {
  // 状态
  activeConversationID,       // 当前激活的会话ID
  messageList,               // 消息列表
  hasMoreOlderMessage,       // 是否有更多历史消息
  hasMoreNewerMessage,       // 是否有更多新消息
  enableReadReceipt,         // 是否启用已读回执
  isDisableScroll,           // 是否禁用滚动
  recalledMessageIDList,     // 已撤回消息ID列表
  
  // 方法
  loadMoreMessage,           // 加载更多消息
  setEnableReadReceipt,      // 设置已读回执状态
  setIsDisableScroll,        // 设置滚动禁用状态
} = useMessageListState();

// 使用示例
const handleLoadMore = async () => {
  await loadMoreMessage();
};

✏️ useMessageInputState - 消息输入状态管理

管理消息输入框的状态和操作。

import { useMessageInputState } from 'tuikit-atomicx-react';
import type { Editor } from '@tiptap/react';

const {
  // 状态
  editor,                    // TipTap 编辑器实例
  inputRawValue,             // 输入框原始值
  isPeerTyping,              // 对方是否正在输入
  
  // 方法
  updateRawValue,            // 更新输入值
  setEditorInstance,         // 设置编辑器实例
  setContent,                // 设置编辑器内容
  insertContent,             // 插入内容到编辑器
  focusEditor,               // 聚焦编辑器
  sendMessage,               // 发送消息
  setIsPeerTyping,           // 设置对方输入状态
} = useMessageInputState();

// 使用示例
const handleSendMessage = () => {
  sendMessage();
};

🎯 useMessageActionState - 消息操作状态管理

管理消息的各种操作状态。

import { useMessageActionState } from 'tuikit-atomicx-react';

const {
  // 状态
  quotedMessage,             // 引用的消息
  forwardMessageIDList,      // 转发消息ID列表
  forwardConversationIDList, // 转发目标会话ID列表
  isForwardMessageSelectionDone, // 是否完成转发消息选择
  
  // 方法
  quoteMessage,              // 引用消息
  copyTextMessage,           // 复制文本消息
  deleteMessage,             // 删除消息
  recallMessage,             // 撤回消息
  setForwardMessageIDList,   // 设置转发消息列表
  setIsForwardMessageSelectionDone, // 设置转发选择完成状态
  setForwardConversationIDList,      // 设置转发目标会话列表
  forwardMessage,            // 转发消息
  resetMessageActionState,   // 重置消息操作状态
} = useMessageActionState();

// 使用示例
const handleQuoteMessage = (message: IMessageModel) => {
  quoteMessage(message);
};

👥 useContactListState - 联系人状态管理

管理联系人列表和好友操作。

import { useContactListState } from 'tuikit-atomicx-react';

const {
  // 状态
  friendList,                // 好友列表
  groupList,                 // 群组列表
  blackList,                 // 黑名单列表
  friendApplicationUnreadCount, // 好友申请未读数
  friendGroupList,           // 好友分组列表
  friendApplicationList,     // 好友申请列表
  groupApplicationList,      // 群组申请列表
  
  // 方法
  addFriend,                 // 添加好友
  markFriendApplicationAsRead, // 标记好友申请为已读
  acceptFriendApplication,   // 接受好友申请
  refuseFriendApplication,   // 拒绝好友申请
  addToBlacklist,            // 添加到黑名单
  removeFromBlacklist,       // 从黑名单移除
  deleteFriend,              // 删除好友
  setFriendRemark,           // 设置好友备注
  createFriendGroup,         // 创建好友分组
  deleteFriendGroup,         // 删除好友分组
  addToFriendGroup,          // 添加到好友分组
  removeFromFriendGroup,     // 从好友分组移除
  renameFriendGroup,         // 重命名好友分组
  joinGroup,                 // 加入群组
  acceptGroupApplication,    // 接受群组申请
  refuseGroupApplication,    // 拒绝群组申请
} = useContactListState();

// 使用示例
const handleAddFriend = async (userID: string) => {
  await addFriend({
    userID,
    addSource: 'AddSource_Type_Web',
    wording: '我想加你为好友',
  });
};

🔐 useLoginState - 登录状态管理

管理用户登录状态和操作。

import { useLoginState, LoginStatus } from 'tuikit-atomicx-react';

const {
  // 状态
  status,                    // 登录状态：IDLE | LOADING | SUCCESS | ERROR
  error,                     // 登录错误信息
  client,                    // ChatEngine 客户端实例
  currentConfig,             // 当前登录配置
  
  // 方法
  login,                     // 登录
  logout,                    // 登出
} = useLoginState({
  SDKAppID: 1400000000,
  userID: 'user123',
  userSig: 'userSig...',
  onSuccess: () => console.log('登录成功'),
  onError: (error) => console.error('登录失败', error),
});

// 使用示例
const handleLogin = async () => {
  try {
    await login({
      SDKAppID: 1400000000,
      userID: 'user123',
      userSig: 'userSig...',
    });
  } catch (error) {
    console.error('登录失败', error);
  }
};

🏠 useC2CSettingState - 单聊设置状态管理

管理单聊设置的状态和操作。

import { useC2CSettingState } from 'tuikit-atomicx-react';

const {
  // 状态
  userID,                    // 用户ID
  nick,                      // 昵称
  avatar,                    // 头像
  signature,                 // 个性签名
  remark,                    // 备注
  isMuted,                   // 是否免打扰
  isPinned,                  // 是否置顶
  isContact,                 // 是否为联系人
  
  // 方法
  setChatPinned,             // 设置置顶状态
  setChatMuted,              // 设置免打扰状态
  setUserRemark,             // 设置用户备注
} = useC2CSettingState();

// 使用示例
const handleSetRemark = (remark: string) => {
  setUserRemark(remark);
};

👥 useGroupSettingState - 群组设置状态管理

管理群组设置的状态和操作。

import { useGroupSettingState } from 'tuikit-atomicx-react';

const {
  // 状态
  groupID,                   // 群组ID
  groupType,                 // 群组类型
  groupName,                 // 群组名称
  avatar,                    // 群组头像
  introduction,              // 群组简介
  notification,              // 群组公告
  nameCard,                  // 群名片
  isMuted,                   // 是否免打扰
  isPinned,                  // 是否置顶
  groupOwner,                // 群主信息
  adminMembers,              // 管理员列表
  allMembers,                // 所有成员列表
  memberCount,               // 成员数量
  maxMemberCount,            // 最大成员数
  currentUserID,             // 当前用户ID
  currentUserRole,           // 当前用户角色
  isMuteAllMembers,          // 是否全员禁言
  isInGroup,                 // 是否在群组中
  inviteOption,              // 邀请选项
  
  // 权限工具方法
  hasPermission,             // 检查权限
  canOperateOnMember,        // 是否可操作成员
  getAvailablePermissions,   // 获取可用权限
  
  // 操作方法
  setChatPinned,             // 设置置顶
  setChatMuted,              // 设置免打扰
  getGroupMemberList,        // 获取群成员列表
  updateGroupProfile,        // 更新群资料
  addGroupMember,            // 添加群成员
  deleteGroupMember,         // 删除群成员
  setGroupMemberRole,        // 设置成员角色
  changeGroupOwner,          // 转让群主
  setGroupMemberMuteTime,    // 设置成员禁言时间
  setGroupMemberNameCard,    // 设置成员群名片
  setMuteAllMember,          // 设置全员禁言
  dismissGroup,              // 解散群组
  quitGroup,                 // 退出群组
} = useGroupSettingState();

// 使用示例
const handleAddMember = async (userIDList: string[]) => {
  await addGroupMember({ userIDList });
};

🖱️ useScrollActionState - 滚动操作状态管理

管理消息列表的滚动状态和操作。

import { useScrollActionState } from 'tuikit-atomicx-react';

const {
  // 状态
  scrollableDomRef,          // 可滚动DOM引用
  scrollTo,                  // 滚动到指定位置
  scrollToBottom,            // 滚动到底部
  scrollToMessage,           // 滚动到指定消息
  getScrollDistanceFromBottom, // 获取距离底部的距离
  
  // 方法
  setScrollableDomRef,       // 设置可滚动DOM引用
  setScrollMethods,          // 设置滚动方法
} = useScrollActionState();

// 使用示例
const handleScrollToBottom = () => {
  scrollToBottom?.('smooth');
};

🎛️ useUIOpenControlState - UI 开关控制状态管理

管理界面开关状态。

import { useUIOpenControlState } from 'tuikit-atomicx-react';

const {
  // 状态
  isChatSettingOpen,         // 聊天设置是否打开
  isChatSearchOpen,          // 聊天搜索是否打开
  
  // 方法
  toggleChatSetting,         // 切换聊天设置状态
  setChatSettingOpen,        // 设置聊天设置开关
  toggleChatSearch,          // 切换聊天搜索状态
  setChatSearchOpen,         // 设置聊天搜索开关
} = useUIOpenControlState();

// 使用示例
const handleToggleSetting = () => {
  toggleChatSetting();
};

支持的语言

• 🇨🇳 简体中文 (zh_CN)
• 🇺🇸 English (en_US)
• 🇯🇵 日本語 (ja_JP)
• 🇰🇷 한국어 (ko_KR)

📄 许可证

本项目基于 MIT 许可证开源。