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 文件了解详情。
📞 支持
- 📧 邮箱: support@digitalsee.cn
- 🐛 问题反馈: GitHub Issues
- 📖 文档: 在线文档
Made with ❤️ by DigitalSee