@mxmweb/aichat

基于 React 的轻量级 AI 聊天对话组件库，提供核心聊天功能和灵活的扩展能力

✨ 核心特性

• ✅ 轻量级设计：Gzip 压缩后仅 ~78KB，专注于核心聊天功能
• ✅ 灵活的组件系统：支持自定义消息卡片、欢迎页、加载状态等
• ✅ 完整的文件上传：支持拖拽上传、多文件管理、上传状态跟踪
• ✅ 动态主题系统：支持运行时主题切换，所有样式可配置
• ✅ 事件驱动架构：通过 eventsEmit 统一处理所有交互事件
• ✅ TypeScript 支持：完整的类型定义，提供良好的开发体验
• ✅ 侧边栏扩展：支持自定义侧边栏组件和动态表单
• ✅ 纯 UI 组件库：v2.0.0 版本专注于 UI 展示层，业务逻辑已分离

📦 安装

# 使用 pnpm（推荐）
pnpm add @mxmweb/aichat react react-dom @mxmweb/zui

# 使用 npm
npm install @mxmweb/aichat react react-dom @mxmweb/zui

# 使用 yarn
yarn add @mxmweb/aichat react react-dom @mxmweb/zui

必需依赖

本库需要以下 peerDependencies：

pnpm add @mxmweb/zui@^1.* react@>=18 react-dom@>=18

样式引入

在项目入口文件中引入样式：

import '@mxmweb/aichat/style.css';

包大小

• Gzip 压缩后：~78KB
• 原始大小：~274KB
• CSS 大小：~58KB (gzip: ~10KB)

💡 优化说明：AIChat 已移除不必要的依赖，专注于核心聊天功能，确保快速加载和简洁的安装体验。

🚀 快速开始

基础用法

import React, { useState } from 'react';
import { AiChat } from '@mxmweb/aichat';
import '@mxmweb/aichat/style.css';

function App() {
  const [chatData, setChatData] = useState({
    id: 'session-1',
    messages: [],
    isNew: true,
  });

  const [status, setStatus] = useState({
    display: 'ready',
    sender: 'ready',
    app: 'ready',
  });

  const handleEventsEmit = (eventName: string, data?: any) => {
    console.log('Event:', eventName, data);
    
    if (eventName === 'sender:send') {
      // 处理消息发送
      const newMessage = {
        id: `msg-${Date.now()}`,
        type: 'user',
        time: new Date().toISOString(),
        content: data.content,
      };
      
      setChatData(prev => ({
        ...prev,
        messages: [...prev.messages, newMessage],
      }));
      
      // 模拟 AI 回复
      setTimeout(() => {
        const aiMessage = {
          id: `msg-${Date.now()}`,
          type: 'ai',
          time: new Date().toISOString(),
          content: '这是一条 AI 回复',
        };
        setChatData(prev => ({
          ...prev,
          messages: [...prev.messages, aiMessage],
        }));
      }, 1000);
    }
  };

  return (
    <div style={{ width: '100%', height: '100vh' }}>
      <AiChat
        activeSessionId="session-1"
        chatData={chatData}
        status={status}
        eventsEmit={handleEventsEmit}
        styles={{
          theme: {
            colors: {
              primary: '#409EFF',
              background: '#F7F8FA',
              text: '#222',
            },
          },
          mode: 'light',
        }}
      />
    </div>
  );
}

export default App;

🔗 链接

• NPM: https://www.npmjs.com/package/@mxmweb/aichat
• GitHub: https://github.com/your-org/aichat

📚 API 文档

📖 完整 API 文档请查看：doc_assets/接口/

• 接口文档: AiChat API
• 更新说明: CHANGELOG
• v2.0.0 升级指南: v2.0.0升级指南 ⭐ 新版本必读
• 演示说明: 演示文档

核心组件（Core Components）

AiChat

核心聊天组件，提供基础的聊天界面和交互能力。

interface AiChatProps {
  activeSessionId: string | undefined;
  chatData: ConversationData;
  sidebar?: SidebarTabConfig[];
  status: AppStatusManager;
  recommandQuestions?: string[];
  eventsEmit?: (eventName: string, data?: any, callback?: () => void) => void;
  CustomComponents?: any;
  fileUploadStatus?: any;
  styles?: Styles;
  senderConfig?: SenderConfig;
  onSenderConfigChange?: (data: {
    name: string;
    checked: boolean;
    all: Record<string, boolean>;
  }) => void;
}

Props 说明：

| 参数 | 类型 | 默认值 | 说明 | |------|------|--------|------| | activeSessionId | string | undefined | - | 当前激活的会话ID | | chatData | ConversationData | 必填 | 聊天数据，包含消息列表 | | sidebar | SidebarTabConfig[] | [] | 侧边栏配置数组 | | status | AppStatusManager | 必填 | 应用状态管理对象 | | recommandQuestions | string[] | [] | 推荐问题列表 | | eventsEmit | (eventName, data, callback) => void | - | 事件回调函数 | | CustomComponents | object | - | 自定义组件配置 | | fileUploadStatus | any[] | [] | 文件上传状态数组 | | styles | Styles | - | 主题样式配置 | | senderConfig | SenderConfig | - | 发送器配置 | | onSenderConfigChange | (data) => void | - | 发送器配置变化回调 |

🛠️ 技术栈

• React >=18 <20 - 前端框架
• @mxmweb/zui ^1.* - UI 组件库
• TypeScript - 类型支持
• anime.js - 动画库
• lucide-react - 图标库

📁 项目结构

src/
├── lib_enter.ts              # 库入口，导出所有公共 API
├── style.css                 # 样式文件
├── components/               # 核心组件（统一组件目录）
│   ├── AiChat.tsx            # AiChat 核心组件
│   ├── AiChat.types.tsx      # 类型定义
│   ├── Sender/               # 发送器组件
│   │   ├── index.tsx
│   │   ├── FilesDisplay.tsx
│   │   ├── FileUpload.tsx
│   │   └── VoiceInput.tsx
│   ├── Displayer/            # 消息展示组件
│   │   ├── index.tsx
│   │   ├── DefaultAiChatBox.tsx
│   │   ├── DefaultUserChatBox.tsx
│   │   └── slate/            # Slate 富文本编辑器
│   ├── DynamicForm.tsx       # 动态表单组件
│   ├── defaultStyleSet.tsx   # 默认主题配置
│   ├── styles.config.ts      # 样式配置
│   └── ...                   # 其他组件
├── utils/                    # 工具函数
│   ├── fileIcon.tsx          # 文件类型图标工具
│   └── commonFn.tsx           # 通用工具函数
└── examples/                 # 演示实例
    ├── BaseChat/
    └── ProChat/

💡 架构说明：v2.0.0 版本已移除业务层代码（LoginPage、servers、adopters、core），专注于核心 UI 组件库功能。

🎯 使用场景

• AI 对话聊天界面
• 智能客服系统
• 知识库问答系统
• 文档对话系统
• 自定义聊天应用

📝 示例

查看 src/examples/ 目录获取更多完整示例：

• BaseChat - 核心组件基础用法
• ProChat - 高级配置完整示例

🤝 贡献

欢迎提交 Issue 和 Pull Request。

📄 许可证

MIT License

👥 作者

• hanfeng_Zhang

⭐ 如果这个项目对你有帮助，请给它一个 Star！