@chat-ui/base

基于 React 和 TypeScript 的聊天界面基座组件库，提供可复用的 UI 组件、主题系统、国际化支持等核心能力。

特性

• 🎨 主题系统 - 支持明暗主题切换，可自定义主题配置
• 🌍 国际化 - 内置中英文支持，易于扩展其他语言
• 📱 响应式设计 - 支持移动端和桌面端适配
• 🧩 模块化组件 - 高度可复用的聊天相关组件
• 📝 TypeScript - 完整的类型定义支持
• 🎯 无业务耦合 - 纯 UI 组件，不包含业务逻辑

安装

npm install @chat-ui/base
# 或
yarn add @chat-ui/base
# 或
pnpm add @chat-ui/base

依赖

本组件库依赖以下 peer dependencies：

• react >= 16.8.0
• react-dom >= 16.8.0
• styled-components >= 5.0.0

快速开始

1. 基础使用

import React from 'react';
import { 
  ThemeProvider, 
  BaseChatProvider, 
  ChatList, 
  ChatInput, 
  Header 
} from '@chat-ui/base';

function App() {
  return (
    <ThemeProvider>
      <BaseChatProvider>
        <div style={{ height: '100vh', display: 'flex', flexDirection: 'column' }}>
          <Header 
            title="我的聊天应用"
            onNewChat={() => console.log('新建对话')}
          />
          <ChatList 
            messages={[]}
            onRetry={(id) => console.log('重试消息', id)}
          />
          <ChatInput 
            onSend={(content, type, metadata) => console.log('发送消息', { content, type, metadata })}
          />
        </div>
      </BaseChatProvider>
    </ThemeProvider>
  );
}

2. 自定义主题

import { ThemeProvider } from '@chat-ui/base';

function App() {
  return (
    <ThemeProvider defaultMode="dark">
      {/* 你的应用 */}
    </ThemeProvider>
  );
}

3. 国际化配置

import { ThemeProvider } from '@chat-ui/base';
import i18n from '@chat-ui/base/i18n';

// 组件库会自动初始化 i18n
function App() {
  return (
    <ThemeProvider>
      {/* 你的应用 */}
    </ThemeProvider>
  );
}

组件

主题系统

ThemeProvider

主题提供者组件，管理应用的主题状态。

interface ThemeProviderProps {
  children: ReactNode;
  defaultMode?: 'light' | 'dark' | 'auto';
}

useTheme

获取当前主题的 Hook。

const { theme, toggleTheme, setThemeMode } = useTheme();

聊天组件

ChatMessage

聊天消息组件，支持多种消息类型。

interface ChatMessageProps {
  message: BaseMessage;
  onRetry?: (messageId: string) => void;
}

ChatInput

聊天输入组件，支持文件上传、多种输入模式。

interface ChatInputProps {
  onSend?: (content: string, type: string, metadata?: any) => void;
  disabled?: boolean;
  placeholder?: string;
}

ChatList

聊天列表组件，展示消息列表。

interface ChatListProps {
  messages: BaseMessage[];
  onRetry?: (messageId: string) => void;
  isLoading?: boolean;
}

布局组件

Header

头部组件，支持移动端菜单。

interface HeaderProps {
  title?: string;
  onNewChat?: () => void;
  onClearChat?: () => void;
  onSettings?: () => void;
  showMobileMenu?: boolean;
  onToggleMobileMenu?: () => void;
}

SettingsPanel

设置面板组件。

interface SettingsPanelProps {
  isOpen: boolean;
  onClose: () => void;
}

消息内容渲染器

MessageContent（已整合）

消息内容渲染器，根据消息类型自动选择合适的渲染器。自 vNext 起，MessageContent 已整合至 components/Chat/MessageContent.tsx，请从包根或 components/Chat 路径导入。

ImageRenderer

图片渲染器，支持预览和下载。

FileRenderer

文件渲染器，支持多种文件类型。

ChartRenderer

图表渲染器（示例实现基于 Recharts）。

MermaidRenderer

Mermaid 图表渲染器。

反馈组件

Toast

消息提示组件。

ToastContainer

消息提示容器。

LoadingSpinner

加载指示器。

类型定义

BaseMessage

基础消息类型。

interface BaseMessage {
  id: string;
  content: string;
  type: 'text' | 'image' | 'chart' | 'markdown' | 'file' | 'code';
  role: 'user' | 'assistant' | 'system';
  timestamp: number;
  metadata?: {
    fileName?: string;
    fileSize?: number;
    fileType?: string;
    chartData?: any;
    codeLanguage?: string;
    imageUrl?: string;
    [key: string]: any;
  };
  status?: 'sending' | 'sent' | 'error' | 'thinking' | 'typing';
  error?: string;
}

BaseChatSession

聊天会话类型。

interface BaseChatSession {
  id: string;
  title: string;
  messages: BaseMessage[];
  createdAt: number;
  updatedAt: number;
  settings?: {
    model?: string;
    temperature?: number;
    maxTokens?: number;
    [key: string]: any;
  };
}

工具函数

消息工具

import { 
  createMessage, 
  createUserMessage, 
  createAssistantMessage,
  formatTimestamp,
  isMessageFromUser 
} from '@chat-ui/base/utils';

文件工具

import { 
  formatFileSize, 
  isImageFile, 
  readFileAsText 
} from '@chat-ui/base/utils';

UUID 工具

import { 
  generateUUID, 
  generateUUID32 
} from '@chat-ui/base/utils';

自定义主题

你可以通过 CSS 变量或直接修改主题对象来自定义主题：

import { ThemeProvider } from '@chat-ui/base';

const customTheme = {
  colors: {
    primary: '#your-color',
    // ... 其他颜色
  },
  // ... 其他主题配置
};

function App() {
  return (
    <ThemeProvider>
      {/* 你的应用 */}
    </ThemeProvider>
  );
}

国际化

组件库内置了中英文支持，你可以通过以下方式切换语言：

import { useI18n } from '@chat-ui/base';

function MyComponent() {
  const { changeLanguage, t } = useI18n();
  
  return (
    <button onClick={() => changeLanguage('en-US')}>
      {t('common.user')}
    </button>
  );
}

许可证

MIT