162 lines
4.0 KiB
Markdown
162 lines
4.0 KiB
Markdown
# 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未定义的问题
|
||
- 添加了完整的错误处理和日志记录 |