digitalsee-chatbox-sdk/README.md

A flexible chatbox SDK for AI conversations with support for text, file, and voice input

# DigitalSee ChatBox SDK

一个功能强大且高度可定制的聊天框SDK，支持AI对话、文件上传和语音输入。基于React + TypeScript + TailwindCSS开发，提供多种集成模式。

## ✨ 功能特性

- 🎈 **悬浮小部件模式** - 可拖拽的悬浮聊天按钮
- 📦 **嵌入式模式** - 集成到现有页面的聊天组件  
- 🖥️ **全屏模式** - 独立的全屏聊天界面
- 💬 **AI对话支持** - 完整的对话流程管理
- 📁 **文件上传** - 支持图片、文档等多种文件类型
- 🎤 **语音输入** - 语音转文字功能
- 🎨 **高度定制** - 主题、样式、位置等全面可配置
- 📱 **响应式设计** - 完美适配桌面和移动端
- ⚡ **轻量高效** - 优化的打包体积和性能

## 🚀 快速开始

### 方式一：npm安装（推荐）

```bash
npm install digitalsee-chatbox-sdk
```

### 方式二：直接引入JavaScript文件

适用于不使用构建工具的传统项目：

```html
<!-- 1. 引入依赖库 -->
<script crossorigin src="https://unpkg.com/react@18/umd/react.production.min.js"></script>
<script crossorigin src="https://unpkg.com/react-dom@18/umd/react-dom.production.min.js"></script>
<script src="https://unpkg.com/antd@5/dist/antd.min.js"></script>
<script src="https://unpkg.com/lucide-react@latest/dist/umd/lucide-react.js"></script>

<!-- 2. 引入ChatBox SDK -->
<script src="https://unpkg.com/digitalsee-chatbox-sdk@latest/dist/index.umd.js"></script>

<script>
// 3. 使用SDK
const widget = DigitalSeeChatboxSDK.ChatBoxSDK.createWidget({
  title: '智能客服',
  onSend: async function(content) {
    // 您的处理逻辑
    return '收到消息: ' + content;
  }
});
</script>
```

### 基础用法

#### 1. 悬浮小部件模式

```javascript
import { ChatBoxSDK } from 'digitalsee-chatbox-sdk';

const widget = ChatBoxSDK.createWidget({
  title: '智能客服',
  placeholder: '请输入您的问题...',
  welcomeMessage: '您好！有什么可以帮助您的吗？',
  enableFileUpload: true,
  enableVoiceInput: true,
  position: 'bottom-right',
  onSend: async (content, files) => {
    // 处理消息发送
    const response = await fetch('/api/chat', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ message: content, files }),
    });
    return response.text();
  },
});
```

#### 2. 嵌入式模式

```javascript
const embedded = ChatBoxSDK.createEmbedded('#chat-container', {
  title: '客服聊天',
  enableFileUpload: true,
  onSend: async (content) => {
    // 自定义消息处理逻辑
    return "这是回复消息";
  },
});
```

#### 3. 全屏模式

```javascript
const fullscreen = ChatBoxSDK.createFullscreen('#app', {
  title: '智能助手',
  enableVoiceInput: true,
  onSend: async (content) => {
    // API调用逻辑
    return await callChatAPI(content);
  },
});
```

## 📖 配置选项

### ChatBoxConfig

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `title` | `string` | `'智能助手'` | 聊天框标题 |
| `placeholder` | `string` | `'输入消息...'` | 输入框占位符 |
| `avatar` | `string` | - | 助手头像URL |
| `welcomeMessage` | `string` | - | 欢迎消息 |
| `enableFileUpload` | `boolean` | `true` | 是否启用文件上传 |
| `enableVoiceInput` | `boolean` | `true` | 是否启用语音输入 |
| `maxFileSize` | `number` | `10` | 最大文件大小(MB) |
| `allowedFileTypes` | `string[]` | `[]` | 允许的文件类型 |
| `position` | `string` | `'bottom-right'` | 悬浮位置 |
| `offset` | `object` | `{x: 20, y: 20}` | 悬浮偏移量 |
| `onSend` | `function` | - | 消息发送处理函数 |
| `onFileUpload` | `function` | - | 文件上传处理函数 |
| `onError` | `function` | - | 错误处理函数 |

### 回调函数

#### onSend
```typescript
onSend: (content: string, files?: FileInfo[]) => Promise<string>
```

#### onFileUpload  
```typescript
onFileUpload: (file: File) => Promise<FileInfo>
```

#### onError
```typescript
onError: (error: Error) => void
```

## 🎨 自定义样式

SDK支持通过CSS变量自定义主题：

```css
.chatbox-light {
  --bg-primary: #ffffff;
  --bg-secondary: #f8fafc;
  --text-primary: #1f2937;
  --text-secondary: #6b7280;
  --border: #e5e7eb;
  --accent: #3b82f6;
}

.chatbox-dark {
  --bg-primary: #1f2937;
  --bg-secondary: #374151;
  --text-primary: #f9fafb;
  --text-secondary: #d1d5db;
  --border: #4b5563;
  --accent: #60a5fa;
}
```

## 🔌 API集成示例

### OpenAI集成

```javascript
const openAIConfig = {
  apiEndpoint: '/api/openai/chat',
  apiKey: 'your-api-key',
  model: 'gpt-3.5-turbo',
  onSend: async (content) => {
    const response = await fetch('/api/openai/chat', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${apiKey}`,
      },
      body: JSON.stringify({
        model: 'gpt-3.5-turbo',
        messages: [{ role: 'user', content }],
      }),
    });
    
    const data = await response.json();
    return data.choices[0].message.content;
  },
};
```

## 🔄 引入方式对比

| 特性 | npm方式 | 直接引入方式 |
|------|---------|-------------|
| **适用场景** | 现代化项目（React、Vue等） | 传统项目、静态网站 |
| **构建工具** | 需要（Webpack、Vite等） | 不需要 |
| **包大小** | 较小（按需加载） | 较大（包含所有依赖） |
| **TypeScript支持** | ✅ 完整支持 | ❌ 无类型提示 |
| **树摇优化** | ✅ 支持 | ❌ 不支持 |
| **版本管理** | ✅ 精确控制 | ⚠️ CDN版本 |
| **离线使用** | ✅ 打包后可离线 | ❌ 依赖CDN |
| **学习成本** | 中等 | 低 |

### 选择建议

- **使用npm方式**：如果您的项目已使用React、Vue、Angular等现代框架
- **使用直接引入**：如果您要快速集成到现有网站或创建简单演示

## 📱 移动端适配

SDK自动适配移动端设备，在小屏幕设备上：

- 悬浮小部件自动调整大小和位置
- 聊天界面自适应屏幕尺寸
- 触摸交互优化
- 虚拟键盘适配

## 🔧 开发调试

```bash
# 安装依赖
npm install

# 启动开发服务器
npm run dev

# 构建SDK
npm run build:lib

# 构建演示站点
npm run build
```

## 📚 高级用法

### 自定义组件（npm方式）

```javascript
import { ChatBox, MessageInput, MessageList } from 'digitalsee-chatbox-sdk';

function CustomChat() {
  return (
    <ChatBox
      config={{
        title: '自定义聊天',
        onSend: handleSend,
      }}
      className="custom-chat-style"
    />
  );
}
```

### 直接引入方式的完整示例

```html
<!DOCTYPE html>
<html>
<head>
    <title>ChatBox 示例</title>
</head>
<body>
    <div id="chat-container" style="width: 400px; height: 500px;"></div>
    
    <!-- 依赖库 -->
    <script src="https://unpkg.com/react@18/umd/react.production.min.js"></script>
    <script src="https://unpkg.com/react-dom@18/umd/react-dom.production.min.js"></script>
    <script src="https://unpkg.com/antd@5/dist/antd.min.js"></script>
    <script src="https://unpkg.com/lucide-react@latest/dist/umd/lucide-react.js"></script>
    
    <!-- ChatBox SDK -->
    <script src="https://unpkg.com/digitalsee-chatbox-sdk@latest/dist/index.umd.js"></script>
    
    <script>
        // 创建悬浮小部件
        const widget = DigitalSeeChatboxSDK.ChatBoxSDK.createWidget({
            title: '智能助手',
            enableFileUpload: true,
            enableVoiceInput: true,
            onSend: async function(content, files) {
                // 模拟API调用
                await new Promise(resolve => setTimeout(resolve, 1000));
                return '收到您的消息: ' + content;
            }
        });
        
        // 创建嵌入式聊天
        const embedded = DigitalSeeChatboxSDK.ChatBoxSDK.createEmbedded('#chat-container', {
            title: '嵌入式聊天',
            welcomeMessage: '欢迎使用！',
            onSend: async function(content) {
                return '嵌入式回复: ' + content;
            }
        });
        
        // 动态更新配置
        setTimeout(() => {
            widget.updateConfig({
                title: '更新后的标题'
            });
        }, 5000);
    </script>
</body>
</html>
```

### 事件监听

```javascript
// npm方式
const sdk = ChatBoxSDK.createWidget({
  onMessage: (message) => {
    console.log('新消息:', message);
  },
  onError: (error) => {
    console.error('错误:', error);
  },
});

// 直接引入方式
const sdk = DigitalSeeChatboxSDK.ChatBoxSDK.createWidget({
  onMessage: function(message) {
    console.log('新消息:', message);
  },
  onError: function(error) {
    console.error('错误:', error);
  },
});

// 动态更新配置
sdk.updateConfig({
  title: '新标题',
  enableVoiceInput: false,
});
```

## 🤝 贡献指南

1. Fork 本项目
2. 创建功能分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 创建 Pull Request

## 📄 许可证

本项目基于 MIT 许可证开源 - 查看 [LICENSE](LICENSE) 文件了解详情。

## 📞 支持

- 📧 邮箱: support@digitalsee.cn
- 🐛 问题反馈: [GitHub Issues](https://github.com/digitalsee/chatbox-sdk/issues)
- 📖 文档: [在线文档](https://digitalsee.github.io/chatbox-sdk)

---

Made with ❤️ by [DigitalSee](https://digitalsee.cn)