# XImagePreview 图片预览组件

轻量级图片展示组件，用于在表格、列表等场景中展示缩略图，点击后弹出全屏预览。

## 功能特性

- ✅ 开箱即用，零配置
- ✅ 与 ImagePreviewModal 无缝集成
- ✅ 支持多种尺寸和形状
- ✅ 自动错误处理和占位显示
- ✅ 阻止事件冒泡，避免触发行点击
- ✅ 悬停显示预览提示
- ✅ 完整的键盘、鼠标交互支持

## 快速开始

### 独立使用

```vue
<template>
  <x-image-preview 
    src="/path/to/image.jpg" 
    :size="60"
    shape="square"
    image-name="产品图片"
  />
</template>
```

### 在 XTable 中使用

```js
// 表格列配置
{
  title: '产品图片',
  dataIndex: 'productImage',
  slotType: 'imageView',      // 设置为 imageView
  imageSize: 60,               // 可选，图片尺寸，默认 60
  imageShape: 'square',        // 可选，图片形状，默认 'square'
  imageNameField: 'productName', // 可选，指定图片名称字段
  width: 100,
  align: 'center'
}
```

## Props 属性

| 属性 | 说明 | 类型 | 默认值 |
|------|------|------|--------|
| src | 图片 URL 地址 | String | '' |
| size | 图片尺寸（单位：px） | Number | 60 |
| shape | 图片形状：'square' 方形 / 'circle' 圆形 | String | 'square' |
| preview | 是否启用预览功能 | Boolean | true |
| imageName | 图片名称（用于下载时的文件名） | String | '' |

## Events 事件

| 事件名 | 说明 | 回调参数 |
|--------|------|---------|
| click | 点击图片时触发（无论是否启用预览） | - |

## 表格配置项（通过 XTable 列配置）

| 配置项 | 说明 | 类型 | 默认值 |
|--------|------|------|--------|
| slotType | 插槽类型，设置为 'imageView' | String | - |
| imageSize | 图片尺寸（px） | Number | 60 |
| imageShape | 图片形状 | 'square' \| 'circle' | 'square' |
| imageNameField | 图片名称字段（用于下载） | String | title |

## 示例文件

- `demo.vue` - 完整的功能演示和 API 文档
- `test-table-integration.vue` - XTable 集成测试示例

## 开发测试

### 1. 查看组件演示

在项目中导入并使用 demo.vue 文件：

```js
import XImagePreviewDemo from '@vue2-client/base-client/components/common/XImagePreview/demo.vue'
```

### 2. 测试表格集成

使用 test-table-integration.vue 文件测试在实际表格中的效果：

```js
import TestTableIntegration from '@vue2-client/base-client/components/common/XImagePreview/test-table-integration.vue'
```

### 3. 验证功能点

- ✅ 图片正常展示（不同尺寸、不同形状）
- ✅ 点击预览功能（打开 ImagePreviewModal）
- ✅ 错误处理（加载失败显示占位图标）
- ✅ 悬停效果（遮罩层、放大图标）
- ✅ 事件冒泡阻止（不触发表格行点击）
- ✅ 样式兼容性（与表格样式协调）

## 技术实现

### 组件架构

```
XImagePreview
├── a-avatar (Ant Design Avatar 组件)
│   └── 处理图片展示和错误占位
├── preview-mask (悬停遮罩层)
│   └── 显示预览图标
└── ImagePreviewModal (预览模态框)
    └── 全屏预览功能
```

### 核心特性

1. **样式处理**
   - 使用 scoped 样式，避免全局污染
   - 响应式尺寸和形状控制
   - 平滑的悬停过渡效果

2. **错误处理**
   - 利用 a-avatar 的内置错误处理
   - 自动显示占位图标
   - 不影响其他功能正常使用

3. **事件管理**
   - 使用 @click.stop 阻止事件冒泡
   - 内部状态控制 Modal 显示
   - 支持自定义事件发射

4. **性能优化**
   - 按需渲染 Modal 组件
   - CSS 动画使用 transition
   - 最小化 DOM 操作

## 浏览器兼容性

- Chrome/Edge（最新版本）✅
- Firefox（最新版本）✅
- Safari（最新版本）✅
- IE 11+（需要 polyfill）⚠️

## 常见问题

### 1. 图片不显示？

检查图片 URL 是否有效，是否存在跨域问题。

### 2. 点击图片触发了行点击？

组件已使用 @click.stop，如果仍有问题，检查是否在外层添加了其他点击事件。

### 3. 样式与表格不协调？

可以通过表格列配置的 width 和 align 属性调整布局。

### 4. 如何自定义占位图标？

组件使用 a-avatar 的默认占位图标，如需自定义，可以修改组件内部的 icon 属性。

## 更新日志

### v1.0.0

- ✨ 初始版本发布
- ✨ 支持基础图片展示和预览功能
- ✨ 支持多种尺寸和形状
- ✨ 集成 ImagePreviewModal
- ✨ 在 XTableWrapper 中添加 imageView slotType 支持
- 📝 完整的文档和示例

## License

MIT
