chatwoot-react-ui

Chatwoot React UI

一个可复用的 React 聊天 UI 组件库，支持 Chatwoot 集成。该组件库提供了完整的聊天界面，包括会话列表、消息显示、用户管理等功能。

特性

• 🎨 现代化的聊天 UI 设计
• 📱 响应式布局，支持移动端
• 🔧 高度可定制，支持外部数据驱动
• 💬 支持私聊和群聊
• 🔍 用户搜索功能
• 📎 文件附件支持
• ⌨️ 打字状态显示
• ✅ 消息已读状态
• 🎯 TypeScript 支持

安装

npm install chatwoot-react-ui
# 或
yarn add chatwoot-react-ui
# 或
pnpm add chatwoot-react-ui

基础使用

SimpleChatUI - 简化版本

import React, { useState } from 'react';
import { SimpleChatUI, User, Dialog, Message } from 'chatwoot-react-ui';

const App = () => {
  const [selectedDialog, setSelectedDialog] = useState<Dialog | null>(null);
  const [messages, setMessages] = useState<Record<string, Message[]>>({});

  const handleSelectDialog = (dialog: Dialog) => {
    setSelectedDialog(dialog);
  };

  const handleSendMessage = (text: string) => {
    if (!selectedDialog) return;
    
    const newMessage: Message = {
      _id: Date.now().toString(),
      chat_dialog_id: selectedDialog._id,
      sender_id: 1,
      message: text,
      date_sent: Date.now(),
      read: 0,
    };

    setMessages(prev => ({
      ...prev,
      [selectedDialog._id]: [...(prev[selectedDialog._id] || []), newMessage],
    }));
  };

  return (
    <div style={{ width: '100vw', height: '100vh' }}>
      <SimpleChatUI
        dialogs={dialogs}
        messages={messages}
        users={users}
        selectedDialog={selectedDialog}
        currentUserId={1}
        onSelectDialog={handleSelectDialog}
        onSendMessage={handleSendMessage}
      />
    </div>
  );
};

ChatUI - 完整功能版本

import React, { useState, useCallback } from 'react';
import { ChatUI, User, Dialog, Message } from 'chatwoot-react-ui';

const App = () => {
  const [dialogs, setDialogs] = useState<Dialog[]>([]);
  const [messages, setMessages] = useState<Record<string, Message[]>>({});
  const [users, setUsers] = useState<Record<number, User>>({});
  const [selectedDialog, setSelectedDialog] = useState<Dialog | null>(null);

  const handleSelectDialog = useCallback((dialog: Dialog) => {
    setSelectedDialog(dialog);
    // 加载消息逻辑
  }, []);

  const handleSendMessage = useCallback((text: string) => {
    // 发送消息逻辑
  }, [selectedDialog]);

  const handleSendMessageWithAttachment = useCallback((file: File) => {
    // 发送附件逻辑
  }, []);

  const handleSendTypingStatus = useCallback((isTyping: boolean) => {
    // 打字状态逻辑
  }, []);

  const handleReadMessage = useCallback((messageId: string, senderId: number, dialogId: string) => {
    // 已读状态逻辑
  }, []);

  const handleSearchUsers = useCallback(async (term: string): Promise<User[]> => {
    // 用户搜索逻辑
    return [];
  }, []);

  const handleCreateChat = useCallback(async (opponentId: number): Promise<Dialog> => {
    // 创建私聊逻辑
    return {} as Dialog;
  }, []);

  const handleCreateGroupChat = useCallback(async (userIds: number[], name: string): Promise<Dialog> => {
    // 创建群聊逻辑
    return {} as Dialog;
  }, []);

  const handleAddUsersToGroupChat = useCallback(async (userIds: number[]) => {
    // 添加用户到群聊逻辑
  }, []);

  return (
    <div style={{ width: '100vw', height: '100vh' }}>
      <ChatUI
        dialogs={dialogs}
        messages={messages}
        users={users}
        selectedDialog={selectedDialog}
        currentUserId={1}
        onSelectDialog={handleSelectDialog}
        onSendMessage={handleSendMessage}
        onSendMessageWithAttachment={handleSendMessageWithAttachment}
        onSendTypingStatus={handleSendTypingStatus}
        onReadMessage={handleReadMessage}
        onSearchUsers={handleSearchUsers}
        onCreateChat={handleCreateChat}
        onCreateGroupChat={handleCreateGroupChat}
        onAddUsersToGroupChat={handleAddUsersToGroupChat}
        showUsersTab={true}
        className="border border-gray-300 rounded-lg"
        style={{ maxWidth: '1200px', margin: '0 auto' }}
      />
    </div>
  );
};

API 参考

SimpleChatUI Props

属性	类型	必需	描述
dialogs	Dialog[]	✅	会话列表
messages	Record<string, Message[]>	✅	消息数据
users	Record<number, User>	✅	用户数据
selectedDialog	Dialog | null	✅	当前选中的会话
currentUserId	number	✅	当前用户ID
onSelectDialog	(dialog: Dialog) => void	✅	选择会话回调
onSendMessage	(text: string) => void	✅	发送消息回调
showUsersTab	boolean	❌	是否显示用户标签页
className	string	❌	自定义CSS类名
style	React.CSSProperties	❌	自定义样式

ChatUI Props

包含 SimpleChatUI 的所有属性，另外还有：

属性	类型	必需	描述
onSendMessageWithAttachment	(file: File) => void	❌	发送附件回调
onSendTypingStatus	(isTyping: boolean) => void	❌	打字状态回调
onReadMessage	(messageId: string, senderId: number, dialogId: string) => void	❌	已读消息回调
onSearchUsers	(term: string) => Promise<User[]>	❌	搜索用户回调
onCreateChat	(opponentId: number) => Promise	❌	创建私聊回调
onCreateGroupChat	(userIds: number[], name: string) => Promise	❌	创建群聊回调
onAddUsersToGroupChat	(userIds: number[]) => Promise	❌	添加用户到群聊回调
lastMessageSentTimeString	(dialog: Dialog) => string	❌	最后消息时间格式化函数
messageSentTimeString	(msg: Message) => string	❌	消息时间格式化函数

数据类型

User

interface User {
  id: number;
  full_name?: string;
  login?: string;
  avatar?: string;
}

Dialog

interface Dialog {
  _id: string;
  name: string;
  photo?: string;
  type: number; // 2: group, 3: private
  last_message?: string;
  last_message_user_id?: number;
  unread_messages_count: number;
  last_message_date_sent?: number;
  created_at?: number;
  occupants_ids: number[];
}

Message

interface Message {
  _id: string;
  chat_dialog_id: string;
  sender_id: number;
  message: string;
  date_sent: number;
  read: number;
  attachments?: Array<{ url: string }>;
}

样式定制

组件使用 Tailwind CSS 构建，你可以通过以下方式定制样式：

• 通过 className 属性：添加自定义CSS类
• 通过 style 属性：添加内联样式
• 覆盖 Tailwind 类：在你的项目中重新定义 Tailwind 类

开发

# 安装依赖
npm install

# 启动开发服务器
npm run dev

# 构建组件库
npm run build:lib

# 类型检查
npm run typecheck

# 代码检查
npm run lint

许可证

MIT License

贡献

欢迎提交 Issue 和 Pull Request！

更新日志

v1.0.0

• 初始版本发布
• 支持基础聊天功能
• 支持私聊和群聊
• 支持用户搜索
• 支持文件附件
• 支持打字状态
• 支持消息已读状态