@ai-widget/chatbot-ui

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

安装

``bash


npm

npm install @ai-widget/chatbot-ui

pnpm

pnpm add @ai-widget/chatbot-ui

yarn

yarn add @ai-widget/chatbot-ui
`

$3

需要安装以下对等依赖：

`bash
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 模式选择器 |

快速开始

$3

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

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

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

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

return (
sidebarProps={{
userInfo: {
name: '用户名',
email: 'user@example.com',
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
/>
)
}
`

$3

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

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

function SimpleChatPage() {
const [messages, setMessages] = useState([])
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 (



)
}
`

$3

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

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

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

API 参考

$3

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

$3

| 属性 | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| 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 | 是否显示分支选择器 |

$3

| 属性 | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| 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 | - | 自定义工具栏内容 |

$3

`typescript
// 消息类型
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 的样式系统，请确保在应用入口引入样式：

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

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

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

与 AI SDK 集成

结合 Vercel AI SDK 使用：

`tsx
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 (
messages={uiMessages}
onSubmit={(msg) => {
setInput(msg.text)
handleSubmit()
}}
status={status === 'in_progress' ? 'streaming' : 'ready'}
/>
)
}
``

License

MIT