Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

digitalsee-chatbox-sdk

digitalsee8MIT1.1.0TypeScript support: included

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

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

readme

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

🤝 贡献指南

  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 文件了解详情。

📞 支持


Made with ❤️ by DigitalSee