@blueking/bkui-knowledge 0.0.1-beta.13 → 0.0.1-beta.15

package/knowledge/skills/chat-x-custom-component/references/integration-guide.md

@@ -0,0 +1,666 @@
+# 集成指南
+
+本文档详细说明如何将自定义消息组件集成到 Chat-X 的 `MessageContainer` 中。
+
+## MessageContainer 插槽机制
+
+### 默认插槽
+
+`MessageContainer` 提供默认插槽用于自定义消息渲染：
+
+```vue
+<MessageContainer
+  :messages="messages"
+  :on-agent-action="handleAgentAction"
+  :on-user-action="handleUserAction"
+>
+  <!-- 默认插槽接收 message 参数 -->
+  <template #default="{ message }">
+    <!-- 自定义渲染逻辑 -->
+  </template>
+</MessageContainer>
+```
+
+### 插槽参数
+
+```typescript
+interface SlotProps {
+  message: Message; // 当前消息对象
+}
+```
+
+## 集成模式
+
+### 模式 1：条件渲染（推荐）
+
+根据消息角色条件渲染不同组件：
+
+```vue
+<template>
+  <MessageContainer :messages="messages">
+    <template #default="{ message }">
+      <!-- 自定义消息类型 -->
+      <ChartMessage
+        v-if="message.role === 'chart'"
+        :message="message"
+      />
+      <TableMessage
+        v-else-if="message.role === 'table'"
+        :message="message"
+      />
+      <!-- 使用 MessageRender 处理内置类型 -->
+      <MessageRender
+        v-else
+        :message="message"
+        :on-action="handleAction"
+      />
+    </template>
+  </MessageContainer>
+</template>
+
+<script setup lang="ts">
+import { MessageContainer, MessageRender } from '@blueking/chat-x';
+import ChartMessage from './chart-message.vue';
+import TableMessage from './table-message.vue';
+</script>
+```
+
+### 模式 2：动态组件
+
+使用动态组件注册表：
+
+```vue
+<template>
+  <MessageContainer :messages="messages">
+    <template #default="{ message }">
+      <component
+        :is="getMessageComponent(message.role)"
+        :message="message"
+        :on-action="handleAction"
+      />
+    </template>
+  </MessageContainer>
+</template>
+
+<script setup lang="ts">
+import { type Component, markRaw } from 'vue';
+import { MessageRender } from '@blueking/chat-x';
+import ChartMessage from './chart-message.vue';
+import TableMessage from './table-message.vue';
+
+// 组件注册表
+const componentMap: Record<string, Component> = {
+  chart: markRaw(ChartMessage),
+  table: markRaw(TableMessage),
+};
+
+function getMessageComponent(role: string): Component {
+  return componentMap[role] || MessageRender;
+}
+</script>
+```
+
+### 模式 3：插件式注册
+
+创建可扩展的消息渲染系统：
+
+```typescript
+// plugins/message-renderer.ts
+import { type Component, markRaw, shallowReactive } from 'vue';
+import { MessageRender } from '@blueking/chat-x';
+
+interface MessageRendererPlugin {
+  role: string;
+  component: Component;
+  priority?: number;
+}
+
+class MessageRendererRegistry {
+  private plugins = shallowReactive<MessageRendererPlugin[]>([]);
+
+  register(plugin: MessageRendererPlugin) {
+    this.plugins.push({
+      ...plugin,
+      component: markRaw(plugin.component),
+    });
+    // 按优先级排序
+    this.plugins.sort((a, b) => (b.priority || 0) - (a.priority || 0));
+  }
+
+  getComponent(role: string): Component {
+    const plugin = this.plugins.find(p => p.role === role);
+    return plugin?.component || MessageRender;
+  }
+}
+
+export const messageRegistry = new MessageRendererRegistry();
+```
+
+使用插件注册：
+
+```typescript
+// main.ts
+import { messageRegistry } from './plugins/message-renderer';
+import ChartMessage from './components/chart-message.vue';
+
+// 注册自定义消息组件
+messageRegistry.register({
+  role: 'chart',
+  component: ChartMessage,
+  priority: 10,
+});
+```
+
+组件中使用：
+
+```vue
+<template>
+  <MessageContainer :messages="messages">
+    <template #default="{ message }">
+      <component
+        :is="messageRegistry.getComponent(message.role)"
+        :message="message"
+      />
+    </template>
+  </MessageContainer>
+</template>
+
+<script setup lang="ts">
+import { messageRegistry } from './plugins/message-renderer';
+</script>
+```
+
+## 全局配置 Provider
+
+### useGlobalConfig
+
+在容器层级提供全局配置，使子组件能够使用 `useMessageSlotId`：
+
+```vue
+<!-- App.vue 或根容器 -->
+<template>
+  <div class="app-container">
+    <!-- Slot 渲染目标 -->
+    <div
+      :id="rawMessageSlotId"
+      class="message-slot-container"
+    ></div>
+    
+    <!-- 聊天区域 -->
+    <div class="chat-area">
+      <MessageContainer :messages="messages">
+        <template #default="{ message }">
+          <!-- 自定义消息可以使用 useMessageSlotId -->
+          <CustomMessage :message="message" />
+        </template>
+      </MessageContainer>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { useGlobalConfig } from '@blueking/chat-x';
+
+// 调用 useGlobalConfig 提供配置
+const { rawMessageSlotId, messageSlotId } = useGlobalConfig();
+</script>
+
+<style lang="scss" scoped>
+.app-container {
+  display: flex;
+}
+
+.message-slot-container {
+  flex: 0 0 auto;
+  width: 400px;
+  overflow: auto;
+  background: #f5f7fa;
+  
+  &:empty {
+    display: none;
+  }
+}
+
+.chat-area {
+  flex: 1;
+  overflow: hidden;
+}
+</style>
+```
+
+### Slot 容器布局
+
+典型的布局模式：
+
+```scss
+// 左右布局
+.app-container {
+  display: flex;
+  
+  // slot 在左边
+  &.slot-left {
+    flex-direction: row;
+  }
+  
+  // slot 在右边
+  &.slot-right {
+    flex-direction: row-reverse;
+  }
+}
+
+// 上下布局
+.app-container {
+  display: flex;
+  flex-direction: column;
+  
+  .message-slot-container {
+    height: 300px;
+  }
+}
+
+// 弹窗模式
+.message-slot-container {
+  position: fixed;
+  top: 50%;
+  left: 50%;
+  transform: translate(-50%, -50%);
+  z-index: 9999;
+  background: #fff;
+  border-radius: 8px;
+  box-shadow: 0 4px 24px rgba(0, 0, 0, 0.15);
+}
+```
+
+## 事件处理
+
+### MessageContainer 事件
+
+```vue
+<MessageContainer
+  :messages="messages"
+  :message-status="currentStatus"
+  :on-agent-action="handleAgentAction"
+  :on-user-action="handleUserAction"
+  @stop-streaming="handleStopStreaming"
+>
+  <!-- 内容 -->
+</MessageContainer>
+
+<script setup lang="ts">
+import type { IToolBtn } from '@blueking/chat-x';
+
+// Agent 消息工具栏点击（复制、分享等）
+const handleAgentAction = (tool: IToolBtn) => {
+  console.log('Agent action:', tool.id);
+};
+
+// 用户消息操作（编辑、删除等）
+const handleUserAction = (tool: IToolBtn) => {
+  console.log('User action:', tool.id);
+};
+
+// 停止流式输出
+const handleStopStreaming = () => {
+  // 中断当前流式请求
+};
+</script>
+```
+
+### 自定义消息事件冒泡
+
+自定义消息组件可以触发事件向上传递：
+
+```vue
+<!-- custom-message.vue -->
+<script setup lang="ts">
+const emit = defineEmits<{
+  action: [action: string, payload: any];
+}>();
+
+const handleButtonClick = () => {
+  emit('action', 'button-click', { id: 'xxx' });
+};
+</script>
+```
+
+在父组件中监听：
+
+```vue
+<CustomMessage
+  :message="message"
+  @action="handleCustomAction"
+/>
+
+<script setup lang="ts">
+const handleCustomAction = (action: string, payload: any) => {
+  switch (action) {
+    case 'button-click':
+      // 处理按钮点击
+      break;
+    case 'form-submit':
+      // 处理表单提交
+      break;
+  }
+};
+</script>
+```
+
+## 消息状态同步
+
+### 流式更新
+
+```typescript
+import { type Message, MessageStatus } from '@blueking/chat-x';
+
+// 添加 pending 消息
+const addPendingMessage = () => {
+  messages.value.push({
+    id: 'new-message',
+    messageId: 'new-message',
+    role: 'chart',
+    status: MessageStatus.Pending,
+    content: null,
+  });
+};
+
+// 流式更新内容
+const updateMessage = (id: string, content: any, status: MessageStatus) => {
+  const message = messages.value.find(m => m.id === id);
+  if (message) {
+    message.content = content;
+    message.status = status;
+  }
+};
+
+// 完成消息
+const completeMessage = (id: string, content: any) => {
+  updateMessage(id, content, MessageStatus.Complete);
+};
+```
+
+### 状态驱动渲染
+
+```vue
+<template>
+  <div class="custom-message">
+    <!-- Pending 状态 -->
+    <template v-if="message.status === MessageStatus.Pending">
+      <LoadingSkeleton />
+    </template>
+    
+    <!-- Streaming 状态 -->
+    <template v-else-if="message.status === MessageStatus.Streaming">
+      <PartialContent :content="message.content" />
+      <LoadingIndicator />
+    </template>
+    
+    <!-- Error 状态 -->
+    <template v-else-if="message.status === MessageStatus.Error">
+      <ErrorDisplay :error="message.error" @retry="handleRetry" />
+    </template>
+    
+    <!-- Complete 状态 -->
+    <template v-else>
+      <FullContent :content="message.content" />
+    </template>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { MessageStatus } from '@blueking/chat-x';
+</script>
+```
+
+## 工具栏集成
+
+### 自定义消息工具栏
+
+```vue
+<template>
+  <div class="custom-message">
+    <div class="content">
+      <!-- 消息内容 -->
+    </div>
+    <MessageTools
+      :tools="customTools"
+      :on-action="handleToolAction"
+    />
+  </div>
+</template>
+
+<script setup lang="ts">
+import { CONST_MESSAGE_TOOLS, MessageTools, type IToolBtn } from '@blueking/chat-x';
+
+// 扩展默认工具栏
+const customTools: IToolBtn[] = [
+  ...CONST_MESSAGE_TOOLS,
+  {
+    id: 'export',
+    name: '导出',
+    description: '导出数据',
+    icon: 'export-icon',
+  },
+  {
+    id: 'refresh',
+    name: '刷新',
+    description: '刷新数据',
+    icon: 'refresh-icon',
+  },
+];
+
+const handleToolAction = (tool: IToolBtn) => {
+  switch (tool.id) {
+    case 'export':
+      exportData();
+      break;
+    case 'refresh':
+      refreshData();
+      break;
+    default:
+      // 默认处理
+      break;
+  }
+};
+</script>
+```
+
+## 完整集成示例
+
+```vue
+<!-- ChatApp.vue -->
+<template>
+  <div
+    class="chat-app"
+    :class="{ 'slot-visible': hasSlotContent }"
+  >
+    <!-- Teleport 目标容器 -->
+    <aside
+      :id="rawMessageSlotId"
+      class="chat-app-slot"
+    ></aside>
+    
+    <!-- 主聊天区域 -->
+    <main class="chat-app-main">
+      <!-- 消息列表 -->
+      <MessageContainer
+        :messages="messages"
+        :message-status="streamingStatus"
+        :on-agent-action="handleAgentAction"
+        :on-user-action="handleUserAction"
+        @stop-streaming="handleStopStreaming"
+      >
+        <template #default="{ message }">
+          <!-- 图表消息 -->
+          <ChartMessage
+            v-if="message.role === 'chart'"
+            :message="message"
+            @action="handleCustomAction"
+          />
+          <!-- 表格消息 -->
+          <TableMessage
+            v-else-if="message.role === 'table'"
+            :message="message"
+            @export="handleExport"
+          />
+          <!-- 卡片消息 -->
+          <CardMessage
+            v-else-if="message.role === 'card'"
+            :message="message"
+          />
+          <!-- 内置消息 -->
+          <MessageRender
+            v-else
+            :message="message"
+            :on-action="handleAgentAction"
+          />
+        </template>
+      </MessageContainer>
+      
+      <!-- 输入框 -->
+      <ChatInput
+        v-model="input"
+        :on-send-message="handleSend"
+        :on-stop-sending="handleStopStreaming"
+      />
+    </main>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref as deepRef, shallowRef, computed } from 'vue';
+import {
+  type Message,
+  type IToolBtn,
+  MessageContainer,
+  MessageRender,
+  ChatInput,
+  MessageStatus,
+  useGlobalConfig,
+} from '@blueking/chat-x';
+import ChartMessage from './components/chart-message.vue';
+import TableMessage from './components/table-message.vue';
+import CardMessage from './components/card-message.vue';
+
+// 全局配置
+const { rawMessageSlotId } = useGlobalConfig();
+
+// 状态
+const messages = deepRef<Message[]>([]);
+const input = shallowRef('');
+const streamingStatus = shallowRef<MessageStatus>(MessageStatus.Complete);
+
+// 计算属性
+const hasSlotContent = computed(() => {
+  // 检查 slot 容器是否有内容
+  return document.getElementById(rawMessageSlotId)?.hasChildNodes() || false;
+});
+
+// 事件处理
+const handleSend = async (value: string) => {
+  // 添加用户消息
+  messages.value.push({
+    id: `user-${Date.now()}`,
+    messageId: `user-${Date.now()}`,
+    role: 'user',
+    content: value,
+    status: MessageStatus.Complete,
+  });
+  
+  // 发送请求并处理响应...
+};
+
+const handleAgentAction = (tool: IToolBtn) => {
+  console.log('Agent action:', tool);
+};
+
+const handleUserAction = (tool: IToolBtn) => {
+  console.log('User action:', tool);
+};
+
+const handleStopStreaming = () => {
+  streamingStatus.value = MessageStatus.Stop;
+};
+
+const handleCustomAction = (action: string, payload: any) => {
+  console.log('Custom action:', action, payload);
+};
+
+const handleExport = (data: any) => {
+  console.log('Export:', data);
+};
+</script>
+
+<style lang="scss" scoped>
+.chat-app {
+  display: flex;
+  height: 100vh;
+  background: #f5f7fa;
+
+  &-slot {
+    width: 0;
+    overflow: hidden;
+    background: #fff;
+    border-left: 1px solid #eaebf0;
+    transition: width 0.3s ease;
+
+    &:not(:empty) {
+      width: 400px;
+    }
+  }
+
+  &-main {
+    flex: 1;
+    display: flex;
+    flex-direction: column;
+    overflow: hidden;
+    padding: 16px;
+    background: #fff;
+  }
+
+  &.slot-visible .chat-app-main {
+    max-width: calc(100% - 400px);
+  }
+}
+</style>
+```
+
+## 调试技巧
+
+### 检查 Slot 挂载
+
+```typescript
+import { onMounted, watch } from 'vue';
+import { useMessageSlotId } from '@blueking/chat-x';
+
+const { messageSlotId } = useMessageSlotId();
+
+onMounted(() => {
+  console.log('Slot ID:', messageSlotId.value);
+  
+  // 监听变化
+  watch(messageSlotId, (id) => {
+    console.log('Slot ID changed:', id);
+    const element = document.querySelector(id || '');
+    console.log('Slot element:', element);
+  });
+});
+```
+
+### 验证消息类型
+
+```typescript
+// 在开发环境添加类型验证
+if (import.meta.env.DEV) {
+  watch(
+    () => messages.value,
+    (msgs) => {
+      msgs.forEach((msg) => {
+        if (!['user', 'assistant', 'chart', 'table'].includes(msg.role)) {
+          console.warn(`Unknown message role: ${msg.role}`);
+        }
+      });
+    },
+    { deep: true }
+  );
+}
+```