图片组件注释

public/local-images/README.md

@@ -1,6 +1,10 @@
 # 本地图片目录
 
-这个目录用于存放本地图片，用于替换远程图片URL。
+> 作者：系统开发团队  
+> 日期：2023-05-15  
+> 版本：1.0.0
+
+这个目录用于存放本地图片，用于替换远程图片URL。主要用于开发环境中，可以提高开发效率，避免频繁请求远程图片。
 
 ## 目录结构
 
@@ -14,6 +18,8 @@ local-images/
   2/
     image3.jpg
   ...
+  custom/  # 自定义目录，用于特殊映射
+    special-example.jpg
 ```
 
 ## 使用方法
@@ -22,7 +28,33 @@ local-images/
 2. 按照原始URL中的ID和文件名组织目录结构
 3. 在环境变量中设置 `VITE_USE_LOCAL_IMAGES=true` 启用本地图片映射
 
+## 映射规则
+
+系统支持两种映射方式：
+
+1. **URL前缀替换**：将远程URL中的API基础路径替换为本地路径
+2. **特定路径模式匹配**：根据特定的URL模式提取路径信息，构建本地路径
+3. **特定映射配置**：在 `src/config/image-mapping.ts` 中配置特定的映射规则
+
 ## 示例
 
-远程URL: `http://localhost:48081/admin-api/infra/file/1/get/example.jpg`
-本地路径: `/local-images/1/example.jpg` 
+### 基本映射
+
+远程URL: `http://localhost:48081/admin-api/infra/file/1/get/example.jpg`  
+本地路径: `/local-images/1/example.jpg`
+
+### 特定映射
+
+在 `src/config/image-mapping.ts` 中配置：
+
+```typescript
+export const imageMapping: Record<string, string> = {
+  'http://localhost:48081/admin-api/infra/file/1/get/example.jpg': '/local-images/custom/special-example.jpg'
+}
+```
+
+## 注意事项
+
+1. 本地图片映射功能仅在开发环境中启用，生产环境中将使用远程图片
+2. 确保本地图片与远程图片保持一致，避免显示差异
+3. 定期更新本地图片，与远程图片保持同步 

src/components/common/AppImage.vue

@@ -1,3 +1,28 @@
+<!--
+/**
+ * 全局图片组件
+ * 
+ * @author 系统开发团队
+ * @date 2023-05-15
+ * @version 1.0.0
+ * @description 
+ *   该组件是一个全局图片组件，用于处理图片URL，支持将远程图片URL转换为本地路径。
+ *   主要特点：
+ *   1. 自动处理图片URL，支持本地映射
+ *   2. 处理图片加载失败的情况，显示默认图片
+ *   3. 支持所有原生img标签的属性
+ * 
+ * @example
+ * <AppImage src="http://example.com/image.jpg" alt="示例图片" />
+ * 
+ * @example
+ * <AppImage 
+ *   src="http://example.com/image.jpg" 
+ *   alt="示例图片" 
+ *   fallbackSrc="/images/default.png" 
+ * />
+ */
+-->
 <template>
   <img :src="processedSrc" :alt="alt" v-bind="$attrs" @error="handleError" />
 </template>
@@ -6,30 +31,59 @@
 import { computed, ref } from 'vue'
 import { convertImageUrl } from '@/utils/image-helper'
 
+/**
+ * 组件属性定义
+ */
 const props = defineProps({
+  /**
+   * 图片URL
+   * 原始图片URL，将通过convertImageUrl函数处理
+   */
   src: {
     type: String,
     required: true
   },
+  /**
+   * 图片alt属性
+   * 图片的替代文本，用于无法显示图片时
+   */
   alt: {
     type: String,
     default: ''
   },
+  /**
+   * 图片加载失败时显示的默认图片
+   * 当原始图片加载失败时，将显示此图片
+   */
   fallbackSrc: {
     type: String,
     default: '/images/no-image.png'
   }
 })
 
+/**
+ * 图片加载失败标志
+ * 用于跟踪图片是否加载失败
+ */
 const imgError = ref(false)
 
+/**
+ * 处理后的图片URL
+ * 根据图片加载状态和配置，返回最终要显示的图片URL
+ */
 const processedSrc = computed(() => {
+  // 如果图片加载失败且有设置fallbackSrc，则显示fallbackSrc
   if (imgError.value && props.fallbackSrc) {
     return props.fallbackSrc
   }
+  // 否则返回处理后的原始URL
   return convertImageUrl(props.src)
 })
 
+/**
+ * 处理图片加载失败事件
+ * 当图片加载失败时，设置imgError为true，触发显示fallbackSrc
+ */
 const handleError = () => {
   console.warn(`图片加载失败: ${props.src}`)
   imgError.value = true

src/config/image-mapping.ts

@@ -1,6 +1,24 @@
+/**
+ * 图片映射配置文件
+ *
+ * @author 系统开发团队
+ * @date 2023-05-15
+ * @version 1.0.0
+ * @description
+ *   该配置文件用于定义特定图片URL的映射规则。
+ *   可以为特定的远程图片URL指定本地路径，优先级高于通用映射规则。
+ *   主要用于处理特殊情况，如需要将某些图片映射到特定的本地路径。
+ */
+
 /**
  * 图片映射配置
  * 可以为特定的远程图片URL指定本地路径
+ *
+ * @example
+ * {
+ *   'http://example.com/image1.jpg': '/local-images/special/image1.jpg',
+ *   'http://example.com/image2.jpg': '/local-images/special/image2.jpg'
+ * }
  */
 export const imageMapping: Record<string, string> = {
   // 远程URL: 本地路径
@@ -13,6 +31,14 @@ export const imageMapping: Record<string, string> = {
  * 获取映射的本地路径
  * @param url 远程图片URL
  * @returns 映射的本地路径，如果没有映射则返回null
+ *
+ * @example
+ * // 如果有映射，返回映射的本地路径
+ * getMappedImagePath('http://example.com/image1.jpg') // 返回: '/local-images/special/image1.jpg'
+ *
+ * @example
+ * // 如果没有映射，返回null
+ * getMappedImagePath('http://example.com/no-mapping.jpg') // 返回: null
  */
 export const getMappedImagePath = (url: string): string | null => {
   return imageMapping[url] || null

src/directives/image/index.ts

@@ -1,3 +1,13 @@
+/**
+ * 图片URL处理指令模块
+ *
+ * @author 系统开发团队
+ * @date 2023-05-15
+ * @version 1.0.0
+ * @description
+ *   该模块提供了一个自定义指令，用于处理图片URL，支持将远程图片URL转换为本地路径。
+ *   主要用于简化图片URL处理，减少重复代码，统一处理逻辑。
+ */
 import type { App, Directive } from 'vue'
 import { convertImageUrl } from '@/utils/image-helper'
 
@@ -5,8 +15,27 @@ import { convertImageUrl } from '@/utils/image-helper'
  * 图片URL处理指令
  * 使用方法：v-image="imageUrl"
  * 或者：v-image:[属性名]="imageUrl" 例如 v-image:src="imageUrl"
+ *
+ * @example
+ * <!-- 基本用法，处理src属性 -->
+ * <img v-image="imageUrl" alt="图片描述" />
+ *
+ * @example
+ * <!-- 指定属性，处理background属性 -->
+ * <div v-image:background="imageUrl">内容</div>
+ *
+ * @example
+ * <!-- 与Element Plus结合使用 -->
+ * <el-image v-image="product.image" />
  */
 export const imageDirective: Directive = {
+  /**
+   * 指令挂载时调用
+   * 当元素第一次绑定指令时执行
+   *
+   * @param el 指令绑定的元素
+   * @param binding 指令的绑定值和参数
+   */
   mounted(el, binding) {
     const attributeName = binding.arg || 'src'
     const url = binding.value
@@ -16,6 +45,14 @@ export const imageDirective: Directive = {
       el.setAttribute(attributeName, convertedUrl)
     }
   },
+
+  /**
+   * 指令更新时调用
+   * 当绑定值变化时执行
+   *
+   * @param el 指令绑定的元素
+   * @param binding 指令的绑定值和参数
+   */
   updated(el, binding) {
     const attributeName = binding.arg || 'src'
     const url = binding.value
@@ -27,6 +64,16 @@ export const imageDirective: Directive = {
   }
 }
 
+/**
+ * 设置图片处理指令
+ * 在应用中注册v-image指令
+ *
+ * @param app Vue应用实例
+ *
+ * @example
+ * // 在main.ts中调用
+ * setupImageDirective(app)
+ */
 export function setupImageDirective(app: App) {
   app.directive('image', imageDirective)
 }

src/directives/index.ts

@@ -1,17 +1,16 @@
 import type { App } from 'vue'
 import { hasRole } from './permission/hasRole'
 import { hasPermi } from './permission/hasPermi'
-import { setupPermissionDirective } from './permission'
 import { setupImageDirective } from './image'
 
 /**
  * 导出指令：v-xxx
  * @methods hasRole 用户权限，用法: v-hasRole
  * @methods hasPermi 按钮权限，用法: v-hasPermi
+ * @methods v-image 图片URL处理指令，用法: v-image="imageUrl" 或 v-image:src="imageUrl"
  */
 export function setupAuth(app: App<Element>) {
   hasRole(app)
   hasPermi(app)
-  setupPermissionDirective(app)
   setupImageDirective(app)
 }

src/utils/image-helper.ts

@@ -1,6 +1,16 @@
 /**
  * 图片URL处理工具
  * 将远程图片URL转换为本地路径
+ *
+ * @author 系统开发团队
+ * @date 2023-05-15
+ * @version 1.0.0
+ * @description
+ *   该工具用于处理图片URL，支持将远程图片URL转换为本地路径。
+ *   主要用于开发环境中，可以通过环境变量控制是否启用本地图片映射。
+ *   支持两种映射方式：
+ *   1. URL前缀替换：将远程URL中的API基础路径替换为本地路径
+ *   2. 特定路径模式匹配：根据特定的URL模式提取路径信息，构建本地路径
  */
 import { getMappedImagePath } from '@/config/image-mapping'
 
@@ -8,6 +18,15 @@ import { getMappedImagePath } from '@/config/image-mapping'
  * 转换图片URL为本地路径
  * @param url 原始图片URL
  * @returns 转换后的URL
+ *
+ * @example
+ * // 返回原始URL（未启用本地映射）
+ * convertImageUrl('http://example.com/image.jpg')
+ *
+ * @example
+ * // 返回本地路径（启用本地映射）
+ * convertImageUrl('http://localhost:48081/admin-api/infra/file/1/get/image.jpg')
+ * // 返回: '/local-images/1/image.jpg'
  */
 export const convertImageUrl = (url: string): string => {
   if (!url) return ''
@@ -56,6 +75,10 @@ export const convertImageUrl = (url: string): string => {
  * 检查URL是否为图片
  * @param url 要检查的URL
  * @returns 是否为图片URL
+ *
+ * @example
+ * isImageUrl('image.jpg') // 返回: true
+ * isImageUrl('document.pdf') // 返回: false
  */
 export const isImageUrl = (url: string): boolean => {
   if (!url) return false
@@ -66,6 +89,9 @@ export const isImageUrl = (url: string): boolean => {
  * 获取图片文件名
  * @param url 图片URL
  * @returns 文件名
+ *
+ * @example
+ * getImageFileName('http://example.com/images/photo.jpg') // 返回: 'photo.jpg'
  */
 export const getImageFileName = (url: string): string => {
   if (!url) return ''