@ai-widget/chatbot-ui

Chatbot UI 组件库，提供开箱即用的聊天界面组件，用于快速构建 AI 对话应用。

安装

# npm
npm install @ai-widget/chatbot-ui

# pnpm
pnpm add @ai-widget/chatbot-ui

# yarn
yarn add @ai-widget/chatbot-ui

对等依赖

需要安装以下对等依赖：

pnpm add react react-dom @ai-sdk/react ai sonner lucide-react

| 依赖 | 版本要求 | |------|---------| | react | ^18.0.0 \|\| ^19.0.0 | | react-dom | ^18.0.0 \|\| ^19.0.0 | | @ai-sdk/react | ^1.0.0 | | ai | ^4.0.0 \|\| ^5.0.0 \|\| ^6.0.0 | | sonner | ^1.0.0 | | lucide-react | ^0.460.0 (可选) |

组件列表

| 组件 | 描述 | |------|------| | ChatLayout | 完整聊天布局，包含侧边栏和聊天界面 | | ChatInterface | 聊天界面，包含消息列表和输入框 | | ChatInput | 聊天输入框，支持文件附件、模型选择、模式切换 | | MessageList | 消息列表组件 | | ChatAppSidebar | 聊天应用侧边栏 | | NavConversations | 会话导航列表 | | ChatNavUser | 用户信息导航 | | ModeSelector | Agent 模式选择器 |

快速开始

基础用法 - ChatLayout

ChatLayout 是最常用的组件，提供完整的聊天界面布局：

import { ChatLayout } from '@ai-widget/chatbot-ui'
import type { UIMessage } from '@ai-widget/chatbot-ui'

function ChatPage() {
  const [messages, setMessages] = useState<UIMessage[]>([])

  const handleSubmit = (message: { text: string; files: File[] }) => {
    // 处理用户消息
    console.log('User message:', message.text)
  }

  return (
    <ChatLayout
      sidebarProps={{
        userInfo: {
          name: '用户名',
          email: '[email protected]',
          avatar: '/avatar.png',
        },
        conversationGroups: [
          {
            label: '今天',
            conversations: [
              { id: '1', title: '对话 1', isActive: true },
              { id: '2', title: '对话 2' },
            ],
          },
        ],
        onConversationClick: (id) => console.log('Switch to:', id),
        onNewChat: () => console.log('New chat'),
      }}
      chatProps={{
        messages,
        onSubmit: handleSubmit,
        status: 'ready',
        placeholder: '输入您的问题...',
        suggestions: ['你好', '帮我写代码', '解释一下'],
      }}
      title="AI 助手"
      showHeader
    />
  )
}

单独使用 ChatInterface

如果只需要聊天界面（不需要侧边栏）：

import { ChatInterface } from '@ai-widget/chatbot-ui'
import type { UIMessage, ModelConfig } from '@ai-widget/chatbot-ui'

function SimpleChatPage() {
  const [messages, setMessages] = useState<UIMessage[]>([])
  const [selectedModel, setSelectedModel] = useState('gpt-4')

  const models: ModelConfig[] = [
    { id: 'gpt-4', name: 'GPT-4', provider: 'OpenAI', providerSlug: 'openai' },
    { id: 'claude-3', name: 'Claude 3', provider: 'Anthropic', providerSlug: 'anthropic' },
  ]

  return (
    <div className="h-screen">
      <ChatInterface
        messages={messages}
        onSubmit={(msg) => console.log(msg)}
        status="ready"
        selectedModel={selectedModel}
        onModelChange={setSelectedModel}
        models={models}
        locale="zh"
      />
    </div>
  )
}

单独使用 ChatInput

import { ChatInput } from '@ai-widget/chatbot-ui'
import type { AgentMode } from '@ai-widget/chatbot-ui'

function InputOnly() {
  const [mode, setMode] = useState<AgentMode>('normal')

  return (
    <ChatInput
      onSubmit={(msg) => console.log(msg)}
      status="ready"
      placeholder="请输入..."
      suggestions={['示例问题 1', '示例问题 2']}
      selectedMode={mode}
      onModeChange={setMode}
      locale="zh"
    />
  )
}

API 参考

ChatLayoutProps

| 属性 | 类型 | 默认值 | 描述 | |------|------|--------|------| | sidebarProps | ChatAppSidebarProps | - | 侧边栏配置 | | chatProps | ChatInterfaceProps | - | 聊天界面配置 | | defaultOpen | boolean | true | 侧边栏默认是否展开 | | title | string | - | 头部标题 | | showHeader | boolean | true | 是否显示头部 | | headerRight | ReactNode | - | 头部右侧自定义内容 |

ChatInterfaceProps

| 属性 | 类型 | 默认值 | 描述 | |------|------|--------|------| | messages | UIMessage[] | - | 消息列表 | | onSubmit | (message: PromptInputMessage) => void | - | 提交回调 | | status | 'ready' \| 'submitted' \| 'streaming' \| 'error' | - | 聊天状态 | | placeholder | string | - | 输入框占位符 | | suggestions | string[] | [] | 建议问题 | | selectedModel | string | - | 当前选中的模型 ID | | onModelChange | (modelId: string) => void | - | 模型变更回调 | | models | ModelConfig[] | [] | 可用模型列表 | | selectedMode | AgentMode | - | 当前 Agent 模式 | | onModeChange | (mode: AgentMode) => void | - | 模式变更回调 | | onApprovalResponse | (response: ToolApprovalResponse) => void | - | 工具审批回调 (HITL) | | locale | 'zh' \| 'en' | 'zh' | 语言设置 | | isLoadingHistory | boolean | false | 是否正在加载历史记录 | | showBranchSelector | boolean | true | 是否显示分支选择器 |

ChatInputProps

| 属性 | 类型 | 默认值 | 描述 | |------|------|--------|------| | onSubmit | (message: PromptInputMessage) => void | - | 提交回调 | | status | ChatStatus | - | 聊天状态 | | placeholder | string | - | 输入框占位符 | | suggestions | string[] | [] | 建议问题 | | selectedModel | string | - | 当前选中的模型 ID | | onModelChange | (modelId: string) => void | - | 模型变更回调 | | models | ModelConfig[] | [] | 可用模型列表 | | selectedMode | AgentMode | - | 当前 Agent 模式 | | onModeChange | (mode: AgentMode) => void | - | 模式变更回调 | | locale | 'zh' \| 'en' | 'zh' | 语言设置 | | showAttachments | boolean | true | 是否显示附件功能 | | customTools | ReactNode | - | 自定义工具栏内容 |

类型定义

// 消息类型
interface UIMessage {
  id: string
  role: 'user' | 'assistant' | 'system'
  content: string
  // ... 其他属性
}

// 模型配置
interface ModelConfig {
  id: string
  name: string
  provider: string
  providerSlug: string
}

// Agent 模式
type AgentMode = 'normal' | 'deep-research'

// 聊天状态
type ChatStatus = 'ready' | 'submitted' | 'streaming' | 'error'

// 工具审批响应
interface ToolApprovalResponse {
  toolCallId: string
  approved: boolean
}

样式配置

本组件库依赖 @ai-widget/ui 的样式系统，请确保在应用入口引入样式：

// 在 app/layout.tsx 或入口文件中
import '@ai-widget/ui/styles.css'

同时需要配置 tailwind.config.js 以包含组件库的样式：

module.exports = {
  content: [
    // ... 你的项目文件
    './node_modules/@ai-widget/*/dist/**/*.{js,mjs}',
  ],
  // ...
}

与 AI SDK 集成

结合 Vercel AI SDK 使用：

import { useChat } from '@ai-sdk/react'
import { ChatInterface, convertToMessageType } from '@ai-widget/chatbot-ui'

function AIChatPage() {
  const { messages, handleSubmit, status, input, setInput } = useChat({
    api: '/api/chat',
  })

  // 转换消息格式
  const uiMessages = messages.map(convertToMessageType)

  return (
    <ChatInterface
      messages={uiMessages}
      onSubmit={(msg) => {
        setInput(msg.text)
        handleSubmit()
      }}
      status={status === 'in_progress' ? 'streaming' : 'ready'}
    />
  )
}

License

MIT