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

Package detail

digitalsee-chatbox-sdk

readme