@blueking/chat-x 0.0.5 → 0.0.7

package/dist/mcp/generated/docs/file-content.md

@@ -0,0 +1,300 @@
+<!-- AI SUMMARY -->
+## 快速了解
+
+FileContent 展示消息或输入区附件列表：图片显示缩略图并可进入 ImagePreview，文档以卡片展示文件名、类型与大小。 支持删除、图片加载失败占位及仅有远端文件名的降级展示。
+
+### 关联组件
+- **image-preview** — 点击图片缩略图打开全屏预览
+- **user-message** — 用户消息只读展示附件列表
+
+---
+<!-- FULL DOC -->
+
+# FileContent 文件内容展示
+
+> **层级**：分子组件 · **功能域**：文件与图片
+
+文件列表展示组件，支持图片缩略图预览、点击图片全屏预览（`ImagePreview`）、文档卡片展示（文件名/扩展名/文件大小）、图片加载失败占位和删除操作。
+
+## 渲染决策逻辑
+
+每个文件按以下优先级决定渲染方式：
+
+```
+file.url 存在？
+├── 是 → 图片模式（用 file.url 作为 <img src>，点击可全屏预览）
+│        图片加载失败 → 错误占位（粉色背景 + 红色边框 + 灰色图标）
+└── 否 → 检查 mimeType 或 file.file?.type
+         ├── 以 'image/' 开头 → 图片模式（用 getFilePreviewUrl(file.file) 作为 src，点击可全屏预览）
+         └── 其他            → 文档卡片模式（图标 + 文件名 + 扩展名 + 大小）
+```
+
+> **注意**：`file.url` 存在时**无论文件 MIME 类型是什么**都会走图片模式。若要将 PDF 等非图片文件显示为文档卡片，确保不设置 `url` 字段（或设为 `undefined`）。
+
+## 基础用法（文档文件）
+
+无 `url` 字段、MIME 类型非 `image/*` 的文件，渲染为文档卡片（文档图标 + 文件名 + 扩展名 + 大小）：
+
+```vue
+<template>
+  <FileContent
+    :files="files"
+    @delete-file="handleDeleteFile"
+  />
+</template>
+
+<script setup lang="ts">
+  import { ref } from 'vue';
+  import { FileContent, type UploadFile } from '@blueking/chat-x';
+
+  const files = ref<Partial<UploadFile>[]>([
+    { file: new File(['content'], 'report.pdf', { type: 'application/pdf' }) },
+    { file: new File(['content'], 'data.xlsx', { type: 'application/vnd.ms-excel' }) },
+    { file: new File(['readme'], 'README.md', { type: 'text/markdown' }) },
+  ]);
+
+  const handleDeleteFile = (file: Partial<UploadFile>) => {
+    files.value = files.value.filter(f => f !== file);
+  };
+</script>
+```
+
+**渲染效果**（悬停文件卡片，右上角出现删除按钮）
+
+## 图片文件预览
+
+设置了 `url` 字段时，渲染为 48×48 的图片缩略图（`cursor: zoom-in`）。点击图片可打开全屏预览（内部集成 `ImagePreview` 组件），支持缩放、旋转、下载等操作：
+
+```vue
+<script setup lang="ts">
+  import { ref } from 'vue';
+  import { type UploadFile } from '@blueking/chat-x';
+
+  const imageFiles = ref<Partial<UploadFile>[]>([
+    {
+      url: 'https://example.com/cat.jpg', // 有 url → 图片模式
+      filename: 'cat.jpg',
+      mimeType: 'image/jpeg',
+      file: new File([''], 'cat.jpg', { type: 'image/jpeg' }),
+    },
+    {
+      url: 'https://example.com/dog.png',
+      filename: 'dog.png',
+      mimeType: 'image/png',
+      file: new File([''], 'dog.png', { type: 'image/png' }),
+    },
+  ]);
+</script>
+```
+
+**渲染效果**
+
+## 图片点击预览
+
+图片模式下点击缩略图会打开全屏预览弹窗。多张图片时支持左右切换。加载失败的图片不会出现在预览列表中：
+
+```vue
+<template>
+  <FileContent :files="imageFiles" />
+</template>
+
+<script setup lang="ts">
+  import { ref } from 'vue';
+  import { FileContent, type UploadFile } from '@blueking/chat-x';
+
+  const imageFiles = ref<Partial<UploadFile>[]>([
+    { url: 'https://example.com/cat.jpg', filename: 'cat.jpg', mimeType: 'image/jpeg' },
+    { url: 'https://example.com/dog.png', filename: 'dog.png', mimeType: 'image/png' },
+  ]);
+</script>
+```
+
+> **预览行为**：组件内部自动维护 `ImagePreview` 实例，无需外部管理预览状态。只有加载成功的图片才会进入预览列表，加载失败的图片被自动过滤。
+
+## 图片加载失败
+
+`<img>` 触发 `onerror` 时，切换为粉色背景 + 红色边框的错误占位：
+
+## 混合文件（图片 + 文档）
+
+同一列表中可同时包含图片和文档文件，横向 flex 布局、换行排列：
+
+```vue
+<script setup lang="ts">
+  const files = [
+    { url: 'https://example.com/photo.jpg', filename: 'photo.jpg', mimeType: 'image/jpeg' },
+    { file: new File(['content'], 'report.pdf', { type: 'application/pdf' }) },
+    { file: new File(['data'], 'data.xlsx', { type: 'application/vnd.ms-excel' }) },
+  ];
+</script>
+```
+
+**渲染效果**
+
+## 只读模式（readonly）
+
+传入 `readonly` 时，隐藏删除按钮，适用于用户消息中展示已发送的文件：
+
+```vue
+<FileContent :files="files" :readonly="true" />
+```
+
+**渲染效果**（悬停无删除按钮）
+
+## 仅有 filename（无 File 对象）
+
+从服务端恢复的历史文件没有 `File` 对象时，仍可渲染文档卡片，但**文件大小不显示**，扩展名从 `filename` 或 `mimeType` 推断：
+
+```vue
+<script setup lang="ts">
+  const remoteFiles = [
+    // 无 file 对象，文件大小显示为空
+    { filename: 'server-report.pdf', mimeType: 'application/pdf' },
+    { filename: 'config.json', mimeType: 'application/json' },
+  ];
+</script>
+```
+
+**渲染效果**（大小区域为空）
+
+## 在 ChatInput 中使用
+
+`FileContent` 由 `ChatInput` 内部自动渲染在文件预览区（`slot#files` 的默认内容），通常不需要手动引入。当 `ChatInput` 收到上传文件时，自动更新 `uploadFiles` 并渲染：
+
+```vue
+<template>
+  <ChatInput
+    v-model="inputValue"
+    :on-send-message="handleSendMessage"
+    :on-upload="handleUpload"
+  />
+</template>
+```
+
+若需自定义文件展示，通过 `slot#files` 替换默认 `FileContent`：
+
+```vue
+<template>
+  <ChatInput
+    v-model="inputValue"
+    :on-upload="handleUpload"
+  >
+    <template #files="{ files }">
+      <!-- 自定义文件列表 UI -->
+      <FileContent
+        :files="files"
+        readonly
+      />
+    </template>
+  </ChatInput>
+</template>
+```
+
+## API
+
+### Props
+
+| 属性名   | 类型                    | 默认值  | 必填 | 说明                            |
+| -------- | ----------------------- | ------- | ---- | ------------------------------- |
+| files    | `Partial<UploadFile>[]` | -       | ✅   | 文件列表                        |
+| readonly | `boolean`               | `false` | -    | 只读模式，`true` 时隐藏删除按钮 |
+
+### Events
+
+| 事件名     | 参数                          | 触发时机           |
+| ---------- | ----------------------------- | ------------------ |
+| deleteFile | `(file: Partial<UploadFile>)` | 点击删除按钮时触发 |
+
+## 渲染模式详解
+
+### 图片模式
+
+| 条件                               | 图片 src                         | 点击行为       |
+| ---------------------------------- | -------------------------------- | -------------- |
+| `file.url` 有值（优先）            | `file.url`                       | 打开全屏预览   |
+| MIME 以 `image/` 开头（无 url 时） | `URL.createObjectURL(file.file)` | 打开全屏预览   |
+| 图片加载失败                       | 错误占位                         | 不进入预览列表 |
+
+### 文档卡片模式
+
+| 字段     | 取值优先级                                                                                                   |
+| -------- | ------------------------------------------------------------------------------------------------------------ |
+| 文件名   | `file.filename` → `file.file?.name`                                                                          |
+| 扩展名   | 有 `file.file`：取文件名最后一段 `.xxx` 或 MIME 后缀<br>无 `file.file`：取 `filename` 后缀 → `mimeType` 后缀 |
+| 文件大小 | 仅当有 `file.file`（`File` 对象）时显示，否则为空                                                            |
+
+## 类型定义
+
+```typescript
+import type { UploadFile, BinaryInputContent } from '@blueking/chat-x';
+
+// 上传状态（ChatInput 内部使用，FileContent 不使用此字段）
+enum UploadStatus {
+  Pending = 'pending', // 上传中
+  Success = 'success', // 上传成功
+  Error = 'error', // 上传失败
+}
+
+// 上传文件（FileContent 的 files 数组中每一项）
+type UploadFile = BinaryInputContent & {
+  file?: File; // 原始 File 对象，无则文件大小不显示
+  status?: UploadStatus; // 上传状态（ChatInput 使用，FileContent 不消费）
+};
+
+// 二进制内容基础类型
+interface BinaryInputContent {
+  type: 'binary';
+  url?: string; // 文件访问地址，存在时强制走图片模式
+  filename?: string; // 文件名（用于文档卡片）
+  mimeType?: string; // MIME 类型（用于图片判断和扩展名推断）
+}
+```
+
+## 工具函数（内部使用）
+
+```typescript
+// 判断是否走图片模式
+// ⚠️ file.url 存在时直接返回 true，不判断 MIME 类型
+const isImage = (file: Partial<UploadFile>): boolean => {
+  if (file.url) return true;
+  return isImageFile(file.mimeType || file.file?.type);
+};
+
+// 判断 MIME 类型是否为图片
+const isImageFile = (mimeType?: string): boolean => {
+  if (!mimeType) return false;
+  return mimeType.startsWith('image/');
+};
+
+// 获取 File 对象的临时预览 URL（无 url 时的图片模式备选）
+const getFilePreviewUrl = (file?: File): string => {
+  if (!file) return '';
+  return URL.createObjectURL(file);
+};
+
+// 获取文件扩展名
+const getFileExtension = (file?: File): string => {
+  if (!file) return '';
+  return file.name.split('.').pop() || file.type?.split('/').pop() || '';
+};
+
+// 格式化文件大小（需要 File 对象）
+const formatFileSize = (file?: File): string => {
+  if (!file) return '';
+  const size = file.size;
+  const units = ['B', 'KB', 'M', 'GB'];
+  const index = Math.floor(Math.log2(size || 1) / 10);
+  return `${(size / Math.pow(1024, index)).toFixed(2)} ${units[index]}`;
+};
+```
+
+## 使用场景
+
+- **ChatInput 文件预览区**：上传文件后在编辑器上方展示待发送的文件列表（可删除）
+- **用户消息展示**：`UserMessage` 内部以 `readonly` 模式展示已发送的图片和附件
+- **历史消息回放**：服务端返回的文件信息（无 `File` 对象）也能正常渲染文档卡片
+
+## 关联组件
+
+- [ImagePreview](./image-preview.md) — 图片全屏预览
+- [UserMessage](./user-message.md) — 用户消息内附件展示

package/dist/mcp/generated/docs/file-upload-btn.md

@@ -0,0 +1,174 @@
+<!-- AI SUMMARY -->
+## 快速了解
+
+FileUploadBtn 提供隐藏 file input 与图标按钮，选择文件后 emit upload，并内置数量与单文件大小上限校验。 常用于 ChatInput 工具条；与 FileContent 等展示列表配合形成「选择 → 展示 → 发送」链路。
+
+### 关联组件
+- **chat-input** — 输入区附件上传按钮常见挂载位置
+- **file-content** — 选中文件常以列表形式展示待发送内容
+
+---
+<!-- FULL DOC -->
+
+# FileUploadBtn 文件上传按钮
+
+> **层级**：原子组件 · **功能域**：文件与图片
+
+聊天输入框内置的文件上传触发按钮，点击后弹出系统文件选择框。内部包含隐藏的 `<input type="file">` 与可见的图标按钮，并内置文件数量及大小校验逻辑。
+
+## 组件结构
+
+```
+.file-upload-btn（display: flex，align-items: center）
+├── input[type="file"]（.file-upload-btn-input，display: none，multiple，:accept）
+│     触发后走 handleFileInputChange → 校验 → emit upload → target.value = ''
+└── span.ai-shortcut-btn.file-upload-btn-icon（24×24px，color: #979ba5，hover: cursor: pointer）
+      v-tippy: "上传图片, 最多支持上传 3 个, 最大支持 2.4MB"（theme: ai-chat-box，offset: [0, 16]，可通过 tippyOptions 扩展）
+      @click → fileInputRef.click()
+      └── <slot> 默认：FileUploadIcon
+```
+
+## 文件校验逻辑
+
+```
+用户选择文件
+  │
+  ├─ files.length > Math.max(maxFiles, MAX_UPLOAD_FILES[3])
+  │       ↓ true → bkui-vue Message.error("最多上传 N 个文件")，终止，不 emit
+  │
+  └─ emit('upload', files.filter(f => f.size > 0 && f.size < MAX_UPLOAD_FILE_SIZE[2.5MB]))
+        ↓
+      target.value = ''（重置 input，允许再次选择同一文件）
+```
+
+**关键边界行为**：
+
+| 场景                                      | 结果                                                        |
+| ----------------------------------------- | ----------------------------------------------------------- |
+| 文件数超过 `Math.max(maxFiles, 3)`        | 弹出错误 toast，**不触发** `upload`                         |
+| 文件数未超限，但部分文件被大小过滤        | **仍触发** `upload`，payload 为过滤后的数组（可能为空数组） |
+| `file.size === 0`                         | 被过滤（空文件）                                            |
+| `file.size >= 2.5MB`（即 `2621440` 字节） | 被过滤（使用严格小于 `<`，等于 2.5MB 也会被过滤）           |
+| `maxFiles` 设为小于 3 的值（如 `1`）      | 实际限制取 `Math.max(1, 3) = 3`，不低于全局下限             |
+| 选择后取消                                | `files.length === 0`，不触发 `upload`                       |
+
+> `multiple` prop 声明存在但当前模板中 `input` 的 `multiple` 属性为**硬编码**（非 `:multiple="multiple"` 绑定），始终允许多选，该 prop 暂时无实际效果。
+
+## 基础用法
+
+```vue
+<template>
+  <FileUploadBtn @upload="handleUpload" />
+</template>
+
+<script setup lang="ts">
+  import { FileUploadBtn } from '@blueking/chat-x';
+
+  const handleUpload = (files: File[]) => {
+    console.log(
+      '选中文件:',
+      files.map(f => `${f.name}(${f.size}B)`),
+    );
+  };
+</script>
+```
+
+## 限制文件类型
+
+通过 `accept` 属性控制系统文件选择框的过滤条件，遵循 `<input type="file">` 的 `accept` 规范：
+
+```vue
+<template>
+  <!-- 仅图片（默认） -->
+  <FileUploadBtn
+    accept="image/*"
+    @upload="handleUpload"
+  />
+
+  <!-- 文档类型 -->
+  <FileUploadBtn
+    accept=".pdf,.doc,.docx,.xlsx,.pptx"
+    @upload="handleUpload"
+  />
+
+  <!-- 不限制类型 -->
+  <FileUploadBtn
+    accept="*/*"
+    @upload="handleUpload"
+  />
+</template>
+```
+
+> `accept` 仅影响文件选择框的过滤 UI，不做服务端验证，请在 `upload` 回调中自行校验 MIME 类型。
+
+## 限制上传数量
+
+`maxFiles` 限制单次选择的文件上传上限，实际生效值为 `Math.max(maxFiles, 3)`，不会低于全局下限 3：
+
+```vue
+<template>
+  <!-- maxFiles=5：可一次选 5 个文件 -->
+  <FileUploadBtn
+    :max-files="5"
+    @upload="handleUpload"
+  />
+
+  <!-- maxFiles=1：实际等效 maxFiles=3（取 Math.max(1,3)） -->
+  <FileUploadBtn
+    :max-files="1"
+    @upload="handleUpload"
+  />
+</template>
+```
+
+## 自定义图标
+
+通过默认插槽替换上传图标：
+
+```vue
+<template>
+  <FileUploadBtn @upload="handleUpload">
+    <span style="font-size: 16px; line-height: 1;">📎</span>
+  </FileUploadBtn>
+</template>
+```
+
+## API
+
+### Props
+
+| 属性名       | 类型           | 默认值      | 说明                                                   |
+| ------------ | -------------- | ----------- | ------------------------------------------------------ |
+| accept       | `string`       | `'image/*'` | 文件选择框过滤类型，遵循 `<input accept>` 规范         |
+| maxFiles     | `number`       | `3`         | 单次选择文件数上限；实际限制为 `Math.max(maxFiles, 3)` |
+| multiple     | `boolean`      | `true`      | 声明属性（当前版本未实际绑定到 input，始终多选）       |
+| tippyOptions | `AITippyProps` | —           | 扩展 tooltip 配置，会与内置配置合并                    |
+
+### Events
+
+| 事件名 | 参数              | 说明                                                                                      |
+| ------ | ----------------- | ----------------------------------------------------------------------------------------- |
+| upload | `(files: File[])` | 校验通过后触发；`files` 为过滤掉空文件和超大文件（≥ 2.5MB）后的数组；超出数量限制时不触发 |
+
+### Slots
+
+| 插槽名  | 说明                                            |
+| ------- | ----------------------------------------------- |
+| default | 自定义按钮图标内容，默认为内置 `FileUploadIcon` |
+
+## 使用场景
+
+`FileUploadBtn` 由 `ChatInput` 组件内置，当 `ChatInput` 的 `supportUpload` prop 为 `true`（默认值）时自动渲染。一般不需要单独引入，除非构建完全自定义的输入区域。
+
+## 类型定义
+
+```typescript
+import type { TippyOptions } from 'vue-tippy';
+
+type AITippyProps = Partial<Omit<TippyOptions, 'content' | 'getReferenceClientRect' | 'theme' | 'triggerTarget'>>;
+```
+
+## 关联组件
+
+- [ChatInput](../molecular/chat-input.md) — 默认内置上传入口
+- [FileContent](../molecular/file-content.md) — 选中文件列表展示