BF Chat Box

一个基于React和Ant Design X的AI聊天窗口组件，可以轻松集成到任何React项目中。

特性

• 🎨 使用Ant Design X组件库构建，具有美观现代的UI
• 🌊 支持流式响应和普通响应
• 🔄 支持 Server-Sent Events (SSE) 格式的流数据
• 🎯 高度可定制，支持自定义主题颜色
• 🔊 支持语音输入功能
• 📦 独立打包，避免与宿主项目的依赖冲突
• 🔄 支持实时更新聊天内容
• 🌐 支持与任何API后端集成
• 🧩 提供可重用的hook，方便自定义UI实现
• 💬 支持悬浮图标模式，点击展开聊天窗口

安装

1yarn add bf-chatbox

或者

1npm install bf-chatbox

使用方法

基本用法

1// CommonJS 方式引入组件
2const { AIChatBox } = require('bf-chatbox');
3// 不需要额外引入CSS文件，样式已内联到JS中
4
5function App() {
6  const handleSendMessage = (message, params) => {
7    console.log('发送消息:', message, params);
8    // 在这里处理消息发送逻辑
9  };
10
11  return (
12    <AIChatBox
13      onSendMessage={handleSendMessage}
14      baseUrl="https://api.example.com"
15      placeholder="Ask me anything..."
16      height="500px"
17      width="100%"
18      userId="user-123" // 设置用户ID，会在API请求中传递给后端
19    />
20  );
21}

悬浮图标模式

使用 FloatingAIChat 组件可以在页面右下角显示一个悬浮图标，点击后展开聊天窗口：

1// CommonJS 方式引入组件
2const { FloatingAIChat } = require('bf-chatbox');
3const { CommentOutlined } = require('@ant-design/icons'); // 可选，如需自定义图标
4// 不需要额外引入CSS文件
5
6function App() {
7  return (
8    <div className="App">
9      {/* 你的应用内容 */}
10      
11      {/* 悬浮聊天图标 */}
12      <FloatingAIChat
13        baseUrl="https://api.example.com"
14        useStream={true}
15        themeColor="#10b981"
16        // 设置用户ID
17        userId="user-123"
18        // 允许调整大小
19        resizable={true}
20        // 自定义初始位置
21        initialPosition={{ right: 20, bottom: 100 }}
22        // 自定义图标（可选）
23        buttonIcon={<CommentOutlined style={{ fontSize: 24, color: 'white' }} />}
24        // 自定义图标尺寸（可选）
25        iconSize={50}  // 默认 50px
26        // 自定义z-index（可选）
27        zIndex={1000} // 默认 1000
28      />
29    </div>
30  );
31}

添加 GET 查询参数

You can add GET query parameters to the API URL:

1// CommonJS 方式引入组件
2const { AIChatBox } = require('bf-chatbox');
3
4function App() {
5  const handleSendMessage = (message, params) => {
6    console.log('发送消息:', message, params);
7    // 在这里处理消息发送逻辑
8  };
9
10  return (
11    <AIChatBox
12      onSendMessage={handleSendMessage}
13      baseUrl="https://api.example.com"
14      environmentParams={{
15        urlParams: {
16          model: 'gpt-4',
17          temperature: 0.7,
18          userId: 'user123'
19        },
20        sessionId: 'session-xyz',
21        context: 'customer-support'
22      }}
23      useStream={true}
24    />
25  );
26}

使用 useChatApi Hook

这个库也提供了一个可重用的 Hook useChatApi，允许您创建完全自定义的聊天界面：

1// CommonJS 方式引入Hook
2const React = require('react');
3const { useState } = React;
4const { useChatApi } = require('bf-chatbox');
5
6function CustomChatInterface() {
7  const [inputValue, setInputValue] = useState('');
8  
9  const {
10    messages,      // 消息列表
11    setMessages,   // 设置消息列表的函数
12    isLoading,     // 是否正在加载
13    sendMessage,   // 发送消息的函数
14    clearMessages  // 清空消息列表的函数
15  } = useChatApi({
16    baseUrl: 'https://api.example.com',
17    useStream: true,
18    streamResponseField: 'answer',
19    responseField: 'message',
20    headers: {
21      'Authorization': 'Bearer your-token-here'
22    },
23    environmentParams: {
24      urlParams: {
25        model: 'gpt-4'
26      }
27    },
28    onSendMessage: (message, params) => {
29      console.log('发送消息:', message, params);
30    },
31    userId: 'user-123' // 设置用户ID
32  });
33
34  const handleSubmit = (e) => {
35    e.preventDefault();
36    if (inputValue.trim()) {
37      sendMessage(inputValue);
38      setInputValue('');
39    }
40  };
41
42  return (
43    <div className="custom-chat">
44      <div className="messages">
45        {messages.map(msg => (
46          <div key={msg.id} className={`message ${msg.role}`}>
47            {msg.type === 'loading' ? (
48              <div className="loading">思考中...</div>
49            ) : (
50              <div className="content">{msg.content}</div>
51            )}
52          </div>
53        ))}
54      </div>
55      
56      <form onSubmit={handleSubmit}>
57        <input
58          value={inputValue}
59          onChange={(e) => setInputValue(e.target.value)}
60          placeholder="输入消息..."
61          disabled={isLoading}
62        />
63        <button type="submit" disabled={isLoading || !inputValue.trim()}>
64          发送
65        </button>
66        <button type="button" onClick={clearMessages}>
67          清空消息
68        </button>
69      </form>
70    </div>
71  );
72}

处理 JSON 流式响应

如果您的 API 返回 JSON 格式的流式响应，可以指定应该从哪个字段提取文本内容：

1// CommonJS 方式引入组件
2const { AIChatBox } = require('bf-chatbox');
3
4function App() {
5  return (
6    <AIChatBox
7      baseUrl="https://api.example.com"
8      useStream={true}
9      streamResponseField="answer" // 从 JSON 中的 answer 字段提取内容
10      responseField="message" // 从非流式响应中的 message 字段提取内容
11    />
12  );
13}

组件支持两种流式数据格式：

1. 纯 JSON 格式：

1{"event":"message","answer":"AI 生成的回复内容在这里"}

2. Server-Sent Events (SSE) 格式：

data:{"event":"node_started","answer":""}
data:{"event":"message","answer":"AI 生成的回复内容在这里"}

组件会自动检测并处理两种格式。对于 SSE 格式，它会自动移除 data: 前缀并解析后面的 JSON 数据。

对于具有 event 字段的 JSON 对象，组件有特殊处理：

• node_started：标记流开始，但不显示内容
• message、node_done、stream_data：这些事件会显示其中的内容
• 其他事件类型：如果包含内容也会尝试显示

组件支持多种流式数据接收模式：

1. 单个完整的 JSON 对象
2. 多个 JSON 对象（按行分隔）
3. 部分 JSON 对象（会累积直到收到完整对象）

调整聊天窗口大小

通过设置 resizable={true} 属性，可以启用悬浮聊天窗口的拖拽调整大小功能。启用后，聊天窗口的右下角会出现一个调整大小的手柄，用户可以通过拖拽该手柄来调整窗口的宽度和高度。

注意：调整大小功能仅在使用 FloatingAIChat 组件（悬浮聊天窗口）时可用。

1// CommonJS 方式引入组件
2const { FloatingAIChat } = require('bf-chatbox');
3
4function App() {
5  return (
6    <FloatingAIChat
7      baseUrl="https://api.example.com"
8      // 启用调整大小功能
9      resizable={true}
10    />
11  );
12}

启用后，用户可以通过拖拽窗口右下角的调整大小手柄来自由调整聊天窗口的大小，以适应不同的内容或屏幕布局需求。

参数

AIChatBox 组件参数

参数名	类型	默认值	描述
messages	ChatMessage[]	[]	聊天历史记录
loading	boolean	false	是否处于加载状态
useStream	boolean	false	是否使用流式响应
onSendMessage	(message: string, customParams?: Record<string, any>) => void	-	发送消息时的回调函数
onInitialize	(customParams?: Record<string, any>) => void	-	组件初始化时的回调函数
baseUrl	string	-	API的基础URL，用于构建完整API请求地址
headers	Record<string, string>	-	自定义请求头
environmentParams	object	-	环境参数，会传递给回调函数或API请求
environmentParams.urlParams	object	-	GET查询参数，添加到URL
streamResponseField	string	'answer'	从流式JSON响应中提取内容的字段名
responseField	string	'message'	从普通JSON响应中提取内容的字段名
width	string | number	'100%'	组件宽度
height	string | number	'500px'	组件高度
placeholder	string	'Type something...'	输入框的占位符文本
themeColor	string	'#6d28d9'	主题颜色
allowVoiceMessages	boolean	false	是否允许语音消息输入
userId	string	'guest'	用户ID，用于在请求时传递给后端

FloatingAIChat 组件参数

FloatingAIChat 组件继承了 AIChatBox 的所有参数，并添加了以下特有参数：

参数名	类型	默认值	描述
visible	boolean	false	是否显示浮动聊天窗口
onClose	() => void	-	关闭按钮点击时的回调函数
buttonIcon	ReactNode	-	自定义触发按钮图标
closeIcon	ReactNode	-	自定义关闭按钮图标
resizable	boolean	true	是否允许通过拖拽调整聊天窗口大小（右下角）
initialPosition	{ right: number, bottom: number }	{ right: 20, bottom: 20 }	初始位置
iconSize	number	50	触发按钮大小
zIndex	number	1000	组件的z-index值

useChatApi Hook 参数

参数名	类型	默认值	描述
baseUrl	string	-	API的基础URL，用于构建完整API请求地址
useStream	boolean	false	是否使用流式响应
headers	Record<string, string>	-	自定义请求头
environmentParams	object	-	环境参数，会传递给回调函数或API请求
environmentParams.urlParams	object	-	GET查询参数，添加到URL
streamResponseField	string	'answer'	从流式JSON响应中提取内容的字段名
responseField	string	'message'	从普通JSON响应中提取内容的字段名
onSendMessage	(message: string, customParams?: Record<string, any>) => void	-	发送消息时的回调函数
userId	string	'guest'	用户ID，用于在请求时传递给后端

useChatApi Hook 返回值

名称	类型	描述
messages	ChatMessage[]	当前消息列表
setMessages	React.Dispatch<React.SetStateAction<ChatMessage[]>>	设置消息列表的函数
isLoading	boolean	是否正在加载
sendMessage	(text: string) => Promise	发送消息的函数
clearMessages	() => void	清空消息列表的函数

本地开发

1. 克隆仓库：

   1git clone ssh://git@gitlab.bytesforce.com:7001/front-end/ai-chat-box.git
   2cd ai-chat-box

2. 安装依赖：

   1yarn install

3. 构建库：

   1yarn build

4. 运行示例：

   1yarn start-example

通过局域网访问示例项目

示例项目已配置为支持局域网访问，您可以从同一网络中的其他设备访问开发服务器。步骤如下：

1. 启动示例项目：

   1yarn start-example

2. 找到您电脑的局域网 IP 地址：

   • Windows：打开命令提示符并输入 ipconfig
   • macOS：打开系统偏好设置 > 网络，或在终端输入 ifconfig
   • Linux：在终端输入 ip addr 或 ifconfig

3. 在同一网络的其他设备上，使用浏览器访问：

   http://您的IP地址:5173
   

   例如：http://192.168.1.100:5173

4. 如果您需要更改默认端口或其他配置，请修改 example/vite.config.ts 文件中的 server 部分：

   1server: {
   2  host: '0.0.0.0',
   3  port: 5173, // 修改这里以更改端口
   4  open: true,
   5  strictPort: false,
   6  cors: true,
   7}

注意：确保您的防火墙允许通过 5173 端口（或您设置的其他端口）的连接。

许可证

MIT