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

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

@@ -0,0 +1,861 @@
+# 组件模板参考
+
+本文档提供常用自定义消息组件的完整模板代码。
+
+## 基础模板
+
+### 最小化组件模板
+
+```vue
+<!-- components/simple-message.vue -->
+<template>
+  <div class="simple-message">
+    <div class="simple-message-content">
+      {{ message.content }}
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { type BaseMessage } from '@blueking/chat-x';
+
+interface SimpleContent {
+  text: string;
+}
+
+defineProps<{
+  message: Partial<BaseMessage<'simple', SimpleContent>>;
+}>();
+</script>
+
+<style lang="scss" scoped>
+.simple-message {
+  padding: 12px 16px;
+  background: #f5f7fa;
+  border-radius: 8px;
+
+  &-content {
+    color: #313238;
+    font-size: 14px;
+    line-height: 1.6;
+  }
+}
+</style>
+```
+
+## 图表组件模板
+
+### ECharts 图表消息
+
+```vue
+<!-- components/echart-message.vue -->
+<template>
+  <div class="echart-message">
+    <div class="echart-message-header">
+      <span class="title">{{ message.content?.title || '图表' }}</span>
+      <div class="actions">
+        <Button
+          size="small"
+          @click="handleFullscreen"
+        >
+          全屏查看
+        </Button>
+      </div>
+    </div>
+    <div
+      ref="chartRef"
+      class="echart-message-chart"
+    ></div>
+    
+    <!-- 全屏弹窗 -->
+    <template v-if="fullscreenVisible && messageSlotId">
+      <Teleport :to="messageSlotId">
+        <div class="echart-fullscreen">
+          <div class="echart-fullscreen-header">
+            <span>{{ message.content?.title }}</span>
+            <Button @click="handleCloseFullscreen">关闭</Button>
+          </div>
+          <div
+            ref="fullscreenChartRef"
+            class="echart-fullscreen-chart"
+          ></div>
+        </div>
+      </Teleport>
+    </template>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { onMounted, onUnmounted, shallowRef, useTemplateRef, watch, nextTick } from 'vue';
+import { Button } from 'bkui-vue';
+import * as echarts from 'echarts';
+import { type BaseMessage, useMessageSlotId } from '@blueking/chat-x';
+
+// 类型定义
+interface ChartContent {
+  chartType: 'line' | 'bar' | 'pie' | 'scatter';
+  data: Record<string, any>;
+  title?: string;
+  options?: Record<string, any>;
+}
+
+// Props
+const props = defineProps<{
+  message: Partial<BaseMessage<'chart', ChartContent>>;
+}>();
+
+// Refs
+const chartRef = useTemplateRef<HTMLElement>('chartRef');
+const fullscreenChartRef = useTemplateRef<HTMLElement>('fullscreenChartRef');
+const { messageSlotId } = useMessageSlotId();
+
+// State
+const chartInstance = shallowRef<echarts.ECharts | null>(null);
+const fullscreenChartInstance = shallowRef<echarts.ECharts | null>(null);
+const fullscreenVisible = shallowRef(false);
+
+// 生成图表配置
+function generateChartOption(content: ChartContent): echarts.EChartsOption {
+  const baseOption: echarts.EChartsOption = {
+    title: { text: content.title },
+    tooltip: { trigger: 'axis' },
+    legend: { bottom: 10 },
+    ...content.options,
+  };
+
+  switch (content.chartType) {
+    case 'line':
+      return {
+        ...baseOption,
+        xAxis: { type: 'category', data: content.data.labels || [] },
+        yAxis: { type: 'value' },
+        series: content.data.series || [],
+      };
+    case 'bar':
+      return {
+        ...baseOption,
+        xAxis: { type: 'category', data: content.data.labels || [] },
+        yAxis: { type: 'value' },
+        series: (content.data.series || []).map(s => ({ ...s, type: 'bar' })),
+      };
+    case 'pie':
+      return {
+        ...baseOption,
+        series: [{
+          type: 'pie',
+          radius: '60%',
+          data: content.data.series || [],
+        }],
+      };
+    default:
+      return baseOption;
+  }
+}
+
+// 初始化图表
+function initChart(container: HTMLElement, content: ChartContent): echarts.ECharts {
+  const chart = echarts.init(container);
+  chart.setOption(generateChartOption(content));
+  return chart;
+}
+
+// 事件处理
+const handleFullscreen = () => {
+  fullscreenVisible.value = true;
+};
+
+const handleCloseFullscreen = () => {
+  fullscreenVisible.value = false;
+  fullscreenChartInstance.value?.dispose();
+  fullscreenChartInstance.value = null;
+};
+
+// 生命周期
+onMounted(() => {
+  if (chartRef.value && props.message.content) {
+    chartInstance.value = initChart(chartRef.value, props.message.content);
+  }
+});
+
+onUnmounted(() => {
+  chartInstance.value?.dispose();
+  fullscreenChartInstance.value?.dispose();
+});
+
+// 监听全屏状态
+watch(fullscreenVisible, async (visible) => {
+  if (visible && props.message.content) {
+    await nextTick();
+    if (fullscreenChartRef.value) {
+      fullscreenChartInstance.value = initChart(
+        fullscreenChartRef.value,
+        props.message.content
+      );
+    }
+  }
+});
+
+// 监听内容变化
+watch(
+  () => props.message.content,
+  (content) => {
+    if (content && chartInstance.value) {
+      chartInstance.value.setOption(generateChartOption(content), true);
+    }
+  }
+);
+</script>
+
+<style lang="scss" scoped>
+.echart-message {
+  padding: 16px;
+  background: #fff;
+  border: 1px solid #eaebf0;
+  border-radius: 8px;
+
+  &-header {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    margin-bottom: 12px;
+
+    .title {
+      font-size: 14px;
+      font-weight: 500;
+      color: #313238;
+    }
+  }
+
+  &-chart {
+    width: 100%;
+    height: 300px;
+  }
+}
+
+.echart-fullscreen {
+  position: fixed;
+  inset: 0;
+  z-index: 9999;
+  display: flex;
+  flex-direction: column;
+  padding: 24px;
+  background: #fff;
+
+  &-header {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    margin-bottom: 16px;
+    font-size: 16px;
+    font-weight: 500;
+  }
+
+  &-chart {
+    flex: 1;
+    width: 100%;
+  }
+}
+</style>
+```
+
+## 表格组件模板
+
+### 数据表格消息
+
+```vue
+<!-- components/table-message.vue -->
+<template>
+  <div class="table-message">
+    <div class="table-message-header">
+      <span class="title">{{ message.content?.title || '数据表格' }}</span>
+      <div class="actions">
+        <Button
+          size="small"
+          @click="handleExport"
+        >
+          导出
+        </Button>
+      </div>
+    </div>
+    <div class="table-message-body">
+      <Table
+        :data="tableData"
+        :columns="columns"
+        :pagination="pagination"
+        @page-change="handlePageChange"
+      />
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { computed, shallowRef } from 'vue';
+import { Table, Button } from 'bkui-vue';
+import { type BaseMessage } from '@blueking/chat-x';
+
+// 类型定义
+interface Column {
+  key: string;
+  title: string;
+  width?: number | string;
+  sortable?: boolean;
+  align?: 'left' | 'center' | 'right';
+}
+
+interface TableContent {
+  title?: string;
+  columns: Column[];
+  rows: Record<string, any>[];
+  pagination?: {
+    current: number;
+    pageSize: number;
+    total: number;
+  };
+}
+
+// Props
+const props = defineProps<{
+  message: Partial<BaseMessage<'table', TableContent>>;
+}>();
+
+// Emits
+const emit = defineEmits<{
+  export: [data: Record<string, any>[]];
+  pageChange: [page: number];
+}>();
+
+// State
+const currentPage = shallowRef(1);
+
+// Computed
+const columns = computed(() => {
+  return (props.message.content?.columns || []).map(col => ({
+    field: col.key,
+    label: col.title,
+    width: col.width,
+    sort: col.sortable,
+    align: col.align,
+  }));
+});
+
+const tableData = computed(() => {
+  return props.message.content?.rows || [];
+});
+
+const pagination = computed(() => {
+  const p = props.message.content?.pagination;
+  if (!p) return false;
+  return {
+    current: currentPage.value,
+    count: p.total,
+    limit: p.pageSize,
+  };
+});
+
+// 事件处理
+const handlePageChange = (page: number) => {
+  currentPage.value = page;
+  emit('pageChange', page);
+};
+
+const handleExport = () => {
+  emit('export', tableData.value);
+};
+</script>
+
+<style lang="scss" scoped>
+.table-message {
+  padding: 16px;
+  background: #fff;
+  border: 1px solid #eaebf0;
+  border-radius: 8px;
+
+  &-header {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    margin-bottom: 12px;
+
+    .title {
+      font-size: 14px;
+      font-weight: 500;
+      color: #313238;
+    }
+  }
+
+  &-body {
+    overflow-x: auto;
+  }
+}
+</style>
+```
+
+## 卡片组件模板
+
+### 卡片列表消息
+
+```vue
+<!-- components/card-list-message.vue -->
+<template>
+  <div
+    class="card-list-message"
+    :class="[`layout-${layout}`]"
+  >
+    <div class="card-list-message-grid">
+      <div
+        v-for="item in items"
+        :key="item.id"
+        class="card-item"
+        @click="handleItemClick(item)"
+      >
+        <img
+          v-if="item.image"
+          :src="item.image"
+          :alt="item.title"
+          class="card-item-image"
+        />
+        <div class="card-item-body">
+          <h4 class="card-item-title">{{ item.title }}</h4>
+          <p
+            v-if="item.description"
+            class="card-item-desc"
+          >
+            {{ item.description }}
+          </p>
+          <div
+            v-if="item.tags?.length"
+            class="card-item-tags"
+          >
+            <span
+              v-for="tag in item.tags"
+              :key="tag"
+              class="tag"
+            >
+              {{ tag }}
+            </span>
+          </div>
+        </div>
+      </div>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { computed } from 'vue';
+import { type BaseMessage } from '@blueking/chat-x';
+
+// 类型定义
+interface CardItem {
+  id: string;
+  title: string;
+  description?: string;
+  image?: string;
+  link?: string;
+  tags?: string[];
+  meta?: Record<string, any>;
+}
+
+interface CardListContent {
+  items: CardItem[];
+  layout?: 'grid' | 'list';
+  columns?: number;
+}
+
+// Props
+const props = defineProps<{
+  message: Partial<BaseMessage<'cardList', CardListContent>>;
+}>();
+
+// Emits
+const emit = defineEmits<{
+  itemClick: [item: CardItem];
+}>();
+
+// Computed
+const items = computed(() => props.message.content?.items || []);
+const layout = computed(() => props.message.content?.layout || 'grid');
+
+// 事件处理
+const handleItemClick = (item: CardItem) => {
+  if (item.link) {
+    window.open(item.link, '_blank');
+  }
+  emit('itemClick', item);
+};
+</script>
+
+<style lang="scss" scoped>
+.card-list-message {
+  &.layout-grid .card-list-message-grid {
+    display: grid;
+    grid-template-columns: repeat(auto-fill, minmax(200px, 1fr));
+    gap: 16px;
+  }
+
+  &.layout-list .card-list-message-grid {
+    display: flex;
+    flex-direction: column;
+    gap: 12px;
+  }
+}
+
+.card-item {
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+  cursor: pointer;
+  background: #fff;
+  border: 1px solid #eaebf0;
+  border-radius: 8px;
+  transition: box-shadow 0.2s, transform 0.2s;
+
+  &:hover {
+    box-shadow: 0 4px 12px rgba(0, 0, 0, 0.1);
+    transform: translateY(-2px);
+  }
+
+  &-image {
+    width: 100%;
+    height: 120px;
+    object-fit: cover;
+  }
+
+  &-body {
+    padding: 12px;
+  }
+
+  &-title {
+    margin: 0 0 8px;
+    font-size: 14px;
+    font-weight: 500;
+    color: #313238;
+  }
+
+  &-desc {
+    margin: 0 0 8px;
+    font-size: 12px;
+    color: #979ba5;
+    line-height: 1.5;
+    display: -webkit-box;
+    -webkit-line-clamp: 2;
+    -webkit-box-orient: vertical;
+    overflow: hidden;
+  }
+
+  &-tags {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 4px;
+
+    .tag {
+      padding: 2px 8px;
+      font-size: 12px;
+      color: #3a84ff;
+      background: #f0f5ff;
+      border-radius: 4px;
+    }
+  }
+}
+
+.layout-list .card-item {
+  flex-direction: row;
+
+  .card-item-image {
+    width: 80px;
+    height: 80px;
+    flex-shrink: 0;
+  }
+}
+</style>
+```
+
+## 交互组件模板
+
+### 确认对话框消息
+
+```vue
+<!-- components/confirm-message.vue -->
+<template>
+  <div
+    class="confirm-message"
+    :class="[`type-${content.type || 'info'}`]"
+  >
+    <div class="confirm-message-icon">
+      <component :is="iconComponent" />
+    </div>
+    <div class="confirm-message-content">
+      <h4 class="title">{{ content.title }}</h4>
+      <p class="message">{{ content.message }}</p>
+    </div>
+    <div class="confirm-message-actions">
+      <Button
+        theme="default"
+        @click="handleCancel"
+      >
+        {{ content.cancelText || '取消' }}
+      </Button>
+      <Button
+        theme="primary"
+        @click="handleConfirm"
+      >
+        {{ content.confirmText || '确认' }}
+      </Button>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { computed } from 'vue';
+import { Button } from 'bkui-vue';
+import { type BaseMessage } from '@blueking/chat-x';
+
+// 类型定义
+interface ConfirmContent {
+  title: string;
+  message: string;
+  confirmText?: string;
+  cancelText?: string;
+  type?: 'info' | 'warning' | 'error' | 'success';
+}
+
+// Props
+const props = defineProps<{
+  message: Partial<BaseMessage<'confirm', ConfirmContent>>;
+}>();
+
+// Emits
+const emit = defineEmits<{
+  confirm: [];
+  cancel: [];
+}>();
+
+// Computed
+const content = computed(() => props.message.content || {
+  title: '',
+  message: '',
+});
+
+const iconComponent = computed(() => {
+  // 根据类型返回不同图标
+  const type = content.value.type || 'info';
+  // 这里可以返回对应的图标组件
+  return 'span'; // 占位
+});
+
+// 事件处理
+const handleConfirm = () => {
+  emit('confirm');
+};
+
+const handleCancel = () => {
+  emit('cancel');
+};
+</script>
+
+<style lang="scss" scoped>
+.confirm-message {
+  display: flex;
+  align-items: flex-start;
+  gap: 12px;
+  padding: 16px;
+  background: #fff;
+  border-radius: 8px;
+  border-left: 4px solid;
+
+  &.type-info {
+    border-left-color: #3a84ff;
+    background: #f0f5ff;
+  }
+
+  &.type-warning {
+    border-left-color: #ff9c01;
+    background: #fff8e6;
+  }
+
+  &.type-error {
+    border-left-color: #ea3636;
+    background: #ffeded;
+  }
+
+  &.type-success {
+    border-left-color: #2dcb56;
+    background: #e8fff3;
+  }
+
+  &-icon {
+    font-size: 20px;
+  }
+
+  &-content {
+    flex: 1;
+
+    .title {
+      margin: 0 0 4px;
+      font-size: 14px;
+      font-weight: 500;
+      color: #313238;
+    }
+
+    .message {
+      margin: 0;
+      font-size: 12px;
+      color: #63656e;
+      line-height: 1.5;
+    }
+  }
+
+  &-actions {
+    display: flex;
+    gap: 8px;
+  }
+}
+</style>
+```
+
+## 加载状态模板
+
+### 带加载状态的消息
+
+```vue
+<!-- components/loading-message.vue -->
+<template>
+  <div class="loading-message">
+    <!-- 加载中 -->
+    <template v-if="isLoading">
+      <div class="loading-message-skeleton">
+        <div class="skeleton-line"></div>
+        <div class="skeleton-line short"></div>
+      </div>
+    </template>
+    
+    <!-- 错误状态 -->
+    <template v-else-if="error">
+      <div class="loading-message-error">
+        <span class="error-icon">⚠️</span>
+        <span class="error-text">{{ error }}</span>
+        <Button
+          size="small"
+          @click="handleRetry"
+        >
+          重试
+        </Button>
+      </div>
+    </template>
+    
+    <!-- 正常内容 -->
+    <template v-else>
+      <slot />
+    </template>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { Button } from 'bkui-vue';
+
+defineProps<{
+  isLoading?: boolean;
+  error?: string | null;
+}>();
+
+const emit = defineEmits<{
+  retry: [];
+}>();
+
+const handleRetry = () => {
+  emit('retry');
+};
+</script>
+
+<style lang="scss" scoped>
+.loading-message {
+  &-skeleton {
+    display: flex;
+    flex-direction: column;
+    gap: 8px;
+    padding: 16px;
+
+    .skeleton-line {
+      height: 14px;
+      background: linear-gradient(90deg, #f0f1f5 25%, #e8e9ed 50%, #f0f1f5 75%);
+      background-size: 200% 100%;
+      animation: shimmer 1.5s infinite;
+      border-radius: 4px;
+
+      &.short {
+        width: 60%;
+      }
+    }
+  }
+
+  &-error {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    padding: 12px 16px;
+    background: #ffeded;
+    border-radius: 8px;
+
+    .error-icon {
+      font-size: 16px;
+    }
+
+    .error-text {
+      flex: 1;
+      font-size: 12px;
+      color: #ea3636;
+    }
+  }
+}
+
+@keyframes shimmer {
+  0% {
+    background-position: -200% 0;
+  }
+  100% {
+    background-position: 200% 0;
+  }
+}
+</style>
+```
+
+## 使用模板
+
+在实际项目中使用这些模板：
+
+```vue
+<template>
+  <MessageContainer :messages="messages">
+    <template #default="{ message }">
+      <!-- 图表消息 -->
+      <EchartMessage
+        v-if="message.role === 'chart'"
+        :message="message"
+      />
+      <!-- 表格消息 -->
+      <TableMessage
+        v-else-if="message.role === 'table'"
+        :message="message"
+        @export="handleExport"
+      />
+      <!-- 卡片列表消息 -->
+      <CardListMessage
+        v-else-if="message.role === 'cardList'"
+        :message="message"
+        @item-click="handleItemClick"
+      />
+      <!-- 确认消息 -->
+      <ConfirmMessage
+        v-else-if="message.role === 'confirm'"
+        :message="message"
+        @confirm="handleConfirm"
+        @cancel="handleCancel"
+      />
+      <!-- 默认消息 -->
+      <MessageRender
+        v-else
+        :message="message"
+      />
+    </template>
+  </MessageContainer>
+</template>
+```