# ai_chat_components

**Repository Path**: wzcool/ai_chat_components

## Basic Information

- **Project Name**: ai_chat_components
- **Description**: AI chat components
- **Primary Language**: TypeScript
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-22
- **Last Updated**: 2026-05-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ai-chat-components

> AI 聊天组件库 - Vue 3 ChatBox 组件，支持流式输出

## 安装

```bash
npm install ai-chat-components
```

## 快速开始

```vue
<template>
  <ChatBox
    :messages="messages"
    :is-loading="loading"
    placeholder="请输入你的问题..."
    @send="handleSend"
    @copy="handleCopy"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { ChatBox, type ChatMessage } from 'ai-chat-components'
import 'ai-chat-components/dist/style.css'

const messages = ref<ChatMessage[]>([])
const loading = ref(false)

function handleSend(content: string) {
  messages.value.push({ role: 'user', content, timestamp: Date.now() })
  loading.value = true

  // 模拟 AI 回复
  setTimeout(() => {
    messages.value.push({
      role: 'assistant',
      content: `收到你的消息："${content}"`,
      timestamp: Date.now()
    })
    loading.value = false
  }, 1000)
}

function handleCopy(msg: ChatMessage) {
  navigator.clipboard.writeText(msg.content)
}
</script>
```

## 调用示例

### 1. 流式输出（模拟 SSE / WebSocket）

```vue
<template>
  <ChatBox
    :messages="messages"
    :is-loading="isStreaming"
    @send="handleSend"
    @stop="stopStream"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { ChatBox, type ChatMessage } from 'ai-chat-components'
import 'ai-chat-components/dist/style.css'

const messages = ref<ChatMessage[]>([])
const isStreaming = ref(false)
let abortController: AbortController | null = null

async function handleSend(content: string) {
  // 添加用户消息
  messages.value.push({ role: 'user', content, timestamp: Date.now() })

  // 创建 AI 占位消息（streaming: true 标记为流式）
  messages.value.push({
    role: 'assistant',
    content: '',
    timestamp: Date.now(),
    streaming: true
  })

  // 从响应式数组中获取索引，通过代理引用修改以触发 Vue 重渲染
  const idx = messages.value.length - 1
  isStreaming.value = true

  // 模拟逐字流式输出
  const fullText = '这是一个流式输出的回复示例。每个字符逐步显示，模拟大模型逐 token 输出的效果，用户可以看到内容实时生成的过程。'
  abortController = new AbortController()

  for (let i = 0; i < fullText.length; i++) {
    if (abortController.signal.aborted) break
    await new Promise(r => setTimeout(r, 30))
    messages.value[idx].content += fullText[i]
  }

  // 流式结束
  messages.value[idx].streaming = false
  isStreaming.value = false
}

function stopStream() {
  abortController?.abort()
  const last = messages.value[messages.value.length - 1]
  if (last) last.streaming = false
  isStreaming.value = false
}
</script>
```

### 2. 暗色主题

```vue
<template>
  <ChatBox
    theme="dark"
    :messages="messages"
    placeholder="输入消息..."
    @send="handleSend"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { ChatBox, type ChatMessage } from 'ai-chat-components'
import 'ai-chat-components/dist/style.css'

const messages = ref<ChatMessage[]>([
  { role: 'assistant', content: '你好！我是 AI 助手', timestamp: Date.now() }
])

function handleSend(content: string) {
  messages.value.push({ role: 'user', content, timestamp: Date.now() })
}
</script>
```

### 3. 启用 Markdown 渲染

```vue
<template>
  <ChatBox
    use-markdown
    :messages="messages"
    placeholder="输入问题，AI 将以 Markdown 回复..."
    @send="handleSend"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { ChatBox, type ChatMessage } from 'ai-chat-components'
import 'ai-chat-components/dist/style.css'

const messages = ref<ChatMessage[]>([
  {
    role: 'assistant',
    content: `## 这是 Markdown 回复

我支持以下格式：

- **粗体文字**
- *斜体文字*
- \`行内代码\`

\`\`\`javascript
// 代码块
console.log('Hello, AI ChatBox!')
\`\`\`

> 了解更多请查看 [文档](https://example.com)`,
    timestamp: Date.now()
  }
])

function handleSend(content: string) {
  messages.value.push({ role: 'user', content, timestamp: Date.now() })
}
</script>
```

### 4. 通过 ref 控制组件方法

```vue
<template>
  <div>
    <div class="toolbar">
      <button @click="chatRef?.focus()">聚焦输入框</button>
      <button @click="chatRef?.clearInput()">清空输入</button>
      <button @click="chatRef?.scrollToBottom()">滚到底部</button>
      <button @click="chatRef?.setInputText('帮我写一首诗')">预设文本</button>
    </div>
    <ChatBox
      ref="chatRef"
      :messages="messages"
      @send="handleSend"
    />
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { ChatBox, type ChatMessage, type ChatBoxExpose } from 'ai-chat-components'
import 'ai-chat-components/dist/style.css'

const chatRef = ref<ChatBoxExpose | null>(null)
const messages = ref<ChatMessage[]>([])

function handleSend(content: string) {
  messages.value.push({ role: 'user', content, timestamp: Date.now() })
}
</script>
```

### 5. 自定义插槽

```vue
<template>
  <ChatBox
    :messages="messages"
    @send="handleSend"
  >
    <!-- 自定义 AI 头像 -->
    <template #avatar="{ role }">
      <span class="custom-avatar">
        {{ role === 'user' ? '🧑' : '🧠' }}
      </span>
    </template>

    <!-- 自定义底部提示 -->
    <template #footer>
      <div class="custom-footer">
        ⚡ 已开启联网搜索 · 响应速度 < 2s
      </div>
    </template>

    <!-- 自定义空状态 -->
    <template #empty>
      <div class="custom-empty">
        <img src="/logo.png" alt="logo" style="width: 80px;" />
        <h3>AI 智能助手</h3>
        <p>我是你的专属助手，可以帮你解答各种问题</p>
        <div class="quick-actions">
          <button @click="chatRef?.setInputText('帮我写一封邮件')">✉️ 写邮件</button>
          <button @click="chatRef?.setInputText('翻译成英文')">🌐 翻译</button>
          <button @click="chatRef?.setInputText('帮我总结一下')">📝 总结</button>
        </div>
      </div>
    </template>
  </ChatBox>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { ChatBox, type ChatMessage, type ChatBoxExpose } from 'ai-chat-components'
import 'ai-chat-components/dist/style.css'

const chatRef = ref<ChatBoxExpose | null>(null)
const messages = ref<ChatMessage[]>([])

function handleSend(content: string) {
  messages.value.push({ role: 'user', content, timestamp: Date.now() })
}
</script>
```

### 6. 完整对话示例（含系统消息）

```vue
<template>
  <ChatBox
    :messages="messages"
    :is-loading="loading"
    :disabled="loading"
    show-footer
    footer-text="AI 回复仅供参考，请核实重要信息"
    @send="handleSend"
    @copy="handleCopy"
    @regenerate="handleRegenerate"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { ChatBox, type ChatMessage } from 'ai-chat-components'
import 'ai-chat-components/dist/style.css'

const loading = ref(false)
const messages = ref<ChatMessage[]>([
  {
    role: 'system',
    content: '你是一个专业的技术顾问。',
    timestamp: Date.now()
  },
  {
    role: 'assistant',
    content: '你好！我是你的技术顾问，有什么可以帮你的？',
    timestamp: Date.now()
  }
])

async function handleSend(content: string) {
  messages.value.push({ role: 'user', content, timestamp: Date.now() })
  loading.value = true

  try {
    const res = await fetch('/api/chat', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        messages: messages.value.map(m => ({ role: m.role, content: m.content }))
      })
    })
    const data = await res.json()
    messages.value.push({
      role: 'assistant',
      content: data.reply,
      timestamp: Date.now()
    })
  } finally {
    loading.value = false
  }
}

function handleCopy(msg: ChatMessage) {
  navigator.clipboard.writeText(msg.content)
}

function handleRegenerate(msg: ChatMessage, index: number) {
  messages.value.splice(index, 1)
  handleSend(messages.value[messages.value.length - 1].content)
}
</script>
```

## Props

| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `messages` | `ChatMessage[]` | `[]` | 消息列表，结构见下方 [类型定义](#类型定义) |
| `placeholder` | `String` | `'输入消息...'` | 输入框占位文字 |
| `theme` | `String` | `'light'` | 主题，可选 `light` / `dark` |
| `isLoading` | `Boolean` | `false` | 是否加载中 |
| `disabled` | `Boolean` | `false` | 是否禁用输入 |
| `showHeader` | `Boolean` | `true` | 是否显示消息头部 |
| `showMessageActions` | `Boolean` | `true` | 是否显示消息操作按钮 |
| `showFooter` | `Boolean` | `false` | 是否显示底部提示 |
| `userAvatar` | `String` | `'👤'` | 用户头像，支持 emoji 或图片 URL |
| `assistantAvatar` | `String` | `'🤖'` | 助手头像，支持 emoji 或图片 URL |
| `userName` | `String` | `'我'` | 用户名称 |
| `assistantName` | `String` | `'AI 助手'` | 助手名称 |
| `emptyText` | `String` | `'开始一段新的对话吧'` | 空状态文字 |
| `sendButtonText` | `String` | `'发送'` | 发送按钮文字 |
| `copyButtonText` | `String` | `'复制'` | 复制按钮文字 |
| `regenerateButtonText` | `String` | `'重新生成'` | 重新生成按钮文字 |
| `footerText` | `String` | `'AI 生成内容仅供参考'` | 底部提示文字 |
| `loadingText` | `String` | `'正在思考中...'` | 加载中提示文字 |
| `useMarkdown` | `Boolean` | `false` | 是否启用 Markdown 渲染 |
| `autoScroll` | `Boolean` | `true` | 是否自动滚动到底部 |
| `primaryColor` | `String` | `'#6366f1'` | 主色调 |
| `userBubbleColor` | `String` | `'#eef2ff'` | 用户气泡背景色 |
| `aiBubbleColor` | `String` | `'#f9fafb'` | AI 气泡背景色 |
| `textColor` | `String` | `'#1f2937'` | 文本颜色 |
| `tools` | `ChatTool[]` | `[]` | 工具栏按钮列表，结构见 [类型定义](#类型定义) |

## Events

| 事件 | 参数 | 说明 |
|------|------|------|
| `send` | `content: string` | 点击发送按钮或按 Enter 发送时触发 |
| `copy` | `message: ChatMessage` | 点击复制按钮时触发 |
| `regenerate` | `message: ChatMessage, index: number` | 点击重新生成按钮时触发 |
| `stop` | - | 停止流式生成 |
| `paste` | `event: ClipboardEvent` | 粘贴事件 |
| `media-preview` | `media: MediaItem` | 点击媒体附件打开预览时触发 |

## Slots

| 插槽 | 说明 |
|------|------|
| `avatar` | 自定义头像 |
| `role-name` | 自定义角色名称 |
| `time` | 自定义时间显示 |
| `message-content` | 自定义消息内容 |
| `message-actions` | 自定义消息操作按钮 |
| `loading` | 自定义加载动画 |
| `loading-text` | 自定义加载中提示文字 |
| `empty` | 自定义空状态 |
| `toolbar` | 自定义工具栏区域 |
| `input-prepend` | 输入框前置内容 |
| `send-icon` | 自定义发送按钮图标 |
| `footer` | 自定义底部内容 |

### 自定义头像与名称

`userAvatar` / `assistantAvatar` 支持两种类型：**emoji 文本** 或 **图片 URL**（自动识别）。

```vue
<ChatBox
  :messages="messages"
  user-avatar="https://example.com/my-avatar.png"
  assistant-avatar="https://example.com/bot-icon.svg"
  user-name="张三"
  assistant-name="客服助手"
  @send="handleSend"
/>
```

> 也可使用 `avatar` 和 `role-name` 插槽实现更灵活的自定义。

### 7. 媒体附件与预览

消息可携带 `mediaList` 展示图片、视频、3D 模型。点击缩略图会打开预览弹窗。

```vue
<template>
  <ChatBox
    :messages="messages"
    @send="handleSend"
    @media-preview="handlePreview"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { ChatBox, type ChatMessage } from 'ai-chat-components'
import 'ai-chat-components/dist/style.css'

const messages = ref<ChatMessage[]>([
  {
    role: 'assistant',
    content: '这是带有媒体附件的回复：',
    timestamp: Date.now(),
    mediaList: [
      { mediaId: 1, type: 'image', url: 'https://picsum.photos/400/300', name: '示例图片' },
      { mediaId: 2, type: 'video', url: 'https://example.com/demo.mp4', name: '演示视频', cover: 'https://picsum.photos/400/225' },
      { mediaId: 3, type: 'model3d', url: 'https://modelviewer.dev/shared-assets/models/Astronaut.glb', name: '3D 模型' }
    ]
  }
])

function handleSend(content: string) {
  messages.value.push({ role: 'user', content, timestamp: Date.now() })
}

function handlePreview(media: any) {
  console.log('预览打开:', media)
}
</script>
```

> **3D 模型预览**基于 `@google/model-viewer`，支持鼠标拖拽旋转、滚轮缩放、右键平移。加载失败自动显示 fallback 提示。

### 8. 证据链文档

消息可携带 `evidenceList` 展示引用的文档证据。

```vue
<template>
  <ChatBox :messages="messages" @send="handleSend" />
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { ChatBox, type ChatMessage } from 'ai-chat-components'
import 'ai-chat-components/dist/style.css'

const messages = ref<ChatMessage[]>([
  {
    role: 'assistant',
    content: '根据查询到的文档，以下是相关结论：',
    timestamp: Date.now(),
    evidenceList: [
      { evId: 1, iconType: 'pdf', docCount: 3, title: '产品需求文档', desc: '第2.3章节 · 共15页' },
      { evId: 2, iconType: 'link', docCount: 1, title: '竞品分析报告', desc: 'market-research.example.com' }
    ]
  }
])

function handleSend(content: string) {
  messages.value.push({ role: 'user', content, timestamp: Date.now() })
}
</script>
```

### 9. 工具栏按钮

通过 `tools` prop 添加输入区上方的工具栏按钮，支持自定义图标和点击事件。

```vue
<template>
  <ChatBox
    :messages="messages"
    :tools="tools"
    @send="handleSend"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { ChatBox, type ChatMessage, type ChatTool } from 'ai-chat-components'
import 'ai-chat-components/dist/style.css'

const messages = ref<ChatMessage[]>([])

const tools: ChatTool[] = [
  { label: '联网搜索', icon: '🌐', click: () => console.log('搜索') },
  { label: '深度思考', icon: '🧠', click: () => console.log('深度思考'), disabled: false },
  { label: '上传文件', icon: '📎', click: () => console.log('上传') }
]

function handleSend(content: string) {
  messages.value.push({ role: 'user', content, timestamp: Date.now() })
}
</script>
```

> 也可使用 `toolbar` 插槽实现更灵活的自定义工具栏。

### 10. 自定义文本与颜色

支持自定义所有按钮文案、加载提示、角色名称，以及主色调和气泡颜色。

```vue
<template>
  <ChatBox
    :messages="messages"
    send-button-text="提交"
    copy-button-text="拷贝"
    regenerate-button-text="重新回答"
    loading-text="AI 正在生成回复..."
    footer-text="以上内容由 AI 生成，仅供参考"
    user-name="小明"
    assistant-name="小助手"
    primary-color="#ec4899"
    user-bubble-color="#fdf2f8"
    ai-bubble-color="#f8fafc"
    @send="handleSend"
  />
</template>
```

## 类型定义

### ChatMessage

| 属性 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `role` | `'user' \| 'assistant' \| 'system'` | 是 | 消息角色 |
| `content` | `string` | 是 | 消息文本内容 |
| `timestamp` | `number` | 否 | 时间戳（毫秒） |
| `streaming` | `boolean` | 否 | 是否流式输出中（内容逐步增长时设为 `true`） |
| `loading` | `boolean` | 否 | 是否正在加载（AI 思考中，尚未开始输出） |
| `hasAudio` | `boolean` | 否 | 是否有语音内容 |
| `isPlaying` | `boolean` | 否 | 语音是否正在播放 |
| `audioDuration` | `string` | 否 | 语音时长（如 `"0:32"`） |
| `mediaList` | `MediaItem[]` | 否 | 多媒体资源列表（图片/视频/3D模型） |
| `evidenceList` | `EvidenceItem[]` | 否 | 证据链文档列表 |

### MediaItem

| 属性 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `mediaId` | `string \| number` | 是 | 媒体唯一 ID |
| `type` | `'image' \| 'video' \| 'model3d'` | 是 | 媒体类型 |
| `url` | `string` | 是 | 资源地址 |
| `cover` | `string` | 否 | 视频/3D 模型的封面图 |
| `name` | `string` | 否 | 媒体名称 |

### EvidenceItem

| 属性 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `evId` | `string \| number` | 是 | 证据唯一 ID |
| `iconType` | `'pdf' \| 'word' \| 'excel' \| 'txt' \| 'ppt' \| 'link'` | 是 | 文档图标类型 |
| `docCount` | `number` | 是 | 文档数量 |
| `title` | `string` | 是 | 证据标题 |
| `desc` | `string` | 是 | 证据描述 |

### ChatTool

| 属性 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `label` | `string` | 是 | 按钮文本 |
| `click` | `() => void` | 是 | 点击事件回调 |
| `icon` | `string` | 否 | 图标（emoji 或 SVG） |
| `disabled` | `boolean` | 否 | 是否禁用 |

## 方法 (通过 ref 调用)

```vue
<ChatBox ref="chatRef" />
```

| 方法 | 说明 |
|------|------|
| `scrollToBottom()` | 手动滚动到底部 |
| `focus()` | 聚焦输入框 |
| `setInputText(text)` | 设置输入框内容 |
| `clearInput()` | 清空输入框 |

## License

MIT