提交代码

docs/开发文档/ImagePreview组件使用说明.md

@@ -0,0 +1,131 @@
+# ImagePreview 组件使用说明
+
+## 概述
+
+ImagePreview 是一个图片预览组件，支持两种模式：
+1. **普通模式**：直接使用URL字符串
+2. **OSS模式**：通过ossid调用接口获取真实URL
+
+## 功能特性
+
+- ✅ 支持单张和多张图片预览
+- ✅ 支持OSS ID模式，自动获取真实URL
+- ✅ 内置缓存机制，避免重复请求
+- ✅ 加载状态显示
+- ✅ 错误状态处理
+- ✅ 响应式尺寸设置
+- ✅ 图片预览功能
+
+## 组件属性
+
+| 属性名 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| src | String | '' | 图片源，可以是URL或OSS ID |
+| width | Number/String | '' | 图片宽度 |
+| height | Number/String | '' | 图片高度 |
+| isOssId | Boolean | false | 是否为OSS ID模式 |
+
+## 使用示例
+
+### 1. 普通模式（直接使用URL）
+
+```vue
+<template>
+  <ImagePreview 
+    src="https://example.com/image1.jpg,https://example.com/image2.jpg"
+    :width="200"
+    :height="150"
+  />
+</template>
+```
+
+### 2. OSS模式（通过ossid获取URL）
+
+```vue
+<template>
+  <ImagePreview 
+    src="123,456,789"
+    :width="200"
+    :height="150"
+    :is-oss-id="true"
+  />
+</template>
+```
+
+### 3. 单张图片
+
+```vue
+<template>
+  <ImagePreview 
+    src="123"
+    :width="100"
+    :height="100"
+    :is-oss-id="true"
+  />
+</template>
+```
+
+## 技术实现
+
+### 核心功能
+
+1. **OSS ID解析**：支持逗号分隔的多个OSS ID
+2. **URL缓存**：使用Map缓存已获取的URL，避免重复请求
+3. **异步加载**：通过watch监听src变化，异步获取真实URL
+4. **错误处理**：完善的错误处理和日志记录
+
+### API调用
+
+组件内部使用 `listByIds` API获取OSS文件信息：
+
+```typescript
+// 通过ossid获取真实URL
+const getUrlByOssId = async (ossId: string): Promise<string> => {
+  // 检查缓存
+  if (urlCache.value.has(ossId)) {
+    return urlCache.value.get(ossId)!;
+  }
+
+  try {
+    loading.value = true;
+    const response = await listByIds(ossId);
+    const ossList: OssVO[] = response.data;
+    
+    if (ossList && ossList.length > 0) {
+      const url = ossList[0].url;
+      // 缓存结果
+      urlCache.value.set(ossId, url);
+      return url;
+    }
+    return '';
+  } catch (error) {
+    console.error('获取OSS URL失败:', error);
+    return '';
+  } finally {
+    loading.value = false;
+  }
+};
+```
+
+### 缓存机制
+
+```typescript
+const urlCache = ref<Map<string, string>>(new Map());
+```
+
+- 使用Map结构缓存ossid到url的映射
+- 避免重复的API调用
+- 提升用户体验和性能
+
+## 注意事项
+
+1. **网络请求**：OSS模式下会发起网络请求，确保网络连接正常
+2. **权限控制**：确保用户有访问OSS文件的权限
+3. **错误处理**：组件内置错误处理，但建议在业务层面也做相应处理
+4. **性能优化**：缓存机制已内置，无需额外优化
+
+## 更新记录
+
+- **2025-08-02**：修复组件，支持OSS ID模式，添加缓存机制和加载状态
+- 修复了导入错误和computed未定义的问题
+- 添加了完整的错误处理和日志记录