@blueking/chat-x 0.0.51-beta.5 → 0.0.52-dev.1

package/skills/blueking-chat-x/references/components/ai-image.md

@@ -0,0 +1,230 @@
+# AiImage 图片展示
+
+> 能力域：媒体文件 ｜ 导入：`import { AiImage } from '@blueking/chat-x'` ｜ since 1.0.0
+
+图片展示组件，组合加载、错误、预览和 extra 插槽。 源码位置：src/components/image-preview/image.vue。
+
+**关联**：image-preview（独立模式下内嵌全屏预览，单图预览入口）、image-preview-group（组内注册子图并统一打开多图预览）
+
+---
+
+# AiImage 图片展示
+## 源码事实
+
+- **源码位置**：`src/components/image-preview/image.vue`
+- **能力域**：媒体文件
+- **能力说明**：图片展示组件，组合加载、错误、预览和 extra 插槽。
+
+> **能力域**：媒体文件
+
+图片展示组件，支持加载状态、加载失败重试、懒加载、点击预览等功能。可独立使用（单图预览），也可配合 `ImagePreviewGroup` 实现多图预览。
+
+## 组件结构
+
+```
+.ai-image（display: inline-block，border-radius: 4px）
+├── <img>（v-if status !== 'error' && actualSrc，object-fit: cover）
+├── .ai-image-error（v-if status === 'error'）
+│     └── ImageErrorIcon（24×24，color: #c4c6cc）
+├── .ai-image-error-overlay（v-if status === 'error'，hover 时显示）
+│     ├── ReloadIcon（16×16）
+│     └── <span>"重新加载"</span>
+├── <slot />
+└── ImagePreview（v-if !groupContext && preview && previewVisible）
+      独立模式下的内置全屏预览
+```
+
+## 基础用法
+
+```vue
+<template>
+  <AiImage
+    src="https://images.unsplash.com/photo-1506744038136-46273834b3fb?w=400&h=300&fit=crop"
+    :width="200"
+    :height="150"
+    alt="风景图"
+    @load="handleLoad"
+    @error="handleError"
+    @preview="handlePreview"
+  />
+</template>
+
+<script setup lang="ts">
+  import { AiImage } from '@blueking/chat-x';
+
+  const handleLoad = (ev: Event) => {
+    console.log('图片加载成功', ev);
+  };
+
+  const handleError = (ev: Event) => {
+    console.log('图片加载失败', ev);
+  };
+
+  const handlePreview = () => {
+    console.log('触发预览');
+  };
+</script>
+```
+
+## 加载失败与重新加载
+
+当图片加载失败时，显示错误占位图标，鼠标悬停后出现"重新加载"遮罩，点击可重新加载（内部通过追加时间戳参数实现缓存破坏）：
+
+```vue
+<template>
+  <AiImage
+    src="https://invalid-url.example.com/not-exist.png"
+    :width="200"
+    :height="150"
+  />
+</template>
+```
+
+## 禁用预览
+
+将 `preview` 设为 `false` 可禁用点击预览功能，此时图片不显示 `zoom-in` 光标：
+
+```vue
+<template>
+  <AiImage
+    src="https://images.unsplash.com/photo-1469474968028-56623f02e42e?w=400&h=300&fit=crop"
+    :width="200"
+    :height="150"
+    :preview="false"
+  />
+</template>
+```
+
+## 预览属性配置
+
+通过 `previewProps` 可为预览弹窗配置不同的图片源（如高清原图）、名称、尺寸信息等：
+
+```vue
+<template>
+  <AiImage
+    src="https://images.unsplash.com/photo-1447752875215-b2761acb3c5d?w=400&h=300&fit=crop"
+    :width="200"
+    :height="150"
+    :preview-props="{
+      src: 'https://images.unsplash.com/photo-1447752875215-b2761acb3c5d?w=1920',
+      name: '森林.jpg',
+      width: 1920,
+      resolution: '1920×1080',
+    }"
+    :show-info="true"
+  />
+</template>
+```
+
+## 多图预览（配合 ImagePreviewGroup）
+
+将多个 `AiImage` 放在 `ImagePreviewGroup` 中，点击任意图片会打开多图预览模式，支持左右切换：
+
+```vue
+<template>
+  <ImagePreviewGroup>
+    <AiImage
+      v-for="(src, i) in images"
+      :key="i"
+      :src="src"
+      :width="160"
+      :height="120"
+    />
+  </ImagePreviewGroup>
+</template>
+
+<script setup lang="ts">
+  import { AiImage, ImagePreviewGroup } from '@blueking/chat-x';
+
+  const images = [
+    'https://images.unsplash.com/photo-1506744038136-46273834b3fb?w=400&h=300&fit=crop',
+    'https://images.unsplash.com/photo-1469474968028-56623f02e42e?w=400&h=300&fit=crop',
+    'https://images.unsplash.com/photo-1447752875215-b2761acb3c5d?w=400&h=300&fit=crop',
+  ];
+</script>
+```
+
+## 自定义下载
+
+通过 `onDownload` 自定义下载行为（例如调用后端接口），不传时使用默认的 `<a>` 标签下载：
+
+```vue
+<template>
+  <AiImage
+    src="https://images.unsplash.com/photo-1506744038136-46273834b3fb?w=400&h=300&fit=crop"
+    :width="200"
+    :height="150"
+    :on-download="handleDownload"
+  />
+</template>
+
+<script setup lang="ts">
+  import { AiImage } from '@blueking/chat-x';
+
+  const handleDownload = (url: string) => {
+    console.log('自定义下载:', url);
+  };
+</script>
+```
+
+## API
+
+### Props
+
+| 属性名       | 类型                    | 默认值  | 说明                                                            |
+| ------------ | ----------------------- | ------- | --------------------------------------------------------------- |
+| src          | `string`                | —       | **必填**，图片地址                                              |
+| alt          | `string`                | `''`    | 图片 alt 属性                                                   |
+| width        | `number \| string`      | —       | 容器宽度，数字时单位为 px                                       |
+| height       | `number \| string`      | —       | 容器高度，数字时单位为 px                                       |
+| lazy         | `boolean`               | `false` | 是否懒加载（IntersectionObserver，rootMargin: 200px）           |
+| preview      | `boolean`               | `true`  | 是否启用点击预览；为 `true` 且图片加载成功时显示 `zoom-in` 光标 |
+| previewProps | `ImagePreviewConfig`    | —       | 预览弹窗配置（可指定高清源、名称、尺寸等）                      |
+| showInfo     | `boolean`               | `false` | 预览工具栏是否显示图片尺寸信息                                  |
+| onDownload   | `(url: string) => void` | —       | 自定义下载回调；不传时使用默认 `<a>` 标签下载                   |
+
+### Events
+
+| 事件名  | 参数          | 说明               |
+| ------- | ------------- | ------------------ |
+| load    | `(ev: Event)` | 图片加载成功时触发 |
+| error   | `(ev: Event)` | 图片加载失败时触发 |
+| preview | —             | 点击触发预览时触发 |
+
+### Slots
+
+| 插槽名  | 说明                                            |
+| ------- | ----------------------------------------------- |
+| default | 覆盖在图片上方的自定义内容                      |
+| extra   | 预览工具栏的额外操作区域（透传给 ImagePreview） |
+
+### Expose
+
+| 属性名         | 类型           | 说明                             |
+| -------------- | -------------- | -------------------------------- |
+| previewVisible | `Ref<boolean>` | 当前预览弹窗是否可见（独立模式） |
+
+## 类型定义
+
+```typescript
+interface ImagePreviewConfig {
+  src?: string;
+  name?: string;
+  width?: number;
+  height?: number;
+  resolution?: string;
+  downloadUrl?: string;
+}
+```
+
+## 使用场景
+
+- AI 对话中的图片消息展示
+- 需要点击放大查看的缩略图
+- 多图浏览场景（配合 `ImagePreviewGroup`）
+- 懒加载长列表中的图片
+
+## 关联组件
+
+- [ImagePreview](/components/medias/image-preview) — 独立模式下的全屏预览
+- [ImagePreviewGroup](/components/medias/image-preview-group) — 多图注册与预览上下文

package/skills/blueking-chat-x/references/components/ai-loading.md

@@ -0,0 +1,131 @@
+# AiLoading 三点加载
+
+> 能力域：辅助能力 ｜ 导入：`import { AiLoading } from '@blueking/chat-x'` ｜ since 1.0.0
+
+小尺寸 AI 加载动效。 源码位置：src/components/ai-loading/ai-loading.vue。
+
+**关联**：loading-message（列表末尾加载占位）、reasoning-message（推理进行中的加载指示）、activity-message（活动消息加载态指示）
+
+---
+
+# AiLoading AI 加载动画
+## 源码事实
+
+- **源码位置**：`src/components/ai-loading/ai-loading.vue`
+- **能力域**：辅助能力
+- **能力说明**：小尺寸 AI 加载动效。
+
+> **能力域**：辅助能力
+
+AI 加载动画基础组件。由两层 SVG 叠加构成：外层旋转光环（带渐变弧线）+ 内层脉冲星形图标，两者共用同一套蓝→紫→粉渐变色。
+
+## 组件结构
+
+```
+.ai-loading（inline-flex，position: relative，width/height 由 size prop 控制）
+│   CSS 同时定义 width/height: 1em 兜底，inline style 优先
+│
+├── .ai-loading-ring（position: absolute，svg 100%×100%）
+│     旋转弧线：ai-loading-rotate 0.8s linear infinite
+│     渐变：#235DFA → #8A77EC → #EB8CEC（蓝 → 紫 → 粉）
+│
+└── .ai-loading-star（position: absolute，svg 100%×100%）
+      脉冲星形：ai-loading-pulse 0.8s ease-in-out infinite
+      关键帧：scale(0.5) → scale(1) → scale(0.5)（小→大→小）
+      渐变：同上
+
+stopLoading=true → 根元素加 .ai-loading-stopped
+  → .ai-loading-stopped .ai-loading-ring { animation-play-state: paused }
+  → .ai-loading-stopped .ai-loading-star { animation-play-state: paused }
+```
+
+## 基础用法
+
+```vue
+<template>
+  <AiLoading />
+</template>
+
+<script setup lang="ts">
+  import { AiLoading } from '@blueking/chat-x';
+</script>
+```
+
+## 自定义尺寸
+
+通过 `size` 属性控制图标大小（单位 px），默认 `16`：
+
+```vue
+<template>
+  <AiLoading />
+  <!-- 16px（默认） -->
+  <AiLoading :size="24" />
+  <AiLoading :size="32" />
+  <AiLoading :size="48" />
+</template>
+```
+
+## 暂停动画
+
+`stopLoading` 为 `true` 时，组件根元素添加 `.ai-loading-stopped` class，两层动画同时进入 `paused` 状态（不移除元素，仅冻结帧）：
+
+```vue
+<template>
+  <AiLoading :stop-loading="isPaused" />
+  <button @click="isPaused = !isPaused">
+    {{ isPaused ? '恢复' : '暂停' }}
+  </button>
+</template>
+
+<script setup lang="ts">
+  import { ref } from 'vue';
+  import { AiLoading } from '@blueking/chat-x';
+
+  const isPaused = ref(false);
+</script>
+```
+
+## 多实例渐变隔离
+
+每个 `AiLoading` 实例通过**模块级 `uid` 计数器**生成唯一的 SVG 渐变 ID：
+
+```
+ai-loading-ring-{instanceId}
+ai-loading-star-{instanceId}
+```
+
+同一页面挂载多个实例时，渐变互不影响。ring 和 star 的 `instanceId` 始终相同（同一组件内），SVG `<path fill="url(#...)" />` 正确引用各自实例的渐变定义。
+
+## 动画规格
+
+| 层                 | 动画名              | 时长 | 缓动        | 关键帧                                  |
+| ------------------ | ------------------- | ---- | ----------- | --------------------------------------- |
+| `.ai-loading-ring` | `ai-loading-rotate` | 0.8s | linear      | `0deg → 360deg` 匀速旋转                |
+| `.ai-loading-star` | `ai-loading-pulse`  | 0.8s | ease-in-out | `0%/100%: scale(0.5)` → `50%: scale(1)` |
+
+脉冲动画节奏：以**半尺寸**起始 → 膨胀至**全尺寸**（0.4s）→ 收缩回**半尺寸**（0.4s），循环往复。
+
+## API
+
+### Props
+
+| 属性名      | 类型      | 默认值  | 说明                                               |
+| ----------- | --------- | ------- | -------------------------------------------------- |
+| size        | `number`  | `16`    | 图标尺寸（px），应用为 inline style，覆盖 CSS 默认 |
+| stopLoading | `boolean` | `false` | `true` 时两层动画均 `paused`，图标停在当前帧       |
+
+## 使用场景
+
+组件库内部以下场景自动使用 `AiLoading`：
+
+| 使用方             | 触发时机                                       | 固定尺寸  |
+| ------------------ | ---------------------------------------------- | --------- |
+| `LoadingMessage`   | 等待 AI 首次响应（loading 消息占位）           | 18px      |
+| `ReasoningMessage` | `status` 为 `pending`/`streaming` 时（思考中） | 默认 16px |
+| `ActivityMessage`  | 活动消息加载状态                               | 默认 16px |
+
+## 关联组件
+
+- [LoadingMessage](/components/message/loading-message) — 对话加载消息
+- [ReasoningMessage](/components/message/reasoning-message) — 推理加载态
+- [ActivityMessage](/components/message/activity-message) — 活动加载态