# 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>
```

### 4. 顶部个人头像（自动识别OSS ID）

```vue
<script setup lang="ts">
import { computed } from 'vue';
import ImagePreview from '@/components/ImagePreview/index.vue';
import { useUserStore } from '@/store/modules/user';

const userStore = useUserStore();
const avatarIsOssId = computed(() => {
  const avatar = userStore.avatar;
  if (!avatar) return false;
  return !/^https?:\/\//i.test(avatar) && !avatar.startsWith('/');
});
</script>

<template>
  <ImagePreview
    v-if="userStore.avatar"
    class="user-avatar"
    :src="userStore.avatar"
    :width="24"
    :height="24"
    :is-oss-id="avatarIsOssId"
  />
</template>
```

> ✅ 用于首页 `Navbar` 头像区域时，`avatarIsOssId` 会自动识别当前值是否为 OSS ID，从而在带 Token 的 `/resource/oss/download/{ossId}` 接口与传统 URL 之间无缝切换，保证头像始终通过认证通道加载。

## 技术实现

### 核心功能

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-11-28**：补充顶部栏个人头像场景示例，强调 OSS ID 自动识别策略，确保 `Navbar` 等公共区域也复用统一的图片安全加载方案。
- **2025-08-02**：修复组件，支持OSS ID模式，添加缓存机制和加载状态
- 修复了导入错误和computed未定义的问题
- 添加了完整的错误处理和日志记录