agui-chat-widget

一个现代化的 React 聊天组件，支持 SSE 流式响应、深色模式和结构化数据渲染。

✨ 特性

• 🎨 深色/浅色主题 - 内置主题切换，自动适配
• 🌊 流式响应 - 完整支持 Server-Sent Events (SSE)
• 💰 结构化数据渲染 - 支持虚拟货币卡片、图表等多种内容类型
• 📱 响应式设计 - 适配各种屏幕尺寸
• 🎯 TypeScript - 完整的类型定义
• 🚀 零配置 - 开箱即用
• 🎭 可定制 - 通过 CSS 变量轻松定制样式

📦 安装

npm install agui-chat-widget

或使用其他包管理器：

yarn add agui-chat-widget
pnpm add agui-chat-widget

🚀 快速开始

基础使用

import { ChatWidget } from 'agui-chat-widget';
import 'agui-chat-widget/dist/index.css';

export default function App() {
  return (
    <div>
      <h1>我的应用</h1>
      <ChatWidget 
        apiEndpoint="https://your-api.com/stream"
        title="AI 助手"
        theme="light"
      />
    </div>
  );
}

深色模式

import { useState } from 'react';
import { ChatWidget } from 'agui-chat-widget';
import 'agui-chat-widget/dist/index.css';

export default function App() {
  const [theme, setTheme] = useState<'light' | 'dark'>('light');

  return (
    <div>
      <button onClick={() => setTheme(t => t === 'light' ? 'dark' : 'light')}>
        切换主题
      </button>
      
      <ChatWidget 
        apiEndpoint="https://your-api.com/stream"
        theme={theme}
      />
    </div>
  );
}

📖 API 文档

Props

| 属性 | 类型 | 默认值 | 描述 | |------|------|--------|------| | apiEndpoint | string | - | SSE 接口地址（必填） | | title | string | 'Assistant' | 聊天窗口标题 | | theme | 'light' \| 'dark' | 'light' | 主题模式 |

SSE 响应格式

您的后端接口需要返回以下格式的 SSE 事件：

1. 开始事件

data: {"event": "start", "data": {"message": null, "type": null}}

2. 文本消息（流式）

data: {"event": "message", "data": {"message": "你好", "type": "text"}}
data: {"event": "message", "data": {"message": "，", "type": "text"}}
data: {"event": "message", "data": {"message": "很高兴", "type": "text"}}

3. 结构化数据 - 虚拟货币卡片

data: {"event": "message", "data": {
  "message": null, 
  "type": "coin", 
  "data": [
    {"coin": "BTC", "price": 90000},
    {"coin": "ETH", "price": 10000}
  ]
}}

4. 结束事件

data: {"event": "end", "data": {"message": null, "type": null}}

完整示例

data: {"event": "start", "data": {"message": null, "type": null}}

data: {"event": "message", "data": {"message": "当前", "type": "text"}}
data: {"event": "message", "data": {"message": "加密", "type": "text"}}
data: {"event": "message", "data": {"message": "货币", "type": "text"}}
data: {"event": "message", "data": {"message": "价格", "type": "text"}}
data: {"event": "message", "data": {"message": "：", "type": "text"}}

data: {"event": "message", "data": {"message": null, "type": "coin", "data": [
  {"coin": "BTC", "price": 90000},
  {"coin": "ETH", "price": 10000},
  {"coin": "SOL", "price": 180}
]}}

data: {"event": "end", "data": {"message": null, "type": null}}

🎨 样式定制

组件使用 CSS 变量，您可以通过覆盖变量来自定义样式：

.agui-chat-widget-container {
  --agui-brand-color: #your-brand-color;
  --agui-bg-primary: #ffffff;
  --agui-text-primary: #171717;
  /* ... 更多变量 */
}

/* 深色模式 */
.agui-chat-widget-container[data-theme="dark"] {
  --agui-bg-primary: #0f0f11;
  --agui-text-primary: #ffffff;
  /* ... */
}

🛠️ 后端实现示例

Next.js App Router

// app/api/stream/route.ts
import { NextRequest, NextResponse } from 'next/server';

export async function POST(req: NextRequest) {
  const encoder = new TextEncoder();

  const stream = new ReadableStream({
    async start(controller) {
      // 开始事件
      controller.enqueue(encoder.encode(
        `data: ${JSON.stringify({ event: "start", data: { message: null, type: null } })}\n\n`
      ));

      // 文本消息
      const text = "你好！这是一条测试消息。";
      for (const char of text) {
        controller.enqueue(encoder.encode(
          `data: ${JSON.stringify({ event: "message", data: { message: char, type: "text" } })}\n\n`
        ));
        await new Promise(resolve => setTimeout(resolve, 50));
      }

      // 虚拟货币数据
      controller.enqueue(encoder.encode(
        `data: ${JSON.stringify({ 
          event: "message", 
          data: { 
            message: null, 
            type: "coin", 
            data: [
              { coin: "BTC", price: 90000 },
              { coin: "ETH", price: 10000 }
            ]
          } 
        })}\n\n`
      ));

      // 结束事件
      controller.enqueue(encoder.encode(
        `data: ${JSON.stringify({ event: "end", data: { message: null, type: null } })}\n\n`
      ));

      controller.close();
    },
  });

  return new NextResponse(stream, {
    headers: {
      'Content-Type': 'text/event-stream',
      'Cache-Control': 'no-cache',
      'Connection': 'keep-alive',
    },
  });
}

🌟 支持的内容类型

目前支持以下内容类型：

• ✅ text: 纯文本消息（流式拼接）
• ✅ coin: 虚拟货币卡片（水平滚动）
• 🔜 chart: 图表数据
• 🔜 table: 表格数据
• 🔜 image: 图片

📝 开发计划

• [ ] 支持更多结构化数据类型（图表、表格等）
• [ ] 添加消息搜索功能
• [ ] 支持文件上传
• [ ] 添加语音输入
• [ ] 国际化支持

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 License

MIT © Agui Team

🔗 相关链接

• GitHub 仓库
• 问题反馈
• 更新日志