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

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）

<template>
  <ImagePreview 
    src="https://example.com/image1.jpg,https://example.com/image2.jpg"
    :width="200"
    :height="150"
  />
</template>

2. OSS模式（通过ossid获取URL）

<template>
  <ImagePreview 
    src="123,456,789"
    :width="200"
    :height="150"
    :is-oss-id="true"
  />
</template>

3. 单张图片

<template>
  <ImagePreview 
    src="123"
    :width="100"
    :height="100"
    :is-oss-id="true"
  />
</template>

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

<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文件信息：

// 通过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;
  }
};

缓存机制

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