digitalsee-chatbox-sdk

v1.1.0

Published

8 months ago

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

0High
0Medium
0Low

zhangzhenx

chatbox ai sdk react typescript conversation voice-input file-upload floating-widget chat-ui

DigitalSee ChatBox SDK

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

✨ 功能特性

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

🚀 快速开始

方式一：npm安装（推荐）

npm install digitalsee-chatbox-sdk

方式二：直接引入JavaScript文件

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

<!-- 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. 悬浮小部件模式

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. 嵌入式模式

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

3. 全屏模式

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

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

onFileUpload

onFileUpload: (file: File) => Promise<FileInfo>

onError

onError: (error: Error) => void

🎨 自定义样式

SDK支持通过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集成

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自动适配移动端设备，在小屏幕设备上：

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

🔧 开发调试

# 安装依赖
npm install

# 启动开发服务器
npm run dev

# 构建SDK
npm run build:lib

# 构建演示站点
npm run build

📚 高级用法

自定义组件（npm方式）

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

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

直接引入方式的完整示例

<!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>

事件监听

// 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,
});

🤝 贡献指南

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

📄 许可证

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

📞 支持

📧 邮箱: [email protected]
🐛 问题反馈: GitHub Issues
📖 文档: 在线文档

Made with ❤️ by DigitalSee